1 #ifndef GIT_SIMPLE_IPC_H
2 #define GIT_SIMPLE_IPC_H
5 * See Documentation/technical/api-simple-ipc.txt
8 #ifdef SUPPORTS_SIMPLE_IPC
12 * Simple IPC Client Side API.
15 enum ipc_active_state
{
17 * The pipe/socket exists and the daemon is waiting for connections.
19 IPC_STATE__LISTENING
= 0,
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.
29 IPC_STATE__NOT_LISTENING
,
32 * The requested pathname is bogus and no amount of retries
35 IPC_STATE__INVALID_PATH
,
38 * The requested pathname is not found. This usually means
39 * that there is no daemon present.
41 IPC_STATE__PATH_NOT_FOUND
,
43 IPC_STATE__OTHER_ERROR
,
46 struct ipc_client_connect_options
{
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
53 unsigned int wait_if_busy
:1;
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.
60 unsigned int wait_if_not_found
:1;
63 * Disallow chdir() when creating a Unix domain socket.
65 unsigned int uds_disallow_chdir
:1;
68 #define IPC_CLIENT_CONNECT_OPTIONS_INIT { 0 }
71 * Determine if a server is listening on this named pipe or socket using
72 * platform-specific logic. This might just probe the filesystem or it
73 * might make a trivial connection to the server using this pathname.
75 enum ipc_active_state
ipc_get_active_state(const char *path
);
77 struct ipc_client_connection
{
82 * Try to connect to the daemon on the named pipe or socket.
84 * Returns IPC_STATE__LISTENING and a connection handle.
86 * Otherwise, returns info to help decide whether to retry or to
87 * spawn/respawn the server.
89 enum ipc_active_state
ipc_client_try_connect(
91 const struct ipc_client_connect_options
*options
,
92 struct ipc_client_connection
**p_connection
);
94 void ipc_client_close_connection(struct ipc_client_connection
*connection
);
97 * Used by the client to synchronously send and receive a message with
98 * the server on the provided client connection.
100 * Returns 0 when successful.
102 * Calls error() and returns non-zero otherwise.
104 int ipc_client_send_command_to_connection(
105 struct ipc_client_connection
*connection
,
106 const char *message
, struct strbuf
*answer
);
109 * Used by the client to synchronously connect and send and receive a
110 * message to the server listening at the given path.
112 * Returns 0 when successful.
114 * Calls error() and returns non-zero otherwise.
116 int ipc_client_send_command(const char *path
,
117 const struct ipc_client_connect_options
*options
,
118 const char *message
, struct strbuf
*answer
);
121 * Simple IPC Server Side API.
124 struct ipc_server_reply_data
;
126 typedef int (ipc_server_reply_cb
)(struct ipc_server_reply_data
*,
127 const char *response
,
128 size_t response_len
);
131 * Prototype for an application-supplied callback to process incoming
132 * client IPC messages and compose a reply. The `application_cb` should
133 * use the provided `reply_cb` and `reply_data` to send an IPC response
134 * back to the client. The `reply_cb` callback can be called multiple
135 * times for chunking purposes. A reply message is optional and may be
136 * omitted if not necessary for the application.
138 * The return value from the application callback is ignored.
139 * The value `SIMPLE_IPC_QUIT` can be used to shutdown the server.
141 typedef int (ipc_server_application_cb
)(void *application_data
,
143 ipc_server_reply_cb
*reply_cb
,
144 struct ipc_server_reply_data
*reply_data
);
146 #define SIMPLE_IPC_QUIT -2
149 * Opaque instance data to represent an IPC server instance.
151 struct ipc_server_data
;
154 * Control parameters for the IPC server instance.
155 * Use this to hide platform-specific settings.
157 struct ipc_server_opts
162 * Disallow chdir() when creating a Unix domain socket.
164 unsigned int uds_disallow_chdir
:1;
168 * Start an IPC server instance in one or more background threads
169 * and return a handle to the pool.
171 * Returns 0 if the asynchronous server pool was started successfully.
173 * Returns -2 if we could not startup because another server is using
174 * the socket or named pipe.
176 * When a client IPC message is received, the `application_cb` will be
177 * called (possibly on a random thread) to handle the message and
178 * optionally compose a reply message.
180 int ipc_server_run_async(struct ipc_server_data
**returned_server_data
,
181 const char *path
, const struct ipc_server_opts
*opts
,
182 ipc_server_application_cb
*application_cb
,
183 void *application_data
);
186 * Gently signal the IPC server pool to shutdown. No new client
187 * connections will be accepted, but existing connections will be
188 * allowed to complete.
190 int ipc_server_stop_async(struct ipc_server_data
*server_data
);
193 * Block the calling thread until all threads in the IPC server pool
194 * have completed and been joined.
196 int ipc_server_await(struct ipc_server_data
*server_data
);
199 * Close and free all resource handles associated with the IPC server
202 void ipc_server_free(struct ipc_server_data
*server_data
);
205 * Run an IPC server instance and block the calling thread of the
206 * current process. It does not return until the IPC server has
207 * either shutdown or had an unrecoverable error.
209 * The IPC server handles incoming IPC messages from client processes
210 * and may use one or more background threads as necessary.
212 * Returns 0 after the server has completed successfully.
213 * Returns -1 if the server cannot be started.
214 * Returns -2 if we could not startup because another server is using
215 * the socket or named pipe.
217 * When a client IPC message is received, the `application_cb` will be
218 * called (possibly on a random thread) to handle the message and
219 * optionally compose a reply message.
221 * Note that `ipc_server_run()` is a synchronous wrapper around the
222 * above asynchronous routines. It effectively hides all of the
223 * server state and thread details from the caller and presents a
224 * simple synchronous interface.
226 int ipc_server_run(const char *path
, const struct ipc_server_opts
*opts
,
227 ipc_server_application_cb
*application_cb
,
228 void *application_data
);
230 #endif /* SUPPORTS_SIMPLE_IPC */
231 #endif /* GIT_SIMPLE_IPC_H */