]> git.ipfire.org Git - thirdparty/git.git/blob - simple-ipc.h
reftable: read reftable files
[thirdparty/git.git] / simple-ipc.h
1 #ifndef GIT_SIMPLE_IPC_H
2 #define GIT_SIMPLE_IPC_H
3
4 /*
5 * See Documentation/technical/api-simple-ipc.txt
6 */
7
8 #ifdef SUPPORTS_SIMPLE_IPC
9 #include "pkt-line.h"
10
11 /*
12 * Simple IPC Client Side API.
13 */
14
15 enum ipc_active_state {
16 /*
17 * The pipe/socket exists and the daemon is waiting for connections.
18 */
19 IPC_STATE__LISTENING = 0,
20
21 /*
22 * The pipe/socket exists, but the daemon is not listening.
23 * Perhaps it is very busy.
24 * Perhaps the daemon died without deleting the path.
25 * Perhaps it is shutting down and draining existing clients.
26 * Perhaps it is dead, but other clients are lingering and
27 * still holding a reference to the pathname.
28 */
29 IPC_STATE__NOT_LISTENING,
30
31 /*
32 * The requested pathname is bogus and no amount of retries
33 * will fix that.
34 */
35 IPC_STATE__INVALID_PATH,
36
37 /*
38 * The requested pathname is not found. This usually means
39 * that there is no daemon present.
40 */
41 IPC_STATE__PATH_NOT_FOUND,
42
43 IPC_STATE__OTHER_ERROR,
44 };
45
46 struct ipc_client_connect_options {
47 /*
48 * Spin under timeout if the server is running but can't
49 * accept our connection yet. This should always be set
50 * unless you just want to poke the server and see if it
51 * is alive.
52 */
53 unsigned int wait_if_busy:1;
54
55 /*
56 * Spin under timeout if the pipe/socket is not yet present
57 * on the file system. This is useful if we just started
58 * the service and need to wait for it to become ready.
59 */
60 unsigned int wait_if_not_found:1;
61
62 /*
63 * Disallow chdir() when creating a Unix domain socket.
64 */
65 unsigned int uds_disallow_chdir:1;
66 };
67
68 #define IPC_CLIENT_CONNECT_OPTIONS_INIT { \
69 .wait_if_busy = 0, \
70 .wait_if_not_found = 0, \
71 .uds_disallow_chdir = 0, \
72 }
73
74 /*
75 * Determine if a server is listening on this named pipe or socket using
76 * platform-specific logic. This might just probe the filesystem or it
77 * might make a trivial connection to the server using this pathname.
78 */
79 enum ipc_active_state ipc_get_active_state(const char *path);
80
81 struct ipc_client_connection {
82 int fd;
83 };
84
85 /*
86 * Try to connect to the daemon on the named pipe or socket.
87 *
88 * Returns IPC_STATE__LISTENING and a connection handle.
89 *
90 * Otherwise, returns info to help decide whether to retry or to
91 * spawn/respawn the server.
92 */
93 enum ipc_active_state ipc_client_try_connect(
94 const char *path,
95 const struct ipc_client_connect_options *options,
96 struct ipc_client_connection **p_connection);
97
98 void ipc_client_close_connection(struct ipc_client_connection *connection);
99
100 /*
101 * Used by the client to synchronously send and receive a message with
102 * the server on the provided client connection.
103 *
104 * Returns 0 when successful.
105 *
106 * Calls error() and returns non-zero otherwise.
107 */
108 int ipc_client_send_command_to_connection(
109 struct ipc_client_connection *connection,
110 const char *message, struct strbuf *answer);
111
112 /*
113 * Used by the client to synchronously connect and send and receive a
114 * message to the server listening at the given path.
115 *
116 * Returns 0 when successful.
117 *
118 * Calls error() and returns non-zero otherwise.
119 */
120 int ipc_client_send_command(const char *path,
121 const struct ipc_client_connect_options *options,
122 const char *message, struct strbuf *answer);
123
124 /*
125 * Simple IPC Server Side API.
126 */
127
128 struct ipc_server_reply_data;
129
130 typedef int (ipc_server_reply_cb)(struct ipc_server_reply_data *,
131 const char *response,
132 size_t response_len);
133
134 /*
135 * Prototype for an application-supplied callback to process incoming
136 * client IPC messages and compose a reply. The `application_cb` should
137 * use the provided `reply_cb` and `reply_data` to send an IPC response
138 * back to the client. The `reply_cb` callback can be called multiple
139 * times for chunking purposes. A reply message is optional and may be
140 * omitted if not necessary for the application.
141 *
142 * The return value from the application callback is ignored.
143 * The value `SIMPLE_IPC_QUIT` can be used to shutdown the server.
144 */
145 typedef int (ipc_server_application_cb)(void *application_data,
146 const char *request,
147 ipc_server_reply_cb *reply_cb,
148 struct ipc_server_reply_data *reply_data);
149
150 #define SIMPLE_IPC_QUIT -2
151
152 /*
153 * Opaque instance data to represent an IPC server instance.
154 */
155 struct ipc_server_data;
156
157 /*
158 * Control parameters for the IPC server instance.
159 * Use this to hide platform-specific settings.
160 */
161 struct ipc_server_opts
162 {
163 int nr_threads;
164
165 /*
166 * Disallow chdir() when creating a Unix domain socket.
167 */
168 unsigned int uds_disallow_chdir:1;
169 };
170
171 /*
172 * Start an IPC server instance in one or more background threads
173 * and return a handle to the pool.
174 *
175 * Returns 0 if the asynchronous server pool was started successfully.
176 * Returns -1 if not.
177 * Returns -2 if we could not startup because another server is using
178 * the socket or named pipe.
179 *
180 * When a client IPC message is received, the `application_cb` will be
181 * called (possibly on a random thread) to handle the message and
182 * optionally compose a reply message.
183 */
184 int ipc_server_run_async(struct ipc_server_data **returned_server_data,
185 const char *path, const struct ipc_server_opts *opts,
186 ipc_server_application_cb *application_cb,
187 void *application_data);
188
189 /*
190 * Gently signal the IPC server pool to shutdown. No new client
191 * connections will be accepted, but existing connections will be
192 * allowed to complete.
193 */
194 int ipc_server_stop_async(struct ipc_server_data *server_data);
195
196 /*
197 * Block the calling thread until all threads in the IPC server pool
198 * have completed and been joined.
199 */
200 int ipc_server_await(struct ipc_server_data *server_data);
201
202 /*
203 * Close and free all resource handles associated with the IPC server
204 * pool.
205 */
206 void ipc_server_free(struct ipc_server_data *server_data);
207
208 /*
209 * Run an IPC server instance and block the calling thread of the
210 * current process. It does not return until the IPC server has
211 * either shutdown or had an unrecoverable error.
212 *
213 * The IPC server handles incoming IPC messages from client processes
214 * and may use one or more background threads as necessary.
215 *
216 * Returns 0 after the server has completed successfully.
217 * Returns -1 if the server cannot be started.
218 * Returns -2 if we could not startup because another server is using
219 * the socket or named pipe.
220 *
221 * When a client IPC message is received, the `application_cb` will be
222 * called (possibly on a random thread) to handle the message and
223 * optionally compose a reply message.
224 *
225 * Note that `ipc_server_run()` is a synchronous wrapper around the
226 * above asynchronous routines. It effectively hides all of the
227 * server state and thread details from the caller and presents a
228 * simple synchronous interface.
229 */
230 int ipc_server_run(const char *path, const struct ipc_server_opts *opts,
231 ipc_server_application_cb *application_cb,
232 void *application_data);
233
234 #endif /* SUPPORTS_SIMPLE_IPC */
235 #endif /* GIT_SIMPLE_IPC_H */