Tweak patch for event_base_foreach_event()

* Fix whitespace
* Explain return value from callback function
* Reinstate return value so that caller can tell whether forech
  exited early.
* Rename event_base_foreach_event_() to
  event_base_foreach_event_nolock_().
* Use event_base_foreach_event_cb_fn typedef in more places
* Be more dire about undefined behavior.

diff --git a/event-internal.h b/event-internal.h
index 5372af887dc29bc4acac9ec6bd7afd404f37737f..8da0edf86b4b312776d881b3b95538c1104ec00e 100644 (file)
--- a/event-internal.h
+++ b/event-internal.h
@@ -400,9 +400,6 @@ void event_base_assert_ok_(struct event_base *base);
 void event_base_assert_ok_nolock_(struct event_base *base);
 
 
-/* Callback type for event_base_foreach_event. */
-//typedef int (*event_base_foreach_event_cb)(struct event_base *base, struct event *, void *);
-
 /* Helper function: Call 'fn' exactly once every inserted or active event in
  * the event_base 'base'.
  *
@@ -411,7 +408,7 @@ void event_base_assert_ok_nolock_(struct event_base *base);
  *
  * Requires that 'base' be locked.
  */
-int event_base_foreach_event_(struct event_base *base,
+int event_base_foreach_event_nolock_(struct event_base *base,
     event_base_foreach_event_cb cb, void *arg);
 
 #ifdef __cplusplus

diff --git a/event.c b/event.c
index 2e1676ce210dcd57bb55712dea3e4bb491aace9b..3e917fb963b4342b38ecfa03768aa4a2d1d6fd82 100644 (file)
--- a/event.c
+++ b/event.c
@@ -3193,7 +3193,7 @@ evthread_make_base_notifiable_nolock_(struct event_base *base)
 }
 
 int
-event_base_foreach_event_(struct event_base *base,
+event_base_foreach_event_nolock_(struct event_base *base,
     event_base_foreach_event_cb fn, void *arg)
 {
        int r, i;
@@ -3308,16 +3308,18 @@ dump_active_event_fn(const struct event_base *base, const struct event *e, void
        return 0;
 }
 
-void 
-event_base_foreach_event(struct event_base *base, 
+int
+event_base_foreach_event(struct event_base *base,
     event_base_foreach_event_cb fn, void *arg)
 {
+       int r;
        if ((!fn) || (!base)) {
                return;
        }
        EVBASE_ACQUIRE_LOCK(base, th_base_lock);
-       event_base_foreach_event_(base, fn, arg);
+       r = event_base_foreach_event_nolock_(base, fn, arg);
        EVBASE_RELEASE_LOCK(base, th_base_lock);
+       return r;
 }
 
 
@@ -3326,10 +3328,10 @@ event_base_dump_events(struct event_base *base, FILE *output)
 {
        EVBASE_ACQUIRE_LOCK(base, th_base_lock);
        fprintf(output, "Inserted events:\n");
-       event_base_foreach_event_(base, dump_inserted_event_fn, output);
+       event_base_foreach_event_nolock_(base, dump_inserted_event_fn, output);
 
        fprintf(output, "Active events:\n");
-       event_base_foreach_event_(base, dump_active_event_fn, output);
+       event_base_foreach_event_nolock_(base, dump_active_event_fn, output);
        EVBASE_RELEASE_LOCK(base, th_base_lock);
 }
 

diff --git a/evmap.c b/evmap.c
index e02e4e91f0f06a4301298756b0244ec78139046a..d2160fbea82eb70ff2fa8e50f26a09462daa058c 100644 (file)
--- a/evmap.c
+++ b/evmap.c
@@ -963,7 +963,7 @@ evmap_check_integrity_(struct event_base *base)
 /* Helper type for evmap_foreach_event_: Bundles a function to call on every
  * event, and the user-provided void* to use as its third argument. */
 struct evmap_foreach_event_helper {
-       int (*fn)(const struct event_base *, const struct event *, void *);
+       event_base_foreach_event_cb fn;
        void *arg;
 };
 
@@ -1001,7 +1001,7 @@ evmap_signal_foreach_event_fn(struct event_base *base, int signum,
 
 int
 evmap_foreach_event_(struct event_base *base,
-    int (*fn)(const struct event_base *, const struct event *, void *), void *arg)
+    event_base_foreach_event_cb fn, void *arg)
 {
        struct evmap_foreach_event_helper h;
        int r;

diff --git a/include/event2/event.h b/include/event2/event.h
index 503b9de189f23232682d67169aa795c64d236146..36a42df1f6c18704458ab17a50d34d4906c1c8c7 100644 (file)
--- a/include/event2/event.h
+++ b/include/event2/event.h
@@ -1327,23 +1327,28 @@ void event_base_dump_events(struct event_base *, FILE *);
 
 
 /**
- * callback for iterating events in an event base via event_base_foreach_event
+ * Callback for iterating events in an event base via event_base_foreach_event
  */
 typedef int (*event_base_foreach_event_cb)(const struct event_base *, const struct event *, void *);
 
 /**
-   Iterate all current events in a given event loop. The method is an
-   alternative to event_base_dump_events, but provides a native interface
-   towards the events. 
+   Iterate over all added or active events events in an event loop, and invoke
+   a given callback on each one.
 
-   Modification of events during iteration is an invalid operation
-   and may lead to unexpected behaviour
+   The callback must not call any function that modifies the event base, or
+   modifies any event in the event base.  Doing so is unsupported and
+   will lead to undefined behavior.
+
+   The callback function must return 0 to continue iteration, or some other
+   integer to stop iterating.
 
    @param base An event_base on which to scan the events.
    @param fn   A callback function to receive the events.
+   @param arg  An argument passed to the callback function.
+   @return 0 if we iterated over every event, or the value returned by the
+      callback function if the loop exited early.
 */
-void event_base_foreach_event(struct event_base *base, event_base_foreach_event_cb fn, void *arg);
-
+int event_base_foreach_event(struct event_base *base, event_base_foreach_event_cb fn, void *arg);
 
 
 /** Sets 'tv' to the current time (as returned by gettimeofday()),