]>
Commit | Line | Data |
---|---|---|
59c7b881 JH |
1 | #ifndef GIT_SIMPLE_IPC_H |
2 | #define GIT_SIMPLE_IPC_H | |
3 | ||
4 | /* | |
5 | * See Documentation/technical/api-simple-ipc.txt | |
6 | */ | |
7 | ||
59c7b881 JH |
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; | |
7cd5dbca JH |
61 | |
62 | /* | |
63 | * Disallow chdir() when creating a Unix domain socket. | |
64 | */ | |
65 | unsigned int uds_disallow_chdir:1; | |
59c7b881 JH |
66 | }; |
67 | ||
608cfd31 | 68 | #define IPC_CLIENT_CONNECT_OPTIONS_INIT { 0 } |
59c7b881 JH |
69 | |
70 | /* | |
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. | |
74 | */ | |
75 | enum ipc_active_state ipc_get_active_state(const char *path); | |
76 | ||
77 | struct ipc_client_connection { | |
78 | int fd; | |
79 | }; | |
80 | ||
81 | /* | |
82 | * Try to connect to the daemon on the named pipe or socket. | |
83 | * | |
84 | * Returns IPC_STATE__LISTENING and a connection handle. | |
85 | * | |
86 | * Otherwise, returns info to help decide whether to retry or to | |
87 | * spawn/respawn the server. | |
88 | */ | |
89 | enum ipc_active_state ipc_client_try_connect( | |
90 | const char *path, | |
91 | const struct ipc_client_connect_options *options, | |
92 | struct ipc_client_connection **p_connection); | |
93 | ||
94 | void ipc_client_close_connection(struct ipc_client_connection *connection); | |
95 | ||
96 | /* | |
97 | * Used by the client to synchronously send and receive a message with | |
98 | * the server on the provided client connection. | |
99 | * | |
100 | * Returns 0 when successful. | |
101 | * | |
102 | * Calls error() and returns non-zero otherwise. | |
103 | */ | |
104 | int ipc_client_send_command_to_connection( | |
105 | struct ipc_client_connection *connection, | |
106 | const char *message, struct strbuf *answer); | |
107 | ||
108 | /* | |
109 | * Used by the client to synchronously connect and send and receive a | |
110 | * message to the server listening at the given path. | |
111 | * | |
112 | * Returns 0 when successful. | |
113 | * | |
114 | * Calls error() and returns non-zero otherwise. | |
115 | */ | |
116 | int ipc_client_send_command(const char *path, | |
117 | const struct ipc_client_connect_options *options, | |
118 | const char *message, struct strbuf *answer); | |
119 | ||
120 | /* | |
121 | * Simple IPC Server Side API. | |
122 | */ | |
123 | ||
124 | struct ipc_server_reply_data; | |
125 | ||
126 | typedef int (ipc_server_reply_cb)(struct ipc_server_reply_data *, | |
127 | const char *response, | |
128 | size_t response_len); | |
129 | ||
130 | /* | |
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. | |
137 | * | |
138 | * The return value from the application callback is ignored. | |
139 | * The value `SIMPLE_IPC_QUIT` can be used to shutdown the server. | |
140 | */ | |
141 | typedef int (ipc_server_application_cb)(void *application_data, | |
142 | const char *request, | |
143 | ipc_server_reply_cb *reply_cb, | |
144 | struct ipc_server_reply_data *reply_data); | |
145 | ||
146 | #define SIMPLE_IPC_QUIT -2 | |
147 | ||
148 | /* | |
149 | * Opaque instance data to represent an IPC server instance. | |
150 | */ | |
151 | struct ipc_server_data; | |
152 | ||
153 | /* | |
154 | * Control parameters for the IPC server instance. | |
155 | * Use this to hide platform-specific settings. | |
156 | */ | |
157 | struct ipc_server_opts | |
158 | { | |
159 | int nr_threads; | |
7cd5dbca JH |
160 | |
161 | /* | |
162 | * Disallow chdir() when creating a Unix domain socket. | |
163 | */ | |
164 | unsigned int uds_disallow_chdir:1; | |
59c7b881 JH |
165 | }; |
166 | ||
167 | /* | |
168 | * Start an IPC server instance in one or more background threads | |
169 | * and return a handle to the pool. | |
170 | * | |
171 | * Returns 0 if the asynchronous server pool was started successfully. | |
172 | * Returns -1 if not. | |
173 | * Returns -2 if we could not startup because another server is using | |
174 | * the socket or named pipe. | |
175 | * | |
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. | |
179 | */ | |
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); | |
184 | ||
185 | /* | |
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. | |
189 | */ | |
190 | int ipc_server_stop_async(struct ipc_server_data *server_data); | |
191 | ||
192 | /* | |
193 | * Block the calling thread until all threads in the IPC server pool | |
194 | * have completed and been joined. | |
195 | */ | |
196 | int ipc_server_await(struct ipc_server_data *server_data); | |
197 | ||
198 | /* | |
199 | * Close and free all resource handles associated with the IPC server | |
200 | * pool. | |
201 | */ | |
202 | void ipc_server_free(struct ipc_server_data *server_data); | |
203 | ||
204 | /* | |
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. | |
208 | * | |
209 | * The IPC server handles incoming IPC messages from client processes | |
210 | * and may use one or more background threads as necessary. | |
211 | * | |
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. | |
216 | * | |
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. | |
220 | * | |
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. | |
225 | */ | |
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); | |
229 | ||
230 | #endif /* SUPPORTS_SIMPLE_IPC */ | |
231 | #endif /* GIT_SIMPLE_IPC_H */ |