ctdb/common/sock_daemon.h

   1 /*
   2    A server based on unix domain socket
   3
   4    Copyright (C) Amitay Isaacs  2016
   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_SOCK_DAEMON_H__
  21 #define __CTDB_SOCK_DAEMON_H__
  22
  23 #include <talloc.h>
  24 #include <tevent.h>
  25
  26 #include "common/logging.h"
  27
  28 /**
  29  * @file sock_daemon.h
  30  *
  31  * @brief A framework for a server based on unix-domain sockets.
  32  *
  33  * This abstraction allows one to build simple servers that communicate using
  34  * unix-domain sockets.  It takes care of the common boilerplate.
  35  */
  36
  37 /**
  38  * @brief The abstract socket daemon context
  39  */
  40 struct sock_daemon_context;
  41
  42 /**
  43  * @brief The abstract socket client context
  44  */
  45 struct sock_client_context;
  46
  47 /**
  48  * @brief The callback routines called during daemon life cycle
  49  *
  50  * startup() is called when the daemon starts running
  51  *      either via sock_daemon_run() or via sock_daemon_run_send()
  52  *      startup() should return 0 for success, non-zero value on failure
  53  *      On failure, sock_daemon_run() will return error.
  54  *
  55  * startup_send()/startup_recv() is the async version of startup()
  56  *
  57  * reconfigure() is called when the daemon receives SIGUSR1
  58  *      reconfigure() should return 0 for success, non-zero value on failure
  59  *      On failure, sock_daemon_run() will continue to run.
  60  *
  61  * reconfigure_send()/reconfigure_recv() is the async version of reconfigure()
  62  *
  63  * reopen_logs() is called when the daemon receives SIGHUP
  64  *      reopen_logs() should return 0 for success, non-zero value on failure
  65  *      On failure, sock_daemon_run() will continue to run.
  66  *
  67  * reopen_logs_send()/reopen_logs_recv() is the async version of reopen_logs()
  68  *
  69  * shutdown() is called when process receives SIGINT or SIGTERM or
  70  *             when wait computation has finished
  71  *
  72  * shutdown_send()/shutdown_recv() is the async version of shutdown()
  73  *
  74  * Please note that only one (sync or async) version of these functions
  75  * will be called.  If both versions are defined, then only async function
  76  * will be called.
  77  *
  78  * wait_send() starts the async computation to keep running the daemon
  79  * wait_recv() ends the async computation to keep running the daemon
  80  *
  81  * If wait_send()/wait_recv() is NULL, then daemon will keep running forever.
  82  * If wait_send() returns req, then when req is over, daemon will shutdown.
  83  */
  84 struct sock_daemon_funcs {
  85         int (*startup)(void *private_data);
  86
  87         struct tevent_req * (*startup_send)(TALLOC_CTX *mem_ctx,
  88                                             struct tevent_context *ev,
  89                                             void *private_data);
  90         bool (*startup_recv)(struct tevent_req *req, int *perr);
  91
  92         int (*reconfigure)(void *private_data);
  93
  94         struct tevent_req * (*reconfigure_send)(TALLOC_CTX *mem_ctx,
  95                                                 struct tevent_context *ev,
  96                                                 void *private_data);
  97         bool (*reconfigure_recv)(struct tevent_req *req, int *perr);
  98
  99         int (*reopen_logs)(void *private_data);
 100
 101         struct tevent_req * (*reopen_logs_send)(TALLOC_CTX *mem_ctx,
 102                                                 struct tevent_context *ev,
 103                                                 void *private_data);
 104         bool (*reopen_logs_recv)(struct tevent_req *req, int *perr);
 105
 106         void (*shutdown)(void *private_data);
 107
 108         struct tevent_req * (*shutdown_send)(TALLOC_CTX *mem_ctx,
 109                                              struct tevent_context *ev,
 110                                              void *private_data);
 111         void (*shutdown_recv)(struct tevent_req *req);
 112
 113         struct tevent_req * (*wait_send)(TALLOC_CTX *mem_ctx,
 114                                          struct tevent_context *ev,
 115                                          void *private_data);
 116         bool (*wait_recv)(struct tevent_req *req, int *perr);
 117 };
 118
 119 /**
 120  * @brief The callback routines called for an unix-domain socket
 121  *
 122  * connect() is called when there is a new connection
 123  *
 124  * @param[in] client The new socket client context
 125  * @param[in] pid The pid of the new client process, or -1 if unknown
 126  * @param[in] private_data Private data set with the socket
 127  * @return true if connection should be accepted, false otherwise
 128  *
 129  *
 130  * disconnect() is called  when client closes connection
 131  *
 132  * @param[in] client The socket client context
 133  * @param[in] private_data Private data associated with the socket
 134  *
 135  *
 136  * read_send() starts the async computation to process data on the socket
 137  *
 138  * @param[in] mem_ctx Talloc memory context
 139  * @param[in] ev Tevent context
 140  * @param[in] client The socket client context
 141  * @param[in] buf Data received from the client
 142  * @param[in] buflen Length of the data
 143  * @param[i] private_data Private data associatedwith the socket
 144  * @return new tevent request, or NULL on failure
 145  *
 146  *
 147  * read_recv() ends the async computation to process data on the socket
 148  *
 149  * @param[in] req Tevent request
 150  * @param[out] perr errno in case of failure
 151  * @return true on success, false on failure
 152  *
 153  */
 154 struct sock_socket_funcs {
 155         bool (*connect)(struct sock_client_context *client,
 156                         pid_t pid,
 157                         void *private_data);
 158         void (*disconnect)(struct sock_client_context *client,
 159                            void *private_data);
 160
 161         struct tevent_req * (*read_send)(TALLOC_CTX *mem_ctx,
 162                                          struct tevent_context *ev,
 163                                          struct sock_client_context *client,
 164                                          uint8_t *buf, size_t buflen,
 165                                          void *private_data);
 166         bool (*read_recv)(struct tevent_req *req, int *perr);
 167 };
 168
 169 /**
 170  * @brief Async computation to send data to the client
 171  *
 172  * @param[in] mem_ctx Talloc memory context
 173  * @param[in] ev Tevent context
 174  * @param[in] client The socket client context
 175  * @param[in] buf Data to be sent to the client
 176  * @param[in] buflen Length of the data
 177  * @return new tevent request, or NULL on failure
 178  */
 179 struct tevent_req *sock_socket_write_send(TALLOC_CTX *mem_ctx,
 180                                           struct tevent_context *ev,
 181                                           struct sock_client_context *client,
 182                                           uint8_t *buf, size_t buflen);
 183
 184 /**
 185  * @brief Async computation end to send data to client
 186  *
 187  * @param[in] req Tevent request
 188  * @param[out] perr errno in case of failure
 189  * @return true on success, false on failure
 190  */
 191 bool sock_socket_write_recv(struct tevent_req *req, int *perr);
 192
 193 /**
 194  * @brief Create a new socket daemon
 195  *
 196  * @param[in] mem_ctx Talloc memory context
 197  * @param[in] daemon_name Name of the daemon, used for logging
 198  * @param[in] logging Logging setup string
 199  * @param[in] debug_level Debug level to log at
 200  * @param[in] funcs Socket daemon callback routines
 201  * @param[in] private_data Private data associated with callback routines
 202  * @param[out] result New socket daemon context
 203  * @return 0 on success, errno on failure
 204  */
 205 int sock_daemon_setup(TALLOC_CTX *mem_ctx, const char *daemon_name,
 206                       const char *logging, const char *debug_level,
 207                       struct sock_daemon_funcs *funcs,
 208                       void *private_data,
 209                       struct sock_daemon_context **result);
 210
 211 /**
 212  * @brief Create and listen to the unix domain socket
 213  *
 214  * @param[in] sockd Socket daemon context
 215  * @param[in] sockpath Unix domain socket path
 216  * @param[in] funcs socket callback routines
 217  * @param[in] private_data Private data associated with callback routines
 218  * @return 0 on success, errno on failure
 219  */
 220 int sock_daemon_add_unix(struct sock_daemon_context *sockd,
 221                          const char *sockpath,
 222                          struct sock_socket_funcs *funcs,
 223                          void *private_data);
 224
 225 /**
 226  * @brief Set file descriptor for indicating startup success
 227  *
 228  * On successful completion, 0 (unsigned int) will be written to the fd.
 229  *
 230  * @param[in] sockd Socket daemon context
 231  * @param[in] fd File descriptor
 232  * @return true on success, false on error
 233  */
 234 bool sock_daemon_set_startup_fd(struct sock_daemon_context *sockd, int fd);
 235
 236 /**
 237  * @brief Async computation start to run a socket daemon
 238  *
 239  * @param[in] mem_ctx Talloc memory context
 240  * @param[in] ev Tevent context
 241  * @param[in] sockd The socket daemon context
 242  * @param[in] pidfile PID file to create, NULL if no PID file required
 243  * @param[in] do_fork Whether the daemon should fork on startup
 244  * @param[in] create_session Whether the daemon should create a new session
 245  * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
 246  * @return new tevent request, NULL on failure
 247  */
 248 struct tevent_req *sock_daemon_run_send(TALLOC_CTX *mem_ctx,
 249                                         struct tevent_context *ev,
 250                                         struct sock_daemon_context *sockd,
 251                                         const char *pidfile,
 252                                         bool do_fork, bool create_session,
 253                                         pid_t pid_watch);
 254
 255 /**
 256  * @brief Async computation end to run a socket daemon
 257  *
 258  * @param[in] req Tevent request
 259  * @param[out] perr errno in case of failure
 260  * @return true on success, false on failure
 261  */
 262 bool sock_daemon_run_recv(struct tevent_req *req, int *perr);
 263
 264 /**
 265  * @brief Sync way to start a daemon
 266  *
 267  * @param[in] ev Tevent context
 268  * @param[in] sockd The socket daemon context
 269  * @param[in] pidfile PID file to create, NULL if no PID file required
 270  * @param[in] do_fork Whether the daemon should fork on startup
 271  * @param[in] create_session Whether the daemon should create a new session
 272  * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
 273  * @return 0 on success, errno on failure
 274  *
 275  * This call will return only on shutdown of the daemon
 276  */
 277 int sock_daemon_run(struct tevent_context *ev,
 278                     struct sock_daemon_context *sockd,
 279                     const char *pidfile,
 280                     bool do_fork, bool create_session,
 281                     pid_t pid_watch);
 282
 283 #endif /* __CTDB_SOCK_DAEMON_H__ */