Event-Based Programming on the CE

EVENTLIB is a specialty library designed for integration with the TI-84+ CE toolchain that allows developers to easily implement event-based programming into their projects without needing to worry about low-level implementation details. It also allows for bugfixes, feature additions, and changes to be pushed to the library usually without requiring developers to rebuild their projects.

If this is your first introduction to the CE Toolchain, check out the toolchain repository and familiarize yourself with how it works.

API Documentation

#include <eventlib.h>
enum _ev_flags

Defines flags that can be passed to ev_register.

Values:

enumerator EV_WATCHER_ENABLE = 0b1

Enables the watcher upon registration, eliminating need for ev_watch.

enumerator EV_WATCHER_NOENABLE = 0

Does not enable watcher upon registration, ev_watch needed to enable.

enumerator EV_DISABLE_AFTER_RUN = 0b10

Disables watcher for this event binding upon callback completion.

enumerator EV_PERSIST_AFTER_RUN = 0

Persist the watcher for this event binding upon callback completion.

bool ev_Setup(void *(*malloc)(size_t), void (*free)(void*))

Initialzes the events system, allocates an array of structs for registered events, and saves pointer to malloc/free.

Parameters

  • malloc – Pointer to toolchain malloc function.

  • free – Pointer to toolchain free function.

Returns

Returns status of events initialization.

event_t ev_RegisterEvent(uint8_t event_id, uint8_t ev_flags, void (*callback)(void*, size_t), void *callback_data, size_t callback_data_len)

Registers an event callback bound to a specific event ID, registers any associated data.

Note

Functions compatible with this API should bear the following signature: 

void function(void* data, size_t len);

Note

It is possible to register multiple callbacks to the same event by calling register with the same event_id and different callback parameters.

Note

This function passes the data by copy, not by reference, as there is no way to ensure the data is in scope at the time the event callback would trigger. malloc is used to allocate a buffer for a copy of the callback data and that pointer is placed into the event metadata.

Parameters

  • event_id – Event identifier to bind.

  • ev_flags – Bitwise OR of event flags (see _ev_flags).

  • callback – Pointer to function to execute if event is triggered.

  • callback_data – Pointer to data that should be passed to the callback.

  • callback_data_len – Length of data that should be passed to the callback.

Returns

Slot number to which event is bound (for use with unregister and edit callbacks), or -1 for failure.

bool ev_UnregisterEvent(event_t ev_slot)

Deletes a specific event registration by slot number.

Parameters

ev_slot – Event registration to delete.

Returns

Returns status of deletion.

void ev_PurgeEvent(uint8_t event_id, uint8_t count)

Purges up to count bindings for an event, starting from the earliest.

Parameters

  • event_id – Event identifier to delete binding(s) for.

  • count – Maximum number of bindings to delete.

bool ev_UpdateCallbacks(event_t ev_slot, void (*callback)(void*, size_t), void *callback_data, size_t callback_data_len, void *(*realloc)(void*, size_t))

Updates the callback info for the specific event registration.

Note

Reallocation occurs if passed memory block differs in size from existing block.

Note

Old callback data is always overwritten with new data if data and length are non-NULL.

Parameters

  • ev_slot – Event registration to update.

  • callback – Pointer to new callback function, or NULL to not update.

  • callback_data – Pointer to new data to provide to callback, or NULL for no data.

  • callback_data_len – Length of new data to update, or 0 for no data.

  • realloc – Pointer to toolchain realloc function used to perform any reallocation.

Returns

Returns status of callback update.

void ev_Watch(uint8_t event_id)

Enables watchers for an event ID.

Note

If ev_register is called with enable_watcher=True, you do not need to call this function.

Note

Enabling a watcher only affects events of that type registered up until this point. If you register new events of the same type you must pass them with the EV_WATCHER_ENABLE flag or call this function again.

Parameters

event_id – Event ID to enable watchers for.

void ev_Unwatch(uint8_t event_id)

Disables watchers for an event ID.

Parameters

event_id – Event ID to disable watchers for.

void ev_Trigger(uint8_t event_id)

Triggers event by ID.

Note

The event will not trigger if watching is not enabled for this event.

Parameters

event_id – Informs watcher that indicated event occurred.

void ev_HandleEvents(void)

Polls all event watchers and executes callbacks for any events that have occurred.

void ev_Cleanup(void)

Cleans up all allocated callback_data blocks.