1 files changed, 43 insertions, 13 deletions
diff --git a/libmpv/client.h b/libmpv/client.h
index d1fe312500..3608f453f9 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -1179,7 +1179,10 @@ void mpv_wakeup(mpv_handle *ctx);
  *
  * In general, the client API expects you to call mpv_wait_event() to receive
  * notifications, and the wakeup callback is merely a helper utility to make
- * this easier in certain situations.
+ * this easier in certain situations. Note that it's possible that there's
+ * only one wakeup callback invocation for multiple events. You should call
+ * mpv_wait_event() with no timeout until MPV_EVENT_NONE is reached, at which
+ * point the event queue is empty.
  *
  * If you actually want to do processing in a callback, spawn a thread that
  * does nothing but call mpv_wait_event() in a loop and dispatches the result
@@ -1197,7 +1200,8 @@ void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d);
  * pipe can be used to wake up a poll() based processing loop. The purpose of
  * this function is very similar to mpv_set_wakeup_callback(), and provides
  * a primitive mechanism to handle coordinating a foreign event loop and the
- * libmpv event loop.
+ * libmpv event loop. The pipe is non-blocking. It's closed when the mpv_handle
+ * is destroyed. This function always returns the same value (on success).
  *
  * This is in fact implemented using the same underlying code as for
  * mpv_set_wakeup_callback() (though they don't conflict), and it is as if each
@@ -1205,17 +1209,43 @@ void mpv_set_wakeup_callback(mpv_handle *ctx, void (*cb)(void *d), void *d);
  * becomes readable, the code calling poll() (or select()) on the pipe should
  * read all contents of the pipe and then call mpv_wait_event(c, 0) until
  * no new events are returned. The pipe contents do not matter and can just
- * be discarded.
- *
- * Note that this call lazily creates the pipe, and always returns the same
- * handle once it's created. The client API will destroy both the read and
- * write ends of the pipe in mpv_destroy(). If you need something more
- * complex, it's better to implement your own mechanisms using
- * mpv_set_wakeup_callback().
- *
- * On Windows, this will always return -1.
- *
- * @return A UNIX FD of the read end of the wakeup pipe, -1 on error.
+ * be discarded. There is not necessarily one byte per readable event in the
+ * pipe. For example, the pipes are non-blocking, and mpv won't block if the
+ * pipe is full. Pipes are normally limited to 4096 bytes, so if there are
+ * more than 4096 events, the number of readable bytes can not equal the number
+ * of events queued. Also, it's possible that mpv does not write to the pipe
+ * once it's guaranteed that the client was already signaled. See the example
+ * below how to do it correctly.
+ *
+ * Example:
+ *
+ *  int pipefd = mpv_get_wakeup_pipe(mpv);
+ *  if (pipefd < 0)
+ *      error();
+ *  while (1) {
+ *      struct pollfd pfds[1] = {
+ *          { .fd = pipefd, .events = POLLIN },
+ *      };
+ *      // Wait until there are possibly a new mpv events.
+ *      poll(pfds, 1, -1);
+ *      if (pfds[0].revents & POLLIN) {
+ *          // Empty the pipe. Doing this before calling mpv_wait_event()
+ *          // ensures that no wakeups get missed.
+ *          char unused[256];
+ *          read(pipefd, unused, sizeof(unused));
+ *          while (1) {
+ *              mpv_event *ev = mpv_wait_event(mpv, 0);
+ *              // If MPV_EVENT_NONE is received, the event queue is empty.
+ *              if (ev->event_id == MPV_EVENT_NONE)
+ *                  break;
+ *              // Process the event.
+ *              ...
+ *          }
+ *      }
+ *  }
+ *
+ * @return A UNIX FD of the read end of the wakeup pipe, or -1 on error.
+ *         On MS Windows/MinGW, this will always return -1.
  */
 int mpv_get_wakeup_pipe(mpv_handle *ctx);