1.\" $OpenBSD: refcnt_init.9,v 1.2 2022/03/16 14:13:01 visa 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: March 16 2022 $ 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_shared , 27.Nm refcnt_read , 28.Nm REFCNT_INITIALIZER 29.Nd reference count API 30.Sh SYNOPSIS 31.In sys/refcnt.h 32.Ft void 33.Fn "refcnt_init" "struct refcnt *r" 34.Ft void 35.Fn "refcnt_take" "struct refcnt *r" 36.Ft int 37.Fn "refcnt_rele" "struct refcnt *r" 38.Ft void 39.Fn "refcnt_rele_wake" "struct refcnt *r" 40.Ft void 41.Fn "refcnt_finalize" "struct refcnt *r" "const char *wmesg" 42.Ft int 43.Fn "refcnt_shared" "struct refcnt *r" 44.Ft unsigned int 45.Fn "refcnt_read" "struct refcnt *r" 46.Fn "REFCNT_INITIALIZER" 47.Sh DESCRIPTION 48The refcnt API provides simple reference counters that can be used 49to manage the lifetime of a shared object. 50.Pp 51.Fn refcnt_init 52sets the initial value of the counter to 1 to account for the caller's 53reference to the object. 54.Pp 55.Fn refcnt_take 56is used to acquire a new reference. 57It is the responsibility of the caller to guarantee that it holds 58a valid reference before taking a new reference. 59.Pp 60.Fn refcnt_rele 61is used to release an existing reference. 62.Pp 63.Fn refcnt_rele_wake 64is used to release an existing reference and wakes up a process 65that is currently waiting in 66.Fn refcnt_finalize 67for all the references to released. 68.Pp 69.Fn refcnt_finalize 70releases the caller's reference and sleeps until all the other 71references to the relevant object have been released. 72There may only be one caller to 73.Fn refcnt_finalize 74per refcnt 75.Fa r . 76.Pp 77.Fn refcnt_shared 78tests if the object has multiple references. 79.Pp 80.Fn refcnt_read 81returns a snapshot of the counter value. 82Its use is discouraged, 83code should use 84.Fn refcnt_shared 85whenever possible. 86.Pp 87.Fn REFCNT_INITIALIZER 88initialises a declaration of a refcnt to 1. 89.Sh CONTEXT 90.Fn refcnt_init , 91.Fn refcnt_take , 92.Fn refcnt_rele , 93.Fn refcnt_rele_wake , 94.Fn refcnt_shared 95and 96.Fn refcnt_read 97can be called during autoconf, from process context, or from interrupt 98context. 99.Pp 100.Fn refcnt_finalize 101can be called from process context. 102.Sh RETURN VALUES 103.Fn refcnt_rele 104returns a non-zero value if the last reference has been released, 105otherwise 0. 106.Pp 107.Fn refcnt_shared 108returns a non-zero value if the object has multiple references, 109otherwise 0. 110.Pp 111.Fn refcnt_read 112returns a snapshot of the counter value. 113