Read-Copy-Update (RCU)

Read-Copy-Update (RCU) primitive. More...

Collaboration diagram for Read-Copy-Update (RCU):

Detailed Description

Read-Copy-Update (RCU) primitive.

RCU is a synchronization mechanism that allows readers to access shared data structures concurrently with writers, without using locks.

Implementation

RCU works by delaying the freeing of a resource until its known to be impossible for any CPU to be using said resource.

This is implemented by allowing the resource to persist for a grace period, which is defined as the time taken for all CPUs to pass through a quiescent state. A quiescent state is any point at which the CPU is known to not be accessing RCU protected data.

In our case, it is illegal for a context switch to occur while accessing RCU protected data, as preemption is disabled using rcu_read_lock(). Therefor, we know that once all CPUs, which were not idle, have performed a context switch, they must have passed through a quiescent state and it is thus safe to free any pending resources.

Using RCU

Using RCU is fairly straightforward, any data structure that is to be protected by RCU must include a rcu_entry_t member, when the structure is to be freed after use rcu_call() should be called with the address of the rcu_entry_t member and a callback function that will free the structure.

To access RCU protected data, a read-side critical section must be created using rcu_read_lock() and rcu_read_unlock(), or the RCU_READ_SCOPE() macro.

See also

Wikipedia for more information about RCU.

kernel.org for a explanation of RCU in the Linux Kernel.

Data Structures
struct	rcu_entry_t
	Intrusive RCU head structure. More...

Macros
#define	RCU_READ_SCOPE()
	RCU read-side critical section for the current scope.

Typedefs
typedef void(*	rcu_callback_t) (void *arg)
	RCU callback function type.

Functions
static void	rcu_read_lock (void)
	RCU read-side critical section begin.
static void	rcu_read_unlock (void)
	RCU read-side critical section end.
void	rcu_synchronize (void)
	Wait for all pre-existing RCU read-side critical sections to complete.
void	rcu_call (rcu_entry_t *entry, rcu_callback_t func, void *arg)
	Add a callback to be executed after a grace period.
void	rcu_report_quiescent (void)
	Called during a context switch to report a quiescent state.
void	rcu_call_free (void *arg)
	Helper callback to free a pointer.
void	rcu_call_cache_free (void *arg)
	Helper callback to free a cache object.
static void	rcu_read_unlock_cleanup (int *_)

Macro Definition Documentation

RCU_READ_SCOPE

#define RCU_READ_SCOPE

(

)

Value:

    rcu_read_lock(); \
    __attribute__((cleanup(rcu_read_unlock_cleanup))) int CONCAT(r, __COUNTER__) = 1;

RCU read-side critical section for the current scope.

Definition at line 93 of file rcu.h.

Typedef Documentation

rcu_callback_t

typedef void(* rcu_callback_t) (void *arg)

RCU callback function type.

Parameters

rcu	The RCU entry being processed.

Definition at line 56 of file rcu.h.

Function Documentation

rcu_read_lock()

static void rcu_read_lock ( void  )

inlinestatic

RCU read-side critical section begin.

Should be called before accessing RCU protected data.

Definition at line 75 of file rcu.h.

Here is the call graph for this function:

Here is the caller graph for this function:

rcu_read_unlock()

static void rcu_read_unlock ( void  )

inlinestatic

RCU read-side critical section end.

Should be called after accessing RCU protected data.

Definition at line 85 of file rcu.h.

Here is the call graph for this function:

Here is the caller graph for this function:

rcu_synchronize()

void rcu_synchronize

(

void

)

Wait for all pre-existing RCU read-side critical sections to complete.

This function blocks until all RCU read-side critical sections that were active at the time of the call have completed.

Definition at line 56 of file rcu.c.

Here is the call graph for this function:

rcu_call()

void rcu_call	(	rcu_entry_t *	entry,
		rcu_callback_t	func,
		void *	arg
	)

Add a callback to be executed after a grace period.

Parameters

entry	The RCU entry structure embedded in the object to be freed.
func	The callback function to execute.

Definition at line 72 of file rcu.c.

Here is the call graph for this function:

Here is the caller graph for this function:

rcu_report_quiescent()

void rcu_report_quiescent

(

void

)

Called during a context switch to report a quiescent state.

Definition at line 173 of file rcu.c.

Here is the call graph for this function:

Here is the caller graph for this function:

rcu_call_free()

void rcu_call_free

(

void *

arg

)

Helper callback to free a pointer.

Can be used as a generic callback to free memory allocated with malloc().

Parameters

arg	The pointer to free.

Definition at line 188 of file rcu.c.

Here is the call graph for this function:

Here is the caller graph for this function:

rcu_call_cache_free()

void rcu_call_cache_free

(

void *

arg

)

Helper callback to free a cache object.

Can be used as a generic callback to free memory allocated from a cache.

Parameters

arg	The pointer to free.

Definition at line 193 of file rcu.c.

Here is the call graph for this function:

Here is the caller graph for this function:

rcu_read_unlock_cleanup()

static void rcu_read_unlock_cleanup ( int *  _ )

inlinestatic

Definition at line 136 of file rcu.h.

Here is the call graph for this function: