2 * Copyright (c) 2015 Nicira, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at:
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #define DB_CTL_BASE_H 1
21 #include "openvswitch/dynamic-string.h"
22 #include "openvswitch/shash.h"
29 struct ovsdb_symbol_table
;
32 /* This library module contains the common parts for ovsdb manipulation
33 * (structs, commands and functions). To utilize this module, user must
34 * define the following:
36 * - the command syntaxes for each command. (See 'struct ctl_command_syntax'
37 * for more info) and regiters them using ctl_register_commands().
39 * - the *ctl command context by inheriting the 'struct ctl_context' for
40 * additional commands implemented by user. (See 'struct ctl_context' for
44 /* ctl_fatal() also logs the error, so it is preferred in this file. */
45 #define ovs_fatal please_use_ctl_fatal_instead_of_ovs_fatal
47 struct ctl_table_class
;
48 struct cmd_show_table
;
49 void ctl_init(const struct ctl_table_class
*tables
,
50 const struct cmd_show_table
*cmd_show_tables
,
51 void (*ctl_exit_func
)(int status
));
52 char *ctl_default_db(void);
53 OVS_NO_RETURN
void ctl_fatal(const char *, ...) OVS_PRINTF_FORMAT(1, 2);
55 /* *ctl command syntax structure, to be defined by each command implementation.
60 * Three stylized functions accompany each of these data structures:
62 * "pre-run" "run" "post-run"
63 * --------------- ------------ -----------------
64 * *ctl ->prerequisites ->run ->postprocess
66 * Any *ctl command implementation should go through the following execution
69 * 1. parses user command-line input and finds the corresponding syntax
72 * 2. calls prerequisites() for getting the columns or tables used by each
75 * 3. calls run() to execute each command and to generate output.
77 * 4. calls postprocess() after output has been committed. (Only needed
78 * by 'create' command sofar)
83 * Each of the stylized functions requires the 'struct ctl_context' as input
84 * to provide context e.g. command-line arguments, table to be modified. User
85 * may define more specific context (by inheriting 'struct ctl_context') and
86 * write stylized functions that use it. In that case, CONTAINER_OF() can
87 * be used to cast the generic context to the specific one.
90 struct ctl_command_syntax
{
91 const char *name
; /* e.g. "add-br" */
92 int min_args
; /* Min number of arguments following name. */
93 int max_args
; /* Max number of arguments following name. */
95 /* Names that roughly describe the arguments that the command
96 * uses. These should be similar to the names displayed in the
97 * man page or in the help output. */
98 const char *arguments
;
100 /* If nonnull, calls ovsdb_idl_add_column() or ovsdb_idl_add_table() for
101 * each column or table in ctx->idl that it uses. */
102 void (*prerequisites
)(struct ctl_context
*ctx
);
104 /* Does the actual work of the command and puts the command's output, if
105 * any, in ctx->output or ctx->table.
107 * Alternatively, if some prerequisite of the command is not met and the
108 * caller should wait for something to change and then retry, it may set
109 * ctx->try_again to true. (Only the "wait-until" command currently does
111 void (*run
)(struct ctl_context
*ctx
);
113 /* If nonnull, called after the transaction has been successfully
114 * committed. ctx->output is the output from the "run" function, which
115 * this function may modify and otherwise postprocess as needed. (Only the
116 * "create" command currently does any postprocessing.) */
117 void (*postprocess
)(struct ctl_context
*ctx
);
119 /* A comma-separated list of supported options, e.g. "--a,--b", or the
120 * empty string if the command does not support any options. */
123 enum { RO
, RW
} mode
; /* Does this command modify the database? */
126 /* A command extracted from command-line input plus the structs for
127 * output generation. */
129 /* Data that remains constant after initialization. */
130 const struct ctl_command_syntax
*syntax
;
133 struct shash options
;
135 /* Data modified by commands. */
140 bool ctl_might_write_to_db(char **argv
);
141 const char *ctl_get_db_cmd_usage(void);
142 void ctl_print_commands(void);
143 void ctl_print_options(const struct option
*);
144 void ctl_add_cmd_options(struct option
**, size_t *n_options_p
,
145 size_t *allocated_options_p
, int opt_val
);
146 void ctl_register_commands(const struct ctl_command_syntax
*);
147 struct ctl_command
*ctl_parse_commands(int argc
, char *argv
[],
148 struct shash
*local_options
,
149 size_t *n_commandsp
);
151 /* Sometimes, it is desirable to print the table with weak reference to
152 * rows in a 'cmd_show_table' table. In that case, the 'weak_ref_table'
153 * should be used and user must define all variables. */
154 struct weak_ref_table
{
155 const struct ovsdb_idl_table_class
*table
;
156 const struct ovsdb_idl_column
*name_column
;
157 /* This colum must be a weak reference to the owning
158 * 'struct cmd_show_table''s table row. */
159 const struct ovsdb_idl_column
*wref_column
;
162 /* This struct is for organizing the 'show' command output where:
164 * - 'table' is the table to show.
166 * - if 'name_column' is not null, it is used as the name for each row
169 * - 'columns[]' allows user to specify the print of additional columns
172 * - if 'wref_table' is populated, print 'wref_table.name_column' for
173 * each row in table 'wref_table.table' that has a reference to 'table'
174 * in 'wref_table.wref_column'. Every field must be populated.
177 struct cmd_show_table
{
178 const struct ovsdb_idl_table_class
*table
;
179 const struct ovsdb_idl_column
*name_column
;
180 const struct ovsdb_idl_column
*columns
[3]; /* Seems like a good number. */
181 const struct weak_ref_table wref_table
;
185 /* The base context struct for conducting the common database
186 * operations (commands listed in 'db_ctl_commands'). User should
187 * define the per-schema context by inheriting this struct as base.
192 * User may implement caches for contents of the database to facilitate
193 * specific commands. In that case, the common commands defined in
194 * 'db_ctl_commands' that may invalidate the cache must call the
195 * invalidate_cache().
202 struct shash options
;
204 /* Modifiable state. */
207 struct ovsdb_idl
*idl
;
208 struct ovsdb_idl_txn
*txn
;
209 struct ovsdb_symbol_table
*symtab
;
211 /* For implementation with a cache of the contents of the database,
212 * this function will be called when the database is changed and the
213 * change makes the cache no longer valid. */
214 void (*invalidate_cache
)(struct ctl_context
*);
216 /* A command may set this member to true if some prerequisite is not met
217 * and the caller should wait for something to change and then retry. */
221 void ctl_context_init_command(struct ctl_context
*, struct ctl_command
*);
222 void ctl_context_init(struct ctl_context
*, struct ctl_command
*,
223 struct ovsdb_idl
*, struct ovsdb_idl_txn
*,
224 struct ovsdb_symbol_table
*,
225 void (*invalidate_cache
)(struct ctl_context
*));
226 void ctl_context_done_command(struct ctl_context
*, struct ctl_command
*);
227 void ctl_context_done(struct ctl_context
*, struct ctl_command
*);
230 const struct ovsdb_idl_table_class
*table
;
231 const struct ovsdb_idl_column
*name_column
;
232 const struct ovsdb_idl_column
*uuid_column
;
235 struct ctl_table_class
{
236 struct ovsdb_idl_table_class
*class;
237 struct ctl_row_id row_ids
[2];
240 void ctl_set_column(const char *table_name
,
241 const struct ovsdb_idl_row
*, const char *arg
,
242 struct ovsdb_symbol_table
*);
244 #endif /* db-ctl-base.h */