sync.h File Reference

#include <grpc/support/port_platform.h>
#include <grpc/support/time.h>
#include <grpc/support/sync_generic.h>

Go to the source code of this file.

Functions
GPRAPI void	gpr_mu_init (gpr_mu *mu)
	Synchronization primitives for GPR. More...
GPRAPI void	gpr_mu_destroy (gpr_mu *mu)
	Cause *mu no longer to be initialized, freeing any memory in use. More...
GPRAPI void	gpr_mu_lock (gpr_mu *mu)
	Wait until no thread has a lock on *mu, cause the calling thread to own an exclusive lock on *mu, then return. More...
GPRAPI void	gpr_mu_unlock (gpr_mu *mu)
	Release an exclusive lock on *mu held by the calling thread. More...
GPRAPI int	gpr_mu_trylock (gpr_mu *mu)
	Without blocking, attempt to acquire an exclusive lock on *mu for the calling thread, then return non-zero iff success. More...
GPRAPI void	gpr_cv_init (gpr_cv *cv)
	— Condition variable interface — More...
GPRAPI void	gpr_cv_destroy (gpr_cv *cv)
	Cause *cv no longer to be initialized, freeing any memory in use. More...
GPRAPI int	gpr_cv_wait (gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline)
	Atomically release *mu and wait on *cv. More...
GPRAPI void	gpr_cv_signal (gpr_cv *cv)
	If any threads are waiting on *cv, wake at least one. More...
GPRAPI void	gpr_cv_broadcast (gpr_cv *cv)
	Wake all threads waiting on *cv. More...
GPRAPI void	gpr_once_init (gpr_once *once, void(*init_function)(void))
	— One-time initialization — More...
GPRAPI void	gpr_event_init (gpr_event *ev)
	— One-time event notification — More...
GPRAPI void	gpr_event_set (gpr_event *ev, void *value)
	Set *ev so that gpr_event_get() and gpr_event_wait() will return value. More...
GPRAPI void *	gpr_event_get (gpr_event *ev)
	Return the value set by gpr_event_set(ev, ...), or NULL if no such call has completed. More...
GPRAPI void *	gpr_event_wait (gpr_event *ev, gpr_timespec abs_deadline)
	Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is exceeded, then return gpr_event_get(ev). More...
GPRAPI void	gpr_ref_init (gpr_refcount *r, int n)
	— Reference counting — More...
GPRAPI void	gpr_ref (gpr_refcount *r)
	Increment the reference count *r. More...
GPRAPI void	gpr_ref_non_zero (gpr_refcount *r)
	Increment the reference count *r. More...
GPRAPI void	gpr_refn (gpr_refcount *r, int n)
	Increment the reference count *r by n. More...
GPRAPI int	gpr_unref (gpr_refcount *r)
	Decrement the reference count *r and return non-zero iff it has reached zero. More...
GPRAPI int	gpr_ref_is_unique (gpr_refcount *r)
	Return non-zero iff the reference count of *r is one, and thus is owned by exactly one object. More...
GPRAPI void	gpr_stats_init (gpr_stats_counter *c, intptr_t n)
	— Stats counters — More...
GPRAPI void	gpr_stats_inc (gpr_stats_counter *c, intptr_t inc)
	*c += inc. More...
GPRAPI intptr_t	gpr_stats_read (const gpr_stats_counter *c)
	Return *c. More...

Function Documentation

gpr_cv_broadcast()

GPRAPI void gpr_cv_broadcast

(

gpr_cv *

cv

)

Wake all threads waiting on *cv.

Requires: *cv initialized.

gpr_cv_destroy()

GPRAPI void gpr_cv_destroy

(

gpr_cv *

cv

)

Cause *cv no longer to be initialized, freeing any memory in use.

Requires: cv initialized; no other concurrent operation on *cv.

gpr_cv_init()

GPRAPI void gpr_cv_init

(

gpr_cv *

cv

)

— Condition variable interface —

A while-loop should be used with gpr_cv_wait() when waiting for conditions to become true. See the example below. Variables of type gpr_cv are uninitialized when first declared.
Initialize *cv. Requires: *cv uninitialized.

gpr_cv_signal()

GPRAPI void gpr_cv_signal

(

gpr_cv *

cv

)

If any threads are waiting on *cv, wake at least one.

Clients may treat this as an optimization of gpr_cv_broadcast() for use in the case where waking more than one waiter is not useful. Requires: *cv initialized.

gpr_cv_wait()

GPRAPI int gpr_cv_wait	(	gpr_cv *	cv,
		gpr_mu *	mu,
		gpr_timespec	abs_deadline
	)

Atomically release *mu and wait on *cv.

When the calling thread is woken from *cv or the deadline abs_deadline is exceeded, execute gpr_mu_lock(mu) and return whether the deadline was exceeded. Use abs_deadline==gpr_inf_future for no deadline. abs_deadline can be either an absolute deadline, or a GPR_TIMESPAN. May return even when not woken explicitly. Requires: *mu and *cv initialized; the calling thread holds an exclusive lock on *mu.

gpr_event_get()

GPRAPI void* gpr_event_get

(

gpr_event *

ev

)

Return the value set by gpr_event_set(ev, ...), or NULL if no such call has completed.

If the result is non-NULL, all operations that occurred prior to the gpr_event_set(ev, ...) set will be visible after this call returns. Requires: *ev initialized. This operation is faster than acquiring a mutex on most platforms.

