[3/4] wispr: Add documentation about reference counting.

Commit Message

Grant Erickson Nov. 10, 2023, 4:46 a.m. UTC

This adds documentation about the balanced retain/release reference
counting done to handle the weak reference to the WISPr/portal context
maintained by 'g_web_request_get'.
---
 src/wispr.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

Patch

diff --git a/src/wispr.c b/src/wispr.c
index 96c5f454..b496b7f9 100644
--- a/src/wispr.c
+++ b/src/wispr.c
@@ -574,6 +574,11 @@  static void wispr_portal_request_portal(
 		connman_service_get_identifier(wp_context->service),
 		wp_context->type, __connman_ipconfig_type2string(wp_context->type));
 
+	/*
+	 * Retain a reference to the WISPr/portal context to account for
+	 * 'g_web_request_get' maintaining a weak reference to it. This will
+	 * be released in the 'wispr_portal_web_result' callback.
+	 */
 	wispr_portal_context_ref(wp_context);
 	wp_context->request_id = g_web_request_get(wp_context->web,
 					wp_context->status_url,
@@ -873,6 +878,12 @@  static bool wispr_portal_web_result(GWebResult *result, gpointer user_data)
 	wp_context->request_id = 0;
 done:
 	wp_context->wispr_msg.message_type = -1;
+
+	/*
+	 * Release a reference to the WISPr/portal context to balance the
+	 * earlier reference retained to account for 'g_web_request_get'
+	 * maintaining a weak reference to it.
+	 */
 	wispr_portal_context_unref(wp_context);
 	return false;
 }