ctdb/common/run_event.h

   1 /*
   2    Run scripts in a directory with specific event arguments
   3
   4    Copyright (C) Amitay Isaacs  2017
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef __CTDB_RUN_EVENT_H__
  21 #define __CTDB_RUN_EVENT_H__
  22
  23 #include <talloc.h>
  24 #include <tevent.h>
  25
  26 #include "common/run_proc.h"
  27
  28 /**
  29  * @file run_event.h
  30  *
  31  * @brief Run scripts in a directory with specific event arguments.
  32  *
  33  * This abstraction allows to execute multiple scripts in a directory
  34  * (specified by script_dir) with given event and arguments.
  35  *
  36  * At one time, only one event can be run.  Multiple run_event calls
  37  * will cause events to be queued up.  They will be run sequentially.
  38  *
  39  * A "monitor" event is special and has special semantics.
  40  *
  41  * If a monitor event is running and another event is scheduled, the
  42  * currently running monitor event is cancelled.
  43  *
  44  * If an event (not monitor) is running and monitor event is scheduled,
  45  * then the monior event will be cancelled immediately.
  46  */
  47
  48 /**
  49  * @brief The run process context
  50  */
  51 struct run_event_context;
  52
  53 struct run_event_script {
  54         char *name;
  55         struct timeval begin, end;
  56         struct run_proc_result result;
  57         int summary;
  58         char *output;
  59 };
  60
  61 struct run_event_script_list {
  62         uint32_t num_scripts;
  63         struct run_event_script *script;
  64         int summary;
  65 };
  66
  67
  68 /**
  69  * @brief Initialize the context for running events
  70  *
  71  * @param[in] mem_ctx Talloc memory context
  72  * @param[in] ev Tevent context
  73  * @param[in] script_dir Directory containing script to run
  74  * @param[in] debug_prog Path of a program to run if a script hangs
  75  * @param[out] result New run_event context
  76  * @return 0 on success, errno on error
  77  */
  78 int run_event_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
  79                    const char *script_dir, const char *debug_prog,
  80                    struct run_event_context **result);
  81
  82 /**
  83  * @brief Get a list of scripts
  84  *
  85  * @param[in] run_ctx Run_event context
  86  * @param[in] mem_ctx Talloc memory context
  87  * @param[out] output List of valid scripts
  88  * @return 0 on success, errno on failure
  89  */
  90 int run_event_script_list(struct run_event_context *run_ctx,
  91                           TALLOC_CTX *mem_ctx,
  92                           struct run_event_script_list **output);
  93
  94 /**
  95  * @brief Enable a script
  96  *
  97  * @param[in] run_ctx Run_event context
  98  * @param[in] script_name Name of the script to enable
  99  * @return 0 on success, errno on failure
 100  */
 101 int run_event_script_enable(struct run_event_context *run_ctx,
 102                             const char *script_name);
 103
 104 /**
 105  * @brief Disable a script
 106  *
 107  * @param[in] run_ctx Run_event context
 108  * @param[in] script_name Name of the script to disable
 109  * @return 0 on success, errno on failure
 110  */
 111 int run_event_script_disable(struct run_event_context *run_ctx,
 112                              const char *script_name);
 113
 114 /**
 115  * @brief Async computation start to run an event
 116  *
 117  * @param[in] mem_ctx Talloc memory context
 118  * @param[in] ev Tevent context
 119  * @param[in] run_ctx Run_event context
 120  * @param[in] event_str The event argument to the script
 121  * @param[in] arg_str Event arguments to the script
 122  * @param[in] timeout How long to wait for execution
 123  * @return new tevent request, or NULL on failure
 124  *
 125  * arg_str contains optional arguments for an event.
 126  */
 127 struct tevent_req *run_event_send(TALLOC_CTX *mem_ctx,
 128                                   struct tevent_context *ev,
 129                                   struct run_event_context *run_ctx,
 130                                   const char *event_str,
 131                                   const char *arg_str,
 132                                   struct timeval timeout);
 133
 134 /**
 135  * @brief Async computation end to run an event
 136  *
 137  * @param[in] req Tevent request
 138  * @param[out] perr errno in case of failure
 139  * @param[in] mem_ctx Talloc memory context
 140  * @param[out] output List of scripts executed and their status
 141  * @return true on success, false on failure
 142  */
 143 bool run_event_recv(struct tevent_req *req, int *perr,
 144                     TALLOC_CTX *mem_ctx,
 145                     struct run_event_script_list **output);
 146
 147 #endif /* __CTDB_RUN_EVENT_H__ */
 148