110 lines
2.8 KiB
Markdown
110 lines
2.8 KiB
Markdown
# Event System
|
|
|
|
Source: `src/dusk/event/`
|
|
|
|
## Overview
|
|
|
|
The event system is a simple publish-subscribe mechanism backed by
|
|
caller-owned static arrays. There is no heap allocation in the event
|
|
system itself -- the caller provides the backing storage.
|
|
|
|
## API
|
|
|
|
```c
|
|
typedef void (*eventcallback_t)(void *params, void *user);
|
|
|
|
typedef struct {
|
|
eventcallback_t *callbacks;
|
|
void **users;
|
|
size_t size;
|
|
uint32_t count;
|
|
} event_t;
|
|
```
|
|
|
|
### Initialise
|
|
|
|
```c
|
|
void eventInit(
|
|
event_t *event,
|
|
eventcallback_t *callbacks,
|
|
void **users,
|
|
size_t size
|
|
);
|
|
```
|
|
|
|
`callbacks` and `users` are caller-owned arrays of length `size`. Both
|
|
are zeroed by `eventInit`. `users` may be `NULL` if no subscriber needs
|
|
a user pointer.
|
|
|
|
### Subscribe / unsubscribe
|
|
|
|
```c
|
|
void eventSubscribe(event_t *event, eventcallback_t callback, void *user);
|
|
void eventUnsubscribe(event_t *event, eventcallback_t callback);
|
|
```
|
|
|
|
The same `(callback, user)` pair may only be subscribed once --
|
|
`eventSubscribe` asserts on a duplicate. `eventUnsubscribe` is a no-op
|
|
if the pair is not found. Unsubscribing uses swap-with-last to keep the
|
|
array packed; ordering is not preserved.
|
|
|
|
### Fire
|
|
|
|
```c
|
|
void eventInvoke(const event_t *event, void *params);
|
|
```
|
|
|
|
Calls every subscriber in registration order, passing `params` and
|
|
each subscriber's `user` pointer.
|
|
|
|
## Usage pattern
|
|
|
|
Declare the backing arrays alongside the event struct, typically as
|
|
struct fields or static variables:
|
|
|
|
```c
|
|
#define MY_EVENT_CAPACITY 4
|
|
|
|
typedef struct {
|
|
event_t onComplete;
|
|
eventcallback_t _completeCbs[MY_EVENT_CAPACITY];
|
|
void *_completeUsers[MY_EVENT_CAPACITY];
|
|
} mystate_t;
|
|
|
|
// Init:
|
|
eventInit(
|
|
&state.onComplete,
|
|
state._completeCbs,
|
|
state._completeUsers,
|
|
MY_EVENT_CAPACITY
|
|
);
|
|
|
|
// Publish:
|
|
eventInvoke(&state.onComplete, &someParams);
|
|
|
|
// Subscribe from outside:
|
|
eventSubscribe(&state.onComplete, myHandler, myUserPtr);
|
|
```
|
|
|
|
## Constraints
|
|
|
|
- Capacity is fixed at init time. Exceeding it is a runtime assertion.
|
|
- Subscriber order is not stable after an unsubscribe.
|
|
- `eventInvoke` is synchronous -- all callbacks run on the calling
|
|
thread before it returns.
|
|
- Do not subscribe or unsubscribe from inside a callback -- the array
|
|
may shift during iteration.
|
|
|
|
## Where events are used
|
|
|
|
| Subsystem | Event | Fires when |
|
|
|-----------|-------|-----------|
|
|
| `inputactiondata_t` | `onPressed`, `onReleased` | Action button state changes |
|
|
| `uitextbox_t` | `onPageComplete` | Typewriter scroll reveals the full page |
|
|
| `uitextbox_t` | `onLastPage` | Last page is fully scrolled |
|
|
| `uifullbox_t` | `onTransitionEnd` | Colour transition animation completes |
|
|
| `uiloading_t` | `onShow` / `onHide` | Loading indicator fade completes |
|
|
| Asset system | `assetbatch_t` callback | All entries in a batch reach LOADED/ERROR |
|
|
|
|
See `.claude/ui.md` for the UI event details.
|