pintos-os.org Git - openvswitch/blob - lib/ovsdb-data.h

   1 /* Copyright (c) 2009, 2010, 2011, 2012 Nicira, Inc.
   2  *
   3  * Licensed under the Apache License, Version 2.0 (the "License");
   4  * you may not use this file except in compliance with the License.
   5  * You may obtain a copy of the License at:
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   9  * Unless required by applicable law or agreed to in writing, software
  10  * distributed under the License is distributed on an "AS IS" BASIS,
  11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12  * See the License for the specific language governing permissions and
  13  * limitations under the License.
  14  */
  15
  16 #ifndef OVSDB_DATA_H
  17 #define OVSDB_DATA_H 1
  18
  19 #include <stdlib.h>
  20 #include "compiler.h"
  21 #include "ovsdb-types.h"
  22 #include "shash.h"
  23
  24 struct ds;
  25 struct ovsdb_symbol_table;
  26 struct smap;
  27
  28 /* One value of an atomic type (given by enum ovs_atomic_type). */
  29 union ovsdb_atom {
  30     int64_t integer;
  31     double real;
  32     bool boolean;
  33     char *string;
  34     struct uuid uuid;
  35 };
  36
  37 void ovsdb_atom_init_default(union ovsdb_atom *, enum ovsdb_atomic_type);
  38 const union ovsdb_atom *ovsdb_atom_default(enum ovsdb_atomic_type);
  39 bool ovsdb_atom_is_default(const union ovsdb_atom *, enum ovsdb_atomic_type);
  40 void ovsdb_atom_clone(union ovsdb_atom *, const union ovsdb_atom *,
  41                       enum ovsdb_atomic_type);
  42 void ovsdb_atom_swap(union ovsdb_atom *, union ovsdb_atom *);
  43
  44 /* Returns false if ovsdb_atom_destroy() is a no-op when it is applied to an
  45  * initialized atom of the given 'type', true if ovsdb_atom_destroy() actually
  46  * does something.
  47  *
  48  * This can be used to avoid calling ovsdb_atom_destroy() for each element in
  49  * an array of homogeneous atoms.  (It's not worthwhile for a single atom.) */
  50 static inline bool
  51 ovsdb_atom_needs_destruction(enum ovsdb_atomic_type type)
  52 {
  53     return type == OVSDB_TYPE_STRING;
  54 }
  55
  56 /* Frees the contents of 'atom', which must have the specified 'type'.
  57  *
  58  * This does not actually call free(atom).  If necessary, the caller must be
  59  * responsible for that. */
  60 static inline void
  61 ovsdb_atom_destroy(union ovsdb_atom *atom, enum ovsdb_atomic_type type)
  62 {
  63     if (type == OVSDB_TYPE_STRING) {
  64         free(atom->string);
  65     }
  66 }
  67
  68 uint32_t ovsdb_atom_hash(const union ovsdb_atom *, enum ovsdb_atomic_type,
  69                          uint32_t basis);
  70
  71 int ovsdb_atom_compare_3way(const union ovsdb_atom *,
  72                             const union ovsdb_atom *,
  73                             enum ovsdb_atomic_type);
  74
  75 /* Returns true if 'a' and 'b', which are both of type 'type', has the same
  76  * contents, false if their contents differ.  */
  77 static inline bool ovsdb_atom_equals(const union ovsdb_atom *a,
  78                                      const union ovsdb_atom *b,
  79                                      enum ovsdb_atomic_type type)
  80 {
  81     return !ovsdb_atom_compare_3way(a, b, type);
  82 }
  83
  84 struct ovsdb_error *ovsdb_atom_from_json(union ovsdb_atom *,
  85                                          const struct ovsdb_base_type *,
  86                                          const struct json *,
  87                                          struct ovsdb_symbol_table *)
  88     WARN_UNUSED_RESULT;
  89 struct json *ovsdb_atom_to_json(const union ovsdb_atom *,
  90                                 enum ovsdb_atomic_type);
  91
  92 char *ovsdb_atom_from_string(union ovsdb_atom *,
  93                              const struct ovsdb_base_type *, const char *,
  94                              struct ovsdb_symbol_table *)
  95     WARN_UNUSED_RESULT;
  96 void ovsdb_atom_to_string(const union ovsdb_atom *, enum ovsdb_atomic_type,
  97                           struct ds *);
  98 void ovsdb_atom_to_bare(const union ovsdb_atom *, enum ovsdb_atomic_type,
  99                         struct ds *);
 100
 101 struct ovsdb_error *ovsdb_atom_check_constraints(
 102     const union ovsdb_atom *, const struct ovsdb_base_type *)
 103     WARN_UNUSED_RESULT;
 104 \f
 105 /* An instance of an OVSDB type (given by struct ovsdb_type).
 106  *
 107  * - The 'keys' must be unique and in sorted order.  Most functions that modify
 108  *   an ovsdb_datum maintain these invariants.  Functions that don't maintain
 109  *   the invariants have names that end in "_unsafe".  Use ovsdb_datum_sort()
 110  *   to check and restore these invariants.
 111  *
 112  * - 'n' is constrained by the ovsdb_type's 'n_min' and 'n_max'.
 113  *
 114  *   If 'n' is nonzero, then 'keys' points to an array of 'n' atoms of the type
 115  *   specified by the ovsdb_type's 'key_type'.  (Otherwise, 'keys' should be
 116  *   null.)
 117  *
 118  *   If 'n' is nonzero and the ovsdb_type's 'value_type' is not
 119  *   OVSDB_TYPE_VOID, then 'values' points to an array of 'n' atoms of the type
 120  *   specified by the 'value_type'.  (Otherwise, 'values' should be null.)
 121  *
 122  *   Thus, for 'n' > 0, 'keys' will always be nonnull and 'values' will be
 123  *   nonnull only for "map" types.
 124  */
 125 struct ovsdb_datum {
 126     unsigned int n;             /* Number of 'keys' and 'values'. */
 127     union ovsdb_atom *keys;     /* Each of the ovsdb_type's 'key_type'. */
 128     union ovsdb_atom *values;   /* Each of the ovsdb_type's 'value_type'. */
 129 };
 130
 131 /* Basics. */
 132 void ovsdb_datum_init_empty(struct ovsdb_datum *);
 133 void ovsdb_datum_init_default(struct ovsdb_datum *, const struct ovsdb_type *);
 134 bool ovsdb_datum_is_default(const struct ovsdb_datum *,
 135                             const struct ovsdb_type *);
 136 const struct ovsdb_datum *ovsdb_datum_default(const struct ovsdb_type *);
 137 void ovsdb_datum_clone(struct ovsdb_datum *, const struct ovsdb_datum *,
 138                        const struct ovsdb_type *);
 139 void ovsdb_datum_destroy(struct ovsdb_datum *, const struct ovsdb_type *);
 140 void ovsdb_datum_swap(struct ovsdb_datum *, struct ovsdb_datum *);
 141
 142 /* Checking and maintaining invariants. */
 143 struct ovsdb_error *ovsdb_datum_sort(struct ovsdb_datum *,
 144                                      enum ovsdb_atomic_type key_type)
 145     WARN_UNUSED_RESULT;
 146
 147 void ovsdb_datum_sort_assert(struct ovsdb_datum *,
 148                              enum ovsdb_atomic_type key_type);
 149
 150 size_t ovsdb_datum_sort_unique(struct ovsdb_datum *,
 151                                enum ovsdb_atomic_type key_type,
 152                                enum ovsdb_atomic_type value_type);
 153
 154 struct ovsdb_error *ovsdb_datum_check_constraints(
 155     const struct ovsdb_datum *, const struct ovsdb_type *)
 156     WARN_UNUSED_RESULT;
 157
 158 /* Type conversion. */
 159 struct ovsdb_error *ovsdb_datum_from_json(struct ovsdb_datum *,
 160                                           const struct ovsdb_type *,
 161                                           const struct json *,
 162                                           struct ovsdb_symbol_table *)
 163     WARN_UNUSED_RESULT;
 164 struct json *ovsdb_datum_to_json(const struct ovsdb_datum *,
 165                                  const struct ovsdb_type *);
 166
 167 char *ovsdb_datum_from_string(struct ovsdb_datum *,
 168                               const struct ovsdb_type *, const char *,
 169                               struct ovsdb_symbol_table *)
 170     WARN_UNUSED_RESULT;
 171 void ovsdb_datum_to_string(const struct ovsdb_datum *,
 172                            const struct ovsdb_type *, struct ds *);
 173 void ovsdb_datum_to_bare(const struct ovsdb_datum *,
 174                          const struct ovsdb_type *, struct ds *);
 175
 176 void ovsdb_datum_from_smap(struct ovsdb_datum *, struct smap *);
 177
 178 /* Comparison. */
 179 uint32_t ovsdb_datum_hash(const struct ovsdb_datum *,
 180                           const struct ovsdb_type *, uint32_t basis);
 181 int ovsdb_datum_compare_3way(const struct ovsdb_datum *,
 182                              const struct ovsdb_datum *,
 183                              const struct ovsdb_type *);
 184 bool ovsdb_datum_equals(const struct ovsdb_datum *,
 185                         const struct ovsdb_datum *,
 186                         const struct ovsdb_type *);
 187
 188 /* Search. */
 189 unsigned int ovsdb_datum_find_key(const struct ovsdb_datum *,
 190                                   const union ovsdb_atom *key,
 191                                   enum ovsdb_atomic_type key_type);
 192 unsigned int ovsdb_datum_find_key_value(const struct ovsdb_datum *,
 193                                         const union ovsdb_atom *key,
 194                                         enum ovsdb_atomic_type key_type,
 195                                         const union ovsdb_atom *value,
 196                                         enum ovsdb_atomic_type value_type);
 197
 198 /* Set operations. */
 199 bool ovsdb_datum_includes_all(const struct ovsdb_datum *,
 200                               const struct ovsdb_datum *,
 201                               const struct ovsdb_type *);
 202 bool ovsdb_datum_excludes_all(const struct ovsdb_datum *,
 203                               const struct ovsdb_datum *,
 204                               const struct ovsdb_type *);
 205 void ovsdb_datum_union(struct ovsdb_datum *,
 206                        const struct ovsdb_datum *,
 207                        const struct ovsdb_type *,
 208                        bool replace);
 209 void ovsdb_datum_subtract(struct ovsdb_datum *a,
 210                           const struct ovsdb_type *a_type,
 211                           const struct ovsdb_datum *b,
 212                           const struct ovsdb_type *b_type);
 213
 214 /* Raw operations that may not maintain the invariants. */
 215 void ovsdb_datum_remove_unsafe(struct ovsdb_datum *, size_t idx,
 216                                const struct ovsdb_type *);
 217 void ovsdb_datum_add_unsafe(struct ovsdb_datum *,
 218                             const union ovsdb_atom *key,
 219                             const union ovsdb_atom *value,
 220                             const struct ovsdb_type *);
 221
 222 /* Type checking. */
 223 static inline bool
 224 ovsdb_datum_conforms_to_type(const struct ovsdb_datum *datum,
 225                              const struct ovsdb_type *type)
 226 {
 227     return datum->n >= type->n_min && datum->n <= type->n_max;
 228 }
 229 \f
 230 /* A table mapping from names to data items.  Currently the data items are
 231  * always UUIDs; perhaps this will be expanded in the future. */
 232
 233 struct ovsdb_symbol_table {
 234     struct shash sh;            /* Maps from name to struct ovsdb_symbol *. */
 235 };
 236
 237 struct ovsdb_symbol {
 238     struct uuid uuid;           /* The UUID that the symbol represents. */
 239     bool created;               /* Already used to create row? */
 240     bool strong_ref;            /* Parsed a strong reference to this row? */
 241     bool weak_ref;              /* Parsed a weak reference to this row? */
 242 };
 243
 244 struct ovsdb_symbol_table *ovsdb_symbol_table_create(void);
 245 void ovsdb_symbol_table_destroy(struct ovsdb_symbol_table *);
 246 struct ovsdb_symbol *ovsdb_symbol_table_get(const struct ovsdb_symbol_table *,
 247                                             const char *name);
 248 struct ovsdb_symbol *ovsdb_symbol_table_put(struct ovsdb_symbol_table *,
 249                                             const char *name,
 250                                             const struct uuid *, bool used);
 251 struct ovsdb_symbol *ovsdb_symbol_table_insert(struct ovsdb_symbol_table *,
 252                                                const char *name);
 253 \f
 254 /* Tokenization
 255  *
 256  * Used by ovsdb_atom_from_string() and ovsdb_datum_from_string(). */
 257
 258 char *ovsdb_token_parse(const char **, char **outp) WARN_UNUSED_RESULT;
 259 bool ovsdb_token_is_delim(unsigned char);
 260
 261 #endif /* ovsdb-data.h */