GRPC C++  1.62.0
sync.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2015 gRPC authors.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  */
18 
19 #ifndef GRPC_SUPPORT_SYNC_H
20 #define GRPC_SUPPORT_SYNC_H
21 
22 /* Platform-specific type declarations of gpr_mu and gpr_cv. */
24 
25 #include <grpc/support/time.h> /* for gpr_timespec */
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
50 #include <grpc/support/sync_generic.h> // IWYU pragma: export
51 
52 #if defined(GPR_CUSTOM_SYNC)
53 #include <grpc/support/sync_custom.h> // IWYU pragma: export
54 #elif defined(GPR_ABSEIL_SYNC)
55 #include <grpc/support/sync_abseil.h> // IWYU pragma: export
56 #elif defined(GPR_POSIX_SYNC)
57 #include <grpc/support/sync_posix.h> // IWYU pragma: export
58 #elif defined(GPR_WINDOWS)
59 #include <grpc/support/sync_windows.h> // IWYU pragma: export
60 #else
61 #error Unable to determine platform for sync
62 #endif
63 
72 GPRAPI void gpr_mu_init(gpr_mu* mu);
73 
76 GPRAPI void gpr_mu_destroy(gpr_mu* mu);
77 
81 GPRAPI void gpr_mu_lock(gpr_mu* mu);
82 
85 GPRAPI void gpr_mu_unlock(gpr_mu* mu);
86 
92 
100 GPRAPI void gpr_cv_init(gpr_cv* cv);
101 
104 GPRAPI void gpr_cv_destroy(gpr_cv* cv);
105 
113 GPRAPI int gpr_cv_wait(gpr_cv* cv, gpr_mu* mu, gpr_timespec abs_deadline);
114 
119 GPRAPI void gpr_cv_signal(gpr_cv* cv);
120 
122 GPRAPI void gpr_cv_broadcast(gpr_cv* cv);
123 
135 GPRAPI void gpr_once_init(gpr_once* once, void (*init_function)(void));
136 
146 
150 GPRAPI void gpr_event_set(gpr_event* ev, void* value);
151 
157 GPRAPI void* gpr_event_get(gpr_event* ev);
158 
164 GPRAPI void* gpr_event_wait(gpr_event* ev, gpr_timespec abs_deadline);
165 
171 GPRAPI void gpr_ref_init(gpr_refcount* r, int n);
172 
174 GPRAPI void gpr_ref(gpr_refcount* r);
175 
179 
181 GPRAPI void gpr_refn(gpr_refcount* r, int n);
182 
186 
190 
200 GPRAPI void gpr_stats_init(gpr_stats_counter* c, intptr_t n);
201 
203 GPRAPI void gpr_stats_inc(gpr_stats_counter* c, intptr_t inc);
204 
206 GPRAPI intptr_t gpr_stats_read(const gpr_stats_counter* c);
207 
211 #if 0
212 
213 #define N 4
214 
215  typedef struct queue {
216  gpr_cv non_empty; /* Signalled when length becomes non-zero. */
217  gpr_cv non_full; /* Signalled when length becomes non-N. */
218  gpr_mu mu; /* Protects all fields below.
219  (That is, except during initialization or
220  destruction, the fields below should be accessed
221  only by a thread that holds mu.) */
222  int head; /* Index of head of queue 0..N-1. */
223  int length; /* Number of valid elements in queue 0..N. */
224  int elem[N]; /* elem[head .. head+length-1] are queue elements. */
225  } queue;
226 
227  /* Initialize *q. */
228  void queue_init(queue *q) {
229  gpr_mu_init(&q->mu);
230  gpr_cv_init(&q->non_empty);
231  gpr_cv_init(&q->non_full);
232  q->head = 0;
233  q->length = 0;
234  }
235 
236  /* Free storage associated with *q. */
237  void queue_destroy(queue *q) {
238  gpr_mu_destroy(&q->mu);
239  gpr_cv_destroy(&q->non_empty);
240  gpr_cv_destroy(&q->non_full);
241  }
242 
243  /* Wait until there is room in *q, then append x to *q. */
244  void queue_append(queue *q, int x) {
245  gpr_mu_lock(&q->mu);
246  /* To wait for a predicate without a deadline, loop on the negation of the
247  predicate, and use gpr_cv_wait(..., gpr_inf_future) inside the loop
248  to release the lock, wait, and reacquire on each iteration. Code that
249  makes the condition true should use gpr_cv_broadcast() on the
250  corresponding condition variable. The predicate must be on state
251  protected by the lock. */
252  while (q->length == N) {
253  gpr_cv_wait(&q->non_full, &q->mu, gpr_inf_future);
254  }
255  if (q->length == 0) { /* Wake threads blocked in queue_remove(). */
256  /* It's normal to use gpr_cv_broadcast() or gpr_signal() while
257  holding the lock. */
258  gpr_cv_broadcast(&q->non_empty);
259  }
260  q->elem[(q->head + q->length) % N] = x;
261  q->length++;
262  gpr_mu_unlock(&q->mu);
263  }
264 
265  /* If it can be done without blocking, append x to *q and return non-zero.
266  Otherwise return 0. */
267  int queue_try_append(queue *q, int x) {
268  int result = 0;
269  if (gpr_mu_trylock(&q->mu)) {
270  if (q->length != N) {
271  if (q->length == 0) { /* Wake threads blocked in queue_remove(). */
272  gpr_cv_broadcast(&q->non_empty);
273  }
274  q->elem[(q->head + q->length) % N] = x;
275  q->length++;
276  result = 1;
277  }
278  gpr_mu_unlock(&q->mu);
279  }
280  return result;
281  }
282 
283  /* Wait until the *q is non-empty or deadline abs_deadline passes. If the
284  queue is non-empty, remove its head entry, place it in *head, and return
285  non-zero. Otherwise return 0. */
286  int queue_remove(queue *q, int *head, gpr_timespec abs_deadline) {
287  int result = 0;
288  gpr_mu_lock(&q->mu);
289  /* To wait for a predicate with a deadline, loop on the negation of the
290  predicate or until gpr_cv_wait() returns true. Code that makes
291  the condition true should use gpr_cv_broadcast() on the corresponding
292  condition variable. The predicate must be on state protected by the
293  lock. */
294  while (q->length == 0 &&
295  !gpr_cv_wait(&q->non_empty, &q->mu, abs_deadline)) {
296  }
297  if (q->length != 0) { /* Queue is non-empty. */
298  result = 1;
299  if (q->length == N) { /* Wake threads blocked in queue_append(). */
300  gpr_cv_broadcast(&q->non_full);
301  }
302  *head = q->elem[q->head];
303  q->head = (q->head + 1) % N;
304  q->length--;
305  } /* else deadline exceeded */
306  gpr_mu_unlock(&q->mu);
307  return result;
308  }
309 #endif /* 0 */
310 
311 #ifdef __cplusplus
312 } // extern "C"
313 #endif
314 
315 #endif /* GRPC_SUPPORT_SYNC_H */
gpr_ref
GPRAPI void gpr_ref(gpr_refcount *r)
Increment the reference count *r.
gpr_mu
pthread_mutex_t gpr_mu
Definition: sync_posix.h:45
gpr_mu_destroy
GPRAPI void gpr_mu_destroy(gpr_mu *mu)
Cause *mu no longer to be initialized, freeing any memory in use.
gpr_once_init
GPRAPI void gpr_once_init(gpr_once *once, void(*init_function)(void))
— One-time initialization —
gpr_stats_read
GPRAPI intptr_t gpr_stats_read(const gpr_stats_counter *c)
Return *c.
sync_windows.h
sync_abseil.h
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.
gpr_inf_future
GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type)
The far future.
gpr_event_init
GPRAPI void gpr_event_init(gpr_event *ev)
— One-time event notification —
gpr_refcount
Definition: sync_generic.h:37
gpr_stats_counter
Definition: sync_generic.h:42
gpr_ref_init
GPRAPI void gpr_ref_init(gpr_refcount *r, int n)
— Reference counting —
gpr_cv_init
GPRAPI void gpr_cv_init(gpr_cv *cv)
— Condition variable interface —
gpr_cv_destroy
GPRAPI void gpr_cv_destroy(gpr_cv *cv)
Cause *cv no longer to be initialized, freeing any memory in use.
gpr_once
pthread_once_t gpr_once
Definition: sync_posix.h:48
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.
sync_generic.h
gpr_stats_inc
GPRAPI void gpr_stats_inc(gpr_stats_counter *c, intptr_t inc)
*c += inc.
gpr_cv_signal
GPRAPI void gpr_cv_signal(gpr_cv *cv)
If any threads are waiting on *cv, wake at least one.
gpr_cv
pthread_cond_t gpr_cv
Definition: sync_posix.h:46
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,...
GPRAPI
#define GPRAPI
Definition: port_platform.h:718
gpr_cv_broadcast
GPRAPI void gpr_cv_broadcast(gpr_cv *cv)
Wake all threads waiting on *cv.
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,...
sync_custom.h
gpr_event
Definition: sync_generic.h:29
gpr_mu_unlock
GPRAPI void gpr_mu_unlock(gpr_mu *mu)
Release an exclusive lock on *mu held by the calling thread.
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_g...
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_stats_init
GPRAPI void gpr_stats_init(gpr_stats_counter *c, intptr_t n)
— Stats counters —
gpr_unref
GPRAPI int gpr_unref(gpr_refcount *r)
Decrement the reference count *r and return non-zero iff it has reached zero.
gpr_refn
GPRAPI void gpr_refn(gpr_refcount *r, int n)
Increment the reference count *r by n.
sync_posix.h
gpr_mu_init
GPRAPI void gpr_mu_init(gpr_mu *mu)
Synchronization primitives for GPR.
gpr_timespec
Analogous to struct timespec.
Definition: time.h:48
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.
gpr_ref_non_zero
GPRAPI void gpr_ref_non_zero(gpr_refcount *r)
Increment the reference count *r.
time.h
port_platform.h