1# Zircon Signals
2
3## Introduction
4
5A signal is a single bit of information that waitable zircon kernel objects expose to
6applications.  Each object can expose one or more signals; some are generic and some
7are specific to the type of object.
8
9For example, the signal *ZX_CHANNEL_READABLE* indicates "this channel endpoint has
10messages to read", and **ZX_PROCESS_TERMINATED** indicates "this process stopped running."
11
12The signals for an object are stored in a uint32 bitmask, and their values (which are
13object-specific) are defined in the header[`zircon/types.h`](../system/public/zircon/types.h).
14The typedef `zx_signals_t` is used to refer to signal bitmasks in syscalls and other APIs.
15
16Most objects are waitable.  Ports are an example of a non-waitable object.
17To determine if an object is waitable, call [object_get_info](syscalls/object_get_info.md)
18with **ZX_INFO_HANDLE_BASIC** topic and test for **ZX_OBJ_PROP_WAITABLE**.
19
20## State, State Changes and their Terminology
21
22A signal is said to be **Active** when its bit is 1 and **Inactive** when its bit is 0.
23
24A signal is said to be **Asserted** when it is made **Active** in response to an event
25(even if it was already **Active**), and is said to be **Deasserted** when it is made
26**Inactive** in response to an event (even if it was already **Inactive**).
27
28For example:  When a message is written into a Channel endpoint, the *ZX_CHANNEL_READABLE*
29signal of the opposing endpoint is **asserted** (which causes that signal to become **active**,
30if it were not already active).  When the last message in a Channel endpoint's
31queue is read from that endpoint, the *ZX_CHANNEL_READABLE* signal of that endpoint is
32**deasserted** (which causes that signal to become **inactive**)
33
34## Observing Signals
35
36The syscalls **zx_object_wait_one**(), **zx_object_wait_many**(), and **zx_object_wait_async**() (in
37combination with a Port), can be used to wait for specified signals on one or more objects.
38
39## Common Signals
40
41### ZX_SIGNAL_HANDLE_CLOSED
42
43This synthetic signal only exists in the results of [object_wait_one](syscalls/object_wait_one.md)
44or [object_wait_many](syscalls/object_wait_many.md) and indicates that a handle that was
45being waited upon has been been closed causing the wait operation to be aborted.
46
47This signal can only be obtained as a result of the above two wait calls when the wait itself
48returns with **ZX_ERR_CANCELED**.
49
50## User Signals
51
52There are eight User Signals (**ZX_USER_SIGNAL_0** through **ZX_USER_SIGNAL_7**) which may
53asserted or deasserted using the **zx_object_signal**() and **zx_object_signal_peer**() syscalls,
54provided the handle has the appropriate rights (**ZX_RIGHT_SIGNAL** or **ZX_RIGHT_SIGNAL_PEER**,
55respectively).  These User Signals are always initially inactive, and are only modified by
56the object signal syscalls.
57
58## See Also
59
60[object_signal](syscalls/object_signal.md),
61[object_signal_peer](syscalls/object_signal.md),
62[object_wait_async](syscalls/object_wait_async.md),
63[object_wait_many](syscalls/object_wait_many.md),
64[object_wait_one](syscalls/object_wait_one.md).
65