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 "dynamic-string.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 'the_idl' and 'the_idl_txn'.
38 * - the 'cmd_show_tables'. (See 'struct cmd_show_table' for more info).
40 * - the command syntaxes for each command. (See 'struct ctl_command_syntax'
41 * for more info) and regiters them using ctl_register_commands().
43 * - the *ctl command context by inheriting the 'struct ctl_context' for
44 * additional commands implemented by user. (See 'struct ctl_context' for
48 /* ctl_fatal() also logs the error, so it is preferred in this file. */
49 #define ovs_fatal please_use_ctl_fatal_instead_of_ovs_fatal
51 /* idl and idl transaction to be used for the *ctl command execution.
52 * User must provide them. */
53 extern struct ovsdb_idl
*the_idl
;
54 extern struct ovsdb_idl_txn
*the_idl_txn
;
56 struct ctl_table_class
;
57 void ctl_init(const struct ctl_table_class
*tables
);
58 char *ctl_default_db(void);
59 OVS_NO_RETURN
void ctl_exit(int status
);
60 OVS_NO_RETURN
void ctl_fatal(const char *, ...) OVS_PRINTF_FORMAT(1, 2);
62 /* *ctl command syntax structure, to be defined by each command implementation.
67 * Three stylized functions accompany each of these data structures:
69 * "pre-run" "run" "post-run"
70 * --------------- ------------ -----------------
71 * *ctl ->prerequisites ->run ->postprocess
73 * Any *ctl command implementation should go through the following execution
76 * 1. parses user command-line input and finds the corresponding syntax
79 * 2. calls prerequisites() for getting the columns or tables used by each
82 * 3. calls run() to execute each command and to generate output.
84 * 4. calls postprocess() after output has been committed. (Only needed
85 * by 'create' command sofar)
90 * Each of the stylized functions requires the 'struct ctl_context' as input
91 * to provide context e.g. command-line arguments, table to be modified. User
92 * may define more specific context (by inheriting 'struct ctl_context') and
93 * write stylized functions that use it. In that case, CONTAINER_OF() can
94 * be used to cast the generic context to the specific one.
97 struct ctl_command_syntax
{
98 const char *name
; /* e.g. "add-br" */
99 int min_args
; /* Min number of arguments following name. */
100 int max_args
; /* Max number of arguments following name. */
102 /* Names that roughly describe the arguments that the command
103 * uses. These should be similar to the names displayed in the
104 * man page or in the help output. */
105 const char *arguments
;
107 /* If nonnull, calls ovsdb_idl_add_column() or ovsdb_idl_add_table() for
108 * each column or table in ctx->idl that it uses. */
109 void (*prerequisites
)(struct ctl_context
*ctx
);
111 /* Does the actual work of the command and puts the command's output, if
112 * any, in ctx->output or ctx->table.
114 * Alternatively, if some prerequisite of the command is not met and the
115 * caller should wait for something to change and then retry, it may set
116 * ctx->try_again to true. (Only the "wait-until" command currently does
118 void (*run
)(struct ctl_context
*ctx
);
120 /* If nonnull, called after the transaction has been successfully
121 * committed. ctx->output is the output from the "run" function, which
122 * this function may modify and otherwise postprocess as needed. (Only the
123 * "create" command currently does any postprocessing.) */
124 void (*postprocess
)(struct ctl_context
*ctx
);
126 /* A comma-separated list of supported options, e.g. "--a,--b", or the
127 * empty string if the command does not support any options. */
130 enum { RO
, RW
} mode
; /* Does this command modify the database? */
133 /* A command extracted from command-line input plus the structs for
134 * output generation. */
136 /* Data that remains constant after initialization. */
137 const struct ctl_command_syntax
*syntax
;
140 struct shash options
;
142 /* Data modified by commands. */
147 bool ctl_might_write_to_db(char **argv
);
148 const char *ctl_get_db_cmd_usage(void);
149 void ctl_print_commands(void);
150 void ctl_print_options(const struct option
*);
151 void ctl_add_cmd_options(struct option
**, size_t *n_options_p
,
152 size_t *allocated_options_p
, int opt_val
);
153 void ctl_register_commands(const struct ctl_command_syntax
*);
154 struct ctl_command
*ctl_parse_commands(int argc
, char *argv
[],
155 struct shash
*local_options
,
156 size_t *n_commandsp
);
158 /* This struct is for organizing the 'show' command output where:
160 * - 'table' is the table to show.
162 * - if 'name_column' is not null, it is used as the name for each row
165 * - 'columns[]' allows user to specify the print of additional columns
168 * - 'recurse' is used to avoid duplicate print.
171 struct cmd_show_table
{
172 const struct ovsdb_idl_table_class
*table
;
173 const struct ovsdb_idl_column
*name_column
;
174 const struct ovsdb_idl_column
*columns
[3]; /* Seems like a good number. */
178 /* This array defines the 'show' command output format. User can check the
179 * definition in utilities/ovs-vsctl.c as reference.
181 * Particularly, if an element in 'columns[]' represents a reference to
182 * another table, the referred table must also be defined as an entry in
183 * in 'cmd_show_tables[]'.
185 * The definition must end with an all-NULL entry.
187 extern struct cmd_show_table cmd_show_tables
[];
190 /* The base context struct for conducting the common database
191 * operations (commands listed in 'db_ctl_commands'). User should
192 * define the per-schema context by inheriting this struct as base.
197 * User may implement caches for contents of the database to facilitate
198 * specific commands. In that case, the common commands defined in
199 * 'db_ctl_commands' that may invalidate the cache must call the
200 * invalidate_cache().
207 struct shash options
;
209 /* Modifiable state. */
212 struct ovsdb_idl
*idl
;
213 struct ovsdb_idl_txn
*txn
;
214 struct ovsdb_symbol_table
*symtab
;
216 /* For implementation with a cache of the contents of the database,
217 * this function will be called when the database is changed and the
218 * change makes the cache no longer valid. */
219 void (*invalidate_cache
)(struct ctl_context
*);
221 /* A command may set this member to true if some prerequisite is not met
222 * and the caller should wait for something to change and then retry. */
226 void ctl_context_init_command(struct ctl_context
*, struct ctl_command
*);
227 void ctl_context_init(struct ctl_context
*, struct ctl_command
*,
228 struct ovsdb_idl
*, struct ovsdb_idl_txn
*,
229 struct ovsdb_symbol_table
*,
230 void (*invalidate_cache
)(struct ctl_context
*));
231 void ctl_context_done_command(struct ctl_context
*, struct ctl_command
*);
232 void ctl_context_done(struct ctl_context
*, struct ctl_command
*);
235 const struct ovsdb_idl_table_class
*table
;
236 const struct ovsdb_idl_column
*name_column
;
237 const struct ovsdb_idl_column
*uuid_column
;
240 struct ctl_table_class
{
241 struct ovsdb_idl_table_class
*class;
242 struct ctl_row_id row_ids
[2];
245 void ctl_set_column(const char *table_name
,
246 const struct ovsdb_idl_row
*, const char *arg
,
247 struct ovsdb_symbol_table
*);
249 #endif /* db-ctl-base.h */