diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/Doc | 2 | ||||
| -rw-r--r-- | lib/event.c | 54 | ||||
| -rw-r--r-- | lib/resource.sgml | 10 |
3 files changed, 56 insertions, 10 deletions
@@ -6,5 +6,5 @@ D resource.sgml S resource.c S mempool.c S slab.c -S socket.h S event.c +S ../sysdep/unix/io.c diff --git a/lib/event.c b/lib/event.c index 1f418d2..788aab4 100644 --- a/lib/event.c +++ b/lib/event.c @@ -6,6 +6,21 @@ * Can be freely distributed and used under the terms of the GNU GPL. */ +/** + * DOC: Events + * + * Events are there to keep track of deferred execution. + * Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller + * parts, so that no module can monopolize the CPU. To split such a task, just create + * an &event resource, point it to the function you want to have called and call ev_schedule() + * to ask the core to run the event when nothing more important will require attention. + * + * You can also define your own event lists (the &event_list structure), enqueue your + * events in them and explicitly ask to run them. + * + * The actual implementation is system dependent. + */ + #include "nest/bird.h" #include "lib/event.h" @@ -39,6 +54,13 @@ static struct resclass ev_class = { ev_dump }; +/** + * ev_new - create a new event + * @p: resource pool + * + * This function creates a new event resource. To use it, + * you need to fill the structure fields and call ev_schedule(). + */ event * ev_new(pool *p) { @@ -50,6 +72,16 @@ ev_new(pool *p) return e; } +/** + * ev_run - run an event + * @e: an event + * + * This function explicitly runs the event @e (calls its hook + * function) and removes it from an event list if it's linked to any. + * + * From the hook function, you can call ev_enqueue() or ev_schedule() + * to re-add the event. + */ inline void ev_run(event *e) { @@ -57,6 +89,14 @@ ev_run(event *e) e->hook(e->data); } +/** + * ev_enqueue - enqueue an event + * @l: an event list + * @e: an event + * + * ev_enqueue() stores the event @e to the specified event + * list @l which can be run by calling ev_run_list(). + */ inline void ev_enqueue(event_list *l, event *e) { @@ -64,12 +104,26 @@ ev_enqueue(event_list *l, event *e) add_tail(l, &e->n); } +/** + * ev_schedule - schedule an event + * @e: an event + * + * This function schedules an event by enqueueing it to a system-wide + * event list which is run by the platform dependent code whenever + * appropriate. + */ void ev_schedule(event *e) { ev_enqueue(&global_event_list, e); } +/** + * ev_run_list - run an event list + * @l: an event list + * + * This function calls ev_run() for all events enqueued in the list @l. + */ int ev_run_list(event_list *l) { diff --git a/lib/resource.sgml b/lib/resource.sgml index 4123dd6..df02bbf 100644 --- a/lib/resource.sgml +++ b/lib/resource.sgml @@ -36,15 +36,7 @@ type. <item><it/Memory blocks/ <item><it/Linear memory pools/ (<struct/linpool/) <item><it/Slabs/ (<struct/slab/) -<item><it/Sockets/ (<struct/socket/) <item><it/Events/ (<struct/event/) -<!-- - are there to keep track of deferred execution. - Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller - parts, so that no module can monopolize the CPU. To split such a task, just create - an <struct/event/ resource, point it to the function you want to have called and call <func/ev_schedule()/ - to ask the core to run the event when nothing more important will require attention. - The actual implementation is system dependent. ---> <item><it/Timers/ (<struct/timer/) +<item><it/Sockets/ (<struct/socket/) </itemize> |