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
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.
To determine if an object is waitable, call
with ZX_INFO_HANDLE_BASIC topic and test for ZX_OBJ_PROP_WAITABLE.
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)
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.
ZX_SIGNAL_HANDLE_CLOSED is a synthetic signal only exists in the
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.
There are eight User Signals (ZX_USER_SIGNAL_0 through ZX_USER_SIGNAL_7) which may
asserted or deasserted using the
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.