Synopsys DWC Portability and Common Library for UWB: dwc

Any "module" can register as an observer or notifier. The notion of "module" is abstract and can mean anything used to identify either an observer or notifier. Usually it will be a pointer to a data structure which contains some state, ie an object.

Before any notifiers can be added, the global notification manager must be brought up with dwc_alloc_notification_manager(). dwc_free_notification_manager() will bring it down and free all resources. These would typically be called upon module load and unload. The notification manager is a single global instance that handles all registered observable modules and observers so this should be done only once.

A module can be observable by using Notifications to publicize some general information about it's state or operation. It does not care who listens, or even if anyone listens, or what they do with the information. The observable modules do not need to know any information about it's observers or their interface, or their state or data.

Any module can register to emit Notifications. It should publish a list of notifications that it can emit and their behavior, such as when they will get triggered, and what information will be provided to the observer. Then it should register itself as an observable module. See dwc_register_notifier().

Any module can observe any observable, registered module, provided it has a handle to the other module and knows what notifications to observe. See dwc_add_observer().

A function of type dwc_notifier_callback_t is called whenever a notification is triggered with one or more observers observing it. This function is called in it's own process so it may sleep or block if needed. It is guaranteed to be called sometime after the notification has occurred and will be called once per each time the notification is triggered. It will NOT be called in the same process context used to trigger the notification.

Limitiations

Also Notification callbacks are not synchronous. If you need to synchronize the behavior between module/observer you must use other means. And perhaps that will mean Notifications are not the proper solution.


Typedefs
typedef dwc_notifier	dwc_notifier_t
typedef void(*)	dwc_notifier_callback_t (void object, char notification, void observer, void notification_data, void *user_data)
	The callback function must be of this type.
Functions
void	dwc_alloc_notification_manager (void)
	Brings up the notification manager.
void	dwc_free_notification_manager (void)
	Brings down the notification manager.
dwc_notifier_t *	dwc_register_notifier (void *object)
	This function register an observable module.
void	dwc_unregister_notifier (dwc_notifier_t *notifier)
	This function unregister an observable module.
int	dwc_add_observer (void observer, void object, char notification, dwc_notifier_callback_t callback, void user_data)
	Add a module as an observer to the observable module.
int	dwc_remove_observer (void *observer)
	Removes the specified observer from all notifications that it is currently observing.
void	dwc_notify (dwc_notifier_t notifier, char notification, void *notification_data)
	This function triggers a Notification.

Typedef Documentation

typedef void(*) dwc_notifier_callback_t(void *object, char *notification, void *observer, void *notification_data, void *user_data)

The callback function must be of this type.

Parameters:

	object	This is the object that is being observed.
	notification	This is the notification that was triggered.
	observer	This is the observer
	notification_data	This is notification-specific data that the notifier has included in this notification. The value of this should be published in the documentation of the observable module with the notifications.
	user_data	This is any custom data that the observer provided when adding itself as an observer to the notification.

Function Documentation

void dwc_alloc_notification_manager ( void )

Brings up the notification manager.

void dwc_free_notification_manager ( void )

Brings down the notification manager.

dwc_notifier_t* dwc_register_notifier ( void * object )

This function register an observable module.

A dwc_notifier_t object is returned to the observable module. This is an opaque object that is used by the observable module to trigger notifications. This object should only be accessible to functions that are authorized to trigger notifications for this module. Observers do not need this object.

void dwc_unregister_notifier ( dwc_notifier_t * notifier )

This function unregister an observable module.

All observers have to be removed prior to unregistration.

int dwc_add_observer	(	void *	observer,
		void *	object,
		char *	notification,
		dwc_notifier_callback_t	callback,
		void *	user_data
	)

Add a module as an observer to the observable module.

The observable module needs to have previously registered with the notification manager.

Parameters:

	observer	The observer module
	object	The module to observe
	notification	The notification to observe
	callback	The callback function to call
	user_data	Any additional user data to pass into the callback function

int dwc_remove_observer ( void * observer )

Removes the specified observer from all notifications that it is currently observing.

void dwc_notify	(	dwc_notifier_t *	notifier,
		char *	notification,
		void *	notification_data
	)

This function triggers a Notification.

It should be called by the observable module, or any module or library which the observable module allows to trigger notification on it's behalf. Such as the dwc_cc_t.

dwc_notify is a non-blocking function. Callbacks are scheduled called in their own process context for each trigger. Callbacks can be blocking. dwc_notify can be called from interrupt context if needed.

dwc_notifier.h File Reference

Detailed Description

Limitiations

Typedefs

Functions

Typedef Documentation

Function Documentation