[urcu.git] / doc / rcu-api.txt

Userspace RCU API
by Mathieu Desnoyers and Paul E. McKenney


void rcu_init(void);

	This must be called before any of the following functions
	are invoked.

void rcu_read_lock(void);

	Begin an RCU read-side critical section.  These critical
	sections may be nested.

void rcu_read_unlock(void);

	End an RCU read-side critical section.

void rcu_register_thread(void);

	Each thread must invoke this function before its first call to
	rcu_read_lock().  Threads that never call rcu_read_lock() need
	not invoke this function.  In addition, rcu-bp ("bullet proof"
	RCU) does not require any thread to invoke rcu_register_thread().

void rcu_unregister_thread(void);

	Each thread that invokes rcu_register_thread() must invoke
	rcu_unregister_thread() before invoking pthread_exit()
	or before returning from its top-level function.

void synchronize_rcu(void);

	Wait until every pre-existing RCU read-side critical section
	has completed.  Note that this primitive will not necessarily
	wait for RCU read-side critical sections that have not yet
	started: this is not a reader-writer lock.  The duration
	actually waited is called an RCU grace period.

void call_rcu(struct rcu_head *head,
	      void (*func)(struct rcu_head *head));

	Registers the callback indicated by "head".  This means
	that "func" will be invoked after the end of a future
	RCU grace period.  The rcu_head structure referenced
	by "head" will normally be a field in a larger RCU-protected
	structure.  A typical implementation of "func" is as
	follows:

		void func(struct rcu_head *head)
		{
			struct foo *p = container_of(head, struct foo, rcu);

			free(p);
		}

	This RCU callback function can be registered as follows
	given a pointer "p" to the enclosing structure:

		call_rcu(&p->rcu, func);

	call_rcu should be called from registered RCU read-side threads.
	For the QSBR flavor, the caller should be online.

void rcu_barrier(void);

	Wait for all call_rcu() work initiated prior to rcu_barrier() by
	_any_ thread on the system to have completed before rcu_barrier()
	returns. rcu_barrier() should never be called from a call_rcu()
	thread. This function can be used, for instance, to ensure that
	all memory reclaim involving a shared object has completed
	before allowing dlclose() of this shared object to complete.

struct call_rcu_data *create_call_rcu_data(unsigned long flags,
					   int cpu_affinity);

	Returns a handle that can be passed to the following
	primitives.  The "flags" argument can be zero, or can be
	URCU_CALL_RCU_RT if the worker threads associated with the
	new helper thread are to get real-time response. The argument
	"cpu_affinity" specifies a cpu on which the call_rcu thread should
	be affined to. It is ignored if negative.

void call_rcu_data_free(struct call_rcu_data *crdp);

	Terminates a call_rcu() helper thread and frees its associated
	data.  The caller must have ensured that this thread is no longer
	in use, for example, by passing NULL to set_thread_call_rcu_data()
	and set_cpu_call_rcu_data() as required.

struct call_rcu_data *get_default_call_rcu_data(void);

	Returns the handle for the default call_rcu() helper thread.
	Creates it if necessary.

struct call_rcu_data *get_cpu_call_rcu_data(int cpu);

	Returns the handle for the current cpu's call_rcu() helper
	thread, or NULL if the current CPU has no helper thread
	currently assigned. The call to this function and use of the
	returned call_rcu_data should be protected by RCU read-side
	lock.

struct call_rcu_data *get_thread_call_rcu_data(void);

	Returns the handle for the current thread's hard-assigned
	call_rcu() helper thread, or NULL if the current thread is
	instead using a per-CPU or the default helper thread.

struct call_rcu_data *get_call_rcu_data(void);

	Returns the handle for the current thread's call_rcu() helper
	thread, which is either, in increasing order of preference:
	per-thread hard-assigned helper thread, per-cpu helper thread,
	or default helper thread. get_call_rcu_data should be called
	from registered RCU read-side threads. For the QSBR flavor, the
	caller should be online.

pthread_t get_call_rcu_thread(struct call_rcu_data *crdp);

	Returns the helper thread's pthread identifier linked to a call
	rcu helper thread data.

void set_thread_call_rcu_data(struct call_rcu_data *crdp);

	Sets the current thread's hard-assigned call_rcu() helper to the
	handle specified by "crdp".  Note that "crdp" can be NULL to
	disassociate this thread from its helper.  Once a thread is
	disassociated from its helper, further call_rcu() invocations
	use the current CPU's helper if there is one and the default
	helper otherwise.

