event-driven
Runs the script once to register listeners, then sleeps on an event queue and runs the listener of each event. It requires ext-events.
Set "runtime": "event-driven" in extra.baremetal and composer require php-baremetal/ext-events. The runtime
requires that package: the build fails without it. It has no options of its own.
The PHP API (Events::listen(), every(), watch_gpio() and the rest) belongs to
ext-events; this page covers what the
runtime does around it.
Lifecycle
-
Step 1: The entry script runs
The whole file runs once. It registers listeners and starts sources (timers, GPIO watchers). If the script fails here, the program ends.
-
Step 2: The listener table freezes
When the script returns, the runtime freezes the listener table and creates the event queue if no source created it yet. Listeners can no longer be added.
-
Step 3: The runtime waits for events
It blocks on the queue with no timeout. The PHP task sleeps, so the CPU idles between events.
-
Step 4: Each event is delivered
Events are taken one at a time in arrival order and their listeners run on the PHP task, never two at once. Any
power_hold()left standing is released after each event.
The runtime never calls setup() or loop(). A long listener delays everything behind it, so keep listeners
short. The garbage collector runs every 256 events.
What delivers events
Sources never call PHP themselves: they post a message to the queue, and the runtime delivers it. With
ext-web installed, HTTP requests and
WebSocket frames arrive through the same queue, as events of a single long-lived PHP run. The
request-timeout option limits one such HTTP handler: PHP gets max_execution_time equal to it, and when it
is exceeded that is a fatal error, which stops the program.
How the program ends
The runtime waits for events for ever, so the program ends only when:
- a listener calls
exit():--- stopped: exit(N) ---; - a fatal error occurs,
max_execution_timeincluded:--- stopped: fatal error ---; - an uncaught exception leaves a listener and
on-errorisstop; - the script asked the board to restart or deep-sleep (
sys_restart(),sys_deep_sleep()); - the queue cannot be created: the runtime prints
phpbm: cannot create the event queueand the program ends (--- end ---).
Then the board waits restart-delay seconds and restarts; see Runtimes.
Errors
An uncaught exception in a listener stops the delivery of that event and follows on-error:
on-error |
Effect |
|---|---|
stop (default) |
The exception is reported as a fatal error and the program ends |
continue |
The exception is printed as a warning and the runtime goes on with the next event |
set_exception_handler() is honoured first. A fatal error always ends the program.
Power saving
With the power-save option on, the chip light-sleeps whenever every task waits, and this runtime waits on
the queue between events. Timers, interrupts and network activity wake it. power_hold() keeps it awake for
the length of one event. See Power saving and the
ext-events docs.
Example
07-event-driven/event-driven-hello: a timer event every second and a GPIO event on the BOOT
button.