unix, windows: make uv_run_once() return a bool

The return value of uv_run_once() now signals if it needs to be called again.

Fixes #427.

include/uv.h

@@ -230,14 +230,17 @@ UV_EXTERN uv_loop_t* uv_default_loop(void);
 
 /*
  * This function starts the event loop. It blocks until the reference count
- * of the loop drops to zero.
+ * of the loop drops to zero. Always returns zero.
  */
-UV_EXTERN int uv_run (uv_loop_t*);
+UV_EXTERN int uv_run(uv_loop_t*);
 
 /*
- * This function polls for new events without blocking.
+ * Poll for new events once. Note that this function blocks if there are no
+ * pending events. Returns zero when done (no active handles or requests left),
+ * or non-zero if more events are expected (meaning you should call
+ * uv_run_once() again sometime in the future).
  */
-UV_EXTERN int uv_run_once (uv_loop_t*);
+UV_EXTERN int uv_run_once(uv_loop_t*);
 
 /*
  * Manually modify the event loop's reference count. Useful if the user wants

src/unix/core.c

@@ -235,8 +235,7 @@ int uv_run(uv_loop_t* loop) {
 
 
 int uv_run_once(uv_loop_t* loop) {
-  uv__run(loop);
-  return 0;
+  return uv__run(loop);
 }
 
 

src/win/core.c

@@ -268,7 +268,7 @@ int uv_run_once(uv_loop_t* loop) {
   } else {
     UV_LOOP_ONCE(loop, uv_poll);
   }
-  return 0;
+  return UV_LOOP_ALIVE(loop);
 }
 
 

test/test-list.h

@@ -21,6 +21,7 @@
 
 TEST_DECLARE   (platform_output)
 TEST_DECLARE   (callback_order)
+TEST_DECLARE   (run_once)
 TEST_DECLARE   (tty)
 TEST_DECLARE   (stdio_over_pipes)
 TEST_DECLARE   (ipc_listen_before_write)
@@ -185,6 +186,7 @@ TASK_LIST_START
 #if 0
   TEST_ENTRY  (callback_order)
 #endif
+  TEST_ENTRY  (run_once)
 
   TEST_ENTRY  (pipe_connect_bad_name)
   TEST_ENTRY  (pipe_connect_to_file)

test/test-run-once.c

@@ -22,23 +22,27 @@
 #include "uv.h"
 #include "task.h"
 
-static idle_counter = 0;
+#define NUM_TICKS 64
+
+static uv_idle_t idle_handle;
+static int idle_counter;
+
 
 static void idle_cb(uv_idle_t* handle, int status) {
-  ASSERT(handle != NULL);
+  ASSERT(handle == &idle_handle);
   ASSERT(status == 0);
-  idle_counter ++;
+
+  if (++idle_counter == NUM_TICKS)
+    uv_idle_stop(handle);
 }
 
 
 TEST_IMPL(run_once) {
-  int n;
-  uv_idle_t h;
-  uv_idle_init(uv_default_loop(), &h);
-  uv_idle_start(&h, idle_cb);
-  for (n = 0; n < 500; n++) {
-    uv_run_once(uv_default_loop());
-  }
-  ASSERT(n == 500);
+  uv_idle_init(uv_default_loop(), &idle_handle);
+  uv_idle_start(&idle_handle, idle_cb);
+
+  while (uv_run_once(uv_default_loop()));
+  ASSERT(idle_counter == NUM_TICKS);
+
   return 0;
 }

uv.gyp

@@ -328,6 +328,7 @@
         'test/test-poll.c',
         'test/test-process-title.c',
         'test/test-ref.c',
+        'test/test-run-once.c',
         'test/test-shutdown-close.c',
         'test/test-shutdown-eof.c',
         'test/test-spawn.c',