1.. _async_notification:
2
3Asynchronous Notifications
4##########################
5
6Zephyr APIs often include :ref:`api_term_async` functions where an
7operation is initiated and the application needs to be informed when it
8completes, and whether it succeeded.  Using :c:func:`k_poll` is
9often a good method, but some application architectures may be more
10suited to a callback notification, and operations like enabling clocks
11and power rails may need to be invoked before kernel functions are
12available so a busy-wait for completion may be needed.
13
14This API is intended to be embedded within specific subsystems such as
15:ref:`resource_mgmt_onoff` and other APIs that support async
16transactions.  The subsystem wrappers are responsible for extracting
17operation-specific data from requests that include a notification
18element, and for invoking callbacks with the parameters required by the
19API.
20
21A limitation is that this API is not suitable for :ref:`syscalls`
22because:
23
24* :c:struct:`sys_notify` is not a kernel object;
25* copying the notification content from userspace will break use of
26  :c:macro:`CONTAINER_OF` in the implementing function;
27* neither the spin-wait nor callback notification methods can be
28  accepted from userspace callers.
29
30Where a notification is required for an asynchronous operation invoked
31from a user mode thread the subsystem or driver should provide a syscall
32API that uses :c:struct:`k_poll_signal` for notification.
33
34API Reference
35*************
36
37.. doxygengroup:: sys_notify_apis
38