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 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  * reconfigure() is called when process receives SIGUSR1 or SIGHUP
  53  * shutdown() is called when process receives SIGINT or SIGTERM or
  54  *             when wait computation has finished
  55  *
  56  * wait_send() starts the async computation to keep running the daemon
  57  * wait_recv() ends the async computation to keep running the daemon
  58  *
  59  * If wait_send()/wait_recv() is NULL, then daemon will keep running forever.
  60  * If wait_send() returns req, then when req is over, daemon will shutdown.
  61  */
  62 struct sock_daemon_funcs {
  63         void (*startup)(void *private_data);
  64         void (*reconfigure)(void *private_data);
  65         void (*shutdown)(void *private_data);
  66
  67         struct tevent_req * (*wait_send)(TALLOC_CTX *mem_ctx,
  68                                          struct tevent_context *ev,
  69                                          void *private_data);
  70         bool (*wait_recv)(struct tevent_req *req, int *perr);
  71 };
  72
  73 /**
  74  * @brief The callback routines called for an unix-domain socket
  75  *
  76  * connect() is called when there is a new connection
  77  *
  78  * @param[in] client The new socket client context
  79  * @param[in] private_data Private data set with the socket
  80  * @retun true if connection should be accepted, false otherwise
  81  *
  82  *
  83  * disconnect() is called  when client closes connection
  84  *
  85  * @param[in] client The socket client context
  86  * @param[in] private_data Private data associated with the socket
  87  *
  88  *
  89  * read_send() starts the async computation to process data on the socket
  90  *
  91  * @param[in] mem_ctx Talloc memory context
  92  * @param[in] ev Tevent context
  93  * @param[in] client The socket client context
  94  * @param[in] buf Data received from the client
  95  * @param[in] buflen Length of the data
  96  * @param[i] private_data Private data associatedwith the socket
  97  * @return new tevent reques, or NULL on failure
  98  *
  99  *
 100  * read_recv() ends the async computation to process data on the socket
 101  *
 102  * @param[in] req Tevent request
 103  * @param[out] perr errno in case of failure
 104  * @return true on success, false on failure
 105  *
 106  */
 107 struct sock_socket_funcs {
 108         bool (*connect)(struct sock_client_context *client,
 109                         void *private_data);
 110         void (*disconnect)(struct sock_client_context *client,
 111                            void *private_data);
 112
 113         struct tevent_req * (*read_send)(TALLOC_CTX *mem_ctx,
 114                                          struct tevent_context *ev,
 115                                          struct sock_client_context *client,
 116                                          uint8_t *buf, size_t buflen,
 117                                          void *private_data);
 118         bool (*read_recv)(struct tevent_req *req, int *perr);
 119 };
 120
 121 /**
 122  * @brief Async computation to send data to the client
 123  *
 124  * @param[in] mem_ctx Talloc memory context
 125  * @param[in] ev Tevent context
 126  * @param[in] client The socket client context
 127  * @param[in] buf Data to be sent to the client
 128  * @param[in] buflen Length of the data
 129  * @return new tevent request, or NULL on failure
 130  */
 131 struct tevent_req *sock_socket_write_send(TALLOC_CTX *mem_ctx,
 132                                           struct tevent_context *ev,
 133                                           struct sock_client_context *client,
 134                                           uint8_t *buf, size_t buflen);
 135
 136 /**
 137  * @brief Async computation end to send data to client
 138  *
 139  * @param[in] req Tevent request
 140  * @param[out] perr errno in case of failure
 141  * @return true on success, false on failure
 142  */
 143 bool sock_socket_write_recv(struct tevent_req *req, int *perr);
 144
 145 /**
 146  * @brief Create a new socket daemon
 147  *
 148  * @param[in] mem_ctx Talloc memory context
 149  * @param[in] daemon_name Name of the daemon, used for logging
 150  * @param[in] logging Logging setup string
 151  * @param[in] debug_level Debug level to log at
 152  * @param[in] pidfile PID file to create, NULL if no PID file required
 153  * @param[in] funcs Socket daemon callback routines
 154  * @param[in] private_data Private data associated with callback routines
 155  * @param[out] result New socket daemon context
 156  * @return 0 on success, errno on failure
 157  */
 158 int sock_daemon_setup(TALLOC_CTX *mem_ctx, const char *daemon_name,
 159                       const char *logging, const char *debug_level,
 160                       const char *pidfile,
 161                       struct sock_daemon_funcs *funcs,
 162                       void *private_data,
 163                       struct sock_daemon_context **result);
 164
 165 /**
 166  * @brief Create and listen to the unix domain socket
 167  *
 168  * @param[in] sockd Socket daemon context
 169  * @param[in] sockpath Unix domain socket path
 170  * @param[in] funcs socket callback routines
 171  * @param[in] private_data Private data associated with callback routines
 172  * @return 0 on success, errno on failure
 173  */
 174 int sock_daemon_add_unix(struct sock_daemon_context *sockd,
 175                          const char *sockpath,
 176                          struct sock_socket_funcs *funcs,
 177                          void *private_data);
 178
 179 /**
 180  * @brief Async computation start to run a socket daemon
 181  *
 182  * @param[in] mem_ctx Talloc memory context
 183  * @param[in] ev Tevent context
 184  * @param[in] sockd The socket daemon context
 185  * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
 186  * @return new tevent request, NULL on failure
 187  */
 188 struct tevent_req *sock_daemon_run_send(TALLOC_CTX *mem_ctx,
 189                                         struct tevent_context *ev,
 190                                         struct sock_daemon_context *sockd,
 191                                         pid_t pid_watch);
 192
 193 /**
 194  * @brief Async computation end to run a socket daemon
 195  *
 196  * @param[in] req Tevent request
 197  * @param[out] perr errno in case of failure
 198  * @return true on success, false on failure
 199  */
 200 bool sock_daemon_run_recv(struct tevent_req *req, int *perr);
 201
 202 /**
 203  * @brief Sync way to start a daemon
 204  *
 205  * @param[in] ev Tevent context
 206  * @param[in] sockd The socket daemon context
 207  * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
 208  * @return 0 on success, errno on failure
 209  *
 210  * This call will return only on shutdown of the daemon
 211  */
 212 int sock_daemon_run(struct tevent_context *ev,
 213                     struct sock_daemon_context *sockd,
 214                     pid_t pid_watch);
 215
 216 #endif /* __CTDB_SOCK_DAEMON_H__ */