auth-chain/trivial: rename nm_auth_chain_unref() to nm_auth_chain_destroy()

NMAuthChain is not really ref-counted. True, we have an internal ref-counter
to ensure that the instance stays alive while the callback is invoked. However,
the user cannot take additional references as there is no nm_auth_chain_ref().

When the user wants to get rid of the auth-chain, with the current API it
is important that the callback won't be called after that point. From the
name nm_auth_chain_unref(), it sounds like that there could be multiple references
to the auth-chain, and merely unreferencing the object might not guarantee that
the callback is canceled. However, that is luckily not the case, because
there is no real ref-counting involved here.

Just rename the destroy function to make this clearer.

1 files changed, 8 insertions, 5 deletions

diff --git a/src/nm-auth-utils.c b/src/nm-auth-utils.c
index 93aee45008..da5843b0bf 100644
--- a/src/nm-auth-utils.c
+++ b/src/nm-auth-utils.c
@@ -219,7 +219,7 @@ auth_chain_finish (gpointer user_data)
 	/* Ensure we stay alive across the callback */
 	self->refcount++;
 	self->done_func (self, NULL, self->context, self->user_data);
-	nm_auth_chain_unref (self);
+	nm_auth_chain_destroy (self);
 	return FALSE;
 }
 
@@ -394,17 +394,20 @@ nm_auth_chain_new_subject (NMAuthSubject *subject,
 }
 
 /**
- * nm_auth_chain_unref:
+ * nm_auth_chain_destroy:
  * @self: the auth-chain
  *
- * Unrefs the auth-chain. By unrefing the auth-chain, you also cancel
+ * Destroys the auth-chain. By destroying the auth-chain, you also cancel
  * the receipt of the done-callback. IOW, the callback will not be invoked.
  *
- * The only exception is, if you call nm_auth_chain_unref() from inside
+ * The only exception is, if may call nm_auth_chain_destroy() from inside
  * the callback. In this case, @self stays alive until the callback returns.
+ *
+ * Note that you might only destroy an auth-chain exactly once, and never
+ * after the callback was handled.
  */
 void
-nm_auth_chain_unref (NMAuthChain *self)
+nm_auth_chain_destroy (NMAuthChain *self)
 {
 	AuthCall *call;