From 525fa2c1f0e955455bed3fdb397aceb1e6e69a57 Mon Sep 17 00:00:00 2001
From: Martin Mares <mj@ucw.cz>
Date: Mon, 5 Jun 2000 12:19:12 +0000
Subject: Documented sockets, events and timers.

---
 lib/event.c | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

(limited to 'lib/event.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)
 {
-- 
cgit v1.2.3