lib/ovsdb-data.h

   1 /* Copyright (c) 2009, 2010, 2011, 2012, 2015, 2016, 2017 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 "openvswitch/shash.h"
  23
  24 #ifdef  __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 #define MAX_OVSDB_ATOM_RANGE_SIZE 4096
  29
  30 struct ds;
  31 struct ovsdb_symbol_table;
  32 struct smap;
  33
  34 /* One value of an atomic type (given by enum ovs_atomic_type). */
  35 union ovsdb_atom {
  36     int64_t integer;
  37     double real;
  38     bool boolean;
  39     char *string;
  40     struct uuid uuid;
  41 };
  42
  43 void ovsdb_atom_init_default(union ovsdb_atom *, enum ovsdb_atomic_type);
  44 const union ovsdb_atom *ovsdb_atom_default(enum ovsdb_atomic_type);
  45 bool ovsdb_atom_is_default(const union ovsdb_atom *, enum ovsdb_atomic_type);
  46 void ovsdb_atom_clone(union ovsdb_atom *, const union ovsdb_atom *,
  47                       enum ovsdb_atomic_type);
  48 void ovsdb_atom_swap(union ovsdb_atom *, union ovsdb_atom *);
  49
  50 /* Returns false if ovsdb_atom_destroy() is a no-op when it is applied to an
  51  * initialized atom of the given 'type', true if ovsdb_atom_destroy() actually
  52  * does something.
  53  *
  54  * This can be used to avoid calling ovsdb_atom_destroy() for each element in
  55  * an array of homogeneous atoms.  (It's not worthwhile for a single atom.) */
  56 static inline bool
  57 ovsdb_atom_needs_destruction(enum ovsdb_atomic_type type)
  58 {
  59     return type == OVSDB_TYPE_STRING;
  60 }
  61
  62 /* Frees the contents of 'atom', which must have the specified 'type'.
  63  *
  64  * This does not actually call free(atom).  If necessary, the caller must be
  65  * responsible for that. */
  66 static inline void
  67 ovsdb_atom_destroy(union ovsdb_atom *atom, enum ovsdb_atomic_type type)
  68 {
  69     if (type == OVSDB_TYPE_STRING) {
  70         free(atom->string);
  71     }
  72 }
  73
  74 uint32_t ovsdb_atom_hash(const union ovsdb_atom *, enum ovsdb_atomic_type,
  75                          uint32_t basis);
  76
  77 int ovsdb_atom_compare_3way(const union ovsdb_atom *,
  78                             const union ovsdb_atom *,
  79                             enum ovsdb_atomic_type);
  80
  81 /* Returns true if 'a' and 'b', which are both of type 'type', has the same
  82  * contents, false if their contents differ.  */
  83 static inline bool ovsdb_atom_equals(const union ovsdb_atom *a,
  84                                      const union ovsdb_atom *b,
  85                                      enum ovsdb_atomic_type type)
  86 {
  87     return !ovsdb_atom_compare_3way(a, b, type);
  88 }
  89
  90 struct ovsdb_error *ovsdb_atom_from_json(union ovsdb_atom *,
  91                                          const struct ovsdb_base_type *,
  92                                          const struct json *,
  93                                          struct ovsdb_symbol_table *)
  94     OVS_WARN_UNUSED_RESULT;
  95 struct json *ovsdb_atom_to_json(const union ovsdb_atom *,
  96                                 enum ovsdb_atomic_type);
  97
  98 char *ovsdb_atom_from_string(union ovsdb_atom *, union ovsdb_atom **,
  99                              const struct ovsdb_base_type *, const char *,
 100                              struct ovsdb_symbol_table *)
 101     OVS_WARN_UNUSED_RESULT;
 102 void ovsdb_atom_to_string(const union ovsdb_atom *, enum ovsdb_atomic_type,
 103                           struct ds *);
 104 void ovsdb_atom_to_bare(const union ovsdb_atom *, enum ovsdb_atomic_type,
 105                         struct ds *);
 106
 107 struct ovsdb_error *ovsdb_atom_check_constraints(
 108     const union ovsdb_atom *, const struct ovsdb_base_type *)
 109     OVS_WARN_UNUSED_RESULT;
 110 \f
 111 /* An instance of an OVSDB type (given by struct ovsdb_type).
 112  *
 113  * - The 'keys' must be unique and in sorted order.  Most functions that modify
 114  *   an ovsdb_datum maintain these invariants.  Functions that don't maintain
 115  *   the invariants have names that end in "_unsafe".  Use ovsdb_datum_sort()
 116  *   to check and restore these invariants.
 117  *
 118  * - 'n' is constrained by the ovsdb_type's 'n_min' and 'n_max'.
 119  *
 120  *   If 'n' is nonzero, then 'keys' points to an array of 'n' atoms of the type
 121  *   specified by the ovsdb_type's 'key_type'.  (Otherwise, 'keys' should be
 122  *   null.)
 123  *
 124  *   If 'n' is nonzero and the ovsdb_type's 'value_type' is not
 125  *   OVSDB_TYPE_VOID, then 'values' points to an array of 'n' atoms of the type
 126  *   specified by the 'value_type'.  (Otherwise, 'values' should be null.)
 127  *
 128  *   Thus, for 'n' > 0, 'keys' will always be nonnull and 'values' will be
 129  *   nonnull only for "map" types.
 130  */
 131 struct ovsdb_datum {
 132     unsigned int n;             /* Number of 'keys' and 'values'. */
 133     union ovsdb_atom *keys;     /* Each of the ovsdb_type's 'key_type'. */
 134     union ovsdb_atom *values;   /* Each of the ovsdb_type's 'value_type'. */
 135 };
 136 #define OVSDB_DATUM_INITIALIZER { 0, NULL, NULL }
 137
 138 /* Basics. */
 139 void ovsdb_datum_init_empty(struct ovsdb_datum *);
 140 void ovsdb_datum_init_default(struct ovsdb_datum *, const struct ovsdb_type *);
 141 bool ovsdb_datum_is_default(const struct ovsdb_datum *,
 142                             const struct ovsdb_type *);
 143 const struct ovsdb_datum *ovsdb_datum_default(const struct ovsdb_type *);
 144 void ovsdb_datum_clone(struct ovsdb_datum *, const struct ovsdb_datum *,
 145                        const struct ovsdb_type *);
 146 void ovsdb_datum_destroy(struct ovsdb_datum *, const struct ovsdb_type *);
 147 void ovsdb_datum_swap(struct ovsdb_datum *, struct ovsdb_datum *);
 148
 149 /* Checking and maintaining invariants. */
 150 struct ovsdb_error *ovsdb_datum_sort(struct ovsdb_datum *,
 151                                      enum ovsdb_atomic_type key_type)
 152     OVS_WARN_UNUSED_RESULT;
 153
 154 void ovsdb_datum_sort_assert(struct ovsdb_datum *,
 155                              enum ovsdb_atomic_type key_type);
 156
 157 size_t ovsdb_datum_sort_unique(struct ovsdb_datum *,
 158                                enum ovsdb_atomic_type key_type,
 159                                enum ovsdb_atomic_type value_type);
 160
 161 struct ovsdb_error *ovsdb_datum_check_constraints(
 162     const struct ovsdb_datum *, const struct ovsdb_type *)
 163     OVS_WARN_UNUSED_RESULT;
 164
 165 /* Type conversion. */
 166 struct ovsdb_error *ovsdb_datum_from_json(struct ovsdb_datum *,
 167                                           const struct ovsdb_type *,
 168                                           const struct json *,
 169                                           struct ovsdb_symbol_table *)
 170     OVS_WARN_UNUSED_RESULT;
 171 struct ovsdb_error *ovsdb_transient_datum_from_json(
 172                                           struct ovsdb_datum *,
 173                                           const struct ovsdb_type *,
 174                                           const struct json *)
 175     OVS_WARN_UNUSED_RESULT;
 176 struct ovsdb_error *
 177 ovsdb_unconstrained_datum_from_json(struct ovsdb_datum *,
 178                                     const struct ovsdb_type *,
 179                                     const struct json *)
 180     OVS_WARN_UNUSED_RESULT;
 181 struct json *ovsdb_datum_to_json(const struct ovsdb_datum *,
 182                                  const struct ovsdb_type *);
 183
 184 char *ovsdb_datum_from_string(struct ovsdb_datum *,
 185                               const struct ovsdb_type *, const char *,
 186                               struct ovsdb_symbol_table *)
 187     OVS_WARN_UNUSED_RESULT;
 188 void ovsdb_datum_to_string(const struct ovsdb_datum *,
 189                            const struct ovsdb_type *, struct ds *);
 190 void ovsdb_datum_to_bare(const struct ovsdb_datum *,
 191                          const struct ovsdb_type *, struct ds *);
 192
 193 void ovsdb_datum_from_smap(struct ovsdb_datum *, const struct smap *);
 194
 195 struct ovsdb_error *ovsdb_datum_convert(struct ovsdb_datum *dst,
 196                                         const struct ovsdb_type *dst_type,
 197                                         const struct ovsdb_datum *src,
 198                                         const struct ovsdb_type *src_type)
 199     OVS_WARN_UNUSED_RESULT;
 200
 201 /* Comparison. */
 202 uint32_t ovsdb_datum_hash(const struct ovsdb_datum *,
 203                           const struct ovsdb_type *, uint32_t basis);
 204 int ovsdb_datum_compare_3way(const struct ovsdb_datum *,
 205                              const struct ovsdb_datum *,
 206                              const struct ovsdb_type *);
 207 bool ovsdb_datum_equals(const struct ovsdb_datum *,
 208                         const struct ovsdb_datum *,
 209                         const struct ovsdb_type *);
 210
 211 /* Search. */
 212 unsigned int ovsdb_datum_find_key(const struct ovsdb_datum *,
 213                                   const union ovsdb_atom *key,
 214                                   enum ovsdb_atomic_type key_type);
 215 unsigned int ovsdb_datum_find_key_value(const struct ovsdb_datum *,
 216                                         const union ovsdb_atom *key,
 217                                         enum ovsdb_atomic_type key_type,
 218                                         const union ovsdb_atom *value,
 219                                         enum ovsdb_atomic_type value_type);
 220
 221 /* Set operations. */
 222 bool ovsdb_datum_includes_all(const struct ovsdb_datum *,
 223                               const struct ovsdb_datum *,
 224                               const struct ovsdb_type *);
 225 bool ovsdb_datum_excludes_all(const struct ovsdb_datum *,
 226                               const struct ovsdb_datum *,
 227                               const struct ovsdb_type *);
 228 void ovsdb_datum_union(struct ovsdb_datum *,
 229                        const struct ovsdb_datum *,
 230                        const struct ovsdb_type *,
 231                        bool replace);
 232 void ovsdb_datum_subtract(struct ovsdb_datum *a,
 233                           const struct ovsdb_type *a_type,
 234                           const struct ovsdb_datum *b,
 235                           const struct ovsdb_type *b_type);
 236
 237 /* Generate and apply diffs */
 238 void ovsdb_datum_diff(struct ovsdb_datum *diff,
 239                       const struct ovsdb_datum *old_datum,
 240                       const struct ovsdb_datum *new_datum,
 241                       const struct ovsdb_type *type);
 242
 243 struct ovsdb_error *ovsdb_datum_apply_diff(struct ovsdb_datum *new_datum,
 244                                            const struct ovsdb_datum *old_datum,
 245                                            const struct ovsdb_datum *diff,
 246                                            const struct ovsdb_type *type)
 247 OVS_WARN_UNUSED_RESULT;
 248
 249 /* Raw operations that may not maintain the invariants. */
 250 void ovsdb_datum_remove_unsafe(struct ovsdb_datum *, size_t idx,
 251                                const struct ovsdb_type *);
 252 void ovsdb_datum_add_unsafe(struct ovsdb_datum *,
 253                             const union ovsdb_atom *key,
 254                             const union ovsdb_atom *value,
 255                             const struct ovsdb_type *,
 256                             const union ovsdb_atom *range_end_atom);
 257
 258 /* Transactions with named-uuid row names. */
 259 struct json *ovsdb_datum_to_json_with_row_names(const struct ovsdb_datum *,
 260                                                 const struct ovsdb_type *);
 261 char *ovsdb_data_row_name(const struct uuid *);
 262
 263 /* Type checking. */
 264 static inline bool
 265 ovsdb_datum_conforms_to_type(const struct ovsdb_datum *datum,
 266                              const struct ovsdb_type *type)
 267 {
 268     return datum->n >= type->n_min && datum->n <= type->n_max;
 269 }
 270 \f
 271 /* A table mapping from names to data items.  Currently the data items are
 272  * always UUIDs; perhaps this will be expanded in the future. */
 273
 274 struct ovsdb_symbol_table {
 275     struct shash sh;            /* Maps from name to struct ovsdb_symbol *. */
 276 };
 277
 278 struct ovsdb_symbol {
 279     struct uuid uuid;           /* The UUID that the symbol represents. */
 280     bool created;               /* Already used to create row? */
 281     bool strong_ref;            /* Parsed a strong reference to this row? */
 282     bool weak_ref;              /* Parsed a weak reference to this row? */
 283 };
 284
 285 struct ovsdb_symbol_table *ovsdb_symbol_table_create(void);
 286 void ovsdb_symbol_table_destroy(struct ovsdb_symbol_table *);
 287 struct ovsdb_symbol *ovsdb_symbol_table_get(const struct ovsdb_symbol_table *,
 288                                             const char *name);
 289 struct ovsdb_symbol *ovsdb_symbol_table_put(struct ovsdb_symbol_table *,
 290                                             const char *name,
 291                                             const struct uuid *, bool used);
 292 struct ovsdb_symbol *ovsdb_symbol_table_insert(struct ovsdb_symbol_table *,
 293                                                const char *name);
 294 \f
 295 /* Tokenization
 296  *
 297  * Used by ovsdb_atom_from_string() and ovsdb_datum_from_string(). */
 298
 299 char *ovsdb_token_parse(const char **, char **outp) OVS_WARN_UNUSED_RESULT;
 300 bool ovsdb_token_is_delim(unsigned char);
 301
 302 struct ovsdb_error *ovsdb_atom_range_check_size(int64_t range_start,
 303                                                 int64_t range_end);
 304
 305 #ifdef  __cplusplus
 306 }
 307 #endif
 308
 309 #endif /* ovsdb-data.h */