e12153c9c71b9974a4d7bd6e87c0be1f19e11d65
[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
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                                          const struct ovsdb_base_type *,
71                                          const struct json *,
72                                          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 *,
78                              const struct ovsdb_base_type *, const char *,
79                              struct ovsdb_symbol_table *)
80     WARN_UNUSED_RESULT;
81 void ovsdb_atom_to_string(const union ovsdb_atom *, enum ovsdb_atomic_type,
82                           struct ds *);
83
84 struct ovsdb_error *ovsdb_atom_check_constraints(
85     const union ovsdb_atom *, const struct ovsdb_base_type *)
86     WARN_UNUSED_RESULT;
87 \f
88 /* An instance of an OVSDB type (given by struct ovsdb_type).
89  *
90  * - The 'keys' must be unique and in sorted order.  Most functions that modify
91  *   an ovsdb_datum maintain these invariants.  Functions that don't maintain
92  *   the invariants have names that end in "_unsafe".  Use ovsdb_datum_sort()
93  *   to check and restore these invariants.
94  *
95  * - 'n' is constrained by the ovsdb_type's 'n_min' and 'n_max'.
96  *
97  *   If 'n' is nonzero, then 'keys' points to an array of 'n' atoms of the type
98  *   specified by the ovsdb_type's 'key_type'.  (Otherwise, 'keys' should be
99  *   null.)
100  *
101  *   If 'n' is nonzero and the ovsdb_type's 'value_type' is not
102  *   OVSDB_TYPE_VOID, then 'values' points to an array of 'n' atoms of the type
103  *   specified by the 'value_type'.  (Otherwise, 'values' should be null.)
104  *
105  *   Thus, for 'n' > 0, 'keys' will always be nonnull and 'values' will be
106  *   nonnull only for "map" types.
107  */
108 struct ovsdb_datum {
109     unsigned int n;             /* Number of 'keys' and 'values'. */
110     union ovsdb_atom *keys;     /* Each of the ovsdb_type's 'key_type'. */
111     union ovsdb_atom *values;   /* Each of the ovsdb_type's 'value_type'. */
112 };
113
114 /* Basics. */
115 void ovsdb_datum_init_empty(struct ovsdb_datum *);
116 void ovsdb_datum_init_default(struct ovsdb_datum *, const struct ovsdb_type *);
117 bool ovsdb_datum_is_default(const struct ovsdb_datum *,
118                             const struct ovsdb_type *);
119 void ovsdb_datum_clone(struct ovsdb_datum *, const struct ovsdb_datum *,
120                        const struct ovsdb_type *);
121 void ovsdb_datum_destroy(struct ovsdb_datum *, const struct ovsdb_type *);
122 void ovsdb_datum_swap(struct ovsdb_datum *, struct ovsdb_datum *);
123
124 /* Checking and maintaining invariants. */
125 struct ovsdb_error *ovsdb_datum_sort(struct ovsdb_datum *,
126                                      enum ovsdb_atomic_type key_type)
127     WARN_UNUSED_RESULT;
128
129 void ovsdb_datum_sort_assert(struct ovsdb_datum *,
130                              enum ovsdb_atomic_type key_type);
131
132 struct ovsdb_error *ovsdb_datum_check_constraints(
133     const struct ovsdb_datum *, const struct ovsdb_type *)
134     WARN_UNUSED_RESULT;
135
136 /* Type conversion. */
137 struct ovsdb_error *ovsdb_datum_from_json(struct ovsdb_datum *,
138                                           const struct ovsdb_type *,
139                                           const struct json *,
140                                           struct ovsdb_symbol_table *)
141     WARN_UNUSED_RESULT;
142 struct json *ovsdb_datum_to_json(const struct ovsdb_datum *,
143                                  const struct ovsdb_type *);
144
145 char *ovsdb_datum_from_string(struct ovsdb_datum *,
146                               const struct ovsdb_type *, const char *,
147                               struct ovsdb_symbol_table *)
148     WARN_UNUSED_RESULT;
149 void ovsdb_datum_to_string(const struct ovsdb_datum *,
150                            const struct ovsdb_type *, struct ds *);
151
152 /* Comparison. */
153 uint32_t ovsdb_datum_hash(const struct ovsdb_datum *,
154                           const struct ovsdb_type *, uint32_t basis);
155 int ovsdb_datum_compare_3way(const struct ovsdb_datum *,
156                              const struct ovsdb_datum *,
157                              const struct ovsdb_type *);
158 bool ovsdb_datum_equals(const struct ovsdb_datum *,
159                         const struct ovsdb_datum *,
160                         const struct ovsdb_type *);
161
162 /* Search. */
163 unsigned int ovsdb_datum_find_key(const struct ovsdb_datum *,
164                                   const union ovsdb_atom *key,
165                                   enum ovsdb_atomic_type key_type);
166 unsigned int ovsdb_datum_find_key_value(const struct ovsdb_datum *,
167                                         const union ovsdb_atom *key,
168                                         enum ovsdb_atomic_type key_type,
169                                         const union ovsdb_atom *value,
170                                         enum ovsdb_atomic_type value_type);
171
172 /* Set operations. */
173 bool ovsdb_datum_includes_all(const struct ovsdb_datum *,
174                               const struct ovsdb_datum *,
175                               const struct ovsdb_type *);
176 bool ovsdb_datum_excludes_all(const struct ovsdb_datum *,
177                               const struct ovsdb_datum *,
178                               const struct ovsdb_type *);
179 void ovsdb_datum_union(struct ovsdb_datum *,
180                        const struct ovsdb_datum *,
181                        const struct ovsdb_type *,
182                        bool replace);
183 void ovsdb_datum_subtract(struct ovsdb_datum *a,
184                           const struct ovsdb_type *a_type,
185                           const struct ovsdb_datum *b,
186                           const struct ovsdb_type *b_type);
187
188 /* Raw operations that may not maintain the invariants. */
189 void ovsdb_datum_remove_unsafe(struct ovsdb_datum *, size_t idx,
190                                const struct ovsdb_type *);
191 void ovsdb_datum_add_unsafe(struct ovsdb_datum *,
192                             const union ovsdb_atom *key,
193                             const union ovsdb_atom *value,
194                             const struct ovsdb_type *);
195
196 /* Type checking. */
197 static inline bool
198 ovsdb_datum_conforms_to_type(const struct ovsdb_datum *datum,
199                              const struct ovsdb_type *type)
200 {
201     return datum->n >= type->n_min && datum->n <= type->n_max;
202 }
203 \f
204 /* A table mapping from names to data items.  Currently the data items are
205  * always UUIDs; perhaps this will be expanded in the future. */
206
207 struct ovsdb_symbol {
208     struct uuid uuid;           /* The UUID that the symbol represents. */
209     bool used;                  /* Already used as row UUID? */
210 };
211
212 struct ovsdb_symbol_table *ovsdb_symbol_table_create(void);
213 void ovsdb_symbol_table_destroy(struct ovsdb_symbol_table *);
214 struct ovsdb_symbol *ovsdb_symbol_table_get(const struct ovsdb_symbol_table *,
215                                             const char *name);
216 struct ovsdb_symbol *ovsdb_symbol_table_put(struct ovsdb_symbol_table *,
217                                             const char *name,
218                                             const struct uuid *, bool used);
219 struct ovsdb_symbol *ovsdb_symbol_table_insert(struct ovsdb_symbol_table *,
220                                                const char *name);
221 const char *ovsdb_symbol_table_find_unused(const struct ovsdb_symbol_table *);
222 \f
223 /* Tokenization
224  *
225  * Used by ovsdb_atom_from_string() and ovsdb_datum_from_string(). */
226
227 char *ovsdb_token_parse(const char **, char **outp) WARN_UNUSED_RESULT;
228 bool ovsdb_token_is_delim(unsigned char);
229
230 #endif /* ovsdb-data.h */