gpr_event_init()

GPRAPI void gpr_event_init

(

gpr_event *

ev

)

— One-time event notification —

These operations act on a gpr_event, which should be initialized with gpr_ev_init(), or with GPR_EVENT_INIT if static, e.g., static gpr_event event_var = GPR_EVENT_INIT; It requires no destruction.
Initialize *ev.

gpr_event_set()

GPRAPI void gpr_event_set	(	gpr_event *	ev,
		void *	value
	)

Set *ev so that gpr_event_get() and gpr_event_wait() will return value.

Requires: *ev initialized; value != NULL; no prior or concurrent calls to gpr_event_set(ev, ...) since initialization.

gpr_event_wait()

GPRAPI void* gpr_event_wait	(	gpr_event *	ev,
		gpr_timespec	abs_deadline
	)

Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is exceeded, then return gpr_event_get(ev).

Requires: *ev initialized. Use abs_deadline==gpr_inf_future for no deadline. When the event has been signalled before the call, this operation is faster than acquiring a mutex on most platforms.

gpr_mu_destroy()

GPRAPI void gpr_mu_destroy

(

gpr_mu *

mu

)

Cause *mu no longer to be initialized, freeing any memory in use.

Requires: mu initialized; no other concurrent operation on *mu.

gpr_mu_init()

GPRAPI void gpr_mu_init

(

gpr_mu *

mu

)

Synchronization primitives for GPR.

The type gpr_mu provides a non-reentrant mutex (lock).

The type gpr_cv provides a condition variable.

The type gpr_once provides for one-time initialization.

The type gpr_event provides one-time-setting, reading, and waiting of a void*, with memory barriers.

The type gpr_refcount provides an object reference counter, with memory barriers suitable to control object lifetimes.

The type gpr_stats_counter provides an atomic statistics counter. It provides no memory barriers. — Mutex interface —

At most one thread may hold an exclusive lock on a mutex at any given time. Actions taken by a thread that holds a mutex exclusively happen after actions taken by all previous holders of the mutex. Variables of type gpr_mu are uninitialized when first declared.
Initialize *mu. Requires: *mu uninitialized.

gpr_mu_lock()

GPRAPI void gpr_mu_lock

(

gpr_mu *

mu

)

Wait until no thread has a lock on *mu, cause the calling thread to own an exclusive lock on *mu, then return.

May block indefinitely or crash if the calling thread has a lock on *mu. Requires: *mu initialized.

gpr_mu_trylock()

GPRAPI int gpr_mu_trylock

(

gpr_mu *

mu

)

Without blocking, attempt to acquire an exclusive lock on *mu for the calling thread, then return non-zero iff success.

Fail, if any thread holds the lock; succeeds with high probability if no thread holds the lock. Requires: *mu initialized.

gpr_mu_unlock()

GPRAPI void gpr_mu_unlock

(

gpr_mu *

mu

)

Release an exclusive lock on *mu held by the calling thread.

Requires: *mu initialized; the calling thread holds an exclusive lock on *mu.

gpr_once_init()

GPRAPI void gpr_once_init	(	gpr_once *	once,
		void(*)(void)	init_function
	)

— One-time initialization —

gpr_once must be declared with static storage class, and initialized with GPR_ONCE_INIT. e.g., static gpr_once once_var = GPR_ONCE_INIT;
Ensure that (*init_function)() has been called exactly once (for the specified gpr_once instance) and then return. If multiple threads call gpr_once() on the same gpr_once instance, one of them will call (*init_function)(), and the others will block until that call finishes.

gpr_ref()

GPRAPI void gpr_ref

(

gpr_refcount *

r

)

Increment the reference count *r.

Requires *r initialized.

gpr_ref_init()

GPRAPI void gpr_ref_init	(	gpr_refcount *	r,
		int	n
	)

— Reference counting —

These calls act on the type gpr_refcount. It requires no destruction.
Initialize *r to value n.

gpr_ref_is_unique()

GPRAPI int gpr_ref_is_unique

(

gpr_refcount *

r

)

Return non-zero iff the reference count of *r is one, and thus is owned by exactly one object.

gpr_ref_non_zero()

GPRAPI void gpr_ref_non_zero

(

gpr_refcount *

r

)

Increment the reference count *r.

Requires *r initialized. Crashes if refcount is zero

gpr_refn()

GPRAPI void gpr_refn	(	gpr_refcount *	r,
		int	n
	)

Increment the reference count *r by n.

Requires *r initialized, n > 0.

gpr_stats_inc()

GPRAPI void gpr_stats_inc	(	gpr_stats_counter *	c,
		intptr_t	inc
	)

*c += inc.

Requires: *c initialized.

gpr_stats_init()

GPRAPI void gpr_stats_init	(	gpr_stats_counter *	c,
		intptr_t	n
	)

— Stats counters —

These calls act on the integral type gpr_stats_counter. It requires no destruction. Static instances may be initialized with gpr_stats_counter c = GPR_STATS_INIT; Beware: These operations do not imply memory barriers. Do not use them to synchronize other events.
Initialize *c to the value n.

gpr_stats_read()

GPRAPI intptr_t gpr_stats_read

(

const gpr_stats_counter *

c

)

Return *c.

Requires: *c initialized.

gpr_unref()

GPRAPI int gpr_unref

(

gpr_refcount *

r

)

Decrement the reference count *r and return non-zero iff it has reached zero.

. Requires *r initialized.