| # Zircon Signals | |
| ## Introduction | |
| A signal is a single bit of information that waitable zircon kernel objects expose to | |
| applications. Each object can expose one or more signals, most of which are specific | |
| to the type of object. | |
| For example, the signal **ZX_CHANNEL_READABLE** indicates "this channel endpoint has | |
| messages to read", and **ZX_PROCESS_TERMINATED** indicates "this process stopped running." | |
| The signals for an object are stored in a `uint32` bitmask, and their values (which are | |
| object-specific) are defined in the header[`zircon/types.h`](/zircon/system/public/zircon/types.h). | |
| The typedef `zx_signals_t` is used to refer to signal bitmasks in syscalls and other APIs. | |
| Most objects are waitable. Ports are an example of a non-waitable object. | |
| ## State, State Changes and their Terminology | |
| A signal is said to be **Active** when its bit is 1 and **Inactive** when its bit is 0. | |
| A signal is said to be **Asserted** when it is made **Active** in response to an event | |
| (even if it was already **Active**), and is said to be **Deasserted** when it is made | |
| **Inactive** in response to an event (even if it was already **Inactive**). | |
| For example: When a message is written into a Channel endpoint, the **ZX_CHANNEL_READABLE** | |
| signal of the opposing endpoint is **asserted** (which causes that signal to become **active**, | |
| if it were not already active). When the last message in a Channel endpoint's | |
| queue is read from that endpoint, the **ZX_CHANNEL_READABLE** signal of that endpoint is | |
| **deasserted** (which causes that signal to become **inactive**) | |
| ## Observing Signals | |
| The syscalls [`zx_object_wait_one()`], [`zx_object_wait_many()`], and | |
| [`zx_object_wait_async()`], in combination with a Port, can be used to wait for | |
| specified signals on one or more objects. | |
| If multiple threads are operating on an object, the results of these syscalls | |
| may already be out of date by the time the calling thread actually acts on them. | |
| For example, a thread waiting on a Channel for the **ZX_CHANNEL_READABLE** | |
| signal may wake from a [`zx_object_wait_one()`] syscall only to find that there | |
| are no pending messages, because another thread has already read it. | |
| ## Synthetic Signals | |
| The signal `ZX_SIGNAL_HANDLE_CLOSED` is a synthetic signal only exists in the | |
| results of [`zx_object_wait_one()`] or [`zx_object_wait_many()`] and indicates | |
| that a handle that was being waited upon has been been closed causing the wait | |
| operation to be aborted. | |
| This signal can only be obtained as a result of the above two wait calls when the wait itself | |
| returns with **ZX_ERR_CANCELED**. | |
| ## User Signals | |
| There are eight User Signals (**ZX_USER_SIGNAL_0** through **ZX_USER_SIGNAL_7**), which may | |
| asserted or deasserted using the [`zx_object_signal()`] and [`zx_object_signal_peer()`] syscalls, | |
| provided the handle has the appropriate rights (**ZX_RIGHT_SIGNAL** or **ZX_RIGHT_SIGNAL_PEER**, | |
| respectively). These User Signals are always initially inactive, and are only modified by | |
| the object signal syscalls. | |
| ## See Also | |
| - [`zx_object_signal()`] | |
| - [`zx_object_signal_peer()`] | |
| - [`zx_object_wait_async()`] | |
| - [`zx_object_wait_many()`] | |
| - [`zx_object_wait_one()`] | |
| [`zx_object_get_info()`]: /reference/syscalls/object_get_info.md | |
| [`zx_object_signal()`]: /reference/syscalls/object_signal.md | |
| [`zx_object_signal_peer()`]: /reference/syscalls/object_signal.md | |
| [`zx_object_wait_async()`]: /reference/syscalls/object_wait_async.md | |
| [`zx_object_wait_many()`]: /reference/syscalls/object_wait_many.md | |
| [`zx_object_wait_one()`]: /reference/syscalls/object_wait_one.md |