2 #ifndef __DWC_NOTIFIER_H__
3 #define __DWC_NOTIFIER_H__
13 * A simple implementation of the Observer pattern. Any "module" can
14 * register as an observer or notifier. The notion of "module" is abstract and
15 * can mean anything used to identify either an observer or notifier. Usually
16 * it will be a pointer to a data structure which contains some state, ie an
19 * Before any notifiers can be added, the global notification manager must be
20 * brought up with dwc_alloc_notification_manager().
21 * dwc_free_notification_manager() will bring it down and free all resources.
22 * These would typically be called upon module load and unload. The
23 * notification manager is a single global instance that handles all registered
24 * observable modules and observers so this should be done only once.
26 * A module can be observable by using Notifications to publicize some general
27 * information about it's state or operation. It does not care who listens, or
28 * even if anyone listens, or what they do with the information. The observable
29 * modules do not need to know any information about it's observers or their
30 * interface, or their state or data.
32 * Any module can register to emit Notifications. It should publish a list of
33 * notifications that it can emit and their behavior, such as when they will get
34 * triggered, and what information will be provided to the observer. Then it
35 * should register itself as an observable module. See dwc_register_notifier().
37 * Any module can observe any observable, registered module, provided it has a
38 * handle to the other module and knows what notifications to observe. See
41 * A function of type dwc_notifier_callback_t is called whenever a notification
42 * is triggered with one or more observers observing it. This function is
43 * called in it's own process so it may sleep or block if needed. It is
44 * guaranteed to be called sometime after the notification has occurred and will
45 * be called once per each time the notification is triggered. It will NOT be
46 * called in the same process context used to trigger the notification.
48 * @section Limitiations
50 * Keep in mind that Notifications that can be triggered in rapid sucession may
51 * schedule too many processes too handle. Be aware of this limitation when
52 * designing to use notifications, and only add notifications for appropriate
53 * observable information.
55 * Also Notification callbacks are not synchronous. If you need to synchronize
56 * the behavior between module/observer you must use other means. And perhaps
57 * that will mean Notifications are not the proper solution.
61 typedef struct dwc_notifier dwc_notifier_t;
63 /** The callback function must be of this type.
65 * @param object This is the object that is being observed.
66 * @param notification This is the notification that was triggered.
67 * @param observer This is the observer
68 * @param notification_data This is notification-specific data that the notifier
69 * has included in this notification. The value of this should be published in
70 * the documentation of the observable module with the notifications.
71 * @param user_data This is any custom data that the observer provided when
72 * adding itself as an observer to the notification. */
73 typedef void (*dwc_notifier_callback_t)(void *object, char *notification, void *observer,
74 void *notification_data, void *user_data);
76 /** Brings up the notification manager. */
77 extern int dwc_alloc_notification_manager(void *mem_ctx, void *wkq_ctx);
78 /** Brings down the notification manager. */
79 extern void dwc_free_notification_manager(void);
81 /** This function registers an observable module. A dwc_notifier_t object is
82 * returned to the observable module. This is an opaque object that is used by
83 * the observable module to trigger notifications. This object should only be
84 * accessible to functions that are authorized to trigger notifications for this
85 * module. Observers do not need this object. */
86 extern dwc_notifier_t *dwc_register_notifier(void *mem_ctx, void *object);
88 /** This function unregisters an observable module. All observers have to be
89 * removed prior to unregistration. */
90 extern void dwc_unregister_notifier(dwc_notifier_t *notifier);
92 /** Add a module as an observer to the observable module. The observable module
93 * needs to have previously registered with the notification manager.
95 * @param observer The observer module
96 * @param object The module to observe
97 * @param notification The notification to observe
98 * @param callback The callback function to call
99 * @param user_data Any additional user data to pass into the callback function */
100 extern int dwc_add_observer(void *observer, void *object, char *notification,
101 dwc_notifier_callback_t callback, void *user_data);
103 /** Removes the specified observer from all notifications that it is currently
105 extern int dwc_remove_observer(void *observer);
107 /** This function triggers a Notification. It should be called by the
108 * observable module, or any module or library which the observable module
109 * allows to trigger notification on it's behalf. Such as the dwc_cc_t.
111 * dwc_notify is a non-blocking function. Callbacks are scheduled called in
112 * their own process context for each trigger. Callbacks can be blocking.
113 * dwc_notify can be called from interrupt context if needed.
116 void dwc_notify(dwc_notifier_t *notifier, char *notification, void *notification_data);
122 #endif /* __DWC_NOTIFIER_H__ */