Runtime system events

Guest code receives host/runtime events by polling with PBSysEventPoll.

Polling API

int32_t PBSysEventPoll(
    PBSysEvent* events,
    uint32_t eventsSize,
    uint64_t deadline,
    uint64_t deadlineLeeway);

eventsSize is a byte size, not event count.

Return behavior:

• > 0: number of events written.
• 0: timeout reached or no events available in non-blocking poll.
• < 0: PBSysErr.
• PBSysErr_END: current thread is stopping.
• PBSysErr_NO_MEM: buffer too small for even one event.

Deadlines

• deadline = UINT64_MAX: wait indefinitely.
• deadline = 0: non-blocking poll.
• deadlineLeeway: nanosecond tolerance for timeout scheduling.

Event layout

Each returned event starts with:

typedef struct PBSysEvent {
    uint16_t     size;
    uint16_t     type;     // PBSysEventType
    PBSysObjectId objectId;
} PBSysEvent;

size is variable by event kind. Iterate by bytes, not by fixed struct count.

Event kinds

Event type (PBSysEventType)	Struct payload
SIGNAL	PBSysSignalEvent
POINTER_ENTER, POINTER_LEAVE, POINTER_DOWN, POINTER_UP, POINTER_MOVE, POINTER_CANCEL	PBSysPointerEvent or PBSysPenPointerEvent when kind == PBSysPointerKind_PEN
SCROLL	PBSysScrollEvent
GESTURE_PAN, GESTURE_PINCH, GESTURE_ROTATE	PBSysGestureEvent
KEY_DOWN, KEY_UP	PBSysKeyboardEvent

PBSysEventSize_MAX defines upper bound for one event payload.

Typical event loop

uint8_t buf[4096];
for (;;) {
    int32_t n = PBSysEventPoll((PBSysEvent*)buf, sizeof(buf), UINT64_MAX, 0);
    if (n < 0) {
        if (n == PBSysErr_END) {
            break;
        }
        // handle error
        continue;
    }

    size_t off = 0;
    for (int32_t i = 0; i < n; i++) {
        PBSysEvent* ev = (PBSysEvent*)(buf + off);
        // dispatch by ev->type
        off += ev->size;
    }
}

See Types for field-level definitions and System calls for poll contract details.