gsocket: Document that g_socket_create_source() holds a socket ref

This is quite important, as it means you can safely let the GSocket drop
out of scope while maintaining a reference to the GSource, and the
socket will remain open. That means fewer closure structures, simpler
code, and fewer allocations.

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

diff --git a/gio/gsocket.c b/gio/gsocket.c
index e59ace8..a233260 100644 (file)
--- a/gio/gsocket.c
+++ b/gio/gsocket.c
@@ -3385,8 +3385,9 @@ socket_source_new (GSocket      *socket,
  * @condition: a #GIOCondition mask to monitor
  * @cancellable: (allow-none): a %GCancellable or %NULL
  *
- * Creates a %GSource that can be attached to a %GMainContext to monitor
- * for the availability of the specified @condition on the socket.
+ * Creates a #GSource that can be attached to a %GMainContext to monitor
+ * for the availability of the specified @condition on the socket. The #GSource
+ * keeps a reference to the @socket.
  *
  * The callback on the source is of the #GSocketSourceFunc type.
  *