From: Mathieu Desnoyers Date: Mon, 3 Jun 2013 20:18:34 +0000 (-0400) Subject: Add QSBR minimal example X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=ad510be0c46853f598268218ca71de60f4ebd94f;p=urcu.git Add QSBR minimal example Signed-off-by: Mathieu Desnoyers --- diff --git a/configure.ac b/configure.ac index da560a4..058be20 100644 --- a/configure.ac +++ b/configure.ac @@ -290,6 +290,7 @@ AC_CONFIG_LINKS([ AC_CONFIG_FILES([ Makefile doc/Makefile + doc/examples/Makefile tests/Makefile liburcu.pc liburcu-bp.pc diff --git a/doc/Makefile.am b/doc/Makefile.am index 3422653..d98f16b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1 +1,3 @@ +SUBDIRS = examples + dist_doc_DATA = rcu-api.txt cds-api.txt uatomic-api.txt diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am new file mode 100644 index 0000000..4583b5b --- /dev/null +++ b/doc/examples/Makefile.am @@ -0,0 +1,12 @@ +SUBDIRS = qsbr-minimal + +doc_examplesdir = ${docdir}/examples + +doc_examples_qsbr_minimaldir = ${doc_examplesdir}/qsbr-minimal + +doc_examples_qsbr_minimal_DATA = \ + qsbr-minimal/Makefile \ + qsbr-minimal/qsbr-minimal.c + +BUILD_EXAMPLES_FROM_TREE = 1 +export diff --git a/doc/examples/qsbr-minimal/Makefile b/doc/examples/qsbr-minimal/Makefile new file mode 100644 index 0000000..5fe65bc --- /dev/null +++ b/doc/examples/qsbr-minimal/Makefile @@ -0,0 +1,43 @@ +# Copyright (C) 2013 Mathieu Desnoyers +# +# THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED +# OR IMPLIED. ANY USE IS AT YOUR OWN RISK. +# +# Permission is hereby granted to use or copy this program for any +# purpose, provided the above notices are retained on all copies. +# Permission to modify the code and to distribute modified code is +# granted, provided the above notices are retained, and a notice that +# the code was modified is included with the above copyright notice. + +CC = gcc +LIBS = -lurcu-qsbr +CFLAGS = -g -O2 + +# Only necessary when building from the source tree and userspace RCU is +# not installed +ifdef BUILD_EXAMPLES_FROM_TREE +LOCAL_CPPFLAGS += -I../../../urcu/ +LIBURCU_QSBR_PATH = ../../../.libs/ +override LDFLAGS += -L$(LIBURCU_QSBR_PATH) -Wl,-rpath='$$ORIGIN/$(LIBURCU_QSBR_PATH)' + +# Third-party Makefiles have to define these targets to integrate with an +# automake project +EMPTY_AUTOMAKE_TARGETS = distdir install install-data install-exec uninstall \ + install-dvi install-html install-info install-ps install-pdf \ + installdirs check installcheck mostlyclean distclean maintainer-clean \ + dvi pdf ps info tags ctags +.PHONY: $(EMPTY_AUTOMAKE_TARGETS) +$(EMPTY_AUTOMAKE_TARGETS): +endif + +all: qsbr-minimal + +qsbr-minimal: qsbr-minimal.o + $(CC) -o $@ $^ $(LDFLAGS) $(LIBS) + +qsbr-minimal.o: qsbr-minimal.c + $(CC) $(CPPFLAGS) $(LOCAL_CPPFLAGS) $(CFLAGS) -c -o $@ $< + +.PHONY: clean +clean: + rm -f *.o qsbr-minimal diff --git a/doc/examples/qsbr-minimal/qsbr-minimal.c b/doc/examples/qsbr-minimal/qsbr-minimal.c new file mode 100644 index 0000000..acb8c8a --- /dev/null +++ b/doc/examples/qsbr-minimal/qsbr-minimal.c @@ -0,0 +1,136 @@ +/* + * Copyright (C) 2013 Mathieu Desnoyers + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#define _LGPL_SOURCE +#include +#include +#include + +#include +#include +#include +#include + +/* + * This is a mock-up example where updates and RCU traversals are + * performed by the same thread to keep things simple on purpose. + */ + +static CDS_LIST_HEAD(mylist); + +struct mynode { + uint64_t value; + struct cds_list_head node; /* linked-list chaining */ + struct rcu_head rcu_head; /* for call_rcu() */ +}; + +static +int add_node(uint64_t v) +{ + struct mynode *node; + + node = calloc(sizeof(*node), 1); + if (!node) + return -1; + node->value = v; + cds_list_add_rcu(&node->node, &mylist); +} + +static +void rcu_free_node(struct rcu_head *rh) +{ + struct mynode *node = caa_container_of(rh, struct mynode, rcu_head); + + free(node); +} + +int main(int argc, char **argv) +{ + uint64_t values[] = { 42, 36, 24, }; + unsigned int i; + int ret; + struct mynode *node, *n; + + /* + * Each thread need using RCU read-side need to be explicitely + * registered. + */ + rcu_register_thread(); + + /* + * Adding nodes to the linked-list. Safe against concurrent + * RCU traversals, require mutual exclusion with list updates. + */ + for (i = 0; i < CAA_ARRAY_SIZE(values); i++) { + ret = add_node(values[i]); + if (ret) + goto end; + } + + /* + * For all RCU flavors except QSBR, we need to explicitly mark + * RCU read-side critical sections with rcu_read_lock() and + * rcu_read_unlock(). They can be nested. Those are no-ops for + * the QSBR flavor. + */ + rcu_read_lock(); + + /* + * RCU traversal of the linked list. + */ + cds_list_for_each_entry_rcu(node, &mylist, node) { + printf("Value: %" PRIu64 "\n", node->value); + } + rcu_read_unlock(); + + /* + * Removing nodes from linked list. Safe against concurrent RCU + * traversals, require mutual exclusion with list updates. + */ + cds_list_for_each_entry_safe(node, n, &mylist, node) { + cds_list_del_rcu(&node->node); + call_rcu(&node->rcu_head, rcu_free_node); + } + + /* + * For QSBR flavor, we need to explicitly announce quiescent + * states. + */ + rcu_quiescent_state(); + + /* + * For QSBR flavor, when a thread needs to be in a quiescent + * state for a long period of time, we use rcu_thread_offline() + * and rcu_thread_online(). + */ + rcu_thread_offline(); + + sleep(1); + + rcu_thread_online(); + + /* + * Waiting for previously called call_rcu handlers to complete + * before program exits is a good practice. + */ + rcu_barrier(); + +end: + rcu_unregister_thread(); + return ret; +}