int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp);

	Sets the specified CPU's call_rcu() helper to the handle
	specified by "crdp".  Again, "crdp" can be NULL to disassociate
	this CPU from its helper thread.  Once a CPU has been
	disassociated from its helper, further call_rcu() invocations
	that would otherwise have used this CPU's helper will instead
	use the default helper.  The caller must wait for a grace-period
	to pass between return from set_cpu_call_rcu_data() and call to
	call_rcu_data_free() passing the previous call rcu data as
	argument.

int create_all_cpu_call_rcu_data(unsigned long flags)

	Creates a separate call_rcu() helper thread for each CPU.
	After this primitive is invoked, the global default call_rcu()
	helper thread will not be called.

	The set_thread_call_rcu_data(), set_cpu_call_rcu_data(), and
	create_all_cpu_call_rcu_data() functions may be combined to set up
	pretty much any desired association between worker and call_rcu()
	helper threads.  If a given executable calls only call_rcu(),
	then that executable will have only the single global default
	call_rcu() helper thread.  This will suffice in most cases.

void free_all_cpu_call_rcu_data(void);

	Clean up all the per-CPU call_rcu threads. Should be paired with
	create_all_cpu_call_rcu_data() to perform teardown. Note that
	this function invokes synchronize_rcu() internally, so the
	caller should be careful not to hold mutexes (or mutexes within a
	dependency chain) that are also taken within a RCU read-side
	critical section, or in a section where QSBR threads are online.

void call_rcu_after_fork_child(void);

	Should be used as pthread_atfork() handler for programs using
	call_rcu and performing fork() or clone() without a following
	exec().
Commit	Line	Data
26ba798a PM	1	Userspace RCU API
	2	by Mathieu Desnoyers and Paul E. McKenney
	3
	4
	5	void rcu_init(void);
	6
	7	This must be called before any of the following functions
	8	are invoked.
	9
	10	void rcu_read_lock(void);
	11
	12	Begin an RCU read-side critical section. These critical
	13	sections may be nested.
	14
	15	void rcu_read_unlock(void);
	16
	17	End an RCU read-side critical section.
	18
f9da0936	19	void rcu_register_thread(void);
26ba798a PM	20
	21	Each thread must invoke this function before its first call to
	22	rcu_read_lock(). Threads that never call rcu_read_lock() need
	23	not invoke this function. In addition, rcu-bp ("bullet proof"
	24	RCU) does not require any thread to invoke rcu_register_thread().
	25
f9da0936	26	void rcu_unregister_thread(void);
26ba798a PM	27
	28	Each thread that invokes rcu_register_thread() must invoke
	29	rcu_unregister_thread() before invoking pthread_exit()
	30	or before returning from its top-level function.
	31
	32	void synchronize_rcu(void);
	33
	34	Wait until every pre-existing RCU read-side critical section
	35	has completed. Note that this primitive will not necessarily
	36	wait for RCU read-side critical sections that have not yet
	37	started: this is not a reader-writer lock. The duration
	38	actually waited is called an RCU grace period.
	39
	40	void call_rcu(struct rcu_head *head,
	41	void (func)(struct rcu_head head));
	42
	43	Registers the callback indicated by "head". This means
	44	that "func" will be invoked after the end of a future
	45	RCU grace period. The rcu_head structure referenced
	46	by "head" will normally be a field in a larger RCU-protected
	47	structure. A typical implementation of "func" is as
	48	follows:
	49
	50	void func(struct rcu_head *head)
	51	{
	52	struct foo *p = container_of(head, struct foo, rcu);
	53
	54	free(p);
	55	}
	56
	57	This RCU callback function can be registered as follows
	58	given a pointer "p" to the enclosing structure:
	59
	60	call_rcu(&p->rcu, func);
	61
f9da0936 MD	62	call_rcu should be called from registered RCU read-side threads.
	63	For the QSBR flavor, the caller should be online.
	64
5e338f70 MD	65	void rcu_barrier(void);
	66
	67	Wait for all call_rcu() work initiated prior to rcu_barrier() by
	68	_any_ thread on the system to have completed before rcu_barrier()
	69	returns. rcu_barrier() should never be called from a call_rcu()
	70	thread. This function can be used, for instance, to ensure that
	71	all memory reclaim involving a shared object has completed
	72	before allowing dlclose() of this shared object to complete.
	73
c1d2c60b MD	74	struct call_rcu_data *create_call_rcu_data(unsigned long flags,
c1d2c60b MD	75	int cpu_affinity);
26ba798a PM	76
	77	Returns a handle that can be passed to the following
	78	primitives. The "flags" argument can be zero, or can be
	79	URCU_CALL_RCU_RT if the worker threads associated with the
