lib/ovsdb-data.h

   1 /* Copyright (c) 2009, 2010 Nicira Networks
   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
  23 struct ds;
  24 struct ovsdb_symbol_table;
  25
  26 /* One value of an atomic type (given by enum ovs_atomic_type). */
  27 union ovsdb_atom {
  28     int64_t integer;
  29     double real;
  30     bool boolean;
  31     char *string;
  32     struct uuid uuid;
  33 };
  34
  35 void ovsdb_atom_init_default(union ovsdb_atom *, enum ovsdb_atomic_type);
  36 bool ovsdb_atom_is_default(const union ovsdb_atom *, enum ovsdb_atomic_type);
  37 void ovsdb_atom_clone(union ovsdb_atom *, const union ovsdb_atom *,
  38                       enum ovsdb_atomic_type);
  39 void ovsdb_atom_swap(union ovsdb_atom *, union ovsdb_atom *);
  40
  41 static inline bool
  42 ovsdb_atom_needs_destruction(enum ovsdb_atomic_type type)
  43 {
  44     return type == OVSDB_TYPE_STRING;
  45 }
  46
  47 static inline void
  48 ovsdb_atom_destroy(union ovsdb_atom *atom, enum ovsdb_atomic_type type)
  49 {
  50     if (type == OVSDB_TYPE_STRING) {
  51         free(atom->string);
  52     }
  53 }
  54
  55 uint32_t ovsdb_atom_hash(const union ovsdb_atom *, enum ovsdb_atomic_type,
  56                          uint32_t basis);
  57
  58 int ovsdb_atom_compare_3way(const union ovsdb_atom *,
  59                             const union ovsdb_atom *,
  60                             enum ovsdb_atomic_type);
  61
  62 static inline bool ovsdb_atom_equals(const union ovsdb_atom *a,
  63                                      const union ovsdb_atom *b,
  64                                      enum ovsdb_atomic_type type)
  65 {
  66     return !ovsdb_atom_compare_3way(a, b, type);
  67 }
  68
  69 struct ovsdb_error *ovsdb_atom_from_json(union ovsdb_atom *,
  70                                          enum ovsdb_atomic_type,
  71                                          const struct json *,
  72                                          const struct ovsdb_symbol_table *)
  73     WARN_UNUSED_RESULT;
  74 struct json *ovsdb_atom_to_json(const union ovsdb_atom *,
  75                                 enum ovsdb_atomic_type);
  76
  77 char *ovsdb_atom_from_string(union ovsdb_atom *, enum ovsdb_atomic_type,
  78                              const char *)
  79     WARN_UNUSED_RESULT;
  80 void ovsdb_atom_to_string(const union ovsdb_atom *, enum ovsdb_atomic_type,
  81                           struct ds *);
  82 \f
  83 /* An instance of an OVSDB type (given by struct ovsdb_type).
  84  *
  85  * - The 'keys' must be unique and in sorted order.  Most functions that modify
  86  *   an ovsdb_datum maintain these invariants.  Functions that don't maintain
  87  *   the invariants have names that end in "_unsafe".  Use ovsdb_datum_sort()
  88  *   to check and restore these invariants.
  89  *
  90  * - 'n' is constrained by the ovsdb_type's 'n_min' and 'n_max'.
  91  *
  92  *   If 'n' is nonzero, then 'keys' points to an array of 'n' atoms of the type
  93  *   specified by the ovsdb_type's 'key_type'.  (Otherwise, 'keys' should be
  94  *   null.)
  95  *
  96  *   If 'n' is nonzero and the ovsdb_type's 'value_type' is not
  97  *   OVSDB_TYPE_VOID, then 'values' points to an array of 'n' atoms of the type
  98  *   specified by the 'value_type'.  (Otherwise, 'values' should be null.)
  99  *
 100  *   Thus, for 'n' > 0, 'keys' will always be nonnull and 'values' will be
 101  *   nonnull only for "map" types.
 102  */
 103 struct ovsdb_datum {
 104     unsigned int n;             /* Number of 'keys' and 'values'. */
 105     union ovsdb_atom *keys;     /* Each of the ovsdb_type's 'key_type'. */
 106     union ovsdb_atom *values;   /* Each of the ovsdb_type's 'value_type'. */
 107 };
 108
 109 /* Basics. */
 110 void ovsdb_datum_init_empty(struct ovsdb_datum *);
 111 void ovsdb_datum_init_default(struct ovsdb_datum *, const struct ovsdb_type *);
 112 bool ovsdb_datum_is_default(const struct ovsdb_datum *,
 113                             const struct ovsdb_type *);
 114 void ovsdb_datum_clone(struct ovsdb_datum *, const struct ovsdb_datum *,
 115                        const struct ovsdb_type *);
 116 void ovsdb_datum_destroy(struct ovsdb_datum *, const struct ovsdb_type *);
 117 void ovsdb_datum_swap(struct ovsdb_datum *, struct ovsdb_datum *);
 118
 119 /* Checking and maintaining invariants. */
 120 struct ovsdb_error *ovsdb_datum_sort(struct ovsdb_datum *,
 121                                      const struct ovsdb_type *);
 122
 123 /* Type conversion. */
 124 struct ovsdb_error *ovsdb_datum_from_json(struct ovsdb_datum *,
 125                                           const struct ovsdb_type *,
 126                                           const struct json *,
 127                                           const struct ovsdb_symbol_table *)
 128     WARN_UNUSED_RESULT;
 129 struct json *ovsdb_datum_to_json(const struct ovsdb_datum *,
 130                                  const struct ovsdb_type *);
 131
 132 char *ovsdb_datum_from_string(struct ovsdb_datum *,
 133                              const struct ovsdb_type *, const char *)
 134     WARN_UNUSED_RESULT;
 135 void ovsdb_datum_to_string(const struct ovsdb_datum *,
 136                            const struct ovsdb_type *, struct ds *);
 137
 138 /* Comparison. */
 139 uint32_t ovsdb_datum_hash(const struct ovsdb_datum *,
 140                           const struct ovsdb_type *, uint32_t basis);
 141 int ovsdb_datum_compare_3way(const struct ovsdb_datum *,
 142                              const struct ovsdb_datum *,
 143                              const struct ovsdb_type *);
 144 bool ovsdb_datum_equals(const struct ovsdb_datum *,
 145                         const struct ovsdb_datum *,
 146                         const struct ovsdb_type *);
 147
 148 /* Search. */
 149 unsigned int ovsdb_datum_find_key(const struct ovsdb_datum *,
 150                                   const union ovsdb_atom *key,
 151                                   enum ovsdb_atomic_type key_type);
 152 unsigned int ovsdb_datum_find_key_value(const struct ovsdb_datum *,
 153                                         const union ovsdb_atom *key,
 154                                         enum ovsdb_atomic_type key_type,
 155                                         const union ovsdb_atom *value,
 156                                         enum ovsdb_atomic_type value_type);
 157
 158 /* Set operations. */
 159 bool ovsdb_datum_includes_all(const struct ovsdb_datum *,
 160                               const struct ovsdb_datum *,
 161                               const struct ovsdb_type *);
 162 bool ovsdb_datum_excludes_all(const struct ovsdb_datum *,
 163                               const struct ovsdb_datum *,
 164                               const struct ovsdb_type *);
 165 void ovsdb_datum_union(struct ovsdb_datum *,
 166                        const struct ovsdb_datum *,
 167                        const struct ovsdb_type *,
 168                        bool replace);
 169 void ovsdb_datum_subtract(struct ovsdb_datum *a,
 170                           const struct ovsdb_type *a_type,
 171                           const struct ovsdb_datum *b,
 172                           const struct ovsdb_type *b_type);
 173
 174 /* Raw operations that may not maintain the invariants. */
 175 void ovsdb_datum_remove_unsafe(struct ovsdb_datum *, size_t idx,
 176                                const struct ovsdb_type *);
 177 void ovsdb_datum_add_unsafe(struct ovsdb_datum *,
 178                             const union ovsdb_atom *key,
 179                             const union ovsdb_atom *value,
 180                             const struct ovsdb_type *);
 181
 182 /* Type checking. */
 183 static inline bool
 184 ovsdb_datum_conforms_to_type(const struct ovsdb_datum *datum,
 185                              const struct ovsdb_type *type)
 186 {
 187     return datum->n >= type->n_min && datum->n <= type->n_max;
 188 }
 189 \f
 190 /* A table mapping from names to data items.  Currently the data items are
 191  * always UUIDs; perhaps this will be expanded in the future. */
 192
 193 struct ovsdb_symbol {
 194     struct uuid uuid;           /* The UUID that the symbol represents. */
 195     bool used;                  /* Already used as row UUID? */
 196 };
 197
 198 struct ovsdb_symbol_table *ovsdb_symbol_table_create(void);
 199 void ovsdb_symbol_table_destroy(struct ovsdb_symbol_table *);
 200 struct ovsdb_symbol *ovsdb_symbol_table_get(const struct ovsdb_symbol_table *,
 201                                             const char *name);
 202 void ovsdb_symbol_table_put(struct ovsdb_symbol_table *, const char *name,
 203                             const struct uuid *, bool used);
 204 \f
 205 /* Tokenization
 206  *
 207  * Used by ovsdb_atom_from_string() and ovsdb_datum_from_string(). */
 208
 209 char *ovsdb_token_parse(const char **, char **outp) WARN_UNUSED_RESULT;
 210 bool ovsdb_token_is_delim(unsigned char);
 211
 212 #endif /* ovsdb-data.h */