More documentation for finalization feature

diff --git a/bufferevent-internal.h b/bufferevent-internal.h
index 09cdb35166bd4becde85d48c3103267d737d4222..9ecede179a8de7832e7d3a77bda3e6c95538b392 100644 (file)
--- a/bufferevent-internal.h
+++ b/bufferevent-internal.h
@@ -252,11 +252,13 @@ struct bufferevent_ops {
         */
        int (*disable)(struct bufferevent *, short);
 
-       /** DOCUMENT */
+       /** Detatches the bufferevent from related data structures. Called as
+        * soon as its reference count reaches 0. */
        void (*unlink)(struct bufferevent *);
 
        /** Free any storage and deallocate any extra data or structures used
-           in this implementation. DOCUMENT
+           in this implementation. Called when the bufferevent is
+           finalized.
         */
        void (*destruct)(struct bufferevent *);
 

diff --git a/bufferevent_openssl.c b/bufferevent_openssl.c
index 48c61c086ad0c40978dcd58315a85d06f4ab401d..1ce124f938b8ccc8cd2a872252b88704de71b4cb 100644 (file)
--- a/bufferevent_openssl.c
+++ b/bufferevent_openssl.c
@@ -1193,8 +1193,8 @@ be_openssl_unlink(struct bufferevent *bev)
                                    "bufferevent with too few references");
                        } else {
                                bufferevent_free(bev_ssl->underlying);
-                               /* We still have a reference to it, since DOCUMENT. So we don't
-                                * drop this. */
+                               /* We still have a reference to it, via our
+                                * BIO. So we don't drop this. */
                                // bev_ssl->underlying = NULL;
                        }
                }

diff --git a/event-internal.h b/event-internal.h
index 07d29e3291665ff3c17432086fd0f8229e5b4377..bce96df518f6ed309e52b46b36f45ae437f23762 100644 (file)
--- a/event-internal.h
+++ b/event-internal.h
@@ -59,15 +59,28 @@ extern "C" {
 #define ev_callback ev_evcallback.evcb_cb_union.evcb_callback
 #define ev_arg ev_evcallback.evcb_arg
 
-/* Possible values for evcb_closure in struct event_callback */
-/* DOCUMENT these. */
+/** @name Event closure codes
+
+    Possible values for evcb_closure in struct event_callback
+
+    @{
+ */
+/** A regular event. Uses the evcb_callback callback */
 #define EV_CLOSURE_EVENT 0
+/** A signal event. Uses the evcb_callback callback */
 #define EV_CLOSURE_EVENT_SIGNAL 1
+/** A persistent non-signal event. Uses the evcb_callback callback */
 #define EV_CLOSURE_EVENT_PERSIST 2
+/** A simple callback. Uses the evcb_selfcb callback. */
 #define EV_CLOSURE_CB_SELF 3
+/** A finalizing callback. Uses the evcb_cbfinalize callback. */
 #define EV_CLOSURE_CB_FINALIZE 4
+/** A finalizing event. Uses the evcb_evfinalize callback. */
 #define EV_CLOSURE_EVENT_FINALIZE 5
+/** A finalizing event that should get freed after. Uses the evcb_evfinalize
+ * callback. */
 #define EV_CLOSURE_EVENT_FINALIZE_FREE 6
+/** @} */
 
 /** Structure to define the backend of a given event_base. */
 struct eventop {
@@ -386,9 +399,19 @@ int evsig_restore_handler_(struct event_base *base, int evsignal);
 
 int event_add_nolock_(struct event *ev,
     const struct timeval *tv, int tv_is_absolute);
+/** Argument for event_del_nolock_. Tells event_del not to block on the event
+ * if it's running in another thread. */
 #define EVENT_DEL_NOBLOCK 0
+/** Argument for event_del_nolock_. Tells event_del to block on the event
+ * if it's running in another thread, regardless of its value for EV_FINALIZE
+ */
 #define EVENT_DEL_BLOCK 1
+/** Argument for event_del_nolock_. Tells event_del to block on the event
+ * if it is running in another thread and it doesn't have EV_FINALIZE set.
+ */
 #define EVENT_DEL_AUTOBLOCK 2
+/** Argument for event_del_nolock_. Tells event_del to procede even if the
+ * event is set up for finalization rather for regular use.*/
 #define EVENT_DEL_EVEN_IF_FINALIZING 3
 int event_del_nolock_(struct event *ev, int blocking);
 int event_remove_timer_nolock_(struct event *ev);

diff --git a/event.c b/event.c
index 0722fad56676030c0a66a0c50792f772830bfb10..6b8c3c5b2a033782e4704f73f22dbe4ef031e7b0 100644 (file)
--- a/event.c
+++ b/event.c
@@ -2599,8 +2599,11 @@ event_del_noblock(struct event *ev)
        return event_del_(ev, EVENT_DEL_NOBLOCK);
 }
 
-/* Helper for event_del: always called with th_base_lock held.
- * DOCUMENT blocking */
+/** Helper for event_del: always called with th_base_lock held.
+ *
+ * "blocking" must be one of the EVENT_DEL_{BLOCK, NOBLOCK, AUTOBLOCK,
+ * EVEN_IF_FINALIZING} values. See those for more information.
+ */
 int
 event_del_nolock_(struct event *ev, int blocking)
 {

diff --git a/include/event2/event.h b/include/event2/event.h
index 3dfce3773a21201c80b798dc5430c629e9544578..4a63765cefecf7e3eb15560dba5b89a632d88cb4 100644 (file)
--- a/include/event2/event.h
+++ b/include/event2/event.h
@@ -599,12 +599,16 @@ struct event_base *event_base_new_with_config(const struct event_config *);
   Note that this function will not close any fds or free any memory passed
   to event_new as the argument to callback.
 
+  If there are any pending finalizer callbacks, this function will invoke
+  them.
 
   @param eb an event_base to be freed
  */
 void event_base_free(struct event_base *);
 
-/** DOCUMENT */
+/**
+   As event_free, but do not run finalizers.
+ */
 void event_base_free_nofinalize(struct event_base *);
 
 /** @name Log severities
@@ -1038,6 +1042,10 @@ typedef void (*event_finalize_callback_fn)(struct event *, void *);
 
    The event_free_finalize() function frees the event after it's finalized;
    event_finalize() does not.
+
+   A finalizer callback must not make events pending or active.  It must not
+   add events, activate events, or attempt to "resucitate" the event being
+   finalized in any way.
  */
 /**@{*/
 void event_finalize(unsigned, struct event *, event_finalize_callback_fn);

diff --git a/include/event2/event_struct.h b/include/event2/event_struct.h
index ad2403ec67a70c3a506c0cf51fe8ff90e899ea56..1c8b71b6b0df87a73fc0bcd7c4d9d8e1ff56f31c 100644 (file)
--- a/include/event2/event_struct.h
+++ b/include/event2/event_struct.h
@@ -105,7 +105,6 @@ struct name {                                                               \
 struct event;
 
 struct event_callback {
-       /* DOCUMENT all these fields */
        TAILQ_ENTRY(event_callback) evcb_active_next;
        short evcb_flags;
        ev_uint8_t evcb_pri;    /* smaller numbers are higher priority */