diff options
author | Thomas Martitz <kugel@rockbox.org> | 2014-03-14 23:15:16 +0100 |
---|---|---|
committer | Thomas Martitz <kugel@rockbox.org> | 2014-03-14 23:36:30 +0100 |
commit | 470989bd708d9a425dbbf2d83b8fcbd0a8d0f488 (patch) | |
tree | f3bef37bc0f8ff7da4beddad9903209ced1bc25a /firmware/export/events.h | |
parent | 50f0dd80d660b332a1739e07a630c2cef1b678c6 (diff) | |
download | rockbox-470989bd708d9a425dbbf2d83b8fcbd0a8d0f488.tar.gz rockbox-470989bd708d9a425dbbf2d83b8fcbd0a8d0f488.zip |
events: Rework event subsystem (add_event, send_event) to be more versatile.
add_event_ex is added that takes an extra user_data pointer. This pointer is
passed to the callback (add_event and add_event_ex have slightly different
callbacks types). All callbacks also get the event id passed. Events added
with add_event_ex must be removed with remove_event_ex because the user_data
pointer must match in addition to the callback pointer.
On the other add_event is simplified to omit the oneshort parameter which
was almost always false (still there with add_event_ex).
As a side effect the ata_idle_notify callbacks are changed as well, they
do not take a data parameter anymore which was always NULL anyway.
This commit also adds some documentation to events.h
Change-Id: I13e29a0f88ef908f175b376d83550f9e0231f772
Diffstat (limited to 'firmware/export/events.h')
-rw-r--r-- | firmware/export/events.h | 69 |
1 files changed, 61 insertions, 8 deletions
diff --git a/firmware/export/events.h b/firmware/export/events.h index 859901c0b4..fd7f9df42e 100644 --- a/firmware/export/events.h +++ b/firmware/export/events.h | |||
@@ -23,12 +23,24 @@ | |||
23 | #define _EVENTS_H | 23 | #define _EVENTS_H |
24 | 24 | ||
25 | #include <stdbool.h> | 25 | #include <stdbool.h> |
26 | |||
27 | /** Only CLASS defines and firmware/ level events should be defined here. | ||
28 | * apps/ level events are defined in apps/appevents.h | ||
29 | */ | ||
30 | |||
31 | /** | 26 | /** |
27 | * Synchronouos event system. | ||
28 | * | ||
29 | * Callbacks are subscribed with add_event() or add_event_ex(). events | ||
30 | * are fired using send_event(). | ||
31 | * | ||
32 | * Events are always dispatched synchronously: the callbacks are called | ||
33 | * in the thread context of the event sender, without context switch. This | ||
34 | * also means that callbacks should be as simple as possible to avoid | ||
35 | * blocking the sender and other callbacks | ||
36 | * | ||
37 | * Use the kernel-level event_queue for cross-thread event dispatching. | ||
38 | * */ | ||
39 | |||
40 | /* | ||
41 | * Only CLASS defines and firmware/ level events should be defined here. | ||
42 | * apps/ level events are defined in apps/appevents.h | ||
43 | * | ||
32 | * High byte = Event class definition | 44 | * High byte = Event class definition |
33 | * Low byte = Event ID | 45 | * Low byte = Event ID |
34 | */ | 46 | */ |
@@ -40,9 +52,50 @@ | |||
40 | #define EVENT_CLASS_RECORDING 0x1000 | 52 | #define EVENT_CLASS_RECORDING 0x1000 |
41 | #define EVENT_CLASS_LCD 0x2000 | 53 | #define EVENT_CLASS_LCD 0x2000 |
42 | 54 | ||
43 | bool add_event(unsigned short id, bool oneshot, void (*handler)(void *data)); | 55 | /** |
44 | void remove_event(unsigned short id, void (*handler)(void *data)); | 56 | * Subscribe to an event with a simple callback. The callback will be called |
57 | * synchronously everytime the event fires, passing the event id and data to | ||
58 | * the callback. | ||
59 | * | ||
60 | * Must be removed with remove_event(). | ||
61 | */ | ||
62 | bool add_event(unsigned short id, void (*handler)(unsigned short id, void *event_data)); | ||
63 | |||
64 | /** | ||
65 | * Subscribe to an event with a detailed callback. The callback will be called | ||
66 | * synchronously everytime the event fires, passing the event id and data, as | ||
67 | * well as the user_data pointer passed here, to the callback. | ||
68 | * | ||
69 | * With oneshot == true, the callback is unsubscribed automatically after | ||
70 | * the event fired for the first time. In this case the event need not to be | ||
71 | * removed with remove_event_ex(). | ||
72 | * | ||
73 | * Must be removed with remove_event_ex(). remove_event() will never remove | ||
74 | * events added with this function. | ||
75 | */ | ||
76 | bool add_event_ex(unsigned short id, bool oneshot, void (*handler)(unsigned short id, void *event_data, void *user_data), void *user_data); | ||
77 | |||
78 | /** | ||
79 | * Unsubscribe a callback from an event. The handler pointer is matched. | ||
80 | * | ||
81 | * This will only work for subscriptions made with add_event(). | ||
82 | */ | ||
83 | void remove_event(unsigned short id, void (*handler)(unsigned short id, void *data)); | ||
84 | |||
85 | /** | ||
86 | * Unsubscribe a callback from an event. The handler and user_data pointers | ||
87 | * are matched. That means the same user_data that was passed to add_event_ex() | ||
88 | * must be passed to this too. | ||
89 | * | ||
90 | * This will only work for subscriptions made with add_event_ex(). | ||
91 | */ | ||
92 | void remove_event_ex(unsigned short id, void (*handler)(unsigned short id, void *event_data, void *user_data), void *user_data); | ||
93 | |||
94 | /** | ||
95 | * Fire an event, which synchronously calls all subscribed callbacks. The | ||
96 | * event id and data pointer are passed to the callbacks as well, and | ||
97 | * optionally the user_data pointer from add_event_ex(). | ||
98 | */ | ||
45 | void send_event(unsigned short id, void *data); | 99 | void send_event(unsigned short id, void *data); |
46 | 100 | ||
47 | #endif | 101 | #endif |
48 | |||