1 /* Copyright (c) 2009, 2010, 2011, 2012, 2013, 2014 Nicira, Inc.
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:
7 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 /* Open vSwitch Database Interface Definition Language (OVSDB IDL).
21 * The OVSDB IDL maintains an in-memory replica of a database. It issues RPC
22 * requests to an OVSDB database server and parses the responses, converting
23 * raw JSON into data structures that are easier for clients to digest. Most
24 * notably, references to rows via UUID become C pointers.
26 * The IDL also assists with issuing database transactions. The client creates
27 * a transaction, manipulates the IDL data structures, and commits or aborts
28 * the transaction. The IDL then composes and issues the necessary JSON-RPC
29 * requests and reports to the client whether the transaction completed
36 #include "ovsdb-types.h"
40 struct ovsdb_idl_class
;
41 struct ovsdb_idl_column
;
42 struct ovsdb_idl_table_class
;
45 struct ovsdb_idl
*ovsdb_idl_create(const char *remote
,
46 const struct ovsdb_idl_class
*,
47 bool monitor_everything_by_default
,
49 void ovsdb_idl_destroy(struct ovsdb_idl
*);
51 void ovsdb_idl_run(struct ovsdb_idl
*);
52 void ovsdb_idl_wait(struct ovsdb_idl
*);
54 void ovsdb_idl_set_lock(struct ovsdb_idl
*, const char *lock_name
);
55 bool ovsdb_idl_has_lock(const struct ovsdb_idl
*);
56 bool ovsdb_idl_is_lock_contended(const struct ovsdb_idl
*);
58 unsigned int ovsdb_idl_get_seqno(const struct ovsdb_idl
*);
59 bool ovsdb_idl_has_ever_connected(const struct ovsdb_idl
*);
60 void ovsdb_idl_enable_reconnect(struct ovsdb_idl
*);
61 void ovsdb_idl_force_reconnect(struct ovsdb_idl
*);
62 void ovsdb_idl_verify_write_only(struct ovsdb_idl
*);
64 bool ovsdb_idl_is_alive(const struct ovsdb_idl
*);
65 int ovsdb_idl_get_last_error(const struct ovsdb_idl
*);
67 /* Choosing columns and tables to replicate. */
69 /* Modes with which the IDL can monitor a column.
71 * If no bits are set, the column is not monitored at all. Its value will
72 * always appear to the client to be the default value for its type.
74 * If OVSDB_IDL_MONITOR is set, then the column is replicated. Its value will
75 * reflect the value in the database. If OVSDB_IDL_ALERT is also set, then the
76 * value returned by ovsdb_idl_get_seqno() will change when the column's value
79 * The possible mode combinations are:
81 * - 0, for a column that a client doesn't care about.
83 * - (OVSDB_IDL_MONITOR | OVSDB_IDL_ALERT), for a column that a client wants
84 * to track and possibly update.
86 * - OVSDB_IDL_MONITOR, for columns that a client treats as "write-only",
87 * that is, it updates them but doesn't want to get alerted about its own
88 * updates. It also won't be alerted about other clients' updates, so this
89 * is suitable only for use by a client that "owns" a particular column.
91 * - OVDSB_IDL_ALERT without OVSDB_IDL_MONITOR is not valid.
93 #define OVSDB_IDL_MONITOR (1 << 0) /* Monitor this column? */
94 #define OVSDB_IDL_ALERT (1 << 1) /* Alert client when column updated? */
96 void ovsdb_idl_add_column(struct ovsdb_idl
*, const struct ovsdb_idl_column
*);
97 void ovsdb_idl_add_table(struct ovsdb_idl
*,
98 const struct ovsdb_idl_table_class
*);
100 void ovsdb_idl_omit(struct ovsdb_idl
*, const struct ovsdb_idl_column
*);
101 void ovsdb_idl_omit_alert(struct ovsdb_idl
*, const struct ovsdb_idl_column
*);
103 /* Reading the database replica. */
105 const struct ovsdb_idl_row
*ovsdb_idl_get_row_for_uuid(
106 const struct ovsdb_idl
*, const struct ovsdb_idl_table_class
*,
107 const struct uuid
*);
108 const struct ovsdb_idl_row
*ovsdb_idl_first_row(
109 const struct ovsdb_idl
*, const struct ovsdb_idl_table_class
*);
110 const struct ovsdb_idl_row
*ovsdb_idl_next_row(const struct ovsdb_idl_row
*);
112 const struct ovsdb_datum
*ovsdb_idl_read(const struct ovsdb_idl_row
*,
113 const struct ovsdb_idl_column
*);
114 const struct ovsdb_datum
*ovsdb_idl_get(const struct ovsdb_idl_row
*,
115 const struct ovsdb_idl_column
*,
116 enum ovsdb_atomic_type key_type
,
117 enum ovsdb_atomic_type value_type
);
118 bool ovsdb_idl_is_mutable(const struct ovsdb_idl_row
*,
119 const struct ovsdb_idl_column
*);
121 bool ovsdb_idl_row_is_synthetic(const struct ovsdb_idl_row
*);
125 * A transaction may modify the contents of a database by modifying the values
126 * of columns, deleting rows, inserting rows, or adding checks that columns in
127 * the database have not changed ("verify" operations), through
128 * ovsdb_idl_txn_*() functions. (The OVSDB IDL code generator produces helper
129 * functions that internally call the ovsdb_idl_txn_*() functions. These are
130 * likely to be more convenient.)
132 * Reading and writing columns and inserting and deleting rows are all
133 * straightforward. The reasons to verify columns are less obvious.
134 * Verification is the key to maintaining transactional integrity. Because
135 * OVSDB handles multiple clients, it can happen that between the time that
136 * OVSDB client A reads a column and writes a new value, OVSDB client B has
137 * written that column. Client A's write should not ordinarily overwrite
138 * client B's, especially if the column in question is a "map" column that
139 * contains several more or less independent data items. If client A adds a
140 * "verify" operation before it writes the column, then the transaction fails
141 * in case client B modifies it first. Client A will then see the new value of
142 * the column and compose a new transaction based on the new contents written
145 * When a transaction is complete, which must be before the next call to
146 * ovsdb_idl_run() on 'idl', call ovsdb_idl_txn_commit() or
147 * ovsdb_idl_txn_abort().
149 * The life-cycle of a transaction looks like this:
151 * 1. Create the transaction and record the initial sequence number:
153 * seqno = ovsdb_idl_get_seqno(idl);
154 * txn = ovsdb_idl_txn_create(idl);
156 * 2. Modify the database with ovsdb_idl_txn_*() functions directly or
159 * 3. Commit the transaction by calling ovsdb_idl_txn_commit(). The first call
160 * to this function probably returns TXN_INCOMPLETE. The client must keep
161 * calling again along as this remains true, calling ovsdb_idl_run() in
162 * between to let the IDL do protocol processing. (If the client doesn't
163 * have anything else to do in the meantime, it can use
164 * ovsdb_idl_txn_commit_block() to avoid having to loop itself.)
166 * 4. If the final status is TXN_TRY_AGAIN, wait for ovsdb_idl_get_seqno() to
167 * change from the saved 'seqno' (it's possible that it's already changed,
168 * in which case the client should not wait at all), then start over from
169 * step 1. Only a call to ovsdb_idl_run() will change the return value of
170 * ovsdb_idl_get_seqno(). (ovsdb_idl_txn_commit_block() calls
174 enum ovsdb_idl_txn_status
{
175 TXN_UNCOMMITTED
, /* Not yet committed or aborted. */
176 TXN_UNCHANGED
, /* Transaction didn't include any changes. */
177 TXN_INCOMPLETE
, /* Commit in progress, please wait. */
178 TXN_ABORTED
, /* ovsdb_idl_txn_abort() called. */
179 TXN_SUCCESS
, /* Commit successful. */
180 TXN_TRY_AGAIN
, /* Commit failed because a "verify" operation
181 * reported an inconsistency, due to a network
182 * problem, or other transient failure. Wait
183 * for a change, then try again. */
184 TXN_NOT_LOCKED
, /* Server hasn't given us the lock yet. */
185 TXN_ERROR
/* Commit failed due to a hard error. */
188 const char *ovsdb_idl_txn_status_to_string(enum ovsdb_idl_txn_status
);
190 struct ovsdb_idl_txn
*ovsdb_idl_txn_create(struct ovsdb_idl
*);
191 void ovsdb_idl_txn_add_comment(struct ovsdb_idl_txn
*, const char *, ...)
192 OVS_PRINTF_FORMAT (2, 3);
193 void ovsdb_idl_txn_set_dry_run(struct ovsdb_idl_txn
*);
194 void ovsdb_idl_txn_increment(struct ovsdb_idl_txn
*,
195 const struct ovsdb_idl_row
*,
196 const struct ovsdb_idl_column
*);
197 void ovsdb_idl_txn_destroy(struct ovsdb_idl_txn
*);
198 void ovsdb_idl_txn_wait(const struct ovsdb_idl_txn
*);
199 enum ovsdb_idl_txn_status
ovsdb_idl_txn_commit(struct ovsdb_idl_txn
*);
200 enum ovsdb_idl_txn_status
ovsdb_idl_txn_commit_block(struct ovsdb_idl_txn
*);
201 void ovsdb_idl_txn_abort(struct ovsdb_idl_txn
*);
203 const char *ovsdb_idl_txn_get_error(const struct ovsdb_idl_txn
*);
205 int64_t ovsdb_idl_txn_get_increment_new_value(const struct ovsdb_idl_txn
*);
206 const struct uuid
*ovsdb_idl_txn_get_insert_uuid(const struct ovsdb_idl_txn
*,
207 const struct uuid
*);
209 void ovsdb_idl_txn_write(const struct ovsdb_idl_row
*,
210 const struct ovsdb_idl_column
*,
211 struct ovsdb_datum
*);
212 void ovsdb_idl_txn_write_clone(const struct ovsdb_idl_row
*,
213 const struct ovsdb_idl_column
*,
214 const struct ovsdb_datum
*);
215 void ovsdb_idl_txn_delete(const struct ovsdb_idl_row
*);
216 const struct ovsdb_idl_row
*ovsdb_idl_txn_insert(
217 struct ovsdb_idl_txn
*, const struct ovsdb_idl_table_class
*,
218 const struct uuid
*);
220 struct ovsdb_idl
*ovsdb_idl_txn_get_idl (struct ovsdb_idl_txn
*);
222 #endif /* ovsdb-idl.h */