2 A server based on unix domain socket
4 Copyright (C) Amitay Isaacs 2016
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.
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.
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/>.
20 #ifndef __CTDB_SOCK_DAEMON_H__
21 #define __CTDB_SOCK_DAEMON_H__
26 #include "common/logging.h"
31 * @brief A framework for a server based on unix-domain sockets.
33 * This abstraction allows one to build simple servers that communicate using
34 * unix-domain sockets. It takes care of the common boilerplate.
38 * @brief The abstract socket daemon context
40 struct sock_daemon_context
;
43 * @brief The abstract socket client context
45 struct sock_client_context
;
48 * @brief The callback routines called during daemon life cycle
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.
55 * startup_send()/startup_recv() is the async version of startup()
57 * reconfigure() is called when the daemon receives SIGUSR1 or SIGHUP
58 * reconfigure() should return 0 for success, non-zero value on failure
59 * On failure, sock_daemon_run() will continue to run.
61 * reconfigure_send()/reconfigure_recv() is the async version of reconfigure()
63 * shutdown() is called when process receives SIGINT or SIGTERM or
64 * when wait computation has finished
66 * shutdown_send()/shutdown_recv() is the async version of shutdown()
68 * Please note that only one (sync or async) version of these functions
69 * will be called. If both versions are defined, then only async function
72 * wait_send() starts the async computation to keep running the daemon
73 * wait_recv() ends the async computation to keep running the daemon
75 * If wait_send()/wait_recv() is NULL, then daemon will keep running forever.
76 * If wait_send() returns req, then when req is over, daemon will shutdown.
78 struct sock_daemon_funcs
{
79 int (*startup
)(void *private_data
);
81 struct tevent_req
* (*startup_send
)(TALLOC_CTX
*mem_ctx
,
82 struct tevent_context
*ev
,
84 bool (*startup_recv
)(struct tevent_req
*req
, int *perr
);
86 int (*reconfigure
)(void *private_data
);
88 struct tevent_req
* (*reconfigure_send
)(TALLOC_CTX
*mem_ctx
,
89 struct tevent_context
*ev
,
91 bool (*reconfigure_recv
)(struct tevent_req
*req
, int *perr
);
93 void (*shutdown
)(void *private_data
);
95 struct tevent_req
* (*shutdown_send
)(TALLOC_CTX
*mem_ctx
,
96 struct tevent_context
*ev
,
98 void (*shutdown_recv
)(struct tevent_req
*req
);
100 struct tevent_req
* (*wait_send
)(TALLOC_CTX
*mem_ctx
,
101 struct tevent_context
*ev
,
103 bool (*wait_recv
)(struct tevent_req
*req
, int *perr
);
107 * @brief The callback routines called for an unix-domain socket
109 * connect() is called when there is a new connection
111 * @param[in] client The new socket client context
112 * @param[in] pid The pid of the new client process, or -1 if unknown
113 * @param[in] private_data Private data set with the socket
114 * @return true if connection should be accepted, false otherwise
117 * disconnect() is called when client closes connection
119 * @param[in] client The socket client context
120 * @param[in] private_data Private data associated with the socket
123 * read_send() starts the async computation to process data on the socket
125 * @param[in] mem_ctx Talloc memory context
126 * @param[in] ev Tevent context
127 * @param[in] client The socket client context
128 * @param[in] buf Data received from the client
129 * @param[in] buflen Length of the data
130 * @param[i] private_data Private data associatedwith the socket
131 * @return new tevent reques, or NULL on failure
134 * read_recv() ends the async computation to process data on the socket
136 * @param[in] req Tevent request
137 * @param[out] perr errno in case of failure
138 * @return true on success, false on failure
141 struct sock_socket_funcs
{
142 bool (*connect
)(struct sock_client_context
*client
,
145 void (*disconnect
)(struct sock_client_context
*client
,
148 struct tevent_req
* (*read_send
)(TALLOC_CTX
*mem_ctx
,
149 struct tevent_context
*ev
,
150 struct sock_client_context
*client
,
151 uint8_t *buf
, size_t buflen
,
153 bool (*read_recv
)(struct tevent_req
*req
, int *perr
);
157 * @brief Async computation to send data to the client
159 * @param[in] mem_ctx Talloc memory context
160 * @param[in] ev Tevent context
161 * @param[in] client The socket client context
162 * @param[in] buf Data to be sent to the client
163 * @param[in] buflen Length of the data
164 * @return new tevent request, or NULL on failure
166 struct tevent_req
*sock_socket_write_send(TALLOC_CTX
*mem_ctx
,
167 struct tevent_context
*ev
,
168 struct sock_client_context
*client
,
169 uint8_t *buf
, size_t buflen
);
172 * @brief Async computation end to send data to client
174 * @param[in] req Tevent request
175 * @param[out] perr errno in case of failure
176 * @return true on success, false on failure
178 bool sock_socket_write_recv(struct tevent_req
*req
, int *perr
);
181 * @brief Create a new socket daemon
183 * @param[in] mem_ctx Talloc memory context
184 * @param[in] daemon_name Name of the daemon, used for logging
185 * @param[in] logging Logging setup string
186 * @param[in] debug_level Debug level to log at
187 * @param[in] funcs Socket daemon callback routines
188 * @param[in] private_data Private data associated with callback routines
189 * @param[out] result New socket daemon context
190 * @return 0 on success, errno on failure
192 int sock_daemon_setup(TALLOC_CTX
*mem_ctx
, const char *daemon_name
,
193 const char *logging
, const char *debug_level
,
194 struct sock_daemon_funcs
*funcs
,
196 struct sock_daemon_context
**result
);
199 * @brief Create and listen to the unix domain socket
201 * @param[in] sockd Socket daemon context
202 * @param[in] sockpath Unix domain socket path
203 * @param[in] funcs socket callback routines
204 * @param[in] private_data Private data associated with callback routines
205 * @return 0 on success, errno on failure
207 int sock_daemon_add_unix(struct sock_daemon_context
*sockd
,
208 const char *sockpath
,
209 struct sock_socket_funcs
*funcs
,
213 * @brief Set file descriptor for indicating startup success
215 * On successful completion, 0 (unsigned int) will be written to the fd.
217 * @param[in] sockd Socket daemon context
218 * @param[in] fd File descriptor
220 void sock_daemon_set_startup_fd(struct sock_daemon_context
*sockd
, int fd
);
223 * @brief Async computation start to run a socket daemon
225 * @param[in] mem_ctx Talloc memory context
226 * @param[in] ev Tevent context
227 * @param[in] sockd The socket daemon context
228 * @param[in] pidfile PID file to create, NULL if no PID file required
229 * @param[in] do_fork Whether the daemon should fork on startup
230 * @param[in] create_session Whether the daemon should create a new session
231 * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
232 * @return new tevent request, NULL on failure
234 struct tevent_req
*sock_daemon_run_send(TALLOC_CTX
*mem_ctx
,
235 struct tevent_context
*ev
,
236 struct sock_daemon_context
*sockd
,
238 bool do_fork
, bool create_session
,
242 * @brief Async computation end to run a socket daemon
244 * @param[in] req Tevent request
245 * @param[out] perr errno in case of failure
246 * @return true on success, false on failure
248 bool sock_daemon_run_recv(struct tevent_req
*req
, int *perr
);
251 * @brief Sync way to start a daemon
253 * @param[in] ev Tevent context
254 * @param[in] sockd The socket daemon context
255 * @param[in] pidfile PID file to create, NULL if no PID file required
256 * @param[in] do_fork Whether the daemon should fork on startup
257 * @param[in] create_session Whether the daemon should create a new session
258 * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
259 * @return 0 on success, errno on failure
261 * This call will return only on shutdown of the daemon
263 int sock_daemon_run(struct tevent_context
*ev
,
264 struct sock_daemon_context
*sockd
,
266 bool do_fork
, bool create_session
,
269 #endif /* __CTDB_SOCK_DAEMON_H__ */