Add change tracking documentation

Change tracking is a bit different from what someone with
"classic" database experience might expect, so let's add
the knowledged gained from the experience of making change
tracking work for incremental processing.

Signed-off-by: RYAN D. MOATS <rmoats@us.ibm.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>

1 files changed, 14 insertions, 1 deletions

diff --git a/lib/ovsdb-idl.h b/lib/ovsdb-idl.h
index bad2dc68a..238f5e65f 100644
--- a/lib/ovsdb-idl.h
+++ b/lib/ovsdb-idl.h
@@ -113,7 +113,20 @@ void ovsdb_idl_add_table(struct ovsdb_idl *,
 void ovsdb_idl_omit(struct ovsdb_idl *, const struct ovsdb_idl_column *);
 void ovsdb_idl_omit_alert(struct ovsdb_idl *, const struct ovsdb_idl_column *);
 
-/* Change tracking. */
+/* Change tracking.
+ *
+ * In OVSDB, change tracking is applied at each client in the IDL layer.  This
+ * means that when a client makes a request to track changes on a particular
+ * table, they are essentially requesting information about the incremental
+ * changes to that table from the point in time that the request is made.  Once
+ * the client clears tracked changes, that information will no longer be
+ * available.
+ *
+ * The implication of the above is that if a client requires replaying
+ * untracked history, it faces the choice of either trying to remember changes
+ * itself (which translates into a memory leak) or of being structured with a
+ * path for processing the full untracked table as well as a path that
+ * processes incremental changes. */
 enum ovsdb_idl_change {
     OVSDB_IDL_CHANGE_INSERT,
     OVSDB_IDL_CHANGE_MODIFY,