vconn: Fix formatting of user message.
[sliver-openvswitch.git] / lib / ovsdb-data.h
1 /* Copyright (c) 2009, 2010, 2011, 2012, 2013 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 size_t ovsdb_atom_json_length(const union ovsdb_atom *,
92                               enum ovsdb_atomic_type);
93
94 char *ovsdb_atom_from_string(union ovsdb_atom *,
95                              const struct ovsdb_base_type *, const char *,
96                              struct ovsdb_symbol_table *)
97     WARN_UNUSED_RESULT;
98 void ovsdb_atom_to_string(const union ovsdb_atom *, enum ovsdb_atomic_type,
99                           struct ds *);
100 void ovsdb_atom_to_bare(const union ovsdb_atom *, enum ovsdb_atomic_type,
101                         struct ds *);
102
103 struct ovsdb_error *ovsdb_atom_check_constraints(
104     const union ovsdb_atom *, const struct ovsdb_base_type *)
105     WARN_UNUSED_RESULT;
106 \f
107 /* An instance of an OVSDB type (given by struct ovsdb_type).
108  *
109  * - The 'keys' must be unique and in sorted order.  Most functions that modify
110  *   an ovsdb_datum maintain these invariants.  Functions that don't maintain
111  *   the invariants have names that end in "_unsafe".  Use ovsdb_datum_sort()
112  *   to check and restore these invariants.
113  *
114  * - 'n' is constrained by the ovsdb_type's 'n_min' and 'n_max'.
115  *
116  *   If 'n' is nonzero, then 'keys' points to an array of 'n' atoms of the type
117  *   specified by the ovsdb_type's 'key_type'.  (Otherwise, 'keys' should be
118  *   null.)
119  *
120  *   If 'n' is nonzero and the ovsdb_type's 'value_type' is not
121  *   OVSDB_TYPE_VOID, then 'values' points to an array of 'n' atoms of the type
122  *   specified by the 'value_type'.  (Otherwise, 'values' should be null.)
123  *
124  *   Thus, for 'n' > 0, 'keys' will always be nonnull and 'values' will be
125  *   nonnull only for "map" types.
126  */
127 struct ovsdb_datum {
128     unsigned int n;             /* Number of 'keys' and 'values'. */
129     union ovsdb_atom *keys;     /* Each of the ovsdb_type's 'key_type'. */
130     union ovsdb_atom *values;   /* Each of the ovsdb_type's 'value_type'. */
131 };
132
133 /* Basics. */
134 void ovsdb_datum_init_empty(struct ovsdb_datum *);
135 void ovsdb_datum_init_default(struct ovsdb_datum *, const struct ovsdb_type *);
136 bool ovsdb_datum_is_default(const struct ovsdb_datum *,
137                             const struct ovsdb_type *);
138 const struct ovsdb_datum *ovsdb_datum_default(const struct ovsdb_type *);
139 void ovsdb_datum_clone(struct ovsdb_datum *, const struct ovsdb_datum *,
140                        const struct ovsdb_type *);
141 void ovsdb_datum_destroy(struct ovsdb_datum *, const struct ovsdb_type *);
142 void ovsdb_datum_swap(struct ovsdb_datum *, struct ovsdb_datum *);
143
144 /* Checking and maintaining invariants. */
145 struct ovsdb_error *ovsdb_datum_sort(struct ovsdb_datum *,
146                                      enum ovsdb_atomic_type key_type)
147     WARN_UNUSED_RESULT;
148
149 void ovsdb_datum_sort_assert(struct ovsdb_datum *,
150                              enum ovsdb_atomic_type key_type);
151
152 size_t ovsdb_datum_sort_unique(struct ovsdb_datum *,
153                                enum ovsdb_atomic_type key_type,
154                                enum ovsdb_atomic_type value_type);
155
156 struct ovsdb_error *ovsdb_datum_check_constraints(
157     const struct ovsdb_datum *, const struct ovsdb_type *)
158     WARN_UNUSED_RESULT;
159
160 /* Type conversion. */
161 struct ovsdb_error *ovsdb_datum_from_json(struct ovsdb_datum *,
162                                           const struct ovsdb_type *,
163                                           const struct json *,
164                                           struct ovsdb_symbol_table *)
165     WARN_UNUSED_RESULT;
166 struct json *ovsdb_datum_to_json(const struct ovsdb_datum *,
167                                  const struct ovsdb_type *);
168 size_t ovsdb_datum_json_length(const struct ovsdb_datum *,
169                                const struct ovsdb_type *);
170
171 char *ovsdb_datum_from_string(struct ovsdb_datum *,
172                               const struct ovsdb_type *, const char *,
173                               struct ovsdb_symbol_table *)
174     WARN_UNUSED_RESULT;
175 void ovsdb_datum_to_string(const struct ovsdb_datum *,
176                            const struct ovsdb_type *, struct ds *);
177 void ovsdb_datum_to_bare(const struct ovsdb_datum *,
178                          const struct ovsdb_type *, struct ds *);
179
180 void ovsdb_datum_from_smap(struct ovsdb_datum *, struct smap *);
181
182 /* Comparison. */
183 uint32_t ovsdb_datum_hash(const struct ovsdb_datum *,
184                           const struct ovsdb_type *, uint32_t basis);
185 int ovsdb_datum_compare_3way(const struct ovsdb_datum *,
186                              const struct ovsdb_datum *,
187                              const struct ovsdb_type *);
188 bool ovsdb_datum_equals(const struct ovsdb_datum *,
189                         const struct ovsdb_datum *,
190                         const struct ovsdb_type *);
191
192 /* Search. */
193 unsigned int ovsdb_datum_find_key(const struct ovsdb_datum *,
194                                   const union ovsdb_atom *key,
195                                   enum ovsdb_atomic_type key_type);
196 unsigned int ovsdb_datum_find_key_value(const struct ovsdb_datum *,
197                                         const union ovsdb_atom *key,
198                                         enum ovsdb_atomic_type key_type,
199                                         const union ovsdb_atom *value,
200                                         enum ovsdb_atomic_type value_type);
201
202 /* Set operations. */
203 bool ovsdb_datum_includes_all(const struct ovsdb_datum *,
204                               const struct ovsdb_datum *,
205                               const struct ovsdb_type *);
206 bool ovsdb_datum_excludes_all(const struct ovsdb_datum *,
207                               const struct ovsdb_datum *,
208                               const struct ovsdb_type *);
209 void ovsdb_datum_union(struct ovsdb_datum *,
210                        const struct ovsdb_datum *,
211                        const struct ovsdb_type *,
212                        bool replace);
213 void ovsdb_datum_subtract(struct ovsdb_datum *a,
214                           const struct ovsdb_type *a_type,
215                           const struct ovsdb_datum *b,
216                           const struct ovsdb_type *b_type);
217
218 /* Raw operations that may not maintain the invariants. */
219 void ovsdb_datum_remove_unsafe(struct ovsdb_datum *, size_t idx,
220                                const struct ovsdb_type *);
221 void ovsdb_datum_add_unsafe(struct ovsdb_datum *,
222                             const union ovsdb_atom *key,
223                             const union ovsdb_atom *value,
224                             const struct ovsdb_type *);
225
226 /* Type checking. */
227 static inline bool
228 ovsdb_datum_conforms_to_type(const struct ovsdb_datum *datum,
229                              const struct ovsdb_type *type)
230 {
231     return datum->n >= type->n_min && datum->n <= type->n_max;
232 }
233 \f
234 /* A table mapping from names to data items.  Currently the data items are
235  * always UUIDs; perhaps this will be expanded in the future. */
236
237 struct ovsdb_symbol_table {
238     struct shash sh;            /* Maps from name to struct ovsdb_symbol *. */
239 };
240
241 struct ovsdb_symbol {
242     struct uuid uuid;           /* The UUID that the symbol represents. */
243     bool created;               /* Already used to create row? */
244     bool strong_ref;            /* Parsed a strong reference to this row? */
245     bool weak_ref;              /* Parsed a weak reference to this row? */
246 };
247
248 struct ovsdb_symbol_table *ovsdb_symbol_table_create(void);
249 void ovsdb_symbol_table_destroy(struct ovsdb_symbol_table *);
250 struct ovsdb_symbol *ovsdb_symbol_table_get(const struct ovsdb_symbol_table *,
251                                             const char *name);
252 struct ovsdb_symbol *ovsdb_symbol_table_put(struct ovsdb_symbol_table *,
253                                             const char *name,
254                                             const struct uuid *, bool used);
255 struct ovsdb_symbol *ovsdb_symbol_table_insert(struct ovsdb_symbol_table *,
256                                                const char *name);
257 \f
258 /* Tokenization
259  *
260  * Used by ovsdb_atom_from_string() and ovsdb_datum_from_string(). */
261
262 char *ovsdb_token_parse(const char **, char **outp) WARN_UNUSED_RESULT;
263 bool ovsdb_token_is_delim(unsigned char);
264
265 #endif /* ovsdb-data.h */