datapath: Convert odp_flow_key to use Netlink attributes instead.
[openvswitch] / 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 struct shash;
26
27 /* One value of an atomic type (given by enum ovs_atomic_type). */
28 union ovsdb_atom {
29     int64_t integer;
30     double real;
31     bool boolean;
32     char *string;
33     struct uuid uuid;
34 };
35
36 void ovsdb_atom_init_default(union ovsdb_atom *, enum ovsdb_atomic_type);
37 const union ovsdb_atom *ovsdb_atom_default(enum ovsdb_atomic_type);
38 bool ovsdb_atom_is_default(const union ovsdb_atom *, enum ovsdb_atomic_type);
39 void ovsdb_atom_clone(union ovsdb_atom *, const union ovsdb_atom *,
40                       enum ovsdb_atomic_type);
41 void ovsdb_atom_swap(union ovsdb_atom *, union ovsdb_atom *);
42
43 /* Returns false if ovsdb_atom_destroy() is a no-op when it is applied to an
44  * initialized atom of the given 'type', true if ovsdb_atom_destroy() actually
45  * does something.
46  *
47  * This can be used to avoid calling ovsdb_atom_destroy() for each element in
48  * an array of homogeneous atoms.  (It's not worthwhile for a single atom.) */
49 static inline bool
50 ovsdb_atom_needs_destruction(enum ovsdb_atomic_type type)
51 {
52     return type == OVSDB_TYPE_STRING;
53 }
54
55 /* Frees the contents of 'atom', which must have the specified 'type'.
56  *
57  * This does not actually call free(atom).  If necessary, the caller must be
58  * responsible for that. */
59 static inline void
60 ovsdb_atom_destroy(union ovsdb_atom *atom, enum ovsdb_atomic_type type)
61 {
62     if (type == OVSDB_TYPE_STRING) {
63         free(atom->string);
64     }
65 }
66
67 uint32_t ovsdb_atom_hash(const union ovsdb_atom *, enum ovsdb_atomic_type,
68                          uint32_t basis);
69
70 int ovsdb_atom_compare_3way(const union ovsdb_atom *,
71                             const union ovsdb_atom *,
72                             enum ovsdb_atomic_type);
73
74 /* Returns true if 'a' and 'b', which are both of type 'type', has the same
75  * contents, false if their contents differ.  */
76 static inline bool ovsdb_atom_equals(const union ovsdb_atom *a,
77                                      const union ovsdb_atom *b,
78                                      enum ovsdb_atomic_type type)
79 {
80     return !ovsdb_atom_compare_3way(a, b, type);
81 }
82
83 struct ovsdb_error *ovsdb_atom_from_json(union ovsdb_atom *,
84                                          const struct ovsdb_base_type *,
85                                          const struct json *,
86                                          struct ovsdb_symbol_table *)
87     WARN_UNUSED_RESULT;
88 struct json *ovsdb_atom_to_json(const union ovsdb_atom *,
89                                 enum ovsdb_atomic_type);
90
91 char *ovsdb_atom_from_string(union ovsdb_atom *,
92                              const struct ovsdb_base_type *, const char *,
93                              struct ovsdb_symbol_table *)
94     WARN_UNUSED_RESULT;
95 void ovsdb_atom_to_string(const union ovsdb_atom *, enum ovsdb_atomic_type,
96                           struct ds *);
97
98 struct ovsdb_error *ovsdb_atom_check_constraints(
99     const union ovsdb_atom *, const struct ovsdb_base_type *)
100     WARN_UNUSED_RESULT;
101 \f
102 /* An instance of an OVSDB type (given by struct ovsdb_type).
103  *
104  * - The 'keys' must be unique and in sorted order.  Most functions that modify
105  *   an ovsdb_datum maintain these invariants.  Functions that don't maintain
106  *   the invariants have names that end in "_unsafe".  Use ovsdb_datum_sort()
107  *   to check and restore these invariants.
108  *
109  * - 'n' is constrained by the ovsdb_type's 'n_min' and 'n_max'.
110  *
111  *   If 'n' is nonzero, then 'keys' points to an array of 'n' atoms of the type
112  *   specified by the ovsdb_type's 'key_type'.  (Otherwise, 'keys' should be
113  *   null.)
114  *
115  *   If 'n' is nonzero and the ovsdb_type's 'value_type' is not
116  *   OVSDB_TYPE_VOID, then 'values' points to an array of 'n' atoms of the type
117  *   specified by the 'value_type'.  (Otherwise, 'values' should be null.)
118  *
119  *   Thus, for 'n' > 0, 'keys' will always be nonnull and 'values' will be
120  *   nonnull only for "map" types.
121  */
122 struct ovsdb_datum {
123     unsigned int n;             /* Number of 'keys' and 'values'. */
124     union ovsdb_atom *keys;     /* Each of the ovsdb_type's 'key_type'. */
125     union ovsdb_atom *values;   /* Each of the ovsdb_type's 'value_type'. */
126 };
127
128 /* Basics. */
129 void ovsdb_datum_init_empty(struct ovsdb_datum *);
130 void ovsdb_datum_init_default(struct ovsdb_datum *, const struct ovsdb_type *);
131 bool ovsdb_datum_is_default(const struct ovsdb_datum *,
132                             const struct ovsdb_type *);
133 const struct ovsdb_datum *ovsdb_datum_default(const struct ovsdb_type *);
134 void ovsdb_datum_clone(struct ovsdb_datum *, const struct ovsdb_datum *,
135                        const struct ovsdb_type *);
136 void ovsdb_datum_destroy(struct ovsdb_datum *, const struct ovsdb_type *);
137 void ovsdb_datum_swap(struct ovsdb_datum *, struct ovsdb_datum *);
138
139 /* Checking and maintaining invariants. */
140 struct ovsdb_error *ovsdb_datum_sort(struct ovsdb_datum *,
141                                      enum ovsdb_atomic_type key_type)
142     WARN_UNUSED_RESULT;
143
144 void ovsdb_datum_sort_assert(struct ovsdb_datum *,
145                              enum ovsdb_atomic_type key_type);
146
147 size_t ovsdb_datum_sort_unique(struct ovsdb_datum *,
148                                enum ovsdb_atomic_type key_type,
149                                enum ovsdb_atomic_type value_type);
150
151 struct ovsdb_error *ovsdb_datum_check_constraints(
152     const struct ovsdb_datum *, const struct ovsdb_type *)
153     WARN_UNUSED_RESULT;
154
155 /* Type conversion. */
156 struct ovsdb_error *ovsdb_datum_from_json(struct ovsdb_datum *,
157                                           const struct ovsdb_type *,
158                                           const struct json *,
159                                           struct ovsdb_symbol_table *)
160     WARN_UNUSED_RESULT;
161 struct json *ovsdb_datum_to_json(const struct ovsdb_datum *,
162                                  const struct ovsdb_type *);
163
164 char *ovsdb_datum_from_string(struct ovsdb_datum *,
165                               const struct ovsdb_type *, const char *,
166                               struct ovsdb_symbol_table *)
167     WARN_UNUSED_RESULT;
168 void ovsdb_datum_to_string(const struct ovsdb_datum *,
169                            const struct ovsdb_type *, struct ds *);
170
171 void ovsdb_datum_from_shash(struct ovsdb_datum *, struct shash *);
172
173 /* Comparison. */
174 uint32_t ovsdb_datum_hash(const struct ovsdb_datum *,
175                           const struct ovsdb_type *, uint32_t basis);
176 int ovsdb_datum_compare_3way(const struct ovsdb_datum *,
177                              const struct ovsdb_datum *,
178                              const struct ovsdb_type *);
179 bool ovsdb_datum_equals(const struct ovsdb_datum *,
180                         const struct ovsdb_datum *,
181                         const struct ovsdb_type *);
182
183 /* Search. */
184 unsigned int ovsdb_datum_find_key(const struct ovsdb_datum *,
185                                   const union ovsdb_atom *key,
186                                   enum ovsdb_atomic_type key_type);
187 unsigned int ovsdb_datum_find_key_value(const struct ovsdb_datum *,
188                                         const union ovsdb_atom *key,
189                                         enum ovsdb_atomic_type key_type,
190                                         const union ovsdb_atom *value,
191                                         enum ovsdb_atomic_type value_type);
192
193 /* Set operations. */
194 bool ovsdb_datum_includes_all(const struct ovsdb_datum *,
195                               const struct ovsdb_datum *,
196                               const struct ovsdb_type *);
197 bool ovsdb_datum_excludes_all(const struct ovsdb_datum *,
198                               const struct ovsdb_datum *,
199                               const struct ovsdb_type *);
200 void ovsdb_datum_union(struct ovsdb_datum *,
201                        const struct ovsdb_datum *,
202                        const struct ovsdb_type *,
203                        bool replace);
204 void ovsdb_datum_subtract(struct ovsdb_datum *a,
205                           const struct ovsdb_type *a_type,
206                           const struct ovsdb_datum *b,
207                           const struct ovsdb_type *b_type);
208
209 /* Raw operations that may not maintain the invariants. */
210 void ovsdb_datum_remove_unsafe(struct ovsdb_datum *, size_t idx,
211                                const struct ovsdb_type *);
212 void ovsdb_datum_add_unsafe(struct ovsdb_datum *,
213                             const union ovsdb_atom *key,
214                             const union ovsdb_atom *value,
215                             const struct ovsdb_type *);
216
217 /* Type checking. */
218 static inline bool
219 ovsdb_datum_conforms_to_type(const struct ovsdb_datum *datum,
220                              const struct ovsdb_type *type)
221 {
222     return datum->n >= type->n_min && datum->n <= type->n_max;
223 }
224 \f
225 /* A table mapping from names to data items.  Currently the data items are
226  * always UUIDs; perhaps this will be expanded in the future. */
227
228 struct ovsdb_symbol {
229     struct uuid uuid;           /* The UUID that the symbol represents. */
230     bool used;                  /* Already used as row UUID? */
231 };
232
233 struct ovsdb_symbol_table *ovsdb_symbol_table_create(void);
234 void ovsdb_symbol_table_destroy(struct ovsdb_symbol_table *);
235 struct ovsdb_symbol *ovsdb_symbol_table_get(const struct ovsdb_symbol_table *,
236                                             const char *name);
237 struct ovsdb_symbol *ovsdb_symbol_table_put(struct ovsdb_symbol_table *,
238                                             const char *name,
239                                             const struct uuid *, bool used);
240 struct ovsdb_symbol *ovsdb_symbol_table_insert(struct ovsdb_symbol_table *,
241                                                const char *name);
242 const char *ovsdb_symbol_table_find_unused(const struct ovsdb_symbol_table *);
243 \f
244 /* Tokenization
245  *
246  * Used by ovsdb_atom_from_string() and ovsdb_datum_from_string(). */
247
248 char *ovsdb_token_parse(const char **, char **outp) WARN_UNUSED_RESULT;
249 bool ovsdb_token_is_delim(unsigned char);
250
251 #endif /* ovsdb-data.h */