[ovs-dev] [PATCH] classifier: Documentation clarifications.
Jarno Rajahalme
jrajahalme at nicira.com
Sat Jun 6 19:48:37 UTC 2015
Signed-off-by: Jarno Rajahalme <jrajahalme at nicira.com>
---
lib/classifier.h | 63 +++++++++++++++++++++++++++++++++++-------------------
1 file changed, 41 insertions(+), 22 deletions(-)
diff --git a/lib/classifier.h b/lib/classifier.h
index 2798752..f41fed3 100644
--- a/lib/classifier.h
+++ b/lib/classifier.h
@@ -227,24 +227,25 @@
* in a way to not remove the rule before all ongoing lookups are finished, the
* rule should be marked as "to be deleted" by setting the rule's visibility to
* the negation of the last version number in which it should be visible.
- * Then, when all the lookups use that future version number, the rule can be
- * actually deleted from the classifier. A rule that is marked for deletion in
- * a future version will not appear in iterations, although it will still be
- * found by lookups using an earlier lookup version number.
+ * Then, when all the lookups use a later version number, the rule can be
+ * actually deleted from the classifier. A rule that is marked for deletion
+ * after a future version will not appear in iterations, although it will still
+ * be found by lookups using a lookup version number up to that future version
+ * number.
*
* Classifiers can hold duplicate rules (rules with the same match criteria and
- * priority) when at most one of the duplicates is visible in any given lookup
- * version. The caller responsible for classifier modifications must maintain
- * this invariant.
+ * priority) when at most one of the duplicates with the same priority is
+ * visible in any given lookup version. The caller responsible for classifier
+ * modifications must maintain this invariant.
*
* The classifier supports versioning for two reasons:
*
- * 1. Support for versioned modifications makes it possible to support
- * an arbitraty series of classifier changes as one atomic transaction,
+ * 1. Support for versioned modifications makes it possible to perform an
+ * arbitraty series of classifier changes as one atomic transaction,
* where intermediate versions of the classifier are not visible to any
* lookups. Also, when a rule is added for a future version, or marked
- * for removal in a future version, such modifications can be reverted
- * without any visible effects to any of the current lookup versions.
+ * for removal after the current version, such modifications can be
+ * reverted without any visible effects to any of the current lookups.
*
* 2. Performance: Adding (or deleting) a large set of rules can, in
* pathological cases, have a cost proportional to the number of rules
@@ -253,23 +254,28 @@
* typically avoided, as long as it is OK for any new rules to be
* invisible until the batch change is complete.
*
+ * Note that the classifier_replace() function replaces a rule immediately, and
+ * is therefore not safe to use with versioning. It is still available for the
+ * users that do not use versioning.
+ *
*
* Deferred Publication
* ====================
*
* Removing large number of rules from classifier can be costly, as the
- * supporting data structures are teared down, just to be re-instantiated right
- * after. In the worst case, as when each rule has a different match pattern
- * (mask), the maintenance of the match pattern can have cost O(N^2), where N
- * is the number of different match patterns. To alleviate this, the
- * classifier supports a "deferred mode", in which changes in internal data
- * structures used for lookups may not be fully computed yet. The computation
- * is finalized when the deferred mode is turned off.
+ * supporting data structures are teared down, in many cases just to be
+ * re-instantiated right after. In the worst case, as when each rule has a
+ * different match pattern (mask), the maintenance of the match patterns can
+ * have cost O(N^2), where N is the number of different match patterns. To
+ * alleviate this, the classifier supports a "deferred mode", in which changes
+ * in internal data structures needed for future version lookups may not be
+ * fully computed yet. The computation is finalized when the deferred mode is
+ * turned off.
*
* This feature can be used with versioning such that all changes to future
- * versions are made in the deferred mode. Then, right before making the new
+ * versions are made in the deferred mode. Then, right before making the new
* version visible to lookups, the deferred mode is turned off so that all the
- * data structures are ready for lookups.
+ * data structures are ready for lookups with the new version number.
*
* To use deferred publication, first call classifier_defer(). Then, modify
* the classifier via additions (classifier_insert() with a specific, future
@@ -281,8 +287,21 @@
* Thread-safety
* =============
*
- * The classifier may safely be accessed by many reader threads concurrently or
- * by a single writer. */
+ * The classifier may safely be accessed by many reader threads concurrently
+ * and by a single writer, or by multiple writers when they guarantee mutually
+ * exlucive access to classifier modifications.
+ *
+ * Since the classifier rules are RCU protected, the rule destruction after
+ * removal from the classifier must be RCU postponed. Also, when versioning is
+ * used, the rule removal itself needs to be typically RCU postponed. In this
+ * case the rule destruction is doubly RCU postponed, i.e., the second
+ * ovsrcu_postpone() call to destruct the rule is called from the first RCU
+ * callback that removes the rule.
+ *
+ * Rules that have never been visible to lookups are an exeption to the above
+ * rule. Such rules can be removed immediately, but their destruction must
+ * still be RCU postponed, as the rule's visibility attribute may be examined
+ * parallel to the rule's removal. */
#include "cmap.h"
#include "match.h"
--
1.7.10.4
More information about the dev
mailing list