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 * 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
56 * wait_send() starts the async computation to keep running the daemon
57 * wait_recv() ends the async computation to keep running the daemon
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.
62 struct sock_daemon_funcs {
63 void (*startup)(void *private_data);
64 void (*reconfigure)(void *private_data);
65 void (*shutdown)(void *private_data);
67 struct tevent_req * (*wait_send)(TALLOC_CTX *mem_ctx,
68 struct tevent_context *ev,
70 bool (*wait_recv)(struct tevent_req *req, int *perr);
74 * @brief The callback routines called for an unix-domain socket
76 * connect() is called when there is a new connection
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
83 * disconnect() is called when client closes connection
85 * @param[in] client The socket client context
86 * @param[in] private_data Private data associated with the socket
89 * read_send() starts the async computation to process data on the socket
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
100 * read_recv() ends the async computation to process data on the socket
102 * @param[in] req Tevent request
103 * @param[out] perr errno in case of failure
104 * @return true on success, false on failure
107 struct sock_socket_funcs {
108 bool (*connect)(struct sock_client_context *client,
110 void (*disconnect)(struct sock_client_context *client,
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,
118 bool (*read_recv)(struct tevent_req *req, int *perr);
122 * @brief Async computation to send data to the client
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
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);
137 * @brief Async computation end to send data to client
139 * @param[in] req Tevent request
140 * @param[out] perr errno in case of failure
141 * @return true on success, false on failure
143 bool sock_socket_write_recv(struct tevent_req *req, int *perr);
146 * @brief Create a new socket daemon
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] funcs Socket daemon callback routines
153 * @param[in] private_data Private data associated with callback routines
154 * @param[out] result New socket daemon context
155 * @return 0 on success, errno on failure
157 int sock_daemon_setup(TALLOC_CTX *mem_ctx, const char *daemon_name,
158 const char *logging, const char *debug_level,
159 struct sock_daemon_funcs *funcs,
161 struct sock_daemon_context **result);
164 * @brief Create and listen to the unix domain socket
166 * @param[in] sockd Socket daemon context
167 * @param[in] sockpath Unix domain socket path
168 * @param[in] funcs socket callback routines
169 * @param[in] private_data Private data associated with callback routines
170 * @return 0 on success, errno on failure
172 int sock_daemon_add_unix(struct sock_daemon_context *sockd,
173 const char *sockpath,
174 struct sock_socket_funcs *funcs,
178 * @brief Async computation start to run a socket daemon
180 * @param[in] mem_ctx Talloc memory context
181 * @param[in] ev Tevent context
182 * @param[in] sockd The socket daemon context
183 * @param[in] pidfile PID file to create, NULL if no PID file required
184 * @param[in] do_fork Whether the daemon should fork on startup
185 * @param[in] create_session Whether the daemon should create a new session
186 * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
187 * @return new tevent request, NULL on failure
189 struct tevent_req *sock_daemon_run_send(TALLOC_CTX *mem_ctx,
190 struct tevent_context *ev,
191 struct sock_daemon_context *sockd,
193 bool do_fork, bool create_session,
197 * @brief Async computation end to run a socket daemon
199 * @param[in] req Tevent request
200 * @param[out] perr errno in case of failure
201 * @return true on success, false on failure
203 bool sock_daemon_run_recv(struct tevent_req *req, int *perr);
206 * @brief Sync way to start a daemon
208 * @param[in] ev Tevent context
209 * @param[in] sockd The socket daemon context
210 * @param[in] pidfile PID file to create, NULL if no PID file required
211 * @param[in] do_fork Whether the daemon should fork on startup
212 * @param[in] create_session Whether the daemon should create a new session
213 * @param[in] pid_watch PID to watch. If PID goes away, shutdown.
214 * @return 0 on success, errno on failure
216 * This call will return only on shutdown of the daemon
218 int sock_daemon_run(struct tevent_context *ev,
219 struct sock_daemon_context *sockd,
221 bool do_fork, bool create_session,
224 #endif /* __CTDB_SOCK_DAEMON_H__ */