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 headerzircon/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.