+/* A flow in dp_netdev's 'flow_table'.
+ *
+ *
+ * Thread-safety
+ * =============
+ *
+ * Except near the beginning or ending of its lifespan, rule 'rule' belongs to
+ * its dp_netdev's classifier. The text below calls this classifier 'cls'.
+ *
+ * Motivation
+ * ----------
+ *
+ * The thread safety rules described here for "struct dp_netdev_flow" are
+ * motivated by two goals:
+ *
+ * - Prevent threads that read members of "struct dp_netdev_flow" 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
+ * dp_netdev_flow" from interfering with each other.
+ *
+ *
+ * Rules
+ * -----
+ *
+ * A flow 'flow' 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
+ * 'flow->ref_cnt' (or both). Code that needs to hold onto a flow for a while
+ * should take 'cls->rwlock', find the flow it needs, increment 'flow->ref_cnt'
+ * with dpif_netdev_flow_ref(), and drop 'cls->rwlock'.
+ *
+ * 'flow->ref_cnt' protects 'flow' from being freed. It doesn't protect the
+ * flow from being deleted from 'cls' (that's 'cls->rwlock') and it doesn't
+ * protect members of 'flow' from modification (that's 'flow->mutex').
+ *
+ * 'flow->mutex' protects the members of 'flow' from modification. It doesn't
+ * protect the flow from being deleted from 'cls' (that's 'cls->rwlock') and it
+ * doesn't prevent the flow from being freed (that's 'flow->ref_cnt').
+ *
+ * Some members, marked 'const', are immutable. Accessing other members
+ * requires synchronization, as noted in more detail below.
+ */