ctdb-common: Don't modify a const argument
[vlendec/samba-autobuild/.git] / 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 or SIGHUP
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  * shutdown() is called when process receives SIGINT or SIGTERM or
64  *             when wait computation has finished
65  *
66  * shutdown_send()/shutdown_recv() is the async version of shutdown()
67  *
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
70  * will be called.
71  *
72  * wait_send() starts the async computation to keep running the daemon
73  * wait_recv() ends the async computation to keep running the daemon
74  *
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.
77  */
78 struct sock_daemon_funcs {
79         int (*startup)(void *private_data);
80
81         struct tevent_req * (*startup_send)(TALLOC_CTX *mem_ctx,
82                                             struct tevent_context *ev,
83                                             void *private_data);
84         bool (*startup_recv)(struct tevent_req *req, int *perr);
85
86         int (*reconfigure)(void *private_data);
87
88         struct tevent_req * (*reconfigure_send)(TALLOC_CTX *mem_ctx,
89                                                 struct tevent_context *ev,
90                                                 void *private_data);
91         bool (*reconfigure_recv)(struct tevent_req *req, int *perr);
92
93         void (*shutdown)(void *private_data);
94
95         struct tevent_req * (*shutdown_send)(TALLOC_CTX *mem_ctx,
96                                              struct tevent_context *ev,
97                                              void *private_data);
98         void (*shutdown_recv)(struct tevent_req *req);
99
100         struct tevent_req * (*wait_send)(TALLOC_CTX *mem_ctx,
101                                          struct tevent_context *ev,
102                                          void *private_data);
103         bool (*wait_recv)(struct tevent_req *req, int *perr);
104 };
105
106 /**
107  * @brief The callback routines called for an unix-domain socket
108  *
109  * connect() is called when there is a new connection
110  *
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
115  *
116  *
117  * disconnect() is called  when client closes connection
118  *
119  * @param[in] client The socket client context
120  * @param[in] private_data Private data associated with the socket
121  *
122  *
123  * read_send() starts the async computation to process data on the socket
124  *
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
132  *
133  *
134  * read_recv() ends the async computation to process data on the socket
135  *
136  * @param[in] req Tevent request
137  * @param[out] perr errno in case of failure
138  * @return true on success, false on failure
139  *
140  */
141 struct sock_socket_funcs {
142         bool (*connect)(struct sock_client_context *client,
143                         pid_t pid,
144                         void *private_data);
145         void (*disconnect)(struct sock_client_context *client,
146                            void *private_data);
147
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,
152                                          void *private_data);
153         bool (*read_recv)(struct tevent_req *req, int *perr);
154 };
155
156 /**
157  * @brief Async computation to send data to the client
158  *
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
165  */
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);
170
171 /**
172  * @brief Async computation end to send data to client
173  *
174  * @param[in] req Tevent request
175  * @param[out] perr errno in case of failure
176  * @return true on success, false on failure
177  */
178 bool sock_socket_write_recv(struct tevent_req *req, int *perr);
179
180 /**
181  * @brief Create a new socket daemon
182  *
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
191  */
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,
195                       void *private_data,
196                       struct sock_daemon_context **result);
197
198 /**
199  * @brief Create and listen to the unix domain socket
200  *
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
206  */
207 int sock_daemon_add_unix(struct sock_daemon_context *sockd,
208                          const char *sockpath,
209                          struct sock_socket_funcs *funcs,
210                          void *private_data);
211
212 /**
213  * @brief Set file descriptor for indicating startup success
214  *
215  * On successful completion, 0 (unsigned int) will be written to the fd.
216  *
217  * @param[in] sockd Socket daemon context
218  * @param[in] fd File descriptor
219  */
220 void sock_daemon_set_startup_fd(struct sock_daemon_context *sockd, int fd);
221
222 /**
223  * @brief Async computation start to run a socket daemon
224  *
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
233  */
234 struct tevent_req *sock_daemon_run_send(TALLOC_CTX *mem_ctx,
235                                         struct tevent_context *ev,
236                                         struct sock_daemon_context *sockd,
237                                         const char *pidfile,
238                                         bool do_fork, bool create_session,
239                                         pid_t pid_watch);
240
241 /**
242  * @brief Async computation end to run a socket daemon
243  *
244  * @param[in] req Tevent request
245  * @param[out] perr errno in case of failure
246  * @return true on success, false on failure
247  */
248 bool sock_daemon_run_recv(struct tevent_req *req, int *perr);
249
250 /**
251  * @brief Sync way to start a daemon
252  *
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
260  *
261  * This call will return only on shutdown of the daemon
262  */
263 int sock_daemon_run(struct tevent_context *ev,
264                     struct sock_daemon_context *sockd,
265                     const char *pidfile,
266                     bool do_fork, bool create_session,
267                     pid_t pid_watch);
268
269 #endif /* __CTDB_SOCK_DAEMON_H__ */