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/Doc           |  2 +-
 lib/event.c       | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 lib/resource.sgml | 10 +---------
 3 files changed, 56 insertions(+), 10 deletions(-)

(limited to 'lib')

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>
-- 
cgit v1.2.3