+ * should not modify them.
+ *
+ *
+ * Thread-safety
+ * =============
+ *
+ * Except near the beginning or ending of its lifespan, rule 'rule' belongs to
+ * the classifier rule->ofproto->tables[rule->table_id].cls. The text below
+ * calls this classifier 'cls'.
+ *
+ * Motivation
+ * ----------
+ *
+ * The thread safety rules described here for "struct rule" are motivated by
+ * two goals:
+ *
+ * - Prevent threads that read members of "struct rule" from reading bad
+ * data due to changes by some thread concurrently modifying those
+ * members.
+ *
+ * - Prevent two threads making changes to members of a given "struct rule"
+ * from interfering with each other.
+ *
+ *
+ * Rules
+ * -----
+ *
+ * A rule 'rule' may be accessed without a risk of being freed by code that
+ * holds a read-lock or write-lock on 'cls->rwlock' or that owns a reference to
+ * 'rule->ref_count' (or both). Code that needs to hold onto a rule for a
+ * while should take 'cls->rwlock', find the rule it needs, increment
+ * 'rule->ref_count' with ofproto_rule_ref(), and drop 'cls->rwlock'.
+ *
+ * 'rule->ref_count' protects 'rule' from being freed. It doesn't protect the
+ * rule from being deleted from 'cls' (that's 'cls->rwlock') and it doesn't
+ * protect members of 'rule' from modification (that's 'rule->mutex').
+ *
+ * 'rule->mutex' protects the members of 'rule' from modification. It doesn't
+ * protect the rule from being deleted from 'cls' (that's 'cls->rwlock') and it
+ * doesn't prevent the rule from being freed (that's 'rule->ref_count').
+ *
+ * Regarding thread safety, the members of a rule fall into the following
+ * categories:
+ *
+ * - Immutable. These members are marked 'const'.
+ *
+ * - Members that may be safely read or written only by code holding
+ * ofproto_mutex. These are marked OVS_GUARDED_BY(ofproto_mutex).
+ *
+ * - Members that may be safely read only by code holding ofproto_mutex or
+ * 'rule->mutex', and safely written only by coding holding ofproto_mutex
+ * AND 'rule->mutex'. These are marked OVS_GUARDED.
+ */