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.
This commit is contained in:
Thomas Haller
2018-04-09 11:52:55 +02:00
parent bfaa291d89
commit 50b74731f6
7 changed files with 32 additions and 29 deletions

View File

@@ -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;