Events and the Event Model

An event (zend_async_event_t) is a universal structure from which all asynchronous primitives inherit: coroutines, future, channels, timers, poll events, signals, and others.

The unified event interface allows:

• Subscribing to any event via callback
• Combining heterogeneous events in a single wait
• Managing the lifecycle through ref-counting

Base Structure

struct _zend_async_event_s {
    uint32_t flags;
    uint32_t extra_offset;           // Offset to additional data

    union {
        uint32_t ref_count;          // For C objects
        uint32_t zend_object_offset; // For Zend objects
    };

    uint32_t loop_ref_count;         // Event loop reference count

    zend_async_callbacks_vector_t callbacks;

    // Methods
    zend_async_event_add_callback_t add_callback;
    zend_async_event_del_callback_t del_callback;
    zend_async_event_start_t start;
    zend_async_event_stop_t stop;
    zend_async_event_replay_t replay;       // Nullable
    zend_async_event_dispose_t dispose;
    zend_async_event_info_t info;           // Nullable
    zend_async_event_callbacks_notify_t notify_handler; // Nullable
};

Virtual Methods of an Event

Each event has a small set of virtual methods.

add_callback

Adds a callback to the event’s dynamic callbacks array. Calls zend_async_callbacks_push(), which increments the callback’s ref_count and adds the pointer to the vector.

del_callback

Removes a callback from the vector (O(1) via swap with the last element) and calls callback->dispose.

Typical scenario: during a select wait on multiple events, when one fires, the others are unsubscribed via del_callback.

start

The start and stop methods are intended for events that can be placed into the EventLoop. Therefore, not all primitives implement this method.

For EventLoop events, start increments the loop_ref_count, which allows the event to remain in the EventLoop as long as it is needed by someone.

stop

The mirror method of start. Decrements the loop_ref_count for EventLoop-type events. The last stop call (when loop_ref_count reaches 0) actually stops the handle.

replay

Allows late subscribers to receive the result of an already completed event. Implemented only by types that store a result.

If a callback is provided, it is called synchronously with the result. If result/exception is provided, values are copied to the pointers. Without replay, waiting on a closed event produces a warning.

dispose

This method attempts to release the event by decrementing its ref_count. If the count reaches zero, actual resource deallocation is triggered.

info

A human-readable string for debugging and logging.

notify_handler

A hook that intercepts notification before callbacks receive the result. By default NULL for all events. Used in Async\Timeout:

Event Lifecycle

An event goes through several states:

• Created – memory allocated, ref_count = 1, callbacks can be subscribed
• Active – registered in the EventLoop (start()), increments active_event_count
• Fired – libuv called the callback. For periodic events (timer, poll) – returns to Active. For one-shot events (DNS, exec, Future) – transitions to Closed
• Stopped – temporarily removed from the EventLoop (stop()), can be reactivated
• Closed – flags |= F_CLOSED, subscription is not possible, when ref_count = 0 is reached, dispose is called

Interaction: Event, Callback, Coroutine

Dual Life: C Object and Zend Object

Events often live in two worlds simultaneously. A timer, poll handle, or DNS query is an internal C object managed by the Reactor. But a coroutine or Future is also a PHP object accessible from user code.

C structures in the EventLoop may live longer than the PHP objects that reference them, and vice versa. C objects use ref_count, while PHP objects use GC_ADDREF/GC_DELREF with the garbage collector.

Therefore, TrueAsync supports several types of bindings between PHP objects and C objects.

C Object

Internal events invisible from PHP code use the ref_count field. When the last owner releases the reference, dispose is called:

ZEND_ASYNC_EVENT_ADD_REF(ev)    // ++ref_count
ZEND_ASYNC_EVENT_DEL_REF(ev)    // --ref_count
ZEND_ASYNC_EVENT_RELEASE(ev)    // DEL_REF + dispose when reaching 0

Zend Object

A coroutine is a PHP object implementing the Awaitable interface. Instead of ref_count, they use the zend_object_offset field, which points to the offset of the zend_object structure.

The ZEND_ASYNC_EVENT_ADD_REF/ZEND_ASYNC_EVENT_RELEASE macros work correctly in all cases.

ZEND_ASYNC_EVENT_ADD_REF(ev)
    -> is_zend_obj ? GC_ADDREF(obj) : ++ref_count

