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.

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

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);
 }
 

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;

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()),