ctdb/common/tmon.h

   1 /*
   2    Trivial FD monitoring
   3
   4    Copyright (C) Martin Schwenke & Amitay Isaacs, DataDirect Networks  2022
   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_TMON_H__
  21 #define __CTDB_TMON_H__
  22
  23 #include <talloc.h>
  24 #include <tevent.h>
  25
  26 /**
  27  * @file tmon.h
  28  *
  29  * @brief Interprocess file descriptor (pipe and socketpair) monitoring
  30  *
  31  * Assumes 2 processes connected by a pipe(2) or a socketpair(2).  A
  32  * simple protocol is defined to allow sending various types of status
  33  * information.  When a pipe(2) is used the reader can monitor for
  34  * close and read packets, while the sender can write packets. When a
  35  * socketpair(2) is used then both ends can monitor for close, and
  36  * read and write packets.  A read timeout can be specified,
  37  * terminating the computation if no packets are received.
  38  *
  39  * A simplified interface is provided to monitor for close and allow
  40  * sending/monitoring of one-way ping packets.  A ping timeout occurs
  41  * when one end is expecting pings but none are received during the
  42  * timeout interval - no response is sent to pings, they merely reset
  43  * a timer on the receiving end.
  44  */
  45
  46 struct tmon_pkt;
  47
  48 struct tmon_actions {
  49         int (*write_callback)(void *private_data, struct tmon_pkt *pkt);
  50         int (*timeout_callback)(void *private_data);
  51         int (*read_callback)(void *private_data, struct tmon_pkt *pkt);
  52         int (*close_callback)(void *private_data);
  53 };
  54
  55 /*
  56  * Return value from write_callback() and read_callback() to cause the
  57  * computation to exit successfully.  For consistency this can also be
  58  * used with timeout_callback() and close_callback().
  59  */
  60 #define TMON_STATUS_EXIT (-1)
  61
  62 /* Return value from write_callback() to skip write */
  63 #define TMON_STATUS_SKIP (-2)
  64
  65 /* For direction, below */
  66 #define TMON_FD_READ  0x1
  67 #define TMON_FD_WRITE 0x2
  68 #define TMON_FD_BOTH  (TMON_FD_READ | TMON_FD_WRITE)
  69
  70 /**
  71  * @brief Async computation to start FD monitoring
  72  *
  73  * @param[in] mem_ctx Talloc memory context
  74  * @param[in] ev Tevent context
  75  * @param[in] fd File descriptor for "this" end of pipe/socketpair
  76  * @param[in] direction Read, write or both - for sanity checking
  77  * @param[in] read_timeout Seconds to trigger timeout when no packets received
  78  * @param[in] write_interval Seconds to trigger write_callback
  79  * @param[in] actions struct containing callbacks
  80  * @param[in] private_data Passed to callbacks
  81  * @return new tevent request or NULL on failure
  82  *
  83  * @note read_timeout implies monitor_close
  84  *
  85  * @note The computation will complete when:
  86  *
  87  * - The writing end closes (e.g. writer process terminates) - EPIPE
  88  * - read_timeout is non-zero and timeout occurs - ETIMEDOUT
  89  * - Packets received with no read_callback defined - EIO
  90  * - Invalid or unexpected packet received - EPROTO
  91  * - File descriptor readable but no bytes to read - error: EPIPE
  92  * - Invalid combination of direction, callbacks, timeouts: EINVAL
  93  * - An unexpected error occurs - other
  94  *
  95  * @note action callbacks return an int that can be used to trigger
  96  * other errors or override an error.  For example:
  97  *
  98  * - write_callback() can return non-zero errno, causing an error
  99  * - close_callback() can return zero, overriding the default EPIPE error
 100  * - timeout_callback() can return something other than ETIMEDOUT
 101  * - read_callback() can return EPROTO for unexpected packet types
 102  *
 103  * Reading of exit and errno packets is handled internally (read
 104  * callback is never called).  Write callback can return special
 105  * value TMON_STATUS_SKIP to avoid sending any data.
 106  */
 107 struct tevent_req *tmon_send(TALLOC_CTX *mem_ctx,
 108                              struct tevent_context *ev,
 109                              int fd,
 110                              int direction,
 111                              unsigned long read_timeout,
 112                              unsigned long write_interval,
 113                              struct tmon_actions *actions,
 114                              void *private_data);
 115
 116 /**
 117  * @brief Async computation to end FD monitoring
 118  *
 119  * @param[in] req Tevent request
 120  * @param[out] perr errno in case of failure
 121  * @return true on success, false on failure
 122  */
 123 bool tmon_recv(struct tevent_req *req, int *perr);
 124
 125 /**
 126  * @brief Fill in an exit packet
 127  *
 128  * @param[in,out] pkt An exit packet
 129  * @return true on success, false on failure
 130  */
 131 bool tmon_set_exit(struct tmon_pkt *pkt);
 132 /**
 133  * @brief Fill in an errno packet
 134  *
 135  * @param[in,out] pkt An errno packet
 136  * @param[in] err An errno to send in packet
 137  * @return true on success, false on failure
 138  */
 139 bool tmon_set_errno(struct tmon_pkt *pkt, int err);
 140 /**
 141  * @brief Fill in a ping packet
 142  *
 143  * @param[in,out] pkt A ping packet
 144  * @return true on success, false on failure
 145  */
 146 bool tmon_set_ping(struct tmon_pkt *pkt);
 147 /**
 148  * @brief Fill in an ASCII packet
 149  *
 150  * @param[in,out] pkt An ASCII packet
 151  * @param[in] c An ASCII character to send in packet
 152  * @return true on success, false on failure
 153  */
 154 bool tmon_set_ascii(struct tmon_pkt *pkt, char c);
 155 /**
 156  * @brief Fill in a custom packet
 157  *
 158  * @param[in,out] pkt A custom packet
 159  * @param[in] val A uint16_t to send in a custom packet
 160  * @return true on success, false on failure
 161  */
 162 bool tmon_set_custom(struct tmon_pkt *pkt, uint16_t val);
 163
 164 /**
 165  * @brief Validate a ping packet
 166  *
 167  * @param[in] pkt A ping packet
 168  * @return true on success, false on failure
 169  */
 170 bool tmon_parse_ping(struct tmon_pkt *pkt);
 171
 172 /**
 173  * @brief Validate ASCII packet and parse out character
 174  *
 175  * @param[in] pkt An ASCII packet
 176  * @param[out] c An ASCII character value from packet
 177  * @return true on success, false on failure
 178  */
 179 bool tmon_parse_ascii(struct tmon_pkt *pkt, char *c);
 180
 181 /**
 182  * @brief Validate custom packet and parse out value
 183  *
 184  * @param[in] pkt A custom packet
 185  * @param[out] val A uint16_t value from packet
 186  * @return true on success, false on failure
 187  */
 188 bool tmon_parse_custom(struct tmon_pkt *pkt, uint16_t *val);
 189
 190 /**
 191  * @brief Write a packet
 192  *
 193  * @param[in] req Tevent request created by tmon_send
 194  * @param[in] pkt Packet to write
 195  * @return true on success, false on failure
 196  */
 197 bool tmon_write(struct tevent_req *req, struct tmon_pkt *pkt);
 198
 199 /**
 200  * @brief Async computation to start ping monitoring
 201  *
 202  * @param[in] mem_ctx Talloc memory context
 203  * @param[in] ev Tevent context
 204  * @param[in] fd File descriptor for "this" end of pipe/socketpair
 205  * @param[in] direction Read, write or both - for sanity checking
 206  * @param[in] timeout Timeout for pings on receiving end
 207  * @param[in] interval Send a ping packet every interval seconds
 208  */
 209 struct tevent_req *tmon_ping_send(TALLOC_CTX *mem_ctx,
 210                                   struct tevent_context *ev,
 211                                   int fd,
 212                                   int direction,
 213                                   unsigned long timeout,
 214                                   unsigned long interval);
 215
 216 bool tmon_ping_recv(struct tevent_req *req, int *perr);
 217
 218 #endif /* __CTDB_TMON_H__ */