Wakers

Overview

Queue work in response to async events.

Learn more: Wakers

Classes
class	pw::async2::Waker

Macros
#define	PW_ASYNC2_DEBUG_WAIT_REASON   1
#define	PW_ASYNC_STORE_WAKER(context, waker_or_queue_out, wait_reason_string)
#define	PW_ASYNC_TRY_STORE_WAKER( context, waker_or_queue_out, wait_reason_string)
#define	PW_ASYNC_CLONE_WAKER(waker_in, waker_or_queue_out, wait_reason_string)
#define	PW_ASYNC_TRY_CLONE_WAKER( waker_in, waker_or_queue_out, wait_reason_string)

Macro Definition Documentation

PW_ASYNC2_DEBUG_WAIT_REASON

#define PW_ASYNC2_DEBUG_WAIT_REASON   1

Controls how the wait_reason_string argument to PW_ASYNC_STORE_WAKER and PW_ASYNC_CLONE_WAKER is used. If enabled, wait reasons are stored within their wakers, allowing easier debugging of sleeping tasks.

Enabled by default.

Note: The module dependencies of pw_async2 vary based on on the value of PW_ASYNC2_DEBUG_WAIT_REASON. When building pw_async2 with Bazel, you should NOT set this module config by adding one of the following constraint_values to the target platform:

• @pigweed//pw_async2:debug_wait_reason_disabled (default)
• @pigweed//pw_async2:debug_wait_reason_enabled

PW_ASYNC_CLONE_WAKER

#define PW_ASYNC_CLONE_WAKER	(		waker_in,
			waker_or_queue_out,
			wait_reason_string
	)

Value:

  do {                                                                         \
    bool waker_or_queue_had_space = PW_ASYNC_TRY_CLONE_WAKER(                  \
        waker_in, waker_or_queue_out, wait_reason_string);                     \
    PW_ASSERT(waker_or_queue_had_space);                                       \
  } while (0)

Attempts to store a waker associated with waker_in into waker_or_queue_out. If the waker cannot be stored into waker_or_queue_out due to the target waker already referencing a task or the queue being full, crashes.

When the stored waker is later awoken with :cpp:func:pw::async2::Waker::Wake, the :cpp:class:pw::async2::Task associated with cx will be awoken and its DoPend method will be invoked again.

wait_reason_string is a human-readable description of why the task is blocked. If the module configuration option PW_ASYNC2_DEBUG_WAIT_REASON is set, this string will be stored with the waker and reported by Dispatcher::LogRegisteredTasks when its associated task is blocked.

PW_ASYNC_STORE_WAKER

#define PW_ASYNC_STORE_WAKER	(		context,
			waker_or_queue_out,
			wait_reason_string
	)

Value:

  do {                                                                        \
    bool waker_or_queue_had_space = PW_ASYNC_TRY_STORE_WAKER(                 \
        context, waker_or_queue_out, wait_reason_string);                     \
    PW_ASSERT(waker_or_queue_had_space);                                      \
  } while (0)

Attempts to store a waker associated with the current context into waker_or_queue_out. If the waker cannot be stored into waker_or_queue_out due to the target waker already referencing a task or the queue being full, crashes.

When the stored waker is later awoken with :cpp:func:pw::async2::Waker::Wake, the :cpp:class:pw::async2::Task associated with cx will be awoken and its DoPend method will be invoked again.

wait_reason_string is a human-readable description of why the task is blocked. If the module configuration option PW_ASYNC2_DEBUG_WAIT_REASON is set, this string will be stored with the waker and reported by Dispatcher::LogRegisteredTasks when its associated task is blocked.

PW_ASYNC_TRY_CLONE_WAKER

#define PW_ASYNC_TRY_CLONE_WAKER	(		waker_in,
			waker_or_queue_out,
			wait_reason_string
	)

Value:

  _PW_ASYNC_TRY_GET_WAKER(::pw::async2::internal::CloneWaker, \
                          waker_in,                           \
                          waker_or_queue_out,                 \
                          wait_reason_string)

Attempts to store a waker associated with waker_in into waker_or_queue_out. If the waker cannot be stored into waker_or_queue_out due to the target waker already referencing a task or the queue being full, returns false and does not modify it.

When the stored waker is later awoken with :cpp:func:pw::async2::Waker::Wake, the :cpp:class:pw::async2::Task associated with cx will be awoken and its DoPend method will be invoked again.

wait_reason_string is a human-readable description of why the task is blocked. If the module configuration option PW_ASYNC2_DEBUG_WAIT_REASON is set, this string will be stored with the waker and reported by Dispatcher::LogRegisteredTasks when its associated task is blocked.

PW_ASYNC_TRY_STORE_WAKER

#define PW_ASYNC_TRY_STORE_WAKER	(		context,
			waker_or_queue_out,
			wait_reason_string
	)

Value:

  _PW_ASYNC_TRY_GET_WAKER(::pw::async2::internal::StoreWaker, \
                          context,                            \
                          waker_or_queue_out,                 \
                          wait_reason_string)

Attempts to store a waker associated with the current context into waker_or_queue_out. If the waker cannot be stored into waker_or_queue_out due to the target waker already referencing a task or the queue being full, returns false and does not modify it.

When the stored waker is later awoken with :cpp:func:pw::async2::Waker::Wake, the :cpp:class:pw::async2::Task associated with cx will be awoken and its DoPend method will be invoked again.

wait_reason_string is a human-readable description of why the task is blocked. If the module configuration option PW_ASYNC2_DEBUG_WAIT_REASON is set, this string will be stored with the waker and reported by Dispatcher::LogRegisteredTasks when its associated task is blocked.