summaryrefslogtreecommitdiffstats
path: root/lib/event.c
diff options
context:
space:
mode:
authorMartin Mares <mj@ucw.cz>2000-06-05 14:19:12 +0200
committerMartin Mares <mj@ucw.cz>2000-06-05 14:19:12 +0200
commit525fa2c1f0e955455bed3fdb397aceb1e6e69a57 (patch)
tree132508eaa88ce0328a984f7544413a398f7661bb /lib/event.c
parent10304bed435034cf8432b1c6262f7e7f0d84d49c (diff)
downloadbird-525fa2c1f0e955455bed3fdb397aceb1e6e69a57.tar
bird-525fa2c1f0e955455bed3fdb397aceb1e6e69a57.zip
Documented sockets, events and timers.
Diffstat (limited to 'lib/event.c')
-rw-r--r--lib/event.c54
1 files changed, 54 insertions, 0 deletions
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)
{