ovsdb-idl: Add some more implementation comments.

I wrote this code and if I have to rediscover how it works, it's time to
improve the commnts.

Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Andy Zhou <azhou@ovn.org>

2 files changed, 38 insertions, 2 deletions

diff --git a/lib/ovsdb-idl-provider.h b/lib/ovsdb-idl-provider.h
index bac77543c..1e375de11 100644
--- a/lib/ovsdb-idl-provider.h
+++ b/lib/ovsdb-idl-provider.h
@@ -25,6 +25,42 @@
 #include "openvswitch/shash.h"
 #include "uuid.h"
 
+/* A local copy of a row in an OVSDB table, replicated from an OVSDB server.
+ * This structure is used as a header for a larger structure that translates
+ * the "struct ovsdb_datum"s into easier-to-use forms, via the ->parse() and
+ * ->unparse functions in struct ovsdb_idl_column.  (Those functions are
+ * generated automatically via ovsdb-idlc.)
+ *
+ * When no transaction is in progress:
+ *
+ *     - 'old' points to the data committed to the database and currently
+ *       in the row.
+ *
+ *     - 'new == old'.
+ *
+ * When a transaction is in progress, the situation is a little different.  For
+ * a row inserted in the transaction, 'old' is NULL and 'new' points to the
+ * row's initial contents.  Otherwise:
+ *
+ *     - 'old' points to the data committed to the database and currently in
+ *       the row.  (This is the same as when no transaction is in progress.)
+ *
+ *     - If the transaction does not modify the row, 'new == old'.
+ *
+ *     - If the transaction modifies the row, 'new' points to the modified
+ *       data.
+ *
+ *     - If the transaction deletes the row, 'new' is NULL.
+ *
+ * Thus:
+ *
+ *     - 'old' always points to committed data, except that it is NULL if the
+ *       row is inserted within the current transaction.
+ *
+ *     - 'new' always points to the newest, possibly uncommitted version of the
+ *       row's data, except that it is NULL if the row is deleted within the
+ *       current transaction.
+ */
 struct ovsdb_idl_row {
     struct hmap_node hmap_node; /* In struct ovsdb_idl_table's 'rows'. */
     struct uuid uuid;           /* Row "_uuid" field. */
diff --git a/lib/ovsdb-idl.c b/lib/ovsdb-idl.c
index a1fcd1913..e1df634ac 100644
--- a/lib/ovsdb-idl.c
+++ b/lib/ovsdb-idl.c
@@ -88,8 +88,8 @@ struct ovsdb_idl {
     const struct ovsdb_idl_class *class;
     struct jsonrpc_session *session;
     struct uuid uuid;
-    struct shash table_by_name;
-    struct ovsdb_idl_table *tables; /* Contains "struct ovsdb_idl_table *"s.*/
+    struct shash table_by_name; /* Contains "struct ovsdb_idl_table *"s.*/
+    struct ovsdb_idl_table *tables; /* Array of ->class->n_tables elements. */
     unsigned int change_seqno;
     bool verify_write_only;