Add g_cancellable_release_fd()

This patch only adds the function. The function is a NOP.
See the API documentation for a rationale.

Part of: Bug 591388 - number of GCancellables available is too limited

docs/reference/gio/gio-sections.txt

@@ -1090,6 +1090,7 @@ g_cancellable_is_cancelled
 g_cancellable_set_error_if_cancelled
 g_cancellable_get_fd
 g_cancellable_make_pollfd
+g_cancellable_release_fd
 g_cancellable_get_current
 g_cancellable_pop_current
 g_cancellable_push_current

gio/gcancellable.c

@@ -417,6 +417,10 @@ g_cancellable_set_error_if_cancelled (GCancellable  *cancellable,
  * readable status. Reading to unset the readable status is done
  * with g_cancellable_reset().
  * 
+ * After a successful return from this function, you should use 
+ * g_cancellable_release_fd() to free up resources allocated for 
+ * the returned file descriptor.
+ *
  * See also g_cancellable_make_pollfd().
  *
  * Returns: A valid file descriptor. %-1 if the file descriptor 
@@ -457,6 +461,10 @@ g_cancellable_get_fd (GCancellable *cancellable)
  * for unix systems without a native poll and for portability to
  * windows.
  *
+ * When this function returns %TRUE, you should use 
+ * g_cancellable_release_fd() to free up resources allocated for the 
+ * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
+ *
  * If this function returns %FALSE, either no @cancellable was given or
  * resource limits prevent this function from allocating the necessary 
  * structures for polling. (On Linux, you will likely have reached 
@@ -504,6 +512,28 @@ g_cancellable_make_pollfd (GCancellable *cancellable, GPollFD *pollfd)
   pollfd->revents = 0;
 }
 
+/**
+ * g_cancellable_release_fd:
+ * @cancellable: a #GCancellable
+ *
+ * Releases a resources previously allocated by g_cancellable_get_fd()
+ * or g_cancellable_make_pollfd().
+ *
+ * For compatibility reasons with older releases, calling this function 
+ * is not strictly required, the resources will be automatically freed
+ * when the @cancellable is finalized. However, the @cancellable will
+ * block scarce file descriptors until it is finalized if this function
+ * is not called. This can cause the application to run out of file 
+ * descriptors when many #GCancellables are used at the same time.
+ * 
+ * @Since: 2.22
+ **/
+void
+g_cancellable_release_fd (GCancellable *cancellable)
+{
+  g_return_if_fail (G_IS_CANCELLABLE (cancellable));
+}
+
 /**
  * g_cancellable_cancel:
  * @cancellable: a #GCancellable object.

gio/gcancellable.h

@@ -81,6 +81,7 @@ gboolean      g_cancellable_set_error_if_cancelled (GCancellable  *cancellable,
 int           g_cancellable_get_fd                 (GCancellable  *cancellable);
 gboolean      g_cancellable_make_pollfd            (GCancellable  *cancellable,
 						    GPollFD       *pollfd);
+void          g_cancellable_release_fd             (GCancellable  *cancellable);
 
 GCancellable *g_cancellable_get_current            (void);
 void          g_cancellable_push_current           (GCancellable  *cancellable);

gio/ginputstream.c

@@ -508,7 +508,7 @@ async_ready_close_callback_wrapper (GObject      *source_object,
  * You can then call g_input_stream_read_finish() to get the result of the 
  * operation.
  *
- * During an async request no other sync and async calls are allowed, and will
+ * During an async request no other sync and async calls are allowed on @stream, and will
  * result in %G_IO_ERROR_PENDING errors. 
  *
  * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.

gio/gio.symbols

@@ -129,6 +129,7 @@ g_cancellable_is_cancelled
 g_cancellable_set_error_if_cancelled
 g_cancellable_get_fd
 g_cancellable_make_pollfd
+g_cancellable_release_fd
 g_cancellable_get_current
 g_cancellable_push_current
 g_cancellable_pop_current