NAME

REFCOUNT — reference counting

SYNOPSIS

#include <sys/refcount.h>

void
refcount_init(struct refcount *refcount);

void
refcount_fini(struct refcount *refcount);

int
refcount_inc(struct refcount *refcount);

bool
refcount_dec_local(struct refcount *refcount);

bool
refcount_dec_lock(struct refcount *refcount, kmutex_t *interlock);

void
refcount_dec_signal(struct refcount *refcount, kmutex_t *interlock, kcondvar_t *cv);

void
refcount_dec_broadcast(struct refcount *refcount, kmutex_t *interlock, kcondvar_t *cv);

void
refcount_dec_drain(struct refcount *refcount, kmutex_t *interlock, kcondvar_t *cv);

#if DIAGNOSTIC

bool
refcount_referenced_p(const struct refcount *refcount);

bool
refcount_exclusive_p(const struct refcount *refcount);

#endif /* DIAGNOSTIC */

DESCRIPTION

REFCOUNT 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 refcount, which users should treat as opaque and should not inspect or copy. The struct refcount must be initialized with refcount_init() before use, and finalized with refcount_fini() when done. When acquiring a reference to an object, use refcount_inc(), which increments its reference count. When releasing a reference to an object, use one of the refcount_dec_*() routines.

The REFCOUNT abstraction supports 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.

  Users of the object should use refcount_dec_signal() or refcount_dec_broadcast() to notify the free operation when they are done, and the free operation should use refcount_dec_drain() to wait until there are no users left.

• The object is stored in a global cache, and has no explicit free operation -- its lifetime ends when the last user is done with it, at which point it must be removed from the cache and freed.

  Each user of the object should use refcount_dec_lock() when done, which returns true and enters a mutex if and only if that user is the last one. This allows the last user to safely remove the object from the global cache without a window during which new references can be acquired.

• The object has no explicit free operation and is not stored in any global tables.

  Each user of the object should use refcount_dec_local() when done, which returns true if and only if that user is the last one, who can then free the object.

The transition from nonzero to zero references is permanent. It is also guaranteed to happen under an interlock excluding new references whenever there is a possibility that one thread may acquire a new reference at the same time another is releasing what would have been the last one.

Note that refcount_dec_local() is not simply a primitive out of which the other refcount_dec_*() functions are built. It is not correct to replace

if (refcount_dec_lock(&obj->obj_refcount, &obj->obj_lock)) { 
	... 
}

by:

if (refcount_dec_local(&obj->obj_refcount)) { 
	mutex_enter(&obj->obj_lock); 
	... 
}

The reason is that refcount_dec_lock() guarantees the transition from nonzero to zero happens under the interlock, which the above fragment does not. The name refcount_dec_local() was chosen instead of the alternative refcount_dec() to emphasize that it is not a part of refcount_dec_lock() but a different variant altogether, which is safe only when the object is not reachable from any global tables that it must be removed from under a mutex when it becomes unreferenced.

FUNCTIONS

refcount_init(refcount)

Initialize refcount for use with REFCOUNT.

refcount_fini(refcount)

Finalize refcount. Further use with REFCOUNT is not allowed.

refcount_inc(refcount)

Try to increment refcount. If there are too many other references (UINT_MAX), return EBUSY. Otherwise, return zero.

refcount_dec_local(refcount)

Decrement refcount. If it drops to zero, return true. Otherwise return false.

This is useful only when the object whose references are counted by refcount is not stored in any global tables or caches, so that, without interlocks, if the reference count would drop to zero, there is no way for other threads to acquire new references.

refcount_dec_lock(refcount, interlock)

Decrement refcount. If it 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.

refcount_dec_signal(refcount, interlock, cv)

Decrement refcount. If it 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.

refcount_dec_broadcast(refcount, interlock, cv)

Decrement refcount. If it 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.

refcount_dec_drain(refcount, interlock, cv)

Decrement refcount, and wait under interlock on cv until the reference count drops to zero.

The caller must hold interlock.

May sleep.

refcount_referenced_p(refcount)

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

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

refcount_exclusive_p(refcount)

Return true if caller's reference to refcount is exclusive -- that is, if the reference count of refcount is one. Otherwise return false. refcount 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 refcount_exclusive_p().

CODE REFERENCES

The REFCOUNT abstraction is implemented in sys/sys/refcount.h.

SEE ALSO

condvar(9), mutex(9)

BUGS

There are no examples in this man page.

The implementation is untested.