poll: Clarify when FALSE is returned from read/write_control()

And also mention what the expected values of errno are going to be.

write_control() will only ever return FALSE if there was a critical error. It
will never return because of EINTR, EAGAIN or EWOULDBLOCK.

read_control() will return FALSE if there was no byte to read, in which case
errno would be EWOULDBLOCK.
In all other cases there was a critical error.

https://bugzilla.gnome.org/show_bug.cgi?id=750397

diff --git a/gst/gstpoll.c b/gst/gstpoll.c
index ae6a6e9..53b6268 100644 (file)
--- a/gst/gstpoll.c
+++ b/gst/gstpoll.c
@@ -1638,8 +1638,9 @@ gst_poll_set_flushing (GstPoll * set, gboolean flushing)
  * This function only works for timer #GstPoll objects created with
  * gst_poll_new_timer().
  *
- * Returns: %TRUE on success. %FALSE when @set is not controllable or when the
- * byte could not be written.
+ * Returns: %TRUE on success. %FALSE when when the byte could not be written.
+ * errno contains the detailed error code but will never be EAGAIN, EINTR or
+ * EWOULDBLOCK. %FALSE always signals a critical error.
  */
 gboolean
 gst_poll_write_control (GstPoll * set)
@@ -1663,8 +1664,10 @@ gst_poll_write_control (GstPoll * set)
  * This function only works for timer #GstPoll objects created with
  * gst_poll_new_timer().
  *
- * Returns: %TRUE on success. %FALSE when @set is not controllable or when there
- * was no byte to read.
+ * Returns: %TRUE on success. %FALSE when when there was no byte to read or
+ * reading the byte failed. If there was no byte to read, and only then, errno
+ * will contain EWOULDBLOCK. For all other values of errno this always signals a
+ * critical error.
  */
 gboolean
 gst_poll_read_control (GstPoll * set)