lib/db-ctl-base.h

   1 /*
   2  * Copyright (c) 2015, 2017 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"
  21 #include "openvswitch/dynamic-string.h"
  22 #include "openvswitch/shash.h"
  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  *
  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)
  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
  47 struct ctl_table_class;
  48 struct ovsdb_idl_class;
  49 struct ovsdb_idl_table_class;
  50 struct cmd_show_table;
  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_class, table_classes, ctl_classes, cmd_show_table, \
  55                  ctl_exit_func)                                         \
  56     (BUILD_ASSERT(ARRAY_SIZE(table_classes) == ARRAY_SIZE(ctl_classes)),  \
  57      ctl_init__(idl_class, ctl_classes, cmd_show_table, ctl_exit_func))
  58 void ctl_init__(const struct ovsdb_idl_class *, const struct ctl_table_class *,
  59                 const struct cmd_show_table *cmd_show_tables,
  60                 void (*ctl_exit_func)(int status));
  61 char *ctl_default_db(void);
  62 void ctl_error(struct ctl_context *, const char *, ...)
  63 OVS_PRINTF_FORMAT(2, 3);
  64 OVS_NO_RETURN void ctl_fatal(const char *, ...) OVS_PRINTF_FORMAT(1, 2);
  65
  66 /* *ctl command syntax structure, to be defined by each command implementation.
  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  *
  77  * Any *ctl command implementation should go through the following execution
  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      *
 133      * Arguments are determined by appending special characters to option
 134      * names:
 135      *
 136      *   - Append "=" (e.g. "--id=") for a required argument.
 137      *
 138      *   - Append "?" (e.g. "--ovs?") for an optional argument.
 139      *
 140      *   - Otherwise an option does not accept an argument. */
 141     const char *options;
 142
 143     enum { RO, RW } mode;   /* Does this command modify the database? */
 144 };
 145
 146 /* A command extracted from command-line input plus the structs for
 147  * output generation. */
 148 struct ctl_command {
 149     /* Data that remains constant after initialization. */
 150     const struct ctl_command_syntax *syntax;
 151     int argc;
 152     char **argv;
 153     struct shash options;
 154
 155     /* Data modified by commands. */
 156     struct ds output;
 157     struct table *table;
 158 };
 159
 160 bool ctl_might_write_to_db(const struct ctl_command *, size_t n);
 161 const char *ctl_get_db_cmd_usage(void);
 162
 163 const char *ctl_list_db_tables_usage(void);
 164 void ctl_print_commands(void);
 165 void ctl_print_options(const struct option *);
 166 void ctl_add_cmd_options(struct option **, size_t *n_options_p,
 167                          size_t *allocated_options_p, int opt_val);
 168 void ctl_register_commands(const struct ctl_command_syntax *);
 169 char * OVS_WARN_UNUSED_RESULT ctl_parse_commands(
 170     int argc, char *argv[], struct shash *local_options,
 171     struct ctl_command **commandsp, size_t *n_commandsp);
 172
 173 /* Sometimes, it is desirable to print the table with weak reference to
 174  * rows in a 'cmd_show_table' table.  In that case, the 'weak_ref_table'
 175  * should be used and user must define all variables. */
 176 struct weak_ref_table {
 177     const struct ovsdb_idl_table_class *table;
 178     const struct ovsdb_idl_column *name_column;
 179     /* This colum must be a weak reference to the owning
 180      * 'struct cmd_show_table''s table row. */
 181     const struct ovsdb_idl_column *wref_column;
 182 };
 183
 184 /* This struct is for organizing the 'show' command output where:
 185  *
 186  * - 'table' is the table to show.
 187  *
 188  * - if 'name_column' is not null, it is used as the name for each row
 189  *   in 'table'.
 190  *
 191  * - 'columns[]' allows user to specify the print of additional columns
 192  *   in 'table'.
 193  *
 194  * - if 'wref_table' is populated, print 'wref_table.name_column' for
 195  *   each row in table 'wref_table.table' that has a reference to 'table'
 196  *   in 'wref_table.wref_column'.  Every field must be populated.
 197  *
 198  * */
 199 struct cmd_show_table {
 200     const struct ovsdb_idl_table_class *table;
 201     const struct ovsdb_idl_column *name_column;
 202     const struct ovsdb_idl_column *columns[4]; /* Seems like a good number. */
 203     const struct weak_ref_table wref_table;
 204 };
 205
 206 \f
 207 /* The base context struct for conducting the common database
 208  * operations (commands listed in 'db_ctl_commands').  User should
 209  * define the per-schema context by inheriting this struct as base.
 210  *
 211  * Database Caches
 212  * ===============
 213  *
 214  * User may implement caches for contents of the database to facilitate
 215  * specific commands.  In that case, the common commands defined in
 216  * 'db_ctl_commands' that may invalidate the cache must call the
 217  * invalidate_cache().
 218  *
 219  **/
 220 struct ctl_context {
 221     /* Read-only. */
 222     int argc;
 223     char **argv;
 224     struct shash options;
 225
 226     /* Modifiable state. */
 227     char *error;
 228     struct ds output;
 229     struct table *table;
 230     struct ovsdb_idl *idl;
 231     struct ovsdb_idl_txn *txn;
 232     struct ovsdb_symbol_table *symtab;
 233
 234     /* For implementation with a cache of the contents of the database,
 235      * this function will be called when the database is changed and the
 236      * change makes the cache no longer valid. */
 237     void (*invalidate_cache_cb)(struct ctl_context *);
 238
 239     /* A command may set this member to true if some prerequisite is not met
 240      * and the caller should wait for something to change and then retry. */
 241     bool try_again;
 242 };
 243
 244 void ctl_context_init_command(struct ctl_context *, struct ctl_command *);
 245 void ctl_context_init(struct ctl_context *, struct ctl_command *,
 246                       struct ovsdb_idl *, struct ovsdb_idl_txn *,
 247                       struct ovsdb_symbol_table *,
 248                       void (*invalidate_cache)(struct ctl_context *));
 249 void ctl_context_done_command(struct ctl_context *, struct ctl_command *);
 250 void ctl_context_done(struct ctl_context *, struct ctl_command *);
 251
 252 /* A way to identify a particular row in the database based on a user-provided
 253  * string.  If all fields are NULL, the struct is ignored.  Otherwise,
 254  * 'name_column' designates a column whose table is searched for rows that
 255  * match with the user string.  If 'key' is NULL, then 'name_column' should be
 256  * a string or integer-valued column; otherwise it should be a map from a
 257  * string to one of those types and the value corresponding to 'key' is what is
 258  * matched.  If a matching row is found, then:
 259  *
 260  *    - If 'uuid_column' is NULL, the matching row is the final row.
 261  *
 262  *    - Otherwise 'uuid_column' must designate a UUID-typed column whose value
 263  *      refers to exactly one row, which is the final row.
 264  */
 265 struct ctl_row_id {
 266     const struct ovsdb_idl_column *name_column;
 267     const char *key;
 268     const struct ovsdb_idl_column *uuid_column;
 269 };
 270
 271 struct ctl_table_class {
 272     struct ctl_row_id row_ids[4];
 273 };
 274
 275 char *ctl_get_row(struct ctl_context *, const struct ovsdb_idl_table_class *,
 276                   const char *record_id, bool must_exist,
 277                   const struct ovsdb_idl_row **);
 278
 279 char *ctl_set_column(const char *table_name, const struct ovsdb_idl_row *,
 280                      const char *arg, struct ovsdb_symbol_table *);
 281
 282 #endif /* db-ctl-base.h */