NAME

REFCNT — reference counting

SYNOPSIS

#include <sys/refcnt.h>

struct refcnt;

void
refcnt_init(struct refcnt *refcnt);

void
refcnt_fini(struct refcnt *refcnt);

int
refcnt_acquire(struct refcnt *refcnt);

bool
refcnt_release_tryenter(struct refcnt *refcnt, kmutex_t *interlock);

void
refcnt_release_signal(struct refcnt *refcnt, kmutex_t *interlock, kcondvar_t *cv);

void
refcnt_release_broadcast(struct refcnt *refcnt, kmutex_t *interlock, kcondvar_t *cv);

void
refcnt_release_wait(struct refcnt *refcnt, kmutex_t *interlock, kcondvar_t *cv);

void
refcnt_release_wait_unlocked(struct refcnt *refcnt, kmutex_t *interlock, kcondvar_t *cv);

DESCRIPTION

REFCNT is an abstraction for maintaining reference counts to objects that may be shared between multiple threads. Each object with a reference count should embed a struct refcnt object, which users should treat as opaque and should not inspect or copy. The struct refcnt object must be initialized with refcnt_init() before use, and finalized with refcnt_fini() when done. References are acquired with refcnt_acquire(), and released with one of the refcnt_release_*() routines.

The REFCNT abstraction admits multiple approaches to freeing objects when they are no longer referenced:

• The object's lifetime is ended by an explicit free operation, and the reference count serves only to notify the free operation when the object is no longer in use.

  In this case, users of the object should use refcnt_release_signal() or refcnt_release_broadcast() to notify the free operation when they are done, and the free operation should use refcnt_release_wait() or refcnt_release_wait_unlocked() to wait until there are no users left.

• The object has no explicit free operation -- its lifetime ends when the last user is done with it.

  In this case, each user of the object should use refcnt_release_tryenter(), which returns true and enters a mutex if and only if that user is the last one, so that the last user can remove it from any global tables and free it.

The transition from nonzero references to zero references is guaranteed to happen under an interlock, except in the case of refcnt_release_wait_unlocked() whose caller must guarantee that no new references to the object can be created.

FUNCTIONS

refcnt_init(refcnt)

Initialize refcnt for use with REFCNT.

refcnt_fini(refcnt)

Finalize refcnt. Further use with REFCNT is not allowed.

refcnt_acquire(refcnt)

Try to acquire a reference to refcnt. If there are too many other references (UINT_MAX), return EBUSY. Otherwise, increment the reference count of refcnt and return zero.

refcnt_release_tryenter(refcnt, interlock)

Release a reference to refcnt. If the reference count drops to zero, enter the mutex interlock and return true. Otherwise return false.

May enter interlock even if it returns false, in case another thread acquired a reference at the same time.

refcnt_release_signal(refcnt, interlock, cv)

Release a reference to refcnt. If the reference count drops to zero, enter the mutex interlock, signal cv, and exit interlock.

May enter interlock even if it does not signal cv, in case another thread acquired a reference at the same time.

refcnt_release_broadcast(refcnt, interlock, cv)

Release a reference to refcnt. If the reference count drops to zero, enter the mutex interlock, broadcast cv, and exit interlock.

May enter interlock even if it does not broadcast cv, in case another thread acquired a reference at the same time.

refcnt_release_wait(refcnt, interlock, cv)

Release a reference to refcnt, and wait under interlock on cv until the reference count drops to zero.

The caller must hold interlock.

May sleep.

refcnt_release_wait_unlocked(refcnt, interlock, cv)

Release a reference to refcnt, enter the mutex interlock, wait on cv until the reference count drops to zero, and exit interlock.

The caller must guarantee no new references can be made before calling refcnt_release_wait_unlocked(), e.g. by setting a flag in the object causing prospective users to skip it before attempting refcnt_acquire().

May enter interlock and exit it on return. May sleep.

As an optimization, refcnt_release_wait_unlocked() may avoid interprocessor synchronization if the caller holds the only reference.

refcnt_referenced_p(refcnt)

Return true if the reference count of refcnt is positive, false if zero.

May be used only under DIAGNOSTIC for assertions. Do not make run-time decisions on the basis of refcnt_referenced_p().

refcnt_exclusive_p(refcnt)

Return true if caller's reference to refcnt is exclusive -- that is, if the reference count of refcnt is one. Otherwise return false. refcnt must be referenced: the reference count may not be zero.

May be used only under DIAGNOSTIC for assertions. Do not make run-time decisions on the basis of refcnt_exclusive_p().

CODE REFERENCES

The REFCNT abstraction is implemented in sys/sys/refcnt.h.

SEE ALSO

condvar(9), mutex(9)

BUGS

There are no examples in this man page.

The implementation is untested.