From d797877dc3c6608d165b69ca466a8e8448e388b6 Mon Sep 17 00:00:00 2001 From: Justin Pettit Date: Tue, 3 Mar 2015 15:12:49 -0800 Subject: [PATCH] ovsdb-idlc: Add comments for remaining non-"set" non-static functions. Signed-off-by: Justin Pettit Acked-by: Ben Pfaff --- ovsdb/ovsdb-idlc.in | 76 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 64 insertions(+), 12 deletions(-) diff --git a/ovsdb/ovsdb-idlc.in b/ovsdb/ovsdb-idlc.in index 55b695eb5..4ef4f224e 100755 --- a/ovsdb/ovsdb-idlc.in +++ b/ovsdb/ovsdb-idlc.in @@ -373,10 +373,11 @@ static void # Row Initialization function. print """ +/* Clears the contents of 'row' in table "%(t)s". */ void %(s)s_init(struct %(s)s *row) { - memset(row, 0, sizeof *row); """ % {'s': structName} + memset(row, 0, sizeof *row); """ % {'s': structName, 't': tableName} for columnName, column in sorted(table.columns.iteritems()): if column.type.is_smap(): print " smap_init(&row->%s);" % columnName @@ -384,18 +385,28 @@ void # First, next functions. print ''' +/* Searches table "%(t)s" in 'idl' for a row with UUID 'uuid'. Returns + * a pointer to the row if there is one, otherwise a null pointer. */ const struct %(s)s * %(s)s_get_for_uuid(const struct ovsdb_idl *idl, const struct uuid *uuid) { return %(s)s_cast(ovsdb_idl_get_row_for_uuid(idl, &%(p)stable_classes[%(P)sTABLE_%(T)s], uuid)); } +/* Returns a row in table "%(t)s" in 'idl', or a null pointer if that + * table is empty. + * + * Database tables are internally maintained as hash tables, so adding or + * removing rows while traversing the same table can cause some rows to be + * visited twice or not at apply. */ const struct %(s)s * %(s)s_first(const struct ovsdb_idl *idl) { return %(s)s_cast(ovsdb_idl_first_row(idl, &%(p)stable_classes[%(P)sTABLE_%(T)s])); } +/* Returns a row following 'row' within its table, or a null pointer if 'row' + * is the last row in its table. */ const struct %(s)s * %(s)s_next(const struct %(s)s *row) { @@ -403,28 +414,65 @@ const struct %(s)s * }''' % {'s': structName, 'p': prefix, 'P': prefix.upper(), + 't': tableName, 'T': tableName.upper()} print ''' +/* Deletes 'row' from table "%(t)s". 'row' may be freed, so it must not be + * accessed afterward. + * + * The caller must have started a transaction with ovsdb_idl_txn_create(). */ void %(s)s_delete(const struct %(s)s *row) { ovsdb_idl_txn_delete(&row->header_); } +/* Inserts and returns a new row in the table "%(t)s" in the database + * with open transaction 'txn'. + * + * The new row is assigned a randomly generated provisional UUID. + * 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. */ struct %(s)s * %(s)s_insert(struct ovsdb_idl_txn *txn) { return %(s)s_cast(ovsdb_idl_txn_insert(txn, &%(p)stable_classes[%(P)sTABLE_%(T)s], NULL)); -} -''' % {'s': structName, - 'p': prefix, - 'P': prefix.upper(), - 'T': tableName.upper()} +}''' % {'s': structName, + 'p': prefix, + 'P': prefix.upper(), + 't': tableName, + 'T': tableName.upper()} # Verify functions. for columnName, column in sorted(table.columns.iteritems()): print ''' +/* Causes the original contents of column "%(c)s" in 'row' to be + * verified as a prerequisite to completing the transaction. That is, if + * "%(c)s" 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_AGAIN_WAIT or TXN_AGAIN_NOW (depending on whether the database + * change has already been received). + * + * The intention is that, to ensure that no transaction commits based on dirty + * reads, an application should call this function any time "%(c)s" is + * read as part of a read-modify-write operation. + * + * In some cases this function reduces to a no-op, because the current value + * of "%(c)s" is already known: + * + * - If 'row' is a row created by the current transaction (returned by + * %(s)s_insert()). + * + * - If "%(c)s" has already been modified (with + * %(s)s_set_%(c)s()) within the current transaction. + * + * Because of the latter property, always call this function *before* + * %(s)s_set_%(c)s() for a given read-modify-write. + * + * The caller must have started a transaction with ovsdb_idl_txn_create(). */ void %(s)s_verify_%(c)s(const struct %(s)s *row) { @@ -446,10 +494,11 @@ void valueType = '' valueComment = '' print """ -/* Returns the %(c)s column's value in 'row' as a struct ovsdb_datum. - * This is useful occasionally: for example, ovsdb_datum_find_key() is an - * easier and more efficient way to search for a given key than implementing - * the same operation on the "cooked" form in 'row'. +/* Returns the "%(c)s" column's value from the "%(t)s" table in 'row' + * as a struct ovsdb_datum. This is useful occasionally: for example, + * ovsdb_datum_find_key() is an easier and more efficient way to search + * for a given key than implementing the same operation on the "cooked" + * form in 'row'. * * 'key_type' must be %(kt)s.%(vc)s * (This helps to avoid silent bugs if someone changes %(c)s's @@ -460,14 +509,17 @@ void * Various kinds of changes can invalidate the returned value: modifying * 'column' within 'row', deleting 'row', or completing an ongoing transaction. * If the returned value is needed for a long time, it is best to make a copy - * of it with ovsdb_datum_clone(). */ + * of it with ovsdb_datum_clone(). + * + * This function is rarely useful, since it is easier to access the value + * directly through the "%(c)s" member in %(s)s. */ const struct ovsdb_datum * %(s)s_get_%(c)s(const struct %(s)s *row, \tenum ovsdb_atomic_type key_type OVS_UNUSED%(v)s) { ovs_assert(key_type == %(kt)s);%(vt)s return ovsdb_idl_read(&row->header_, &%(s)s_col_%(c)s); -}""" % {'s': structName, 'c': columnName, +}""" % {'t': tableName, 's': structName, 'c': columnName, 'kt': column.type.key.toAtomicType(), 'v': valueParam, 'vt': valueType, 'vc': valueComment} -- 2.20.1