c1d2c60b MD	80	new helper thread are to get real-time response. The argument
	81	"cpu_affinity" specifies a cpu on which the call_rcu thread should
	82	be affined to. It is ignored if negative.
26ba798a	83
f9da0936 MD	84	void call_rcu_data_free(struct call_rcu_data *crdp);
	85
	86	Terminates a call_rcu() helper thread and frees its associated
	87	data. The caller must have ensured that this thread is no longer
	88	in use, for example, by passing NULL to set_thread_call_rcu_data()
	89	and set_cpu_call_rcu_data() as required.
	90
	91	struct call_rcu_data *get_default_call_rcu_data(void);
	92
	93	Returns the handle for the default call_rcu() helper thread.
	94	Creates it if necessary.
	95
	96	struct call_rcu_data *get_cpu_call_rcu_data(int cpu);
	97
	98	Returns the handle for the current cpu's call_rcu() helper
	99	thread, or NULL if the current CPU has no helper thread
	100	currently assigned. The call to this function and use of the
	101	returned call_rcu_data should be protected by RCU read-side
	102	lock.
26ba798a PM	103
	104	struct call_rcu_data *get_thread_call_rcu_data(void);
	105
	106	Returns the handle for the current thread's hard-assigned
	107	call_rcu() helper thread, or NULL if the current thread is
	108	instead using a per-CPU or the default helper thread.
	109
f9da0936 MD	110	struct call_rcu_data *get_call_rcu_data(void);
	111
	112	Returns the handle for the current thread's call_rcu() helper
	113	thread, which is either, in increasing order of preference:
	114	per-thread hard-assigned helper thread, per-cpu helper thread,
b1f69e84 MD	115	or default helper thread. get_call_rcu_data should be called
	116	from registered RCU read-side threads. For the QSBR flavor, the
	117	caller should be online.
f9da0936 MD	118
	119	pthread_t get_call_rcu_thread(struct call_rcu_data *crdp);
	120
	121	Returns the helper thread's pthread identifier linked to a call
	122	rcu helper thread data.
	123
26ba798a PM	124	void set_thread_call_rcu_data(struct call_rcu_data *crdp);
	125
	126	Sets the current thread's hard-assigned call_rcu() helper to the
	127	handle specified by "crdp". Note that "crdp" can be NULL to
	128	disassociate this thread from its helper. Once a thread is
	129	disassociated from its helper, further call_rcu() invocations
	130	use the current CPU's helper if there is one and the default
	131	helper otherwise.
	132
	133	int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp);
	134
	135	Sets the specified CPU's call_rcu() helper to the handle
	136	specified by "crdp". Again, "crdp" can be NULL to disassociate
	137	this CPU from its helper thread. Once a CPU has been
	138	disassociated from its helper, further call_rcu() invocations
	139	that would otherwise have used this CPU's helper will instead
f9da0936 MD	140	use the default helper. The caller must wait for a grace-period
	141	to pass between return from set_cpu_call_rcu_data() and call to
	142	call_rcu_data_free() passing the previous call rcu data as
	143	argument.
26ba798a PM	144
	145	int create_all_cpu_call_rcu_data(unsigned long flags)
	146
	147	Creates a separate call_rcu() helper thread for each CPU.
	148	After this primitive is invoked, the global default call_rcu()
	149	helper thread will not be called.
	150
	151	The set_thread_call_rcu_data(), set_cpu_call_rcu_data(), and
	152	create_all_cpu_call_rcu_data() functions may be combined to set up
	153	pretty much any desired association between worker and call_rcu()
	154	helper threads. If a given executable calls only call_rcu(),
	155	then that executable will have only the single global default
	156	call_rcu() helper thread. This will suffice in most cases.
	157
f9da0936	158	void free_all_cpu_call_rcu_data(void);
26ba798a	159
f9da0936 MD	160	Clean up all the per-CPU call_rcu threads. Should be paired with
	161	create_all_cpu_call_rcu_data() to perform teardown. Note that
	162	this function invokes synchronize_rcu() internally, so the
	163	caller should be careful not to hold mutexes (or mutexes within a
	164	dependency chain) that are also taken within a RCU read-side
	165	critical section, or in a section where QSBR threads are online.
	166
	167	void call_rcu_after_fork_child(void);
	168
	169	Should be used as pthread_atfork() handler for programs using
	170	call_rcu and performing fork() or clone() without a following
	171	exec().