1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
#ifndef __DWC_NOTIFIER_H__
#define __DWC_NOTIFIER_H__
#ifdef __cplusplus
extern "C" {
#endif
#include "dwc_os.h"
/** @file
*
* A simple implementation of the Observer pattern. 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.
*
* @section Limitiations
*
* Keep in mind that Notifications that can be triggered in rapid sucession may
* schedule too many processes too handle. Be aware of this limitation when
* designing to use notifications, and only add notifications for appropriate
* observable information.
*
* 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.
*/
struct dwc_notifier;
typedef struct dwc_notifier dwc_notifier_t;
/** The callback function must be of this type.
*
* @param object This is the object that is being observed.
* @param notification This is the notification that was triggered.
* @param observer This is the observer
* @param 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.
* @param user_data This is any custom data that the observer provided when
* adding itself as an observer to the notification. */
typedef void (*dwc_notifier_callback_t)(void *object, char *notification, void *observer,
void *notification_data, void *user_data);
/** Brings up the notification manager. */
extern int dwc_alloc_notification_manager(void *mem_ctx, void *wkq_ctx);
/** Brings down the notification manager. */
extern void dwc_free_notification_manager(void);
/** This function registers 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. */
extern dwc_notifier_t *dwc_register_notifier(void *mem_ctx, void *object);
/** This function unregisters an observable module. All observers have to be
* removed prior to unregistration. */
extern void dwc_unregister_notifier(dwc_notifier_t *notifier);
/** Add a module as an observer to the observable module. The observable module
* needs to have previously registered with the notification manager.
*
* @param observer The observer module
* @param object The module to observe
* @param notification The notification to observe
* @param callback The callback function to call
* @param user_data Any additional user data to pass into the callback function */
extern int dwc_add_observer(void *observer, void *object, char *notification,
dwc_notifier_callback_t callback, void *user_data);
/** Removes the specified observer from all notifications that it is currently
* observing. */
extern int dwc_remove_observer(void *observer);
/** 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.
*
*/
void dwc_notify(dwc_notifier_t *notifier, char *notification, void *notification_data);
#ifdef __cplusplus
}
#endif
#endif /* __DWC_NOTIFIER_H__ */
|
