[ovs-dev] [PATCH] ovsdb-idl: Document some more functions.

[Justin Pettit]

This is great, Ben.  Thanks.

--Justin


On Oct 25, 2010, at 10:45 AM, Ben Pfaff wrote:

> Suggested-by: Justin Pettit <jpettit at nicira.com>
> ---
> lib/ovsdb-idl.c |   58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 58 insertions(+), 0 deletions(-)
> 
> diff --git a/lib/ovsdb-idl.c b/lib/ovsdb-idl.c
> index b7ee097..cffc5dc 100644
> --- 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,
> -- 
> 1.7.1
> 
> 
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> http://openvswitch.org/mailman/listinfo/dev_openvswitch.org