doc/examples/urcu-flavors/qsbr.c

   1 // SPDX-FileCopyrightText: 2013 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   2 //
   3 // SPDX-License-Identifier: LGPL-2.1-or-later
   4
   5 #include <unistd.h>
   6 #include <stdlib.h>
   7 #include <stdio.h>
   8 #include <stdint.h>
   9 #include <inttypes.h>
  10
  11 #include <urcu/urcu-qsbr.h>     /* QSBR RCU flavor */
  12 #include <urcu/rculist.h>       /* List example */
  13 #include <urcu/compiler.h>      /* For CAA_ARRAY_SIZE */
  14
  15 /*
  16  * Example showing how to use the QSBR Userspace RCU flavor.
  17  *
  18  * This is a mock-up example where updates and RCU traversals are
  19  * performed by the same thread to keep things simple on purpose.
  20  */
  21
  22 static CDS_LIST_HEAD(mylist);
  23
  24 struct mynode {
  25         uint64_t value;
  26         struct cds_list_head node;      /* linked-list chaining */
  27         struct rcu_head rcu_head;       /* for call_rcu() */
  28 };
  29
  30 static
  31 int add_node(uint64_t v)
  32 {
  33         struct mynode *node;
  34
  35         node = calloc(1, sizeof(*node));
  36         if (!node)
  37                 return -1;
  38         node->value = v;
  39         cds_list_add_rcu(&node->node, &mylist);
  40         return 0;
  41 }
  42
  43 static
  44 void rcu_free_node(struct rcu_head *rh)
  45 {
  46         struct mynode *node = caa_container_of(rh, struct mynode, rcu_head);
  47
  48         free(node);
  49 }
  50
  51 int main(void)
  52 {
  53         uint64_t values[] = { 42, 36, 24, };
  54         unsigned int i;
  55         int ret;
  56         struct mynode *node, *n;
  57
  58         /*
  59          * Each thread need using RCU read-side need to be explicitly
  60          * registered.
  61          */
  62         urcu_qsbr_register_thread();
  63
  64         /*
  65          * Adding nodes to the linked-list. Safe against concurrent
  66          * RCU traversals, require mutual exclusion with list updates.
  67          */
  68         for (i = 0; i < CAA_ARRAY_SIZE(values); i++) {
  69                 ret = add_node(values[i]);
  70                 if (ret)
  71                         goto end;
  72         }
  73
  74         /*
  75          * RCU traversal of the linked list.
  76          */
  77         cds_list_for_each_entry_rcu(node, &mylist, node) {
  78                 printf("Value: %" PRIu64 "\n", node->value);
  79         }
  80
  81         /*
  82          * Removing nodes from linked list. Safe against concurrent RCU
  83          * traversals, require mutual exclusion with list updates.
  84          */
  85         cds_list_for_each_entry_safe(node, n, &mylist, node) {
  86                 cds_list_del_rcu(&node->node);
  87                 /*
  88                  * call_rcu() will ensure that the handler
  89                  * "rcu_free_node" is executed after a grace period.
  90                  * call_rcu() can be called from RCU read-side critical
  91                  * sections.
  92                  */
  93                 urcu_qsbr_call_rcu(&node->rcu_head, rcu_free_node);
  94         }
  95
  96         /*
  97          * For QSBR flavor, we need to explicitly announce quiescent
  98          * states. Here is how it is done. This should be performed by
  99          * every online registered RCU threads in the program
 100          * periodically.
 101          */
 102         urcu_qsbr_quiescent_state();
 103
 104         /*
 105          * For QSBR flavor, when a thread needs to be in a quiescent
 106          * state for a long period of time, we use rcu_thread_offline()
 107          * and rcu_thread_online().
 108          */
 109         urcu_qsbr_thread_offline();
 110
 111         sleep(1);
 112
 113         urcu_qsbr_thread_online();
 114
 115         /*
 116          * We can also wait for a quiescent state by calling
 117          * synchronize_rcu() rather than using call_rcu(). It is usually
 118          * a slower approach than call_rcu(), because the latter can
 119          * batch work. Moreover, call_rcu() can be called from a RCU
 120          * read-side critical section, but synchronize_rcu() ensures the
 121          * caller thread is offline, thus acting as a quiescent state.
 122          */
 123         urcu_qsbr_synchronize_rcu();
 124
 125         /*
 126          * Waiting for previously called call_rcu handlers to complete
 127          * before program exits, or in library destructors, is a good
 128          * practice.
 129          */
 130         urcu_qsbr_barrier();
 131
 132 end:
 133         urcu_qsbr_unregister_thread();
 134         return ret;
 135 }