document thread functions

svn:r688

diff --git a/Doxyfile b/Doxyfile
index b6df8512774684779484deb7994b177dc2854512..f3840a544c444e4614a27b54df429c638f4a23cd 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -55,7 +55,7 @@ SORT_BRIEF_DOCS        = YES
 # with spaces.
 
 INPUT                  = event.h evdns.h evhttp.h evrpc.h \
-                      include/event2/buffer.h
+                      include/event2/buffer.h include/event2/thread.h
 
 #---------------------------------------------------------------------------
 # configuration options related to the HTML output

diff --git a/include/event2/thread.h b/include/event2/thread.h
index 7680ff175938d29e8b8d0b70688755c4dde319b7..f49dd27a11c4f5b3d4d1d104ee315ac0ce79b7db 100644 (file)
--- a/include/event2/thread.h
+++ b/include/event2/thread.h
@@ -28,6 +28,26 @@
 #define _EVENT2_THREAD_H_
 
 /** @file thread.h
+    
+  Functions for multi-threaded applications using libevent.
+
+  When using a multi-threaded application in which multiple threads
+  add and delete events from a single event base, libevent needs to
+  lock its data structures.
+
+  A multi-threaded application must provide locking functions to
+  libevent via evthread_set_locking_callback().  Libevent will invoke
+  this callback whenever a lock needs to be acquired or released.
+
+  The total number of locks employed by libevent can be determined
+  via the evthread_num_locks() function.  An application must provision
+  that many locks.
+
+  If the owner of an event base is waiting for events to happen,
+  libevent may signal the thread via a special file descriptor to wake
+  up.   To enable this feature, an application needs to provide a
+  thread identity function via evthread_set_id_callback().
+
  */
 
 #ifdef __cplusplus
@@ -42,12 +62,32 @@ extern "C" {
 #define EVTHREAD_WRITE 0x04
 #define EVTHREAD_READ  0x08
 
-/** returns the number of locks that need to be allocated */
+/**
+   returns the number of locks that need to be allocated
+
+   @return the number of locks required by libevent
+*/
 int evthread_num_locks();
 
 struct event_base;
+/**
+   Sets the function libevent should use for locking.
+
+   @param base the event base for which the locking function should be set
+   @param locking_fn the function that libevent should invoke to acquire
+     or release a lock.  mode has either EVTHREAD_LOCK or EVTHREAD_UNLOCK
+     set, and in addition, either EVHTREAD_WRITE or EVTREAD_READ.
+ */
 void evthread_set_locking_callback(struct event_base *base,
     void (*locking_fn)(int mode, int locknum));
+
+/**
+   Sets the function for derminting the thread id.
+
+   @param base the event base for which to set the id function
+   @param id_fn the identify function libevent should invoke to
+     determine the identity of a thread.
+*/
 void evthread_set_id_callback(struct event_base *base,
     unsigned long (*id_fn)(void));