GRPC Core  43.0.0
Functions
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.