doc/examples/urcu-flavors/mb.c

   1 /*
   2  * Copyright (C) 2013  Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17  */
  18
  19 #include <unistd.h>
  20 #include <stdlib.h>
  21 #include <stdio.h>
  22 #include <stdint.h>
  23 #include <inttypes.h>
  24
  25 #include <urcu/urcu-mb.h>       /* Memory barrier RCU flavor */
  26 #include <urcu/rculist.h>       /* List example */
  27 #include <urcu/compiler.h>      /* For CAA_ARRAY_SIZE */
  28
  29 /*
  30  * Example showing how to use the memory-barrier-based Userspace RCU
  31  * flavor.
  32  *
  33  * This is a mock-up example where updates and RCU traversals are
  34  * performed by the same thread to keep things simple on purpose.
  35  */
  36
  37 static CDS_LIST_HEAD(mylist);
  38
  39 struct mynode {
  40         uint64_t value;
  41         struct cds_list_head node;      /* linked-list chaining */
  42         struct rcu_head rcu_head;       /* for call_rcu() */
  43 };
  44
  45 static
  46 int add_node(uint64_t v)
  47 {
  48         struct mynode *node;
  49
  50         node = calloc(sizeof(*node), 1);
  51         if (!node)
  52                 return -1;
  53         node->value = v;
  54         cds_list_add_rcu(&node->node, &mylist);
  55         return 0;
  56 }
  57
  58 static
  59 void rcu_free_node(struct rcu_head *rh)
  60 {
  61         struct mynode *node = caa_container_of(rh, struct mynode, rcu_head);
  62
  63         free(node);
  64 }
  65
  66 int main(int argc, char **argv)
  67 {
  68         uint64_t values[] = { 42, 36, 24, };
  69         unsigned int i;
  70         int ret;
  71         struct mynode *node, *n;
  72
  73         /*
  74          * Each thread need using RCU read-side need to be explicitly
  75          * registered.
  76          */
  77         urcu_mb_register_thread();
  78
  79         /*
  80          * Adding nodes to the linked-list. Safe against concurrent
  81          * RCU traversals, require mutual exclusion with list updates.
  82          */
  83         for (i = 0; i < CAA_ARRAY_SIZE(values); i++) {
  84                 ret = add_node(values[i]);
  85                 if (ret)
  86                         goto end;
  87         }
  88
  89         /*
  90          * We need to explicitly mark RCU read-side critical sections
  91          * with rcu_read_lock() and rcu_read_unlock(). They can be
  92          * nested. Those are no-ops for the QSBR flavor.
  93          */
  94         urcu_mb_read_lock();
  95
  96         /*
  97          * RCU traversal of the linked list.
  98          */
  99         cds_list_for_each_entry_rcu(node, &mylist, node) {
 100                 printf("Value: %" PRIu64 "\n", node->value);
 101         }
 102         urcu_mb_read_unlock();
 103
 104         /*
 105          * Removing nodes from linked list. Safe against concurrent RCU
 106          * traversals, require mutual exclusion with list updates.
 107          */
 108         cds_list_for_each_entry_safe(node, n, &mylist, node) {
 109                 cds_list_del_rcu(&node->node);
 110                 /*
 111                  * call_rcu() will ensure that the handler
 112                  * "rcu_free_node" is executed after a grace period.
 113                  * call_rcu() can be called from RCU read-side critical
 114                  * sections.
 115                  */
 116                 urcu_mb_call_rcu(&node->rcu_head, rcu_free_node);
 117         }
 118
 119         /*
 120          * We can also wait for a quiescent state by calling
 121          * synchronize_rcu() rather than using call_rcu(). It is usually
 122          * a slower approach than call_rcu(), because the latter can
 123          * batch work. Moreover, call_rcu() can be called from a RCU
 124          * read-side critical section, but synchronize_rcu() should not.
 125          */
 126         urcu_mb_synchronize_rcu();
 127
 128         sleep(1);
 129
 130         /*
 131          * Waiting for previously called call_rcu handlers to complete
 132          * before program exits, or in library destructors, is a good
 133          * practice.
 134          */
 135         urcu_mb_barrier();
 136
 137 end:
 138         urcu_mb_unregister_thread();
 139         return ret;
 140 }