From d1077304ec437bd58bf4f47c9c804764f9939d86 Mon Sep 17 00:00:00 2001
From: Philip Withnall <withnall@endlessm.com>
Date: Tue, 13 Mar 2018 14:03:24 +0000
Subject: [PATCH] gsocketlistener: Document the need to call
 g_socket_listener_close()

GSocketListener can keep internal references to itself for pending
accept() calls, which mean that it can stay alive (and keep listening
on ports) even after a user drops their last reference to it. They need
to call g_socket_listener_close() explicitly to avoid that.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

https://bugzilla.gnome.org/show_bug.cgi?id=794207
---
 gio/gsocketlistener.c | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/gio/gsocketlistener.c b/gio/gsocketlistener.c
index 7e6376bf3..ab17678a9 100644
--- a/gio/gsocketlistener.c
+++ b/gio/gsocketlistener.c
@@ -49,6 +49,13 @@
  * of server sockets and helps you accept sockets from any of the
  * socket, either sync or async.
  *
+ * Add addresses and ports to listen on using g_socket_listener_add_address()
+ * and g_socket_listener_add_inet_port(). These will be listened on until
+ * g_socket_listener_close() is called. Dropping your final reference to the
+ * #GSocketListener will not cause g_socket_listener_close() to be called
+ * implicitly, as some references to the #GSocketListener may be held
+ * internally.
+ *
  * If you want to implement a network server, also look at #GSocketService
  * and #GThreadedSocketService which are subclasses of #GSocketListener
  * that make this even easier.
@@ -309,6 +316,10 @@ g_socket_listener_add_socket (GSocketListener  *listener,
  * requesting a binding to port 0 (ie: "any port").  This address, if
  * requested, belongs to the caller and must be freed.
  *
+ * Call g_socket_listener_close() to stop listening on @address; this will not
+ * be done automatically when you drop your final reference to @listener, as
+ * references may be held internally.
+ *
  * Returns: %TRUE on success, %FALSE on error.
  *
  * Since: 2.22
@@ -404,6 +415,10 @@ g_socket_listener_add_address (GSocketListener  *listener,
  * useful if you're listening on multiple addresses and do
  * different things depending on what address is connected to.
  *
+ * Call g_socket_listener_close() to stop listening on @port; this will not
+ * be done automatically when you drop your final reference to @listener, as
+ * references may be held internally.
+ *
  * Returns: %TRUE on success, %FALSE on error.
  *
  * Since: 2.22