]>
Commit | Line | Data |
---|---|---|
07ff77cc AW |
1 | /* |
2 | * Copyright (c) 2015 Nicira, Inc. | |
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; |
d33340a5 | 48 | struct cmd_show_table; |
ce6f1d1f | 49 | void ctl_init(const struct ctl_table_class *tables, |
d33340a5 AZ |
50 | const struct cmd_show_table *cmd_show_tables, |
51 | void (*ctl_exit_func)(int status)); | |
51a73ff0 | 52 | char *ctl_default_db(void); |
07ff77cc AW |
53 | OVS_NO_RETURN void ctl_fatal(const char *, ...) OVS_PRINTF_FORMAT(1, 2); |
54 | ||
943f394e | 55 | /* *ctl command syntax structure, to be defined by each command implementation. |
07ff77cc AW |
56 | * |
57 | * Execution Path | |
58 | * ============== | |
59 | * | |
60 | * Three stylized functions accompany each of these data structures: | |
61 | * | |
62 | * "pre-run" "run" "post-run" | |
63 | * --------------- ------------ ----------------- | |
64 | * *ctl ->prerequisites ->run ->postprocess | |
65 | * | |
943f394e | 66 | * Any *ctl command implementation should go through the following execution |
07ff77cc AW |
67 | * path: |
68 | * | |
69 | * 1. parses user command-line input and finds the corresponding syntax | |
70 | * structures. | |
71 | * | |
72 | * 2. calls prerequisites() for getting the columns or tables used by each | |
73 | * command. | |
74 | * | |
75 | * 3. calls run() to execute each command and to generate output. | |
76 | * | |
77 | * 4. calls postprocess() after output has been committed. (Only needed | |
78 | * by 'create' command sofar) | |
79 | * | |
80 | * Execution Context | |
81 | * ================= | |
82 | * | |
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. | |
88 | * | |
89 | * */ | |
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. */ | |
94 | ||
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; | |
99 | ||
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); | |
103 | ||
104 | /* Does the actual work of the command and puts the command's output, if | |
105 | * any, in ctx->output or ctx->table. | |
106 | * | |
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 | |
110 | * this.) */ | |
111 | void (*run)(struct ctl_context *ctx); | |
112 | ||
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); | |
118 | ||
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. */ | |
121 | const char *options; | |
122 | ||
1f4a7252 | 123 | enum { RO, RW } mode; /* Does this command modify the database? */ |
07ff77cc AW |
124 | }; |
125 | ||
126 | /* A command extracted from command-line input plus the structs for | |
127 | * output generation. */ | |
128 | struct ctl_command { | |
129 | /* Data that remains constant after initialization. */ | |
130 | const struct ctl_command_syntax *syntax; | |
131 | int argc; | |
132 | char **argv; | |
133 | struct shash options; | |
134 | ||
135 | /* Data modified by commands. */ | |
136 | struct ds output; | |
137 | struct table *table; | |
138 | }; | |
139 | ||
140 | bool ctl_might_write_to_db(char **argv); | |
141 | const char *ctl_get_db_cmd_usage(void); | |
51a73ff0 AW |
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); | |
07ff77cc | 146 | void ctl_register_commands(const struct ctl_command_syntax *); |
07ff77cc AW |
147 | struct ctl_command *ctl_parse_commands(int argc, char *argv[], |
148 | struct shash *local_options, | |
149 | size_t *n_commandsp); | |
af046a16 | 150 | |
016e4684 AW |
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; | |
160 | }; | |
161 | ||
af046a16 AW |
162 | /* This struct is for organizing the 'show' command output where: |
163 | * | |
164 | * - 'table' is the table to show. | |
165 | * | |
166 | * - if 'name_column' is not null, it is used as the name for each row | |
167 | * in 'table'. | |
168 | * | |
169 | * - 'columns[]' allows user to specify the print of additional columns | |
170 | * in 'table'. | |
016e4684 AW |
171 | * |
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. | |
175 | * | |
af046a16 AW |
176 | * */ |
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. */ | |
016e4684 | 181 | const struct weak_ref_table wref_table; |
af046a16 AW |
182 | }; |
183 | ||
07ff77cc AW |
184 | \f |
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. | |
188 | * | |
189 | * Database Caches | |
190 | * =============== | |
191 | * | |
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(). | |
196 | * | |
197 | **/ | |
198 | struct ctl_context { | |
199 | /* Read-only. */ | |
200 | int argc; | |
201 | char **argv; | |
202 | struct shash options; | |
203 | ||
204 | /* Modifiable state. */ | |
205 | struct ds output; | |
206 | struct table *table; | |
207 | struct ovsdb_idl *idl; | |
208 | struct ovsdb_idl_txn *txn; | |
209 | struct ovsdb_symbol_table *symtab; | |
210 | ||
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 *); | |
215 | ||
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. */ | |
218 | bool try_again; | |
219 | }; | |
220 | ||
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 *); | |
228 | ||
229 | struct ctl_row_id { | |
230 | const struct ovsdb_idl_table_class *table; | |
231 | const struct ovsdb_idl_column *name_column; | |
232 | const struct ovsdb_idl_column *uuid_column; | |
233 | }; | |
234 | ||
235 | struct ctl_table_class { | |
236 | struct ovsdb_idl_table_class *class; | |
237 | struct ctl_row_id row_ids[2]; | |
238 | }; | |
239 | ||
15ffc202 AZ |
240 | void ctl_set_column(const char *table_name, |
241 | const struct ovsdb_idl_row *, const char *arg, | |
242 | struct ovsdb_symbol_table *); | |
07ff77cc AW |
243 | |
244 | #endif /* db-ctl-base.h */ |