From 2ce42c885a07e9de427e53901f6a46a2b8504fd7 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Wed, 23 Jun 2010 10:13:39 -0700 Subject: [PATCH] ovsdb-idl: Start documenting the public interface. Long overdue. --- lib/ovsdb-idl.c | 40 ++++++++++++++++++++++++++++++++++++++++ lib/ovsdb-idl.h | 14 ++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/lib/ovsdb-idl.c b/lib/ovsdb-idl.c index da9757932..2c9b95f0d 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, false 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 88bd7b3ac..7832e4eef 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 rows via UUID 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 #include #include "compiler.h" -- 2.43.0