summaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
Diffstat (limited to 'lib')
-rw-r--r--lib/Doc2
-rw-r--r--lib/event.c54
-rw-r--r--lib/resource.sgml10
3 files changed, 56 insertions, 10 deletions
diff --git a/lib/Doc b/lib/Doc
index 6367cd7..6be6250 100644
--- a/lib/Doc
+++ b/lib/Doc
@@ -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>