1.\" $OpenBSD: refcnt_init.9,v 1.1 2015/09/11 19:13:22 dlg Exp $ 2.\" 3.\" Copyright (c) 2015 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 11 2015 $ 18.Dt REFCNT_INIT 9 19.Os 20.Sh NAME 21.Nm refcnt_init , 22.Nm refcnt_take , 23.Nm refcnt_rele , 24.Nm refcnt_rele_wake , 25.Nm refcnt_finalize , 26.Nm REFCNT_INITIALIZER 27.Nd reference count API 28.Sh SYNOPSIS 29.In sys/refcnt.h 30.Ft void 31.Fn "refcnt_init" "struct refcnt *r" 32.Ft void 33.Fn "refcnt_take" "struct refcnt *r" 34.Ft int 35.Fn "refcnt_rele" "struct refcnt *r" 36.Ft void 37.Fn "refcnt_rele_wake" "struct refcnt *r" 38.Ft void 39.Fn "refcnt_finalize" "struct refcnt *r" "const char *wmesg" 40.Fn "REFCNT_INITIALIZER" 41.Sh DESCRIPTION 42The refcnt API provides simple reference counters that can be used 43to manage the lifetime of a shared object. 44.Pp 45.Fn refcnt_init 46sets the initial value of the counter to 1 to account for the caller's 47reference to the object. 48.Pp 49.Fn refcnt_take 50is used to acquire a new reference. 51It is the responsibility of the caller to guarantee that it holds 52a valid reference before taking a new reference. 53.Pp 54.Fn refcnt_rele 55is used to release an existing reference. 56.Pp 57.Fn refcnt_rele_wake 58is used to release an existing reference and wakes up a process 59that is currently waiting in 60.Fn refcnt_finalize 61for all the references to released. 62.Pp 63.Fn refcnt_finalize 64releases the caller's reference and sleeps until all the other 65references to the relevant object have been released. 66There may only be one caller to 67.Fn refcnt_finalize 68per refcnt 69.Fa r . 70.Pp 71.Fn REFCNT_INITIALIZER 72initialises a declaration of a refcnt to 1. 73.Sh CONTEXT 74.Fn refcnt_init , 75.Fn refcnt_take , 76.Fn refcnt_rele , 77and 78.Fn refcnt_rele_wake 79can be called during autoconf, from process context, or from interrupt 80context. 81.Pp 82.Fn refcnt_finalize 83can be called from process context. 84.Sh RETURN VALUES 85.Fn refcnt_rele 86returns a non-zero value if the last reference has been released, 87otherwise 0. 88