mir/ovs
2
0
Fork 0
mirror of https://github.com/openvswitch/ovs synced 2025-08-31 06:15:47 +00:00
Code Issues Releases Wiki Activity

ovsdb-idl: Document some more functions.

Browse Source 
Suggested-by: Justin Pettit <jpettit@nicira.com>
This commit is contained in:
Ben Pfaff
2010-10-25 10:43:28 -07:00
parent 898bf89d80
commit b827c67b9e
1 changed files with 58 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
lib/ovsdb-idl.c
View File

@@ -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,