From: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Date: Sat, 22 Jun 2013 17:13:22 +0000 (-0400)
Subject: doc/examples: enhance rcu-flavor-qsbr example
X-Git-Tag: v0.8.0~31
X-Git-Url: https://git.liburcu.org/?p=urcu.git;a=commitdiff_plain;h=71ea53b1c44c78bac18de7ac205bf1bdc4125353

doc/examples: enhance rcu-flavor-qsbr example

Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
---

diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index acdaaac..74e2666 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -4,6 +4,7 @@ doc_examples_rcu_flavor_qsbrdir = ${doc_examplesdir}/rcu-flavor-qsbr
 
 dist_doc_examples_rcu_flavor_qsbr_DATA = \
 	rcu-flavor-qsbr/Makefile \
+	rcu-flavor-qsbr/Makefile.rcu-flavor-qsbr \
 	rcu-flavor-qsbr/rcu-flavor-qsbr.c
 
 dist_doc_examples_DATA = \
diff --git a/doc/examples/rcu-flavor-qsbr/Makefile b/doc/examples/rcu-flavor-qsbr/Makefile
index b91d205..8e50722 100644
--- a/doc/examples/rcu-flavor-qsbr/Makefile
+++ b/doc/examples/rcu-flavor-qsbr/Makefile
@@ -11,21 +11,9 @@
 #
 # This makefile is purposefully kept simple to support GNU and BSD make.
 
-CC = gcc
-LIBS = -lurcu-qsbr
-CFLAGS = -g -O2 -Wall
-OBJECTS = rcu-flavor-qsbr.o
-
-all: rcu-flavor-qsbr
-
-rcu-flavor-qsbr: $(OBJECTS)
-	$(CC) $(CFLAGS) $(LDFLAGS) $(AM_CFLAGS) $(AM_LDFLAGS) \
-		$(LIBS) -o $@ $(OBJECTS)
-
-rcu-flavor-qsbr.o: rcu-flavor-qsbr.c
-	$(CC) $(CPPFLAGS) $(CFLAGS) $(AM_CPPFLAGS) $(AM_CFLAGS) \
-		-c -o $@ $<
+all:
+	$(MAKE) -f Makefile.rcu-flavor-qsbr
 
 .PHONY: clean
 clean:
-	rm -f *.o rcu-flavor-qsbr
+	$(MAKE) -f Makefile.rcu-flavor-qsbr clean
diff --git a/doc/examples/rcu-flavor-qsbr/Makefile.rcu-flavor-qsbr b/doc/examples/rcu-flavor-qsbr/Makefile.rcu-flavor-qsbr
new file mode 100644
index 0000000..fc85278
--- /dev/null
+++ b/doc/examples/rcu-flavor-qsbr/Makefile.rcu-flavor-qsbr
@@ -0,0 +1,21 @@
+# Copyright (C) 2013  Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+#
+# 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.
+#
+# This makefile is purposefully kept simple to support GNU and BSD make.
+
+EXAMPLE_NAME = rcu-flavor-qsbr
+
+SOURCES = $(EXAMPLE_NAME).c
+OBJECTS = $(EXAMPLE_NAME).o
+BINARY = $(EXAMPLE_NAME)
+LIBS = -lurcu-qsbr
+
+include ../Makefile.examples.template
diff --git a/doc/examples/rcu-flavor-qsbr/rcu-flavor-qsbr.c b/doc/examples/rcu-flavor-qsbr/rcu-flavor-qsbr.c
index a7a6ff4..2b722c0 100644
--- a/doc/examples/rcu-flavor-qsbr/rcu-flavor-qsbr.c
+++ b/doc/examples/rcu-flavor-qsbr/rcu-flavor-qsbr.c
@@ -16,16 +16,15 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
-#define _LGPL_SOURCE
-#include <urcu-qsbr.h>
-#include <urcu/rculist.h>
-#include <urcu/compiler.h>
-
 #include <stdlib.h>
 #include <stdio.h>
 #include <stdint.h>
 #include <inttypes.h>
 
+#include <urcu-qsbr.h>		/* QSBR RCU flavor */
+#include <urcu/rculist.h>	/* List example */
+#include <urcu/compiler.h>	/* For CAA_ARRAY_SIZE */
+
 /*
  * This is a mock-up example where updates and RCU traversals are
  * performed by the same thread to keep things simple on purpose.
@@ -110,7 +109,9 @@ int main(int argc, char **argv)
 
 	/*
 	 * For QSBR flavor, we need to explicitly announce quiescent
-	 * states.
+	 * states. Here is how it is done. This should be performed by
+	 * every online registered RCU threads in the program
+	 * periodically.
 	 */
 	rcu_quiescent_state();
 
@@ -127,7 +128,8 @@ int main(int argc, char **argv)
 
 	/*
 	 * Waiting for previously called call_rcu handlers to complete
-	 * before program exits is a good practice.
+	 * before program exits, or in library destructors, is a good
+	 * practice.
 	 */
 	rcu_barrier();