ZEND_ASYNC_EVENT_RELEASE(ev)
    -> is_zend_obj ? OBJ_RELEASE(obj) : dispose(ev)

The zend_object is part of the event’s C structure and can be recovered using ZEND_ASYNC_EVENT_TO_OBJECT/ZEND_ASYNC_OBJECT_TO_EVENT.

// Get event from PHP object (accounting for event reference)
zend_async_event_t *ev = ZEND_ASYNC_OBJECT_TO_EVENT(obj);

// Get PHP object from event
zend_object *obj = ZEND_ASYNC_EVENT_TO_OBJECT(ev);

Event Reference

Some events face an architectural problem: they cannot be Zend objects directly.

For example, a timer. PHP GC may decide to collect the object at any moment, but libuv requires asynchronous handle closure via uv_close() with a callback. If GC calls the destructor while libuv hasn’t finished working with the handle, we get use-after-free.

In this case, the Event Reference approach is used: the PHP object stores not the event itself, but a pointer to it:

typedef struct {
    uint32_t flags;               // = ZEND_ASYNC_EVENT_REFERENCE_PREFIX
    uint32_t zend_object_offset;
    zend_async_event_t *event;    // Pointer to the actual event
} zend_async_event_ref_t;

With this approach, the lifetimes of the PHP object and the C event are independent. The PHP object can be collected by GC without affecting the handle, and the handle will close asynchronously when ready.

The ZEND_ASYNC_OBJECT_TO_EVENT() macro automatically recognizes a reference by the flags prefix and follows the pointer.

Callback System

Subscribing to events is the primary mechanism of interaction between coroutines and the outside world. When a coroutine wants to wait for a timer, data from a socket, or completion of another coroutine, it registers a callback on the corresponding event.

Each event stores a dynamic array of subscribers:

typedef struct {
    uint32_t length;
    uint32_t capacity;
    zend_async_event_callback_t **data;

    // Pointer to the active iterator index (or NULL)
    uint32_t *current_iterator;
} zend_async_callbacks_vector_t;

current_iterator solves the problem of safely removing callbacks during iteration.

Callback Structure

struct _zend_async_event_callback_s {
    uint32_t ref_count;
    zend_async_event_callback_fn callback;
    zend_async_event_callback_dispose_fn dispose;
};

A callback is also a ref-counted structure. This is necessary because a single callback can be referenced by both the event’s vector and the coroutine’s waker simultaneously. ref_count ensures that memory is freed only when both sides release their reference.

Coroutine Callback

Most callbacks in TrueAsync are used to wake up a coroutine. Therefore, they store information about the coroutine and the event they subscribed to:

struct _zend_coroutine_event_callback_s {
    zend_async_event_callback_t base;    // Inheritance
    zend_coroutine_t *coroutine;         // Who to wake
    zend_async_event_t *event;           // Where it came from
};

This binding is the foundation for the Waker mechanism:

Event Flags

Bit flags in the flags field control the event’s behavior at every stage of its lifecycle:

Deadlock Detection

TrueAsync tracks the number of active events in the EventLoop via active_event_count. When all coroutines are suspended and there are no active events – this is a deadlock: no event can wake any coroutine.

But some events are always present in the EventLoop and are unrelated to user logic: background healthcheck timers, system handlers. If they are counted as “active”, deadlock detection will never trigger.

For such events, the F_HIDDEN flag is used:

ZEND_ASYNC_EVENT_SET_HIDDEN(ev)     // Mark as hidden
ZEND_ASYNC_INCREASE_EVENT_COUNT(ev) // +1, but only if NOT hidden
ZEND_ASYNC_DECREASE_EVENT_COUNT(ev) // -1, but only if NOT hidden

Event Hierarchy

In C there is no class inheritance, but there is a technique: if the first field of a structure is zend_async_event_t, then a pointer to the structure can be safely cast to a pointer to zend_async_event_t. This is exactly how all specialized events “inherit” from the base:

