ZigPC Common Observable

A Common Observable module allows components to maintain their list of observers without the need to set up the overhead to register, unregister, and notify observers. More...

Classes
struct	zigpc_observable_event_entry
struct	zigpc_observable
	Observable instance. More...

Macros
#define	ZIGPC_OBSERVER_EVENTS_MAX   20
	Maximum number of events supported by an observable instance. More...
#define	ZIGPC_OBSERVER_EVENT_CALLBACKS_MAX   5
	Maximum number of listeners per event supported by an observable instance. More...

Typedefs
typedef uint8_t	zigpc_observer_event_t
	Observer event type. More...
typedef void(*	zigpc_observer_callback_t) (void *data)
	Observer callback that is called by subjects when notifying observers of new events. More...

Functions
sl_status_t	zigpc_observable_notify (const struct zigpc_observable *observable, const zigpc_observer_event_t event, void *data)
	Inform Observers of observable instance of an event with data. More...
sl_status_t	zigpc_observable_register (struct zigpc_observable *observable, const zigpc_observer_event_t event, zigpc_observer_callback_t callback)
	Register an observer with a corresponding event to observable instance. More...
sl_status_t	zigpc_observable_unregister (struct zigpc_observable *observable, const zigpc_observer_event_t event, const zigpc_observer_callback_t callback)
	Unregister an observer with a corresponding event from observable instance. More...
sl_status_t	zigpc_observable_init (struct zigpc_observable *observable, const zigpc_observer_event_t *event_list, const uint8_t event_count)
	Initialize observable with an approved event list. More...
void	zigpc_observable_clear (struct zigpc_observable *observable)
	Stop all observers from being notified. More...

Detailed Description

A Common Observable module allows components to maintain their list of observers without the need to set up the overhead to register, unregister, and notify observers.

Observers are defined as callback functions (zigpc_observer_callback_t) invoked based on the event type it's registered with (zigpc_observer_event_t).

The Observable API uses the struct zigpc_observable to allow components(subjects) to store their own specific list of observers.

Example usage :

A component that wants to notify others should initialize the observer list. The component should also pass the list of events that can be allowed for observers to register with.

my_component:

struct struct zigpc_observable my_observable;
zigpc_observer_event_t my_observable_events [3] = {1, 5, 7};

zigpc_observable_init(&my_observable, my_observable_events, 3);


Now, my_component can use the Observable API to delegate observer management.

void my_component_register_observer(event, observer_cb) {
zigpc_observable_register(&my_observable, event, observer_cb);
}

void my_component_unregister_observer(event, observer_cb) {
zigpc_unregister_observer(&my_observable, event, observer_cb);
}


Now a user of my_component can register observer function(s) based on the event type that is desired.

other_component:

void other_component_event_5_cb(void* data);
void other_component_event_1_cb(void* data);

my_component_register_observer(5, other_component_event_5_cb);
my_component_register_observer(1, other_component_event_1_cb);


After this, other_component_event_5_cb() will be called whenever my_component notifies with event type 5.

other_component should de-register callbacks if the events are no longer to be received.

other_component:

my_component_unregister_observer(5, other_component_event_5_cb);
my_component_unregister_observer(1, other_component_event_1_cb);


To stop my_component from notifying of any events, call the clean API

my_component:

zigpc_unregister_clean(&my_observable);


Macro Definition Documentation

ZIGPC_OBSERVER_EVENT_CALLBACKS_MAX

#define ZIGPC_OBSERVER_EVENT_CALLBACKS_MAX   5

Maximum number of listeners per event supported by an observable instance.

ZIGPC_OBSERVER_EVENTS_MAX

#define ZIGPC_OBSERVER_EVENTS_MAX   20

Maximum number of events supported by an observable instance.

Typedef Documentation

zigpc_observer_callback_t

typedef void(* zigpc_observer_callback_t) (void *data)

Observer callback that is called by subjects when notifying observers of new events.

Parameters

event	Notify event
data	Notify data

zigpc_observer_event_t

typedef uint8_t zigpc_observer_event_t

Observer event type.

Function Documentation

zigpc_observable_clear()

void zigpc_observable_clear

(

struct zigpc_observable *

observable

)

Stop all observers from being notified.

Parameters

observable

Observable instance

Instead of clearing all events and callbacks associated with the events, the event_count field is cleared since the rest of the API use this field to manage the observers.

zigpc_observable_init()

sl_status_t zigpc_observable_init	(	struct zigpc_observable *	observable,
		const zigpc_observer_event_t *	event_list,
		const uint8_t	event_count
	)

Initialize observable with an approved event list.

NOTE: the event_list should have unique entries

Parameters

observable	Observable instance
event_list	Event list to register/unregister callbacks with
event_count	Length of event list

Returns

sl_status_t SL_STATUS_OK on success SL_STATUS_INVALID_PARAMETER on invalid observable instance or event_list SL_STATUS_WOULD_OVERFLOW if event_list cannot fit within observable instance SL_STATUS_INVALID_CONFIGURATION if event_list has duplicate entries

zigpc_observable_notify()

sl_status_t zigpc_observable_notify	(	const struct zigpc_observable *	observable,
		const zigpc_observer_event_t	event,
		void *	data
	)

Inform Observers of observable instance of an event with data.

Parameters

observable	Observable instance
event	Event to call registered callbacks
data	Data to provide to callbacks (Can be NULL)

Returns

sl_status_t SL_STATUS_OK on success SL_STATUS_INVALID_PARAMETER on invalid observable instance SL_STATUS_INVALID_TYPE if event is not registered

zigpc_observable_register()

sl_status_t zigpc_observable_register	(	struct zigpc_observable *	observable,
		const zigpc_observer_event_t	event,
		zigpc_observer_callback_t	callback
	)

Register an observer with a corresponding event to observable instance.

If the observer is already registered, nothing will be done.

Parameters

observable	Observable instance
event	Event to register callback with
callback	New observer callback to register

Returns

sl_status_t SL_STATUS_OK on success SL_STATUS_INVALID_PARAMETER on invalid observable instance or callback SL_STATUS_INVALID_TYPE if event is not approved

zigpc_observable_unregister()

sl_status_t zigpc_observable_unregister	(	struct zigpc_observable *	observable,
		const zigpc_observer_event_t	event,
		const zigpc_observer_callback_t	callback
	)

Unregister an observer with a corresponding event from observable instance.

If the observer is not found, nothing will be done.

Parameters

observable	Observable instance
event	Event callback is registered to
callback	Observer callback to register

Returns

sl_status_t SL_STATUS_OK on success SL_STATUS_INVALID_PARAMETER on invalid observable instance or callback SL_STATUS_INVALID_TYPE if event is not approved