lib/db-ctl-base.h

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