NAME

       refcount, refcount_init, refcount_acquire, refcount_release — manage a simple reference counter

SYNOPSIS

       #include <sys/param.h>
       #include <sys/refcount.h>

       void
       refcount_init(volatile u_int *count, u_int value);

       void
       refcount_acquire(volatile u_int *count);

       bool
       refcount_release(volatile u_int *count);

DESCRIPTION

       The  refcount  functions  provide  an  API to manage a simple reference counter.  The caller provides the
       storage for the counter in an unsigned integer.  A pointer to this integer is passed via count.   Usually
       the counter is used to manage the lifetime of an object and is stored as a member of the object.

       The  refcount_init()  function  is used to set the initial value of the counter to value.  It is normally
       used when creating a reference-counted object.

       The refcount_acquire() function is used to acquire a  new  reference.   The  caller  is  responsible  for
       ensuring  that  it holds a valid reference while obtaining a new reference.  For example, if an object is
       stored on a list and the list holds a reference on the object, then holding a lock that protects the list
       provides sufficient protection for acquiring a new reference.

       The refcount_release() function is used to release an existing reference.  The function returns  true  if
       the reference being released was the last reference; otherwise, it returns false.

       Note  that  these  routines  do  not  provide  any  inter-CPU synchronization, data protection, or memory
       ordering guarantees except for managing the counter.   The  caller  is  responsible  for  any  additional
       synchronization  needed  by  consumers  of  any  containing  objects.   In  addition,  the caller is also
       responsible for managing the life cycle of any containing  objects  including  explicitly  releasing  any
       resources when the last reference is released.

RETURN VALUES

       The refcount_release function returns true when releasing the last reference and false when releasing any
       other reference.

HISTORY

       These functions were introduced in FreeBSD 6.0.

Debian                                            July 21, 2019                                      REFCOUNT(9)