1.\" $OpenBSD: smr_call.9,v 1.4 2022/06/22 14:10:49 visa Exp $ 2.\" 3.\" Copyright (c) 2019 Visa Hankala 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: June 22 2022 $ 18.Dt SMR_CALL 9 19.Os 20.Sh NAME 21.Nm smr_read_enter , 22.Nm smr_read_leave , 23.Nm smr_init , 24.Nm smr_call , 25.Nm smr_barrier , 26.Nm smr_flush , 27.Nm SMR_ASSERT_CRITICAL , 28.Nm SMR_ASSERT_NONCRITICAL 29.Nd safe memory reclamation 30.Sh SYNOPSIS 31.In sys/smr.h 32.Ft void 33.Fn smr_read_enter 34.Ft void 35.Fn smr_read_leave 36.Ft void 37.Fn smr_init "struct smr_entry *smr" 38.Ft void 39.Fn smr_call "struct smr_entry *smr" "void (*fn)(void *)" "void *arg" 40.Ft void 41.Fn smr_barrier 42.Ft void 43.Fn smr_flush 44.Ft void 45.Fn SMR_ASSERT_CRITICAL 46.Ft void 47.Fn SMR_ASSERT_NONCRITICAL 48.Sh DESCRIPTION 49The safe memory reclamation API provides a mechanism for reclaiming 50shared objects that readers can access without locking. 51Objects that are reclaimed through SMR are called SMR-protected. 52The mechanism guarantees that SMR-protected objects are not destroyed 53while readers are using them. 54However, it does not control how these objects are modified. 55.Pp 56Readers access SMR-protected objects inside an SMR read-side critical section 57using 58.Xr SMR_PTR_GET 9 . 59.\" or with a higher level API built on top of it. 60The section is entered with 61.Fn smr_read_enter , 62and exited with 63.Fn smr_read_leave . 64These routines never block. 65Sleeping is not allowed within SMR read-side critical section. 66.Pp 67.Fn smr_init 68initializes the entry 69.Fa smr 70for use with 71.Fn smr_call . 72.Pp 73.Fn smr_call 74schedules a callback to be invoked after the entry 75.Fa smr 76cannot be referenced by a reader in SMR read-side critical section. 77On invocation, the system calls function 78.Fa fn 79with argument 80.Fa arg 81in process context without any locks held. 82The implementation may delay the call in order to reduce 83overall system overhead by amortization. 84.Pp 85.Fn smr_barrier 86sleeps until any SMR read-side critical sections that are active on other CPUs 87at the time of invocation have ended. 88Like with 89.Fn smr_call , 90the processing of the request may be delayed. 91.Pp 92.Fn smr_flush 93is like 94.Fn smr_barrier 95but the system is forced to process the request as soon as possible. 96The use of this function is discouraged because of the heavy impact 97on system performance. 98.Pp 99To avoid deadlocks, the caller of 100.Fn smr_barrier 101or 102.Fn smr_flush 103must not hold locks that can block the processing of SMR callbacks. 104.Pp 105The SMR implementation does not limit the number of deferred calls. 106It is important to prevent arbitrary call rate of 107.Fn smr_call . 108Otherwise, it might be possible to exhaust system resources 109if the system is not able to invoke callbacks quickly enough. 110.Pp 111.Fn SMR_ASSERT_CRITICAL 112and 113.Fn SMR_ASSERT_NONCRITICAL 114can be used to assert that the current CPU is or is not 115in SMR read-side critical section. 116.Sh CONTEXT 117.Fn smr_read_enter , 118.Fn smr_read_leave , 119.Fn smr_call 120and 121.Fn smr_init 122can be called during autoconf, from process context, or from interrupt context. 123.Pp 124.Fn smr_barrier 125and 126.Fn smr_flush 127can be called from process context. 128.Sh SEE ALSO 129.Xr mutex 9 , 130.Xr rwlock 9 , 131.Xr SMR_LIST_INIT 9 , 132.Xr SMR_PTR_GET 9 133.Sh HISTORY 134The SMR API first appeared in 135.Ox 6.5 . 136