GRPC Core 0.10.0.0

- Main Page
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
sync.h
Go to the documentation of this file.
1 /*
2 *
3 * Copyright 2015, Google Inc.
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
8 * met:
9 *
10 * * Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above
13 * copyright notice, this list of conditions and the following disclaimer
14 * in the documentation and/or other materials provided with the
15 * distribution.
16 * * Neither the name of Google Inc. nor the names of its
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 */
33
34 #ifndef GRPC_SUPPORT_SYNC_H
35 #define GRPC_SUPPORT_SYNC_H
36 /* Synchronization primitives for GPR.
37
38 The type gpr_mu provides a non-reentrant mutex (lock).
39
40 The type gpr_cv provides a condition variable.
41
42 The type gpr_once provides for one-time initialization.
43
44 The type gpr_event provides one-time-setting, reading, and
45 waiting of a void*, with memory barriers.
46
47 The type gpr_refcount provides an object reference counter,
48 with memory barriers suitable to control
49 object lifetimes.
50
51 The type gpr_stats_counter provides an atomic statistics counter. It
52 provides no memory barriers.
53 */
54
55 /* Platform-specific type declarations of gpr_mu and gpr_cv. */
56 #include <grpc/support/port_platform.h>
57 #include <grpc/support/sync_generic.h>
58
59 #if defined(GPR_POSIX_SYNC)
60 #include <grpc/support/sync_posix.h>
61 #elif defined(GPR_WIN32)
62 #include <grpc/support/sync_win32.h>
63 #elif !defined(GPR_CUSTOM_SYNC)
64 #error Unable to determine platform for sync
65 #endif
66
67 #include <grpc/support/time.h> /* for gpr_timespec */
68 #include <grpc/support/cancellable_platform.h>
69
70 #ifdef __cplusplus
71 extern "C" {
72 #endif
73
74 /* --- Mutex interface ---
75
76 At most one thread may hold an exclusive lock on a mutex at any given time.
77 Actions taken by a thread that holds a mutex exclusively happen after
78 actions taken by all previous holders of the mutex. Variables of type
79 gpr_mu are uninitialized when first declared. */
80
81 /* Initialize *mu. Requires: *mu uninitialized. */
82 void gpr_mu_init(gpr_mu *mu);
83
84 /* Cause *mu no longer to be initialized, freeing any memory in use. Requires:
85 *mu initialized; no other concurrent operation on *mu. */
86 void gpr_mu_destroy(gpr_mu *mu);
87
88 /* Wait until no thread has a lock on *mu, cause the calling thread to own an
89 exclusive lock on *mu, then return. May block indefinitely or crash if the
90 calling thread has a lock on *mu. Requires: *mu initialized. */
91 void gpr_mu_lock(gpr_mu *mu);
92
93 /* Release an exclusive lock on *mu held by the calling thread. Requires: *mu
94 initialized; the calling thread holds an exclusive lock on *mu. */
95 void gpr_mu_unlock(gpr_mu *mu);
96
97 /* Without blocking, attempt to acquire an exclusive lock on *mu for the
98 calling thread, then return non-zero iff success. Fail, if any thread holds
99 the lock; succeeds with high probability if no thread holds the lock.
100 Requires: *mu initialized. */
101 int gpr_mu_trylock(gpr_mu *mu);
102
103 /* --- Condition variable interface ---
104
105 A while-loop should be used with gpr_cv_wait() when waiting for conditions
106 to become true. See the example below. Variables of type gpr_cv are
107 uninitialized when first declared. */
108
109 /* Initialize *cv. Requires: *cv uninitialized. */
110 void gpr_cv_init(gpr_cv *cv);
111
112 /* Cause *cv no longer to be initialized, freeing any memory in use. Requires:
113 *cv initialized; no other concurrent operation on *cv.*/
114 void gpr_cv_destroy(gpr_cv *cv);
115
116 /* Atomically release *mu and wait on *cv. When the calling thread is woken
117 from *cv or the deadline abs_deadline is exceeded, execute gpr_mu_lock(mu)
118 and return whether the deadline was exceeded. Use
119 abs_deadline==gpr_inf_future for no deadline. May return even when not
120 woken explicitly. Requires: *mu and *cv initialized; the calling thread
121 holds an exclusive lock on *mu. */
122 int gpr_cv_wait(gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline);
123
124 /* Behave like gpr_cv_wait(cv, mu, abs_deadline), except behave as though
125 the deadline has expired if *c is cancelled. */
126 int gpr_cv_cancellable_wait(gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline,
127 gpr_cancellable *c);
128
129 /* If any threads are waiting on *cv, wake at least one.
130 Clients may treat this as an optimization of gpr_cv_broadcast()
131 for use in the case where waking more than one waiter is not useful.
132 Requires: *cv initialized. */
133 void gpr_cv_signal(gpr_cv *cv);
134
135 /* Wake all threads waiting on *cv. Requires: *cv initialized. */
136 void gpr_cv_broadcast(gpr_cv *cv);
137
138 /* --- Cancellation ---
139 A gpr_cancellable can be used with gpr_cv_cancellable_wait()
140 or gpr_event_cancellable_wait() cancel pending waits. */
141
142 /* Initialize *c. */
143 void gpr_cancellable_init(gpr_cancellable *c);
144
145 /* Cause *c no longer to be initialized, freeing any memory in use. Requires:
146 *c initialized; no other concurrent operation on *c. */
147 void gpr_cancellable_destroy(gpr_cancellable *c);
148
149 /* Return non-zero iff *c has been cancelled. Requires *c initialized.
150 This call is faster than acquiring a mutex on most platforms. */
151 int gpr_cancellable_is_cancelled(gpr_cancellable *c);
152
153 /* Cancel *c. If *c was not previously cancelled, cause
154 gpr_cancellable_init() to return non-zero, and outstanding and future
155 calls to gpr_cv_cancellable_wait() and gpr_event_cancellable_wait() to
156 return immediately indicating a timeout has occurred; otherwise do nothing.
157 Requires *c initialized.*/
158 void gpr_cancellable_cancel(gpr_cancellable *c);
159
160 /* --- One-time initialization ---
161
162 gpr_once must be declared with static storage class, and initialized with
163 GPR_ONCE_INIT. e.g.,
164 static gpr_once once_var = GPR_ONCE_INIT; */
165
166 /* Ensure that (*init_routine)() has been called exactly once (for the
167 specified gpr_once instance) and then return.
168 If multiple threads call gpr_once() on the same gpr_once instance, one of
169 them will call (*init_routine)(), and the others will block until that call
170 finishes.*/
171 void gpr_once_init(gpr_once *once, void (*init_routine)(void));
172
173 /* --- One-time event notification ---
174
175 These operations act on a gpr_event, which should be initialized with
176 gpr_ev_init(), or with GPR_EVENT_INIT if static, e.g.,
177 static gpr_event event_var = GPR_EVENT_INIT;
178 It requires no destruction. */
179
180 /* Initialize *ev. */
181 void gpr_event_init(gpr_event *ev);
182
183 /* Set *ev so that gpr_event_get() and gpr_event_wait() will return value.
184 Requires: *ev initialized; value != NULL; no prior or concurrent calls to
185 gpr_event_set(ev, ...) since initialization. */
186 void gpr_event_set(gpr_event *ev, void *value);
187
188 /* Return the value set by gpr_event_set(ev, ...), or NULL if no such call has
189 completed. If the result is non-NULL, all operations that occurred prior to
190 the gpr_event_set(ev, ...) set will be visible after this call returns.
191 Requires: *ev initialized. This operation is faster than acquiring a mutex
192 on most platforms. */
193 void *gpr_event_get(gpr_event *ev);
194
195 /* Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is
196 exceeded, then return gpr_event_get(ev). Requires: *ev initialized. Use
197 abs_deadline==gpr_inf_future for no deadline. When the event has been
198 signalled before the call, this operation is faster than acquiring a mutex
199 on most platforms. */
200 void *gpr_event_wait(gpr_event *ev, gpr_timespec abs_deadline);
201
202 /* Behave like gpr_event_wait(ev, abs_deadline), except behave as though
203 the deadline has expired if *c is cancelled. */
204 void *gpr_event_cancellable_wait(gpr_event *ev, gpr_timespec abs_deadline,
205 gpr_cancellable *c);
206
207 /* --- Reference counting ---
208
209 These calls act on the type gpr_refcount. It requires no destruction. */
210
211 /* Initialize *r to value n. */
212 void gpr_ref_init(gpr_refcount *r, int n);
213
214 /* Increment the reference count *r. Requires *r initialized. */
215 void gpr_ref(gpr_refcount *r);
216
217 /* Increment the reference count *r by n. Requires *r initialized, n > 0. */
218 void gpr_refn(gpr_refcount *r, int n);
219
220 /* Decrement the reference count *r and return non-zero iff it has reached
221 zero. . Requires *r initialized. */
222 int gpr_unref(gpr_refcount *r);
223
224 /* --- Stats counters ---
225
226 These calls act on the integral type gpr_stats_counter. It requires no
227 destruction. Static instances may be initialized with
228 gpr_stats_counter c = GPR_STATS_INIT;
229 Beware: These operations do not imply memory barriers. Do not use them to
230 synchronize other events. */
231
232 /* Initialize *c to the value n. */
233 void gpr_stats_init(gpr_stats_counter *c, gpr_intptr n);
234
235 /* *c += inc. Requires: *c initialized. */
236 void gpr_stats_inc(gpr_stats_counter *c, gpr_intptr inc);
237
238 /* Return *c. Requires: *c initialized. */
239 gpr_intptr gpr_stats_read(const gpr_stats_counter *c);
240
241 /* ==================Example use of interface===================
242 A producer-consumer queue of up to N integers,
243 illustrating the use of the calls in this interface. */
244 #if 0
245
246 #define N 4
247
248 typedef struct queue {
249 gpr_cv non_empty; /* Signalled when length becomes non-zero. */
250 gpr_cv non_full; /* Signalled when length becomes non-N. */
251 gpr_mu mu; /* Protects all fields below.
252 (That is, except during initialization or
253 destruction, the fields below should be accessed
254 only by a thread that holds mu.) */
255 int head; /* Index of head of queue 0..N-1. */
256 int length; /* Number of valid elements in queue 0..N. */
257 int elem[N]; /* elem[head .. head+length-1] are queue elements. */
258 } queue;
259
260 /* Initialize *q. */
261 void queue_init(queue *q) {
262 gpr_mu_init(&q->mu);
263 gpr_cv_init(&q->non_empty);
264 gpr_cv_init(&q->non_full);
265 q->head = 0;
266 q->length = 0;
267 }
268
269 /* Free storage associated with *q. */
270 void queue_destroy(queue *q) {
271 gpr_mu_destroy(&q->mu);
272 gpr_cv_destroy(&q->non_empty);
273 gpr_cv_destroy(&q->non_full);
274 }
275
276 /* Wait until there is room in *q, then append x to *q. */
277 void queue_append(queue *q, int x) {
278 gpr_mu_lock(&q->mu);
279 /* To wait for a predicate without a deadline, loop on the negation of the
280 predicate, and use gpr_cv_wait(..., gpr_inf_future) inside the loop
281 to release the lock, wait, and reacquire on each iteration. Code that
282 makes the condition true should use gpr_cv_broadcast() on the
283 corresponding condition variable. The predicate must be on state
284 protected by the lock. */
285 while (q->length == N) {
286 gpr_cv_wait(&q->non_full, &q->mu, gpr_inf_future);
287 }
288 if (q->length == 0) { /* Wake threads blocked in queue_remove(). */
289 /* It's normal to use gpr_cv_broadcast() or gpr_signal() while
290 holding the lock. */
291 gpr_cv_broadcast(&q->non_empty);
292 }
293 q->elem[(q->head + q->length) % N] = x;
294 q->length++;
295 gpr_mu_unlock(&q->mu);
296 }
297
298 /* If it can be done without blocking, append x to *q and return non-zero.
299 Otherwise return 0. */
300 int queue_try_append(queue *q, int x) {
301 int result = 0;
302 if (gpr_mu_trylock(&q->mu)) {
303 if (q->length != N) {
304 if (q->length == 0) { /* Wake threads blocked in queue_remove(). */
305 gpr_cv_broadcast(&q->non_empty);
306 }
307 q->elem[(q->head + q->length) % N] = x;
308 q->length++;
309 result = 1;
310 }
311 gpr_mu_unlock(&q->mu);
312 }
313 return result;
314 }
315
316 /* Wait until the *q is non-empty or deadline abs_deadline passes. If the
317 queue is non-empty, remove its head entry, place it in *head, and return
318 non-zero. Otherwise return 0. */
319 int queue_remove(queue *q, int *head, gpr_timespec abs_deadline) {
320 int result = 0;
321 gpr_mu_lock(&q->mu);
322 /* To wait for a predicate with a deadline, loop on the negation of the
323 predicate or until gpr_cv_wait() returns true. Code that makes
324 the condition true should use gpr_cv_broadcast() on the corresponding
325 condition variable. The predicate must be on state protected by the
326 lock. */
327 while (q->length == 0 &&
328 !gpr_cv_wait(&q->non_empty, &q->mu, abs_deadline)) {
329 }
330 if (q->length != 0) { /* Queue is non-empty. */
331 result = 1;
332 if (q->length == N) { /* Wake threads blocked in queue_append(). */
333 gpr_cv_broadcast(&q->non_full);
334 }
335 *head = q->elem[q->head];
336 q->head = (q->head + 1) % N;
337 q->length--;
338 } /* else deadline exceeded */
339 gpr_mu_unlock(&q->mu);
340 return result;
341 }
342 #endif /* 0 */
343
344 #ifdef __cplusplus
345 }
346 #endif
347
348 #endif /* GRPC_SUPPORT_SYNC_H */
sync_posix.h
value
const char * value
Definition: hpack_table.c:44
gpr_mu_lock
void gpr_mu_lock(gpr_mu *mu)
gpr_ref
void gpr_ref(gpr_refcount *r)
Definition: sync.c:114
gpr_stats_inc
void gpr_stats_inc(gpr_stats_counter *c, gpr_intptr inc)
Definition: sync.c:130
gpr_event_get
void * gpr_event_get(gpr_event *ev)
Definition: sync.c:80
port_platform.h
gpr_cancellable_is_cancelled
int gpr_cancellable_is_cancelled(gpr_cancellable *c)
Definition: cancellable.c:51
gpr_intptr
intptr_t gpr_intptr
Definition: port_platform.h:312
gpr_refn
void gpr_refn(gpr_refcount *r, int n)
Definition: sync.c:116
gpr_refcount
Definition: sync_generic.h:49
gpr_once_init
void gpr_once_init(gpr_once *once, void(*init_routine)(void))
sync_generic.h
gpr_stats_read
gpr_intptr gpr_stats_read(const gpr_stats_counter *c)
Definition: sync.c:134
gpr_cv_destroy
void gpr_cv_destroy(gpr_cv *cv)
time.h
gpr_cv_cancellable_wait
int gpr_cv_cancellable_wait(gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline, gpr_cancellable *c)
Definition: cancellable.c:133
sync_win32.h
gpr_mu_trylock
int gpr_mu_trylock(gpr_mu *mu)
gpr_cv_wait
int gpr_cv_wait(gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline)
gpr_event_wait
void * gpr_event_wait(gpr_event *ev, gpr_timespec abs_deadline)
Definition: sync.c:84
gpr_inf_future
gpr_timespec gpr_inf_future(gpr_clock_type type)
Definition: time.c:83
gpr_event_set
void gpr_event_set(gpr_event *ev, void *value)
Definition: sync.c:70
gpr_once
pthread_once_t gpr_once
Definition: sync_posix.h:43
gpr_stats_counter
Definition: sync_generic.h:54
gpr_cv
pthread_cond_t gpr_cv
Definition: sync_posix.h:42
gpr_mu_init
void gpr_mu_init(gpr_mu *mu)
gpr_cancellable
Definition: cancellable_platform.h:50
gpr_unref
int gpr_unref(gpr_refcount *r)
Definition: sync.c:120
gpr_mu
Definition: sync_win32.h:39
gpr_cancellable_destroy
void gpr_cancellable_destroy(gpr_cancellable *c)
Definition: cancellable.c:49
gpr_mu_unlock
void gpr_mu_unlock(gpr_mu *mu)
gpr_cv_signal
void gpr_cv_signal(gpr_cv *cv)
gpr_cancellable_init
void gpr_cancellable_init(gpr_cancellable *c)
Definition: cancellable.c:40
gpr_cancellable_cancel
void gpr_cancellable_cancel(gpr_cancellable *c)
Definition: cancellable.c:81
cancellable_platform.h
gpr_cv_init
void gpr_cv_init(gpr_cv *cv)
gpr_stats_init
void gpr_stats_init(gpr_stats_counter *c, gpr_intptr n)
Definition: sync.c:126
gpr_event_cancellable_wait
void * gpr_event_cancellable_wait(gpr_event *ev, gpr_timespec abs_deadline, gpr_cancellable *c)
Definition: sync.c:97
gpr_event_init
void gpr_event_init(gpr_event *ev)
Definition: sync.c:65
gpr_mu_destroy
void gpr_mu_destroy(gpr_mu *mu)
gpr_timespec
Definition: time.h:60
gpr_event
Definition: sync_generic.h:41
gpr_cv_broadcast
void gpr_cv_broadcast(gpr_cv *cv)
gpr_ref_init
void gpr_ref_init(gpr_refcount *r, int n)
Definition: sync.c:112