SMR_CALL(9) | Kernel Developer's Manual | SMR_CALL(9)

# NAME

`smr_read_enter`, `smr_read_leave`, `smr_init`, `smr_call`, `smr_barrier`, `smr_flush`, `SMR_ASSERT_CRITICAL`, `SMR_ASSERT_NONCRITICAL` — safe memory reclamation

# SYNOPSIS

`#include <sys/smr.h>`

void
`smr_read_enter`();

void
`smr_read_leave`();

void
`smr_init`(struct smr_entry *smr);

void
`smr_call`(struct smr_entry *smr, void (*fn)(void *), void *arg);

void
`smr_barrier`();

void
`smr_flush`();

void
`SMR_ASSERT_CRITICAL`();

void
`SMR_ASSERT_NONCRITICAL`();

# DESCRIPTION

The safe memory reclamation API provides a mechanism for reclaiming shared objects that readers can access without locking. Objects that are reclaimed through SMR are called SMR-protected. The mechanism guarantees that SMR-protected objects are not destroyed while readers are using them. However, it does not control how these objects are modified.

Readers access SMR-protected objects inside an SMR read-side critical section using SMR_PTR_GET(9). The section is entered with `smr_read_enter`(), and exited with `smr_read_leave`(). These routines never block. Sleeping is not allowed within SMR read-side critical section.

`smr_init`() initializes the entry smr for use with `smr_call`().

`smr_call`() schedules a callback to be invoked after the entry smr cannot be referenced by a reader in SMR read-side critical section. On invocation, the system calls function fn with argument arg in process context without any locks held. The implementation may delay the call in order to reduce overall system overhead by amortization.

`smr_barrier`() sleeps until any SMR read-side critical sections that are active on other CPUs at the time of invocation have ended. Like with `smr_call`(), the processing of the request may be delayed.

`smr_flush`() is like `smr_barrier`() but the system is forced to process the request as soon as possible. The use of this function is discouraged because of the heavy impact on system performance.

To avoid deadlocks, the caller of `smr_barrier`() or `smr_flush`() must not hold locks that can block the processing of SMR callbacks.

The SMR implementation does not limit the number of deferred calls. It is important to prevent arbitrary call rate of `smr_call`(). Otherwise, it might be possible to exhaust system resources if the system is not able to invoke callbacks quickly enough.

`SMR_ASSERT_CRITICAL`() and `SMR_ASSERT_NONCRITICAL`() can be used to assert that the current CPU is or is not in SMR read-side critical section.

# CONTEXT

`smr_read_enter`(), `smr_read_leave`(), `smr_call`() and `smr_init`() can be called during autoconf, from process context, or from interrupt context.

`smr_barrier`() and `smr_flush`() can be called from process context.

# SEE ALSO

mutex(9), rwlock(9), SMR_LIST_INIT(9), SMR_PTR_GET(9)

# HISTORY

The SMR API first appeared in OpenBSD 6.5.

June 22, 2022 | Debian