]>
Commit | Line | Data |
---|---|---|
07ff77cc | 1 | /* |
3f5b5f7b | 2 | * Copyright (c) 2015, 2017 Nicira, Inc. |
07ff77cc AW |
3 | * |
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: | |
7 | * | |
8 | * http://www.apache.org/licenses/LICENSE-2.0 | |
9 | * | |
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. | |
15 | */ | |
16 | ||
17 | #ifndef DB_CTL_BASE_H | |
18 | #define DB_CTL_BASE_H 1 | |
19 | ||
20 | #include "compiler.h" | |
3e8a2ad1 | 21 | #include "openvswitch/dynamic-string.h" |
ee89ea7b | 22 | #include "openvswitch/shash.h" |
07ff77cc AW |
23 | |
24 | struct ctl_context; | |
25 | struct option; | |
26 | struct ovsdb_idl; | |
27 | struct ovsdb_idl_row; | |
28 | struct ovsdb_idl_txn; | |
29 | struct ovsdb_symbol_table; | |
30 | struct table; | |
31 | ||
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: | |
35 | * | |
07ff77cc AW |
36 | * - the command syntaxes for each command. (See 'struct ctl_command_syntax' |
37 | * for more info) and regiters them using ctl_register_commands(). | |
38 | * | |
39 | * - the *ctl command context by inheriting the 'struct ctl_context' for | |
40 | * additional commands implemented by user. (See 'struct ctl_context' for | |
41 | * more info) | |
07ff77cc AW |
42 | */ |
43 | ||
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 | |
46 | ||
802cb46e | 47 | struct ctl_table_class; |
3f5b5f7b BP |
48 | struct ovsdb_idl_class; |
49 | struct ovsdb_idl_table_class; | |
d33340a5 | 50 | struct cmd_show_table; |
3f5b5f7b BP |
51 | |
52 | /* ctl_init() figures out the number of tables on its own and flags an error if | |
53 | * 'ctl_classes' was defined with the wrong number of elements. */ | |
54 | #define ctl_init(idl_classes, ctl_classes, cmd_show_table, ctl_exit_func) \ | |
55 | (BUILD_ASSERT(ARRAY_SIZE(idl_classes) == ARRAY_SIZE(ctl_classes)), \ | |
56 | ctl_init__(idl_classes, ctl_classes, ARRAY_SIZE(idl_classes), \ | |
57 | cmd_show_table, ctl_exit_func)) | |
58 | void ctl_init__(const struct ovsdb_idl_table_class *idl_classes, | |
59 | const struct ctl_table_class *ctl_classes, | |
60 | size_t n_classes, | |
61 | const struct cmd_show_table *cmd_show_tables, | |
62 | void (*ctl_exit_func)(int status)); | |
51a73ff0 | 63 | char *ctl_default_db(void); |
07ff77cc AW |
64 | OVS_NO_RETURN void ctl_fatal(const char *, ...) OVS_PRINTF_FORMAT(1, 2); |
65 | ||
943f394e | 66 | /* *ctl command syntax structure, to be defined by each command implementation. |
07ff77cc AW |
67 | * |
68 | * Execution Path | |
69 | * ============== | |
70 | * | |
71 | * Three stylized functions accompany each of these data structures: | |
72 | * | |
73 | * "pre-run" "run" "post-run" | |
74 | * --------------- ------------ ----------------- | |
75 | * *ctl ->prerequisites ->run ->postprocess | |
76 | * | |
943f394e | 77 | * Any *ctl command implementation should go through the following execution |
07ff77cc AW |
78 | * path: |
79 | * | |
80 | * 1. parses user command-line input and finds the corresponding syntax | |
81 | * structures. | |
82 | * | |
83 | * 2. calls prerequisites() for getting the columns or tables used by each | |
84 | * command. | |
85 | * | |
86 | * 3. calls run() to execute each command and to generate output. | |
87 | * | |
88 | * 4. calls postprocess() after output has been committed. (Only needed | |
89 | * by 'create' command sofar) | |
90 | * | |
91 | * Execution Context | |
92 | * ================= | |
93 | * | |
94 | * Each of the stylized functions requires the 'struct ctl_context' as input | |
95 | * to provide context e.g. command-line arguments, table to be modified. User | |
96 | * may define more specific context (by inheriting 'struct ctl_context') and | |
97 | * write stylized functions that use it. In that case, CONTAINER_OF() can | |
98 | * be used to cast the generic context to the specific one. | |
99 | * | |
100 | * */ | |
101 | struct ctl_command_syntax { | |
102 | const char *name; /* e.g. "add-br" */ | |
103 | int min_args; /* Min number of arguments following name. */ | |
104 | int max_args; /* Max number of arguments following name. */ | |
105 | ||
106 | /* Names that roughly describe the arguments that the command | |
107 | * uses. These should be similar to the names displayed in the | |
108 | * man page or in the help output. */ | |
109 | const char *arguments; | |
110 | ||
111 | /* If nonnull, calls ovsdb_idl_add_column() or ovsdb_idl_add_table() for | |
112 | * each column or table in ctx->idl that it uses. */ | |
113 | void (*prerequisites)(struct ctl_context *ctx); | |
114 | ||
115 | /* Does the actual work of the command and puts the command's output, if | |
116 | * any, in ctx->output or ctx->table. | |
117 | * | |
118 | * Alternatively, if some prerequisite of the command is not met and the | |
119 | * caller should wait for something to change and then retry, it may set | |
120 | * ctx->try_again to true. (Only the "wait-until" command currently does | |
121 | * this.) */ | |
122 | void (*run)(struct ctl_context *ctx); | |
123 | ||
124 | /* If nonnull, called after the transaction has been successfully | |
125 | * committed. ctx->output is the output from the "run" function, which | |
126 | * this function may modify and otherwise postprocess as needed. (Only the | |
127 | * "create" command currently does any postprocessing.) */ | |
128 | void (*postprocess)(struct ctl_context *ctx); | |
129 | ||
130 | /* A comma-separated list of supported options, e.g. "--a,--b", or the | |
131 | * empty string if the command does not support any options. */ | |
132 | const char *options; | |
133 | ||
1f4a7252 | 134 | enum { RO, RW } mode; /* Does this command modify the database? */ |
07ff77cc AW |
135 | }; |
136 | ||
137 | /* A command extracted from command-line input plus the structs for | |
138 | * output generation. */ | |
139 | struct ctl_command { | |
140 | /* Data that remains constant after initialization. */ | |
141 | const struct ctl_command_syntax *syntax; | |
142 | int argc; | |
143 | char **argv; | |
144 | struct shash options; | |
145 | ||
146 | /* Data modified by commands. */ | |
147 | struct ds output; | |
148 | struct table *table; | |
149 | }; | |
150 | ||
151 | bool ctl_might_write_to_db(char **argv); | |
152 | const char *ctl_get_db_cmd_usage(void); | |
51a73ff0 AW |
153 | void ctl_print_commands(void); |
154 | void ctl_print_options(const struct option *); | |
155 | void ctl_add_cmd_options(struct option **, size_t *n_options_p, | |
156 | size_t *allocated_options_p, int opt_val); | |
07ff77cc | 157 | void ctl_register_commands(const struct ctl_command_syntax *); |
07ff77cc AW |
158 | struct ctl_command *ctl_parse_commands(int argc, char *argv[], |
159 | struct shash *local_options, | |
160 | size_t *n_commandsp); | |
af046a16 | 161 | |
016e4684 AW |
162 | /* Sometimes, it is desirable to print the table with weak reference to |
163 | * rows in a 'cmd_show_table' table. In that case, the 'weak_ref_table' | |
164 | * should be used and user must define all variables. */ | |
165 | struct weak_ref_table { | |
166 | const struct ovsdb_idl_table_class *table; | |
167 | const struct ovsdb_idl_column *name_column; | |
168 | /* This colum must be a weak reference to the owning | |
169 | * 'struct cmd_show_table''s table row. */ | |
170 | const struct ovsdb_idl_column *wref_column; | |
171 | }; | |
172 | ||
af046a16 AW |
173 | /* This struct is for organizing the 'show' command output where: |
174 | * | |
175 | * - 'table' is the table to show. | |
176 | * | |
177 | * - if 'name_column' is not null, it is used as the name for each row | |
178 | * in 'table'. | |
179 | * | |
180 | * - 'columns[]' allows user to specify the print of additional columns | |
181 | * in 'table'. | |
016e4684 AW |
182 | * |
183 | * - if 'wref_table' is populated, print 'wref_table.name_column' for | |
184 | * each row in table 'wref_table.table' that has a reference to 'table' | |
185 | * in 'wref_table.wref_column'. Every field must be populated. | |
186 | * | |
af046a16 AW |
187 | * */ |
188 | struct cmd_show_table { | |
189 | const struct ovsdb_idl_table_class *table; | |
190 | const struct ovsdb_idl_column *name_column; | |
191 | const struct ovsdb_idl_column *columns[3]; /* Seems like a good number. */ | |
016e4684 | 192 | const struct weak_ref_table wref_table; |
af046a16 AW |
193 | }; |
194 | ||
07ff77cc AW |
195 | \f |
196 | /* The base context struct for conducting the common database | |
197 | * operations (commands listed in 'db_ctl_commands'). User should | |
198 | * define the per-schema context by inheriting this struct as base. | |
199 | * | |
200 | * Database Caches | |
201 | * =============== | |
202 | * | |
203 | * User may implement caches for contents of the database to facilitate | |
204 | * specific commands. In that case, the common commands defined in | |
205 | * 'db_ctl_commands' that may invalidate the cache must call the | |
206 | * invalidate_cache(). | |
207 | * | |
208 | **/ | |
209 | struct ctl_context { | |
210 | /* Read-only. */ | |
211 | int argc; | |
212 | char **argv; | |
213 | struct shash options; | |
214 | ||
215 | /* Modifiable state. */ | |
216 | struct ds output; | |
217 | struct table *table; | |
218 | struct ovsdb_idl *idl; | |
219 | struct ovsdb_idl_txn *txn; | |
220 | struct ovsdb_symbol_table *symtab; | |
221 | ||
222 | /* For implementation with a cache of the contents of the database, | |
223 | * this function will be called when the database is changed and the | |
224 | * change makes the cache no longer valid. */ | |
225 | void (*invalidate_cache)(struct ctl_context *); | |
226 | ||
227 | /* A command may set this member to true if some prerequisite is not met | |
228 | * and the caller should wait for something to change and then retry. */ | |
229 | bool try_again; | |
230 | }; | |
231 | ||
232 | void ctl_context_init_command(struct ctl_context *, struct ctl_command *); | |
233 | void ctl_context_init(struct ctl_context *, struct ctl_command *, | |
234 | struct ovsdb_idl *, struct ovsdb_idl_txn *, | |
235 | struct ovsdb_symbol_table *, | |
236 | void (*invalidate_cache)(struct ctl_context *)); | |
237 | void ctl_context_done_command(struct ctl_context *, struct ctl_command *); | |
238 | void ctl_context_done(struct ctl_context *, struct ctl_command *); | |
239 | ||
240 | struct ctl_row_id { | |
241 | const struct ovsdb_idl_table_class *table; | |
242 | const struct ovsdb_idl_column *name_column; | |
243 | const struct ovsdb_idl_column *uuid_column; | |
244 | }; | |
245 | ||
246 | struct ctl_table_class { | |
07ff77cc AW |
247 | struct ctl_row_id row_ids[2]; |
248 | }; | |
249 | ||
15ffc202 AZ |
250 | void ctl_set_column(const char *table_name, |
251 | const struct ovsdb_idl_row *, const char *arg, | |
252 | struct ovsdb_symbol_table *); | |
07ff77cc AW |
253 | |
254 | #endif /* db-ctl-base.h */ |