The Read-Copy-Update (RCU) mechanism is a paradigm of memory synchronisation first popularised by the Linux kernel. More...

Files
file	rcu.c
	Read-Copy-Update (RCU) definitions.

file	rcu.h
	Read-Copy-Update (RCU) declarations.

Functions
void	vlc_rcu_read_lock (void)
	Begins a read-side RCU critical section. More...

void	vlc_rcu_read_unlock (void)
	Ends a read-side RCU critical section. More...

VLC_USED bool	vlc_rcu_read_held (void)
	Checks if the thread is in an read-side RCU critical section. More...

void	vlc_rcu_synchronize (void)
	Waits for completion of earlier read-side RCU critical section. More...

Detailed Description

The Read-Copy-Update (RCU) mechanism is a paradigm of memory synchronisation first popularised by the Linux kernel.

It is essentially a mean to safely use atomic pointers, without encountering use-after-free and other lifecycle bugs.

It is an advantageous substitute for the classic reader/writer lock with the following notable differences:

The read side is completely lock-free and wait-free.
The write side is guaranteed to make forward progress even if there are perpetually active readers, provided that all read sides are each individually finitely long.
The protected data consists of a single atomic object, typically an atomic pointer (not to be confused with a pointer to an atomic object).
There is no synchronisation object. RCU maintains its state globally, and with a modicum of per-thread state.

The practical use of RCU differs from reader/writer lock in the following ways:

There is no synchronisation object, so there are no needs for initialisation and destruction.
The directly protected objects are atom, so they must be accessed with atomic type-generics. Specifically:
- Objects are read with atomic load-acquire.
- Objects are written with atomic store-release.
There are no writer lock and unlock functions. Instead there is a synchronisation function, vlc_rcu_synchronize(), which waits for all earlier read-side critical sections to complete.
Synchronisation between concurrent writers is not provided. If multiple writers can race against each other, a separate mutual exclusion lock for interlocking.

Function Documentation

◆ vlc_rcu_read_held()

VLC_USED bool vlc_rcu_read_held ( void )

Checks if the thread is in an read-side RCU critical section.

This function checks if the thread is in a middle of one or more read-side RCU critical section(s). It has no side effects and is primarily meant for self-debugging.

Return values

true	the calling thread is in a read-side RCU critical section.
false	the calling thread is not in a read-side RCU critical section.

References current, and vlc_rcu_thread::recursion.

Referenced by vlc_rcu_read_unlock(), and vlc_rcu_synchronize().

◆ vlc_rcu_read_lock()

void vlc_rcu_read_lock ( void )

Begins a read-side RCU critical section.

This function marks the beginning of a read-side RCU critical section. For the duration of the critical section, RCU-protected data is guaranteed to remain valid, although it might be slightly stale.

To access RCU-protect data, an atomic load-acquire should be used.

Note: Read-side RCU critical section can be nested.

References current, vlc_rcu_thread::generation, generation, vlc_rcu_generation::readers, and vlc_rcu_thread::recursion.

Referenced by config_GetPsz(), config_SaveConfigFile(), and vlc_vaLogSwitch().

◆ vlc_rcu_read_unlock()

void vlc_rcu_read_unlock ( void )

Ends a read-side RCU critical section.

This function marks the end of a read-side RCU critical section. After this function is called, RCU-protected data may be destroyed and can no longer be accessed safely.

Note: In the case of nested critical sections, this function notionally ends the inner-most critical section. In practice, this makes no differences, as the calling thread remains in a critical section until the number of vlc_rcu_read_unlock() calls equals that of vlc_rcu_read_lock() calls.

References current, vlc_rcu_thread::generation, vlc_rcu_generation::readers, vlc_rcu_thread::recursion, unlikely, vlc_assert_unreachable, vlc_atomic_notify_one(), vlc_rcu_read_held(), and vlc_rcu_generation::writer.

Referenced by config_GetPsz(), config_SaveConfigFile(), and vlc_vaLogSwitch().

◆ vlc_rcu_synchronize()

void vlc_rcu_synchronize ( void )

Waits for completion of earlier read-side RCU critical section.

This functions waits until all read-side RCU critical sections that had begun before to complete. Then it is safe to release resources associated with the earlier value(s) of any RCU-protected atomic object.

References ARRAY_SIZE, generation, gens, vlc_rcu_generation::readers, vlc_atomic_wait(), vlc_mutex_lock(), vlc_mutex_unlock(), vlc_rcu_read_held(), vlc_rcu_generation::writer, and writer_lock.

Referenced by vlc_LogSwitch(), and vlc_param_SetString().