Event service

Fans out kernel events to the tasks subscribed to them. More...

Typedefs
typedef void(*	EventServiceAddSubscriberCallback) (PebbleTask task)
	Called on KernelMain when a task subscribes to an event type.
typedef void(*	EventServiceRemoveSubscriberCallback) (PebbleTask task)
	Called on KernelMain when a task unsubscribes from an event type.

Functions
void	event_service_system_init (void)
	Initialize the event service, once during system startup.
void	event_service_init (PebbleEventType type, EventServiceAddSubscriberCallback start_cb, EventServiceRemoveSubscriberCallback stop_cb)
	Register an event type and its subscriber callbacks.
bool	event_service_is_running (PebbleEventType event_type)
	Check whether an event type has subscribers.
void	event_service_handle_event (PebbleEvent *e)
	Deliver an event to its subscribers.
void	event_service_subscribe_from_kernel_main (PebbleSubscriptionEvent *subscription)
	Subscribe to an event type on behalf of a task.
void	event_service_handle_subscription (PebbleSubscriptionEvent *subscription)
	Handle a subscription or unsubscription event.
void	event_service_clear_process_subscriptions (PebbleTask task)
	Remove all subscriptions of a task.
void *	event_service_claim_buffer (PebbleEvent *e)
	Claim the heap buffer of an event so it is not freed with the event.
void	event_service_free_claimed_buffer (void *ref)
	Release a buffer claimed with event_service_claim_buffer().
bool	event_service_is_known_buffer (const void *buf)
	Check whether a buffer is tracked by the event service.

Detailed Description

Fans out kernel events to the tasks subscribed to them.

Tasks subscribe to event types through the applib event service client, which posts subscription events to KernelMain. KernelMain then passes every event it handles to event_service_handle_event(), which copies it to the queue of each subscribed task and handles it inline when the current task is subscribed.

Kernel services that produce an event type can register callbacks to start and stop the underlying hardware or work as subscribers come and go:

static void prv_start(PebbleTask task) {
  // first or additional subscriber: enable the sensor
}
 
static void prv_stop(PebbleTask task) {
  // subscriber gone: disable the sensor if it was the last one
}
 
void my_service_init(void) {
  event_service_init(PEBBLE_COMPASS_DATA_EVENT, prv_start, prv_stop);
}

Events carrying a heap buffer keep it alive until every recipient task has processed the event. A recipient that needs the buffer for longer claims it with event_service_claim_buffer() and later releases it with event_service_free_claimed_buffer().

Typedef Documentation

EventServiceAddSubscriberCallback

typedef void(* EventServiceAddSubscriberCallback) (PebbleTask task)

Called on KernelMain when a task subscribes to an event type.

Parameters

task	Subscribing task.

EventServiceRemoveSubscriberCallback

typedef void(* EventServiceRemoveSubscriberCallback) (PebbleTask task)

Called on KernelMain when a task unsubscribes from an event type.

Parameters

task	Unsubscribing task.

Function Documentation

event_service_claim_buffer()

void * event_service_claim_buffer

(

PebbleEvent *

e

)

Claim the heap buffer of an event so it is not freed with the event.

Only one claim per buffer is supported.

Parameters

e	Event whose buffer is claimed.

Returns

Reference to pass to event_service_free_claimed_buffer(), or NULL if the event has no tracked buffer or it is already claimed.

event_service_clear_process_subscriptions()

void event_service_clear_process_subscriptions

(

PebbleTask

task

)

Remove all subscriptions of a task.

Parameters

task	Task whose subscriptions are removed, e.g. an exiting process.

event_service_free_claimed_buffer()

void event_service_free_claimed_buffer

(

void *

ref

)

Release a buffer claimed with event_service_claim_buffer().

The buffer is freed once no recipient task still needs it.

Parameters

ref	Reference returned by event_service_claim_buffer(), or NULL.

event_service_handle_event()

void event_service_handle_event

(

PebbleEvent *

e

)

Deliver an event to its subscribers.

Called from the KernelMain event loop. Tasks masked out by the event's task mask are skipped. If a subscriber's queue is full, non-release builds close an unprivileged app or worker and assert otherwise.

Parameters

e	Event to deliver.

event_service_handle_subscription()

void event_service_handle_subscription

(

PebbleSubscriptionEvent *

subscription

)

Handle a subscription or unsubscription event.

Called from the KernelMain event loop.

Parameters

subscription

Subscription to add or remove.

event_service_init()

void event_service_init	(	PebbleEventType	type,
		EventServiceAddSubscriberCallback	start_cb,
		EventServiceRemoveSubscriberCallback	stop_cb
	)

Register an event type and its subscriber callbacks.

Called by kernel services producing type, typically at their initialization. Registering again replaces the previous registration and drops its subscribers. Event types without a registration get one without callbacks on first subscription.

Parameters

type	Event type.
start_cb	Called when a task subscribes, or NULL.
stop_cb	Called when a task unsubscribes, or NULL.

event_service_is_known_buffer()

bool event_service_is_known_buffer

(

const void *

buf

)

Check whether a buffer is tracked by the event service.

True for kernel-allocated buffers attached to an in-flight event. Syscalls that dereference an event's embedded data pointer use it to reject pointers fabricated by the caller.

Parameters

buf	Buffer to check.

Returns

true if buf is a tracked event buffer.

event_service_is_running()

bool event_service_is_running

(

PebbleEventType

event_type

)

Check whether an event type has subscribers.

Parameters

event_type

Event type.

Returns

true if at least one task is subscribed.

event_service_subscribe_from_kernel_main()

void event_service_subscribe_from_kernel_main

(

PebbleSubscriptionEvent *

subscription

)

Subscribe to an event type on behalf of a task.

Must be called from KernelMain.

Parameters

subscription

Subscription to add.

event_service_system_init()

void event_service_system_init

(

void

)

Initialize the event service, once during system startup.