+++
title = "`lazy<T, Executor = void>/atomic_lazy<T, Executor = void>`"
description = "A lazily evaluated coroutine awaitable with Outcome customisation."
+++

This is very similar to {{% api "eager<T, Executor = void>" %}}, except that execution of the
`lazy<T>` returning function suspends immediately. Functions which return `lazy<T>`
are therefore suitable for tasks which you need to instantiate right now, but whose
execution will occur elsewhere e.g. in a separate kernel thread. Because of the very
common use case of using worker threads to execute the body of lazily executed
coroutines, most people will want to use `atomic_lazy<T>` instead of `lazy<T>`.

`atomic_lazy<T>` is like `lazy<T>`, except that the setting of the coroutine result
performs an atomic release, whilst the checking of whether the coroutine has finished
is an atomic acquire.

`lazy<T>` has similar semantics to `std::lazy<T>`, which is being standardised. See
https://wg21.link/P1056 *Add lazy coroutine (coroutine task) type*.

The `Executor` template parameter is purely for compatibility with third party software
such as [ASIO](https://think-async.com/Asio/), and this awaitable can be directly used
by ASIO.

Example of use (must be called from within a coroutinised function):

```c++
lazy<int> func(int x)
{
  co_return x + 1;
}
...
// Always suspends perhaps causing other coroutines to execute, then resumes.
int r = co_await func(5);
```

`lazy<T>` has special semantics if `T` is a type capable of constructing from
an `exception_ptr` or `error_code` -- any exceptions thrown during the function's body
are sent via `T`, preferably via the error code route if {{% api "error_from_exception(" %}}`)`
successfully matches the exception throw. This means that a
{{% api "basic_result<T, E, NoValuePolicy>" %}} or {{% api "basic_outcome<T, EC, EP, NoValuePolicy>" %}} where one of its types is
is compatible will have its `.error()` or `.exception()` set.

Note that `lazy<T>` does not otherwise transport exception throws, and rethrows
any exceptions thrown within the coroutine body through the coroutine machinery.
This does not produce reliable consequences in current C++ compilers. You should
therefore wrap the coroutine body in a `try...catch` if `T` is not able to transport
exceptions on its own.

*Requires*: C++ coroutines to be available in your compiler.

*Namespace*: `BOOST_OUTCOME_V2_NAMESPACE::awaitables`

*Header*: `<boost/outcome/coroutine_support.hpp>`
