ck_epoch_synchronize(3)

1CK_EPOCH_SYNCHRONIZE(3)  BSD Library Functions Manual  CK_EPOCH_SYNCHRONIZE(3)
2

NAME

4     ck_epoch_synchronize — block until a grace period has been detected
5

LIBRARY

7     Concurrency Kit (libck, -lck)
8

SYNOPSIS

10     #include <ck_epoch.h>
11
12     void
13     ck_epoch_synchronize(ck_epoch_record_t *record);
14

DESCRIPTION

16     The ck_epoch_synchronize(3) function will block the caller until a grace
17     period has been detected, according to the semantics of epoch reclama‐
18     tion.  It is not safe to call this function on a record that is in an
19     active section.  Any objects requiring safe memory reclamation which are
20     logically deleted are safe for physical deletion following a call to
21     ck_epoch_synchronize(3).  If you require that all callbacks be dis‐
22     patched, then it is suggested that you use ck_epoch_barrier(3) instead or
23     follow a call of ck_epoch_synchronize(3) with ck_epoch_reclaim(3).
24

EXAMPLE

26           #include <ck_epoch.h>
27           #include <ck_stack.h>
28           #include <stdlib.h>
29
30           /*
31            * epoch was previously initialized with ck_epoch_init.
32            * stack was previously initialized with ck_stack_init.
33            */
34           ck_epoch_t *epoch;
35           ck_stack_t *stack;
36
37           void
38           function(void)
39           {
40                   ck_epoch_record_t *record;
41                   ck_stack_entry_t *s;
42
43                   record = malloc(sizeof *record);
44                   ck_epoch_register(&epoch, record);
45
46                   /*
47                    * We are using an epoch section here to guarantee no
48                    * nodes in the stack are deleted while we are dereferencing
49                    * them. This is needed here because there are multiple writers.
50                    * If there was only one thread popping from the this stack,
51                    * then there is no need to ck_epoch_begin/ck_epoch_end.
52                    */
53                   ck_epoch_begin(record);
54
55                   /* Logically delete an object. */
56                   s = ck_stack_pop_upmc(stack);
57
58                   ck_epoch_end(record);
59
60                   /*
61                    * Wait until no threads could possibly have a reference to the
62                    * object we just popped (assume all threads are simply executing
63                    * ck_stack_pop_upmc).
64                    */
65                   ck_epoch_synchronize(record);
66
67                   /* It is now safe to physically delete the object. */
68                   free(s);
69                   return;
70           }
71

RETURN VALUES

73     This function has no return value.
74

ERRORS

76     The object pointed to by .Fa record must have been previously registered
77     via ck_epoch_register(3).
78