From 5413de95bec046cff2cf72482d65f7fa435aa10e Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Mon, 12 Jul 2010 10:03:33 -0700 Subject: [PATCH] ovsdb: Document some ovsdb-data.[ch] functions. --- lib/ovsdb-data.c | 80 +++++++++++++++++++++++++++++++++++++++++++++++- lib/ovsdb-data.h | 12 ++++++++ 2 files changed, 91 insertions(+), 1 deletion(-) diff --git a/lib/ovsdb-data.c b/lib/ovsdb-data.c index fe7d8c40..d08128f5 100644 --- a/lib/ovsdb-data.c +++ b/lib/ovsdb-data.c @@ -37,6 +37,20 @@ wrap_json(const char *name, struct json *wrapped) return json_array_create_2(json_string_create(name), wrapped); } +/* Initializes 'atom' with the default value of the given 'type'. + * + * The default value for an atom is as defined in ovsdb/SPECS: + * + * - "integer" or "real": 0 + * + * - "boolean": false + * + * - "string": "" (the empty string) + * + * - "uuid": 00000000-0000-0000-0000-000000000000 + * + * The caller must eventually arrange for 'atom' to be destroyed (with + * ovsdb_atom_destroy()). */ void ovsdb_atom_init_default(union ovsdb_atom *atom, enum ovsdb_atomic_type type) { @@ -70,6 +84,12 @@ ovsdb_atom_init_default(union ovsdb_atom *atom, enum ovsdb_atomic_type type) } } + +/* Returns true if 'atom', which must have the given 'type', has the default + * value for that type. + * + * See ovsdb_atom_init_default() for an explanation of the default value of an + * atom. */ bool ovsdb_atom_is_default(const union ovsdb_atom *atom, enum ovsdb_atomic_type type) @@ -99,6 +119,10 @@ ovsdb_atom_is_default(const union ovsdb_atom *atom, } } +/* Initializes 'new' as a copy of 'old', with the given 'type'. + * + * The caller must eventually arrange for 'new' to be destroyed (with + * ovsdb_atom_destroy()). */ void ovsdb_atom_clone(union ovsdb_atom *new, const union ovsdb_atom *old, enum ovsdb_atomic_type type) @@ -133,6 +157,7 @@ ovsdb_atom_clone(union ovsdb_atom *new, const union ovsdb_atom *old, } } +/* Swaps the contents of 'a' and 'b', which need not have the same type. */ void ovsdb_atom_swap(union ovsdb_atom *a, union ovsdb_atom *b) { @@ -141,6 +166,8 @@ ovsdb_atom_swap(union ovsdb_atom *a, union ovsdb_atom *b) *b = tmp; } +/* Returns a hash value for 'atom', which has the specified 'type', folding + * 'basis' into the calculation. */ uint32_t ovsdb_atom_hash(const union ovsdb_atom *atom, enum ovsdb_atomic_type type, uint32_t basis) @@ -170,6 +197,8 @@ ovsdb_atom_hash(const union ovsdb_atom *atom, enum ovsdb_atomic_type type, } } +/* Compares 'a' and 'b', which both have type 'type', and returns a + * strcmp()-like result. */ int ovsdb_atom_compare_3way(const union ovsdb_atom *a, const union ovsdb_atom *b, @@ -315,6 +344,13 @@ ovsdb_atom_from_json__(union ovsdb_atom *atom, enum ovsdb_atomic_type type, ovsdb_atomic_type_to_string(type)); } +/* Parses 'json' as an atom of the type described by 'base'. If successful, + * returns NULL and initializes 'atom' with the parsed atom. On failure, + * returns an error and the contents of 'atom' are indeterminate. The caller + * is responsible for freeing the error or the atom that is returned. + * + * If 'symtab' is nonnull, then named UUIDs in 'symtab' are accepted. Refer to + * ovsdb/SPECS information about this and other syntactical details. */ struct ovsdb_error * ovsdb_atom_from_json(union ovsdb_atom *atom, const struct ovsdb_base_type *base, @@ -335,6 +371,8 @@ ovsdb_atom_from_json(union ovsdb_atom *atom, return error; } +/* Converts 'atom', of the specified 'type', to JSON format, and returns the + * JSON. The caller is responsible for freeing the returned JSON. */ struct json * ovsdb_atom_to_json(const union ovsdb_atom *atom, enum ovsdb_atomic_type type) { @@ -463,7 +501,8 @@ ovsdb_atom_from_string__(union ovsdb_atom *atom, enum ovsdb_atomic_type type, * table. * * Returns a null pointer if successful, otherwise an error message describing - * the problem. The caller is responsible for freeing the error. + * the problem. On failure, the contents of 'atom' are indeterminate. The + * caller is responsible for freeing the atom or the error. */ char * ovsdb_atom_from_string(union ovsdb_atom *atom, @@ -706,6 +745,8 @@ alloc_default_atoms(enum ovsdb_atomic_type type, size_t n) } } +/* Initializes 'datum' as an empty datum. (An empty datum can be treated as + * any type.) */ void ovsdb_datum_init_empty(struct ovsdb_datum *datum) { @@ -714,6 +755,18 @@ ovsdb_datum_init_empty(struct ovsdb_datum *datum) datum->values = NULL; } +/* Initializes 'datum' as a datum that has the default value for 'type'. + * + * The default value for a particular type is as defined in ovsdb/SPECS: + * + * - If n_min is 0, then the default value is the empty set (or map). + * + * - If n_min is 1, the default value is a single value or a single + * key-value pair, whose key and value are the defaults for their + * atomic types. (See ovsdb_atom_init_default() for details.) + * + * - n_min > 1 is invalid. See ovsdb_type_is_valid(). + */ void ovsdb_datum_init_default(struct ovsdb_datum *datum, const struct ovsdb_type *type) @@ -723,6 +776,11 @@ ovsdb_datum_init_default(struct ovsdb_datum *datum, datum->values = alloc_default_atoms(type->value.type, datum->n); } +/* Returns true if 'datum', which must have the given 'type', has the default + * value for that type. + * + * See ovsdb_datum_init_default() for an explanation of the default value of a + * datum. */ bool ovsdb_datum_is_default(const struct ovsdb_datum *datum, const struct ovsdb_type *type) @@ -764,6 +822,10 @@ clone_atoms(const union ovsdb_atom *old, enum ovsdb_atomic_type type, size_t n) } } +/* Initializes 'new' as a copy of 'old', with the given 'type'. + * + * The caller must eventually arrange for 'new' to be destroyed (with + * ovsdb_datum_destroy()). */ void ovsdb_datum_clone(struct ovsdb_datum *new, const struct ovsdb_datum *old, const struct ovsdb_type *type) @@ -787,6 +849,10 @@ free_data(enum ovsdb_atomic_type type, free(atoms); } +/* Frees the data owned by 'datum', which must have the given 'type'. + * + * This does not actually call free(datum). If necessary, the caller must be + * responsible for that. */ void ovsdb_datum_destroy(struct ovsdb_datum *datum, const struct ovsdb_type *type) { @@ -794,6 +860,7 @@ ovsdb_datum_destroy(struct ovsdb_datum *datum, const struct ovsdb_type *type) free_data(type->value.type, datum->values, datum->n); } +/* Swaps the contents of 'a' and 'b', which need not have the same type. */ void ovsdb_datum_swap(struct ovsdb_datum *a, struct ovsdb_datum *b) { @@ -828,6 +895,14 @@ ovsdb_datum_sort_swap_cb(size_t a, size_t b, void *cbdata_) } } +/* The keys in an ovsdb_datum must be unique and in sorted order. Most + * functions that modify an ovsdb_datum maintain these invariants. For those + * that don't, this function checks and restores these invariants for 'datum', + * whose keys are of type 'key_type'. + * + * This function returns NULL if successful, otherwise an error message. The + * caller must free the returned error when it is no longer needed. On error, + * 'datum' is sorted but not unique. */ struct ovsdb_error * ovsdb_datum_sort(struct ovsdb_datum *datum, enum ovsdb_atomic_type key_type) { @@ -857,6 +932,9 @@ ovsdb_datum_sort(struct ovsdb_datum *datum, enum ovsdb_atomic_type key_type) } } +/* This function is the same as ovsdb_datum_sort(), except that the caller + * knows that 'datum' is unique. The operation therefore "cannot fail", so + * this function assert-fails if it actually does. */ void ovsdb_datum_sort_assert(struct ovsdb_datum *datum, enum ovsdb_atomic_type key_type) diff --git a/lib/ovsdb-data.h b/lib/ovsdb-data.h index e12153c9..29a5b9e0 100644 --- a/lib/ovsdb-data.h +++ b/lib/ovsdb-data.h @@ -38,12 +38,22 @@ void ovsdb_atom_clone(union ovsdb_atom *, const union ovsdb_atom *, enum ovsdb_atomic_type); void ovsdb_atom_swap(union ovsdb_atom *, union ovsdb_atom *); +/* Returns false if ovsdb_atom_destroy() is a no-op when it is applied to an + * initialized atom of the given 'type', true if ovsdb_atom_destroy() actually + * does something. + * + * This can be used to avoid calling ovsdb_atom_destroy() for each element in + * an array of homogeneous atoms. (It's not worthwhile for a single atom.) */ static inline bool ovsdb_atom_needs_destruction(enum ovsdb_atomic_type type) { return type == OVSDB_TYPE_STRING; } +/* Frees the contents of 'atom', which must have the specified 'type'. + * + * This does not actually call free(atom). If necessary, the caller must be + * responsible for that. */ static inline void ovsdb_atom_destroy(union ovsdb_atom *atom, enum ovsdb_atomic_type type) { @@ -59,6 +69,8 @@ int ovsdb_atom_compare_3way(const union ovsdb_atom *, const union ovsdb_atom *, enum ovsdb_atomic_type); +/* Returns true if 'a' and 'b', which are both of type 'type', has the same + * contents, false if their contents differ. */ static inline bool ovsdb_atom_equals(const union ovsdb_atom *a, const union ovsdb_atom *b, enum ovsdb_atomic_type type) -- 2.30.2