[glib: 1/15] Introduce new GPollableReturn enum

[Philip Withnall <pwithnall src gnome org>]

commit 042b8dc40da9874336a888428a3bebcd4a51806a
Author: Sebastian Dröge <sebastian centricular com>
Date:   Fri Jan 4 12:48:26 2019 +0200

    Introduce new GPollableReturn enum
    
    This allows returning WOULD_BLOCK without allocating a GError, and
    should later be used for various functions of GPollableOutputStream,
    GPollableInputStream and anything else that can potentially block.

 docs/reference/gio/gio-sections.txt |  1 +
 gio/gioenums.h                      | 27 +++++++++++++++++++++++++++
 2 files changed, 28 insertions(+)
---
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 1fe37e488..3f2dd9a18 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -3659,6 +3659,7 @@ g_pollable_output_stream_get_type
 
 <SECTION>
 <FILE>gpollableutils</FILE>
+GPollableReturn
 GPollableSourceFunc
 g_pollable_source_new
 g_pollable_source_new_full
diff --git a/gio/gioenums.h b/gio/gioenums.h
index bf7b8e8b5..9c7d9b6ac 100644
--- a/gio/gioenums.h
+++ b/gio/gioenums.h
@@ -512,6 +512,9 @@ typedef enum {
  * ]|
  * but should instead treat all unrecognized error codes the same as
  * #G_IO_ERROR_FAILED.
+ *
+ * See also #GPollableReturn for a cheaper way of returning
+ * %G_IO_ERROR_WOULD_BLOCK to callers without allocating a #GError.
  **/
 typedef enum {
   G_IO_ERROR_FAILED,
@@ -1922,6 +1925,30 @@ typedef enum {
   G_NETWORK_CONNECTIVITY_FULL        = 4
 } GNetworkConnectivity;
 
+/**
+ * GPollableReturn:
+ * @G_POLLABLE_RETURN_FAILED: Generic error condition for when an operation fails.
+ * @G_POLLABLE_RETURN_OK: The operation was successfully finished.
+ * @G_POLLABLE_RETURN_WOULD_BLOCK: The operation would block.
+ *
+ * Return value for various IO operations that signal errors via the
+ * return value and not necessarily via a #GError.
+ *
+ * This enum exists to be able to return errors to callers without having to
+ * allocate a #GError. Allocating #GErrors can be quite expensive for
+ * regularly happening errors like %G_IO_ERROR_WOULD_BLOCK.
+ *
+ * In case of %G_POLLABLE_RETURN_FAILED a #GError should be set for the
+ * operation to give details about the error that happened.
+ *
+ * Since: 2.60
+ */
+typedef enum {
+  G_POLLABLE_RETURN_FAILED       = 0,
+  G_POLLABLE_RETURN_OK           = 1,
+  G_POLLABLE_RETURN_WOULD_BLOCK  = -G_IO_ERROR_WOULD_BLOCK
+} GPollableReturn;
+
 G_END_DECLS
 
 #endif /* __GIO_ENUMS_H__ */