1497435aaSJohn Baldwin.\" 2*179fa75eSJohn Baldwin.\" Copyright (c) 2009 Hudson River Trading LLC 3497435aaSJohn Baldwin.\" Written by: John H. Baldwin <jhb@FreeBSD.org> 4497435aaSJohn Baldwin.\" All rights reserved. 5497435aaSJohn Baldwin.\" 6497435aaSJohn Baldwin.\" Redistribution and use in source and binary forms, with or without 7497435aaSJohn Baldwin.\" modification, are permitted provided that the following conditions 8497435aaSJohn Baldwin.\" are met: 9497435aaSJohn Baldwin.\" 1. Redistributions of source code must retain the above copyright 10497435aaSJohn Baldwin.\" notice, this list of conditions and the following disclaimer. 11497435aaSJohn Baldwin.\" 2. Redistributions in binary form must reproduce the above copyright 12497435aaSJohn Baldwin.\" notice, this list of conditions and the following disclaimer in the 13497435aaSJohn Baldwin.\" documentation and/or other materials provided with the distribution. 14497435aaSJohn Baldwin.\" 15497435aaSJohn Baldwin.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16497435aaSJohn Baldwin.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17497435aaSJohn Baldwin.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18497435aaSJohn Baldwin.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19497435aaSJohn Baldwin.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20497435aaSJohn Baldwin.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21497435aaSJohn Baldwin.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22497435aaSJohn Baldwin.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23497435aaSJohn Baldwin.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24497435aaSJohn Baldwin.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25497435aaSJohn Baldwin.\" SUCH DAMAGE. 26497435aaSJohn Baldwin.\" 27497435aaSJohn Baldwin.\" $FreeBSD$ 28497435aaSJohn Baldwin.\" 29497435aaSJohn Baldwin.Dd January 20, 2009 30497435aaSJohn Baldwin.Dt REFCOUNT 9 31497435aaSJohn Baldwin.Os 32497435aaSJohn Baldwin.Sh NAME 33497435aaSJohn Baldwin.Nm refcount , 34497435aaSJohn Baldwin.Nm refcount_init , 35497435aaSJohn Baldwin.Nm refcount_acquire , 36497435aaSJohn Baldwin.Nm refcount_release 37497435aaSJohn Baldwin.Nd manage a simple reference counter 38497435aaSJohn Baldwin.Sh SYNOPSIS 39497435aaSJohn Baldwin.In sys/param.h 40497435aaSJohn Baldwin.In sys/refcount.h 41497435aaSJohn Baldwin.Ft void 421e9469d1SChristian Brueffer.Fn refcount_init "volatile u_int *count" "u_int value" 43497435aaSJohn Baldwin.Ft void 44497435aaSJohn Baldwin.Fn refcount_acquire "volatile u_int *count" 45497435aaSJohn Baldwin.Ft int 46497435aaSJohn Baldwin.Fn refcount_release "volatile u_int *count" 47497435aaSJohn Baldwin.Sh DESCRIPTION 48497435aaSJohn BaldwinThe 49497435aaSJohn Baldwin.Nm 50497435aaSJohn Baldwinfunctions provide an API to manage a simple reference counter. 51497435aaSJohn BaldwinThe caller provides the storage for the counter in an unsigned integer. 52497435aaSJohn BaldwinA pointer to this integer is passed via 53497435aaSJohn Baldwin.Fa count . 54497435aaSJohn BaldwinUsually the counter is used to manage the lifetime of an object and is 55497435aaSJohn Baldwinstored as a member of the object. 56497435aaSJohn Baldwin.Pp 57497435aaSJohn BaldwinThe 58497435aaSJohn Baldwin.Fn refcount_init 59497435aaSJohn Baldwinfunction is used to set the initial value of the counter to 60497435aaSJohn Baldwin.Fa value . 61497435aaSJohn BaldwinIt is normally used when creating a reference-counted object. 62497435aaSJohn Baldwin.Pp 63497435aaSJohn BaldwinThe 64497435aaSJohn Baldwin.Fn refcount_acquire 65497435aaSJohn Baldwinfunction is used to acquire a new reference. 66497435aaSJohn BaldwinThe caller is responsible for ensuring that it holds a valid reference 67497435aaSJohn Baldwinwhile obtaining a new reference. 68497435aaSJohn BaldwinFor example, 69497435aaSJohn Baldwinif an object is stored on a list and the list holds a reference on the 70497435aaSJohn Baldwinobject, then holding a lock that protects the list provides sufficient 71497435aaSJohn Baldwinprotection for acquiring a new reference. 72497435aaSJohn Baldwin.Pp 73497435aaSJohn BaldwinThe 74497435aaSJohn Baldwin.Fn refcount_release 75497435aaSJohn Baldwinfunction is used to release an existing reference. 76497435aaSJohn BaldwinThe function returns a non-zero value if the reference being released was 77497435aaSJohn Baldwinthe last reference; 78497435aaSJohn Baldwinotherwise, it returns zero. 79497435aaSJohn Baldwin.Pp 80497435aaSJohn BaldwinNote that these routines do not provide any inter-CPU synchronization, 81497435aaSJohn Baldwindata protection, 82497435aaSJohn Baldwinor memory ordering guarantees except for managing the counter. 83497435aaSJohn BaldwinThe caller is responsible for any additional synchronization needed by 84497435aaSJohn Baldwinconsumers of any containing objects. 85497435aaSJohn BaldwinIn addition, 86497435aaSJohn Baldwinthe caller is also responsible for managing the life cycle of any containing 87497435aaSJohn Baldwinobjects including explicitly releasing any resources when the last reference 88497435aaSJohn Baldwinis released. 89497435aaSJohn Baldwin.Sh RETURN VALUES 90497435aaSJohn BaldwinThe 91497435aaSJohn Baldwin.Nm refcount_release 92497435aaSJohn Baldwinfunction returns non-zero when releasing the last reference and zero when 93497435aaSJohn Baldwinreleasing any other reference. 94497435aaSJohn Baldwin.Sh HISTORY 95497435aaSJohn BaldwinThese functions were introduced in 96497435aaSJohn Baldwin.Fx 6.0 . 97