1.\" $OpenBSD: refcnt_init.9,v 1.3 2022/04/30 14:44:04 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: April 30 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_rele , 78.Fn refcnt_rele_wake 79and 80.Fn refcnt_finalize 81order prior memory loads and stores before the release of the reference. 82The functions enforce control dependency so that after the final reference 83has been released, subsequent loads and stores happen after the release. 84These ensure that concurrent accesses cease before the object's destructor 85runs and that the destructor sees all updates done during the lifetime 86of the object. 87.Pp 88.Fn refcnt_shared 89tests if the object has multiple references. 90.Pp 91.Fn refcnt_read 92returns a snapshot of the counter value. 93Its use is discouraged, 94code should use 95.Fn refcnt_shared 96whenever possible. 97.Pp 98.Fn REFCNT_INITIALIZER 99initialises a declaration of a refcnt to 1. 100.Sh CONTEXT 101.Fn refcnt_init , 102.Fn refcnt_take , 103.Fn refcnt_rele , 104.Fn refcnt_rele_wake , 105.Fn refcnt_shared 106and 107.Fn refcnt_read 108can be called during autoconf, from process context, or from interrupt 109context. 110.Pp 111.Fn refcnt_finalize 112can be called from process context. 113.Sh RETURN VALUES 114.Fn refcnt_rele 115returns a non-zero value if the last reference has been released, 116otherwise 0. 117.Pp 118.Fn refcnt_shared 119returns a non-zero value if the object has multiple references, 120otherwise 0. 121.Pp 122.Fn refcnt_read 123returns a snapshot of the counter value. 124