ovsdb-idl: Document some more functions.

Suggested-by: Justin Pettit <jpettit@nicira.com>

diff --git a/lib/ovsdb-idl.c b/lib/ovsdb-idl.c
index b7ee0976a24d26d8ee94cbc09cee90fdbcd97d72..cffc5dc1226283f2777ae33ac04a2f872bc9bfe8 100644 (file)
--- a/lib/ovsdb-idl.c
+++ b/lib/ovsdb-idl.c
@@ -1539,6 +1539,19 @@ ovsdb_idl_txn_complete(struct ovsdb_idl_txn *txn,
     hmap_remove(&txn->idl->outstanding_txns, &txn->hmap_node);
 }
 
+/* Writes 'datum' to the specified 'column' in 'row_'.  Updates both 'row_'
+ * itself and the structs derived from it (e.g. the "struct ovsrec_*", for
+ * ovs-vswitchd).
+ *
+ * 'datum' must have the correct type for its column.  The IDL does not check
+ * that it meets schema constraints, but ovsdb-server will do so at commit time
+ * so it had better be correct.
+ *
+ * A transaction must be in progress.  Replication of 'column' must not have
+ * been disabled (by calling ovsdb_idl_omit()).
+ *
+ * Usually this function is used indirectly through one of the "set" functions
+ * generated by ovsdb-idlc. */
 void
 ovsdb_idl_txn_write(const struct ovsdb_idl_row *row_,
                     const struct ovsdb_idl_column *column,
@@ -1572,6 +1585,32 @@ ovsdb_idl_txn_write(const struct ovsdb_idl_row *row_,
     (column->parse)(row, &row->new[column_idx]);
 }
 
+/* Causes the original contents of 'column' in 'row_' to be verified as a
+ * prerequisite to completing the transaction.  That is, if 'column' in 'row_'
+ * changed (or if 'row_' was deleted) between the time that the IDL originally
+ * read its contents and the time that the transaction commits, then the
+ * transaction aborts and ovsdb_idl_txn_commit() returns TXN_TRY_AGAIN.
+ *
+ * The intention is that, to ensure that no transaction commits based on dirty
+ * reads, an application should call ovsdb_idl_txn_verify() on each data item
+ * read as part of a read-modify-write operation.
+ *
+ * In some cases ovsdb_idl_txn_verify() reduces to a no-op, because the current
+ * value of 'column' is already known:
+ *
+ *   - If 'row_' is a row created by the current transaction (returned by
+ *     ovsdb_idl_txn_insert()).
+ *
+ *   - If 'column' has already been modified (with ovsdb_idl_txn_write())
+ *     within the current transaction.
+ *
+ * Because of the latter property, always call ovsdb_idl_txn_verify() *before*
+ * ovsdb_idl_txn_write() for a given read-modify-write.
+ *
+ * A transaction must be in progress.
+ *
+ * Usually this function is used indirectly through one of the "verify"
+ * functions generated by ovsdb-idlc. */
 void
 ovsdb_idl_txn_verify(const struct ovsdb_idl_row *row_,
                      const struct ovsdb_idl_column *column)
@@ -1596,6 +1635,13 @@ ovsdb_idl_txn_verify(const struct ovsdb_idl_row *row_,
     bitmap_set1(row->prereqs, column_idx);
 }
 
+/* Deletes 'row_' from its table.  May free 'row_', so it must not be
+ * accessed afterward.
+ *
+ * A transaction must be in progress.
+ *
+ * Usually this function is used indirectly through one of the "delete"
+ * functions generated by ovsdb-idlc. */
 void
 ovsdb_idl_txn_delete(const struct ovsdb_idl_row *row_)
 {
@@ -1619,6 +1665,18 @@ ovsdb_idl_txn_delete(const struct ovsdb_idl_row *row_)
     row->new = NULL;
 }
 
+/* Inserts and returns a new row in the table with the specified 'class' in the
+ * database with open transaction 'txn'.
+ *
+ * The new row is assigned a provisional UUID.  If 'uuid' is null then one is
+ * randomly generated; otherwise 'uuid' should specify a randomly generated
+ * UUID not otherwise in use.  ovsdb-server will assign a different UUID when
+ * 'txn' is committed, but the IDL will replace any uses of the provisional
+ * UUID in the data to be to be committed by the UUID assigned by
+ * ovsdb-server.
+ *
+ * Usually this function is used indirectly through one of the "insert"
+ * functions generated by ovsdb-idlc. */
 const struct ovsdb_idl_row *
 ovsdb_idl_txn_insert(struct ovsdb_idl_txn *txn,
                      const struct ovsdb_idl_table_class *class,