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 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] private_data Private data set with the socket
113 * @retun true if connection should be accepted, false otherwise
116 * disconnect() is called when client closes connection
118 * @param[in] client The socket client context
119 * @param[in] private_data Private data associated with the socket
122 * read_send() starts the async computation to process data on the socket
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 received from the client
128 * @param[in] buflen Length of the data
129 * @param[i] private_data Private data associatedwith the socket
130 * @return new tevent reques, or NULL on failure
133 * read_recv() ends the async computation to process data on the socket
135 * @param[in] req Tevent request
136 * @param[out] perr errno in case of failure
137 * @return true on success, false on failure
140 struct sock_socket_funcs
{
141 bool (*connect
)(struct sock_client_context
*client
,
143 void (*disconnect
)(struct sock_client_context
*client
,
146 struct tevent_req
* (*read_send
)(TALLOC_CTX
*mem_ctx
,
147 struct tevent_context
*ev
,
148 struct sock_client_context
*client
,
149 uint8_t *buf
, size_t buflen
,
151 bool (*read_recv
)(struct tevent_req
*req
, int *perr
);
155 * @brief Async computation to send data to the client
157 * @param[in] mem_ctx Talloc memory context
158 * @param[in] ev Tevent context
159 * @param[in] client The socket client context
160 * @param[in] buf Data to be sent to the client
161 * @param[in] buflen Length of the data
162 * @return new tevent request, or NULL on failure
164 struct tevent_req
*sock_socket_write_send(TALLOC_CTX
*mem_ctx
,
165 struct tevent_context
*ev
,
166 struct sock_client_context
*client
,
167 uint8_t *buf
, size_t buflen
);
170 * @brief Async computation end to send data to client
172 * @param[in] req Tevent request
173 * @param[out] perr errno in case of failure
174 * @return true on success, false on failure
176 bool sock_socket_write_recv(struct tevent_req
*req
, int *perr
);
179 * @brief Create a new socket daemon
181 * @param[in] mem_ctx Talloc memory context
182 * @param[in] daemon_name Name of the daemon, used for logging
183 * @param[in] logging Logging setup string
184 * @param[in] debug_level Debug level to log at
185 * @param[in] funcs Socket daemon callback routines
186 * @param[in] private_data Private data associated with callback routines
187 * @param[out] result New socket daemon context
188 * @return 0 on success, errno on failure
190 int sock_daemon_setup(TALLOC_CTX
*mem_ctx
, const char *daemon_name
,
191 const char *logging
, const char *debug_level
,
192 struct sock_daemon_funcs
*funcs
,
194 struct sock_daemon_context
**result
);
197 * @brief Create and listen to the unix domain socket
199 * @param[in] sockd Socket daemon context
200 * @param[in] sockpath Unix domain socket path
201 * @param[in] funcs socket callback routines
202 * @param[in] private_data Private data associated with callback routines
203 * @return 0 on success, errno on failure
205 int sock_daemon_add_unix(struct sock_daemon_context
*sockd
,
206 const char *sockpath
,
207 struct sock_socket_funcs
*funcs
,
211 * @brief Async computation start to run a socket daemon
213 * @param[in] mem_ctx Talloc memory context
214 * @param[in] ev Tevent context
215 * @param[in] sockd The socket daemon context
216 * @param[in] pidfile PID file to create, NULL if no PID file required
217 * @param[in] do_fork Whether the daemon should fork on startup
218 * @param[in] create_session Whether the daemon should create a new session
219 * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
220 * @return new tevent request, NULL on failure
222 struct tevent_req
*sock_daemon_run_send(TALLOC_CTX
*mem_ctx
,
223 struct tevent_context
*ev
,
224 struct sock_daemon_context
*sockd
,
226 bool do_fork
, bool create_session
,
230 * @brief Async computation end to run a socket daemon
232 * @param[in] req Tevent request
233 * @param[out] perr errno in case of failure
234 * @return true on success, false on failure
236 bool sock_daemon_run_recv(struct tevent_req
*req
, int *perr
);
239 * @brief Sync way to start a daemon
241 * @param[in] ev Tevent context
242 * @param[in] sockd The socket daemon context
243 * @param[in] pidfile PID file to create, NULL if no PID file required
244 * @param[in] do_fork Whether the daemon should fork on startup
245 * @param[in] create_session Whether the daemon should create a new session
246 * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
247 * @return 0 on success, errno on failure
249 * This call will return only on shutdown of the daemon
251 int sock_daemon_run(struct tevent_context
*ev
,
252 struct sock_daemon_context
*sockd
,
254 bool do_fork
, bool create_session
,
257 #endif /* __CTDB_SOCK_DAEMON_H__ */