+ * Classifier Versioning
+ * =====================
+ *
+ * Classifier lookups are always done in a specific classifier version, where
+ * a version is defined to be a natural number.
+ *
+ * When a new rule is added to a classifier, it is set to become visible in a
+ * specific version. If the version number used at insert time is larger than
+ * any version number currently used in lookups, the new rule is said to be
+ * invisible to lookups. This means that lookups won't find the rule, but the
+ * rule is immediately available to classifier iterations.
+ *
+ * Similarly, a rule can be marked as to be deleted in a future version. To
+ * delete a rule in a way to not remove the rule before all ongoing lookups are
+ * finished, the rule should be made invisible in a specific version number.
+ * Then, when all the lookups use a later version number, the rule can be
+ * actually removed from the classifier.
+ *
+ * Classifiers can hold duplicate rules (rules with the same match criteria and
+ * priority) when at most one of these duplicates 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 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 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
+ * already in the classifier. When multiple rules are being added (or
+ * deleted) in one go, though, this pathological case cost can be
+ * 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, 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
+ * version visible to lookups, the deferred mode is turned off so that all the
+ * 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
+ * version number) and deletions (use cls_rule_make_removable_after_version()).
+ * Then call classifier_publish(), and after that, announce the new version
+ * number to be used in lookups.
+ *
+ *