zend_async_event_t
|-- zend_async_poll_event_t      -- fd/socket polling
|   \-- zend_async_poll_proxy_t  -- proxy for event filtering
|-- zend_async_timer_event_t     -- timers (one-shot and periodic)
|-- zend_async_signal_event_t    -- POSIX signals
|-- zend_async_process_event_t   -- waiting for process termination
|-- zend_async_thread_event_t    -- background threads
|-- zend_async_filesystem_event_t -- filesystem changes
|-- zend_async_dns_nameinfo_t    -- reverse DNS
|-- zend_async_dns_addrinfo_t    -- DNS resolution
|-- zend_async_exec_event_t      -- exec/system/passthru/shell_exec
|-- zend_async_listen_event_t    -- TCP server socket
|-- zend_async_trigger_event_t   -- manual wake-up (cross-thread safe)
|-- zend_async_task_t            -- thread pool task
|-- zend_async_io_t              -- unified I/O
|-- zend_coroutine_t             -- coroutine
|-- zend_future_t                -- future
|-- zend_async_channel_t         -- channel
|-- zend_async_group_t           -- task group
|-- zend_async_pool_t            -- resource pool
\-- zend_async_scope_t           -- scope

Thanks to this, a Waker can subscribe to any of these events with the same event->add_callback call, without knowing the specific type.

Examples of Specialized Structures

Each structure adds to the base event only those fields that are specific to its type:

Timer – minimal extension:

struct _zend_async_timer_event_s {
    zend_async_event_t base;
    unsigned int timeout;    // Milliseconds
    bool is_periodic;
};

Poll – I/O tracking on a descriptor:

struct _zend_async_poll_event_s {
    zend_async_event_t base;
    bool is_socket;
    union { zend_file_descriptor_t file; zend_socket_t socket; };
    async_poll_event events;           // What to track: READABLE|WRITABLE|...
    async_poll_event triggered_events; // What actually happened
};

Filesystem – filesystem monitoring:

struct _zend_async_filesystem_event_s {
    zend_async_event_t base;
    zend_string *path;
    unsigned int flags;                // ZEND_ASYNC_FS_EVENT_RECURSIVE
    unsigned int triggered_events;     // RENAME | CHANGE
    zend_string *triggered_filename;   // Which file changed
};

Exec – executing external commands:

struct _zend_async_exec_event_s {
    zend_async_event_t base;
    zend_async_exec_mode exec_mode;    // exec/system/passthru/shell_exec
    bool terminated;
    char *cmd;
    zval *return_value;
    zend_long exit_code;
    int term_signal;
};

Poll Proxy

Imagine a situation: two coroutines on a single TCP socket – one reading, the other writing. They need different events (READABLE vs WRITABLE), but the socket is one.

Poll Proxy solves this problem. Instead of creating two uv_poll_t handles for the same fd (which is impossible in libuv), a single poll_event is created along with several proxies with different masks:

struct _zend_async_poll_proxy_s {
    zend_async_event_t base;
    zend_async_poll_event_t *poll_event;  // Parent poll
    async_poll_event events;               // Event subset for this proxy
    async_poll_event triggered_events;     // What fired
};

The Reactor aggregates masks from all active proxies and passes the combined mask to uv_poll_start. When libuv reports an event, the Reactor checks each proxy and notifies only those whose mask matched.

Async IO

For stream I/O operations (reading from a file, writing to a socket, working with pipes), TrueAsync provides a unified handle:

struct _zend_async_io_s {
    zend_async_event_t event;
    union {
        zend_file_descriptor_t fd;   // For PIPE/FILE
        zend_socket_t socket;        // For TCP/UDP
    } descriptor;
    zend_async_io_type type;         // PIPE, FILE, TCP, UDP, TTY
    uint32_t state;                  // READABLE | WRITABLE | CLOSED | EOF | APPEND
};

The same ZEND_ASYNC_IO_READ/WRITE/CLOSE interface works with any type, and the specific implementation is selected at handle creation time based on type.

All I/O operations are asynchronous and return a zend_async_io_req_t – a one-shot request:

struct _zend_async_io_req_s {
    union { ssize_t result; ssize_t transferred; };
    zend_object *exception;    // Operation error (or NULL)
    char *buf;                 // Data buffer
    bool completed;            // Operation complete?
    void (*dispose)(zend_async_io_req_t *req);
};

A coroutine calls ZEND_ASYNC_IO_READ, receives a req, subscribes to its completion via the Waker, and goes to sleep. When libuv completes the operation, req->completed becomes true, the callback wakes the coroutine, and it retrieves data from req->buf.