[glib] Add g_cancellable_release_fd()

[Benjamin Otte <otte src gnome org>]

commit 63426886ff4066fefbeaf2e6b08a6c04b39a7890
Author: Benjamin Otte <otte gnome org>
Date:   Tue Aug 11 14:52:56 2009 +0200

    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 |    1 +
 gio/gcancellable.c                  |   30 ++++++++++++++++++++++++++++++
 gio/gcancellable.h                  |    1 +
 gio/ginputstream.c                  |    2 +-
 gio/gio.symbols                     |    1 +
 5 files changed, 34 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index f178a70..5089678 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/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
diff --git a/gio/gcancellable.c b/gio/gcancellable.c
index ada764a..be712c4 100644
--- a/gio/gcancellable.c
+++ b/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 
@@ -505,6 +513,28 @@ g_cancellable_make_pollfd (GCancellable *cancellable, GPollFD *pollfd)
 }
 
 /**
+ * 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.
  * 
diff --git a/gio/gcancellable.h b/gio/gcancellable.h
index 9d318c2..dc73ccd 100644
--- a/gio/gcancellable.h
+++ b/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);
diff --git a/gio/ginputstream.c b/gio/ginputstream.c
index d3e2224..7c0f079 100644
--- a/gio/ginputstream.c
+++ b/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.
diff --git a/gio/gio.symbols b/gio/gio.symbols
index 166b677..47ad861 100644
--- a/gio/gio.symbols
+++ b/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