Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-events

bm-ext MIT

Event bus: events, listeners, timer, pin and button sources. Core, every firmware requires it.

ext-events · Reference

Errors and limits

Every exception and warning ext-events raises, and the sizes behind them.

ext-events throws plain \Exception for runtime failures, \RuntimeException for a now() nested too deep, and the standard \ValueError / \TypeError for invalid arguments; it defines no exception classes of its own.

Exceptions

Message Thrown by Cause
Events::listen() must be called in setup(); the listener table is frozen afterwards Events::listen() event-driven runtime, after the top-level script returned.
every(): unknown class '...' or too many sources every() The class does not exist or cannot be instantiated (abstract class, interface, trait, enum), or the event source table (32 entries) is full.
every(): cannot start the timer every(), Timer::setPeriod() The platform could not create or start the timer (after setPeriod() the timer is left stopped).
Cannot directly construct Baremetal\Timer (\Error; the same for Baremetal\GpioWatch and Baremetal\Button) new A handle can only be returned by a function; the same for a PHP subclass of Baremetal\Source, with its own name.
Trying to clone an uncloneable object of class Baremetal\Timer (\Error; the same for Baremetal\GpioWatch and Baremetal\Button) clone A handle cannot be cloned.
Serialization of 'Baremetal\Timer' is not allowed (\Exception; the same for Baremetal\GpioWatch and Baremetal\Button) serialize() A handle cannot be serialized.
watch_gpio(): unknown class '...' or too many sources watch_gpio() As for every().
watch_gpios(): <Class> must extend Baremetal\PinEvent (\TypeError) watch_gpios() <Class> is the name passed, and it does not extend PinEvent.
watch_gpio(): $pin must be a GPIO number between 0 and 63 (\ValueError) watch_gpio() $pin is negative or above 63.
watch_gpios(): $pins must be a non-empty list of GPIO numbers (\ValueError) watch_gpios() $pins is empty, not a list, or holds something other than an integer from 0 to 63.
watch_gpios(): unknown class '...' or too many sources watch_gpios() As for every().
watch_button(): too many buttons watch_button() Four buttons are already watched.
watch_button(): unknown class '...' or too many sources watch_button() A class in $on does not exist or cannot be instantiated, or the source table is full.
events: the event pools could not be allocated every(), watch_gpio(), watch_gpios(), watch_button(), ext-i2c poll() with an event The event slots could not be allocated at boot (see below).
Events::now(): nested too deep (limit 8) (\RuntimeException) Events::now() A listener called now() with 8 now() deliveries already nested. It reaches the caller of that now().

\ValueError is thrown by watch_gpio() for a $pin outside 0 to 63 (watch_gpio(): $pin must be a GPIO number between 0 and 63), by watch_gpios() for an invalid $pins list, and by every() for $ms below 0.1 or NaN (every(): Argument #1 ($ms) must be at least 0.1) and above 4294967295 or INF (every(): Argument #1 ($ms) must be at most 4294967295); Timer::setPeriod() throws the same errors, with its own name (Baremetal\Timer::setPeriod(): Argument #1 ($ms) must be at least 0.1). \TypeError is thrown by Events::listen() for a listener that is not callable, and by Events::now() / Events::dispatch() for an argument that is not a Baremetal\Event.

Dropped events and warnings

Nothing is thrown for a dropped event. A source event that finds no free slot is dropped and counted for its class in Events::stats(); Events::dispatch() returns false (and counts it) when no slot is free or the cascade is deeper than 16. The first drop of each class prints one PHP warning, and so do the interrupt pool and the cascade, once each:

Warning When
events: dropped a <Class> event (no free small slot); further drops of <Class> are counted in Events::stats() The first drop of an event class (a source, dispatch(), an HTTP request or a WebSocket frame).
events: dropped an interrupt event (the interrupt pool is full); further drops are counted in Events::stats() The first watch_gpio() edge that found the 8 interrupt slots taken.
events: Events::dispatch() refused an event nested deeper than 16; further refusals are counted in Events::stats() The first dispatch() refused for the cascade depth.

Coalesced events are counted, never warned about. At boot, when the slots cannot be allocated, the firmware prints events: cannot allocate <n> <small|medium|large> event slots (<KB> KB): lower events-<class> (or the interrupt-pool variant) and the event sources throw.

Limits

Limit Value
Small event slots 64 (events-small, 8 to 65535), shared by every source, dispatch(), ext-i2c and ext-web
Medium / large event slots 16 / 8 (events-medium, events-large, 0 to 65535), for events with a payload
Interrupt slots (watch_gpio(), watch_gpios()) 8, shared by every pin; each pin of watch_gpios() counts as one watch_gpio()
Release reserve 4 small slots
dispatch() cascade 16 levels
now() nesting 8 levels
every() period 0.1 ms to 4294967295 ms, rounded to the microsecond. 0.1 ms is a floor, not a rate to aim for: each event costs a PHP call of tens of microseconds, so a timer faster than its listener coalesces (one tick waits at a time) or, with coalesce: false, runs out of slots and drops ticks
Event sources 32 entries, shared with ext-i2c sample events; one class used with both coalesce values takes two; watch_gpios() takes one entry per class, however many pins
Buttons (watch_button()) 4
Button sample period 10 ms
watch_gpio() debounce 200 ms per event class
watch_gpios() debounce 200 ms per pin
Garbage collection in event-driven every 256 events

The slot counts are package options of ext-events, set in extra.baremetal.options of the project composer.json (see Runtimes and delivery); the other limits are fixed in the extension. A timer, a pin watch or a button is paused with the stop() of its handle, and the button sampler of all buttons with button_sampling(); neither frees its entry in the tables above.

Related