1.\" $OpenBSD: refcnt_init.9,v 1.6 2023/07/12 18:14:13 jmc 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: July 12 2023 $ 18.Dt REFCNT_INIT 9 19.Os 20.Sh NAME 21.Nm refcnt_init , 22.Nm refcnt_init_trace , 23.Nm refcnt_take , 24.Nm refcnt_rele , 25.Nm refcnt_rele_wake , 26.Nm refcnt_finalize , 27.Nm refcnt_shared , 28.Nm refcnt_read , 29.Nm REFCNT_INITIALIZER 30.Nd reference count API 31.Sh SYNOPSIS 32.In sys/refcnt.h 33.Ft void 34.Fn "refcnt_init" "struct refcnt *r" 35.Ft void 36.Fn "refcnt_init_trace" "struct refcnt *r" "int idx" 37.Ft void 38.Fn "refcnt_take" "struct refcnt *r" 39.Ft int 40.Fn "refcnt_rele" "struct refcnt *r" 41.Ft void 42.Fn "refcnt_rele_wake" "struct refcnt *r" 43.Ft void 44.Fn "refcnt_finalize" "struct refcnt *r" "const char *wmesg" 45.Ft int 46.Fn "refcnt_shared" "struct refcnt *r" 47.Ft unsigned int 48.Fn "refcnt_read" "struct refcnt *r" 49.Fn "REFCNT_INITIALIZER" 50.Sh DESCRIPTION 51The refcnt API provides simple reference counters that can be used 52to manage the lifetime of a shared object. 53.Pp 54.Fn refcnt_init 55sets the initial value of the counter to 1 to account for the caller's 56reference to the object. 57.Fn refcnt_init_trace 58additionally accepts a 59.Xr dt 4 60static probe index. 61.Pp 62.Fn refcnt_take 63is used to acquire a new reference. 64It is the responsibility of the caller to guarantee that it holds 65a valid reference before taking a new reference. 66.Pp 67.Fn refcnt_rele 68is used to release an existing reference. 69.Pp 70.Fn refcnt_rele_wake 71is used to release an existing reference and wakes up a process 72that is currently waiting in 73.Fn refcnt_finalize 74for all the references to be released. 75.Pp 76.Fn refcnt_finalize 77releases the caller's reference and sleeps until all the other 78references to the relevant object have been released. 79There may only be one caller to 80.Fn refcnt_finalize 81per refcnt 82.Fa r . 83.Pp 84.Fn refcnt_rele , 85.Fn refcnt_rele_wake 86and 87.Fn refcnt_finalize 88order prior memory loads and stores before the release of the reference. 89The functions enforce control dependency so that after the final reference 90has been released, subsequent loads and stores happen after the release. 91These ensure that concurrent accesses cease before the object's destructor 92runs and that the destructor sees all updates done during the lifetime 93of the object. 94.Pp 95.Fn refcnt_shared 96tests if the object has multiple references. 97.Pp 98.Fn refcnt_read 99returns a snapshot of the counter value. 100Its use is discouraged, 101code should use 102.Fn refcnt_shared 103whenever possible. 104.Pp 105.Fn REFCNT_INITIALIZER 106initialises a declaration of a refcnt to 1. 107.Sh CONTEXT 108.Fn refcnt_init , 109.Fn refcnt_init_trace , 110.Fn refcnt_take , 111.Fn refcnt_rele , 112.Fn refcnt_rele_wake , 113.Fn refcnt_shared 114and 115.Fn refcnt_read 116can be called during autoconf, from process context, or from interrupt 117context. 118.Pp 119.Fn refcnt_finalize 120can be called from process context. 121.Sh RETURN VALUES 122.Fn refcnt_rele 123returns a non-zero value if the last reference has been released, 124otherwise 0. 125.Pp 126.Fn refcnt_shared 127returns a non-zero value if the object has multiple references, 128otherwise 0. 129.Pp 130.Fn refcnt_read 131returns a snapshot of the counter value. 132