[ovs-dev] [Simple DB Stats 04/11] ovsdb-idl: Start documenting the public interface.

[Ben Pfaff]

Long overdue.
---
 lib/ovsdb-idl.c |   40 ++++++++++++++++++++++++++++++++++++++++
 lib/ovsdb-idl.h |   14 ++++++++++++++
 2 files changed, 54 insertions(+), 0 deletions(-)

diff --git a/lib/ovsdb-idl.c b/lib/ovsdb-idl.c
index 83124dc..23d00a8 100644
--- a/lib/ovsdb-idl.c
+++ b/lib/ovsdb-idl.c
@@ -136,6 +136,11 @@ static void ovsdb_idl_txn_abort_all(struct ovsdb_idl *);
 static bool ovsdb_idl_txn_process_reply(struct ovsdb_idl *,
                                         const struct jsonrpc_msg *msg);
 
+/* Creates and returns a connection to database 'remote', which should be in a
+ * form acceptable to jsonrpc_session_open().  The connection will maintain an
+ * in-memory replica of the remote database whose schema is described by
+ * 'class'.  (Ordinarily 'class' is compiled from an OVSDB schema automatically
+ * by ovsdb-idlc.) */
 struct ovsdb_idl *
 ovsdb_idl_create(const char *remote, const struct ovsdb_idl_class *class)
 {
@@ -171,6 +176,7 @@ ovsdb_idl_create(const char *remote, const struct ovsdb_idl_class *class)
     return idl;
 }
 
+/* Destroys 'idl' and all of the data structures that it manages. */
 void
 ovsdb_idl_destroy(struct ovsdb_idl *idl)
 {
@@ -231,6 +237,26 @@ ovsdb_idl_clear(struct ovsdb_idl *idl)
     }
 }
 
+/* Processes a batch of messages from the database server on 'idl'.  Returns
+ * true if the database as seen through 'idl' changed, true if it did not
+ * change.  The initial fetch of the entire contents of the remote database is
+ * considered to be one kind of change.
+ *
+ * When this function returns false, the client may continue to use any data
+ * structures it obtained from 'idl' in the past.  But when it returns true,
+ * the client must not access any of these data structures again, because they
+ * could have freed or reused for other purposes.
+ *
+ * This function can return occasional false positives, that is, report that
+ * the database changed even though it didn't.  This happens if the connection
+ * to the database drops and reconnects, which causes the database contents to
+ * be reloaded even if they didn't change.  (It could also happen if the
+ * database server sends out a "change" that reflects what we already thought
+ * was in the database, but the database server is not supposed to do that.)
+ *
+ * As an alternative to checking the return value, the client may check for
+ * changes in the value returned by ovsdb_idl_get_seqno().
+ */
 bool
 ovsdb_idl_run(struct ovsdb_idl *idl)
 {
@@ -295,6 +321,8 @@ ovsdb_idl_run(struct ovsdb_idl *idl)
     return initial_change_seqno != idl->change_seqno;
 }
 
+/* Arranges for poll_block() to wake up when ovsdb_idl_run() has something to
+ * do or when activity occurs on a transaction on 'idl'. */
 void
 ovsdb_idl_wait(struct ovsdb_idl *idl)
 {
@@ -302,18 +330,30 @@ ovsdb_idl_wait(struct ovsdb_idl *idl)
     jsonrpc_session_recv_wait(idl->session);
 }
 
+/* Returns a number that represents the state of 'idl'.  When 'idl' is updated
+ * (by ovsdb_idl_run()), the return value changes. */
 unsigned int
 ovsdb_idl_get_seqno(const struct ovsdb_idl *idl)
 {
     return idl->change_seqno;
 }
 
+/* Returns true if 'idl' successfully connected to the remote database and
+ * retrieved its contents (even if the connection subsequently dropped and is
+ * in the process of reconnecting).  If so, then 'idl' contains an atomic
+ * snapshot of the database's contents (but it might be arbitrarily old if the
+ * connection dropped).
+ *
+ * Returns false if 'idl' has never connected or retrieved the database's
+ * contents.  If so, 'idl' is empty. */
 bool
 ovsdb_idl_has_ever_connected(const struct ovsdb_idl *idl)
 {
     return ovsdb_idl_get_seqno(idl) != 0;
 }
 
+/* Forces 'idl' to drop its connection to the database and reconnect.  In the
+ * meantime, the contents of 'idl' will not change. */
 void
 ovsdb_idl_force_reconnect(struct ovsdb_idl *idl)
 {
diff --git a/lib/ovsdb-idl.h b/lib/ovsdb-idl.h
index 5f0beab..e320406 100644
--- a/lib/ovsdb-idl.h
+++ b/lib/ovsdb-idl.h
@@ -16,6 +16,20 @@
 #ifndef OVSDB_IDL_H
 #define OVSDB_IDL_H 1
 
+/* Open vSwitch Database Interface Definition Language (OVSDB IDL).
+ *
+ * The OVSDB IDL maintains an in-memory replica of a database.  It issues RPC
+ * requests to an OVSDB database server and parses the responses, converting
+ * raw JSON into data structures that are easier for clients to digest.  Most
+ * notably, references to UUIDs become C pointers.
+ *
+ * The IDL also assists with issuing database transactions.  The client creates
+ * a transaction, manipulates the IDL data structures, and commits or aborts
+ * the transaction.  The IDL then composes and issues the necessary JSON-RPC
+ * requests and reports to the client whether the transaction completed
+ * successfully.
+ */
+
 #include <stdbool.h>
 #include <stdint.h>
 #include "compiler.h"
-- 
1.7.1