-
Notifications
You must be signed in to change notification settings - Fork 25.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'jh/simple-ipc' into jch
A simple IPC interface gets introduced to build services like fsmonitor on top. * jh/simple-ipc: t0052: add simple-ipc tests and t/helper/test-simple-ipc tool simple-ipc: add Unix domain socket implementation unix-stream-server: create unix domain socket under lock unix-socket: disallow chdir() when creating unix domain sockets unix-socket: add backlog size option to unix_stream_listen() unix-socket: eliminate static unix_stream_socket() helper function simple-ipc: add win32 implementation simple-ipc: design documentation for new IPC mechanism pkt-line: add options argument to read_packetized_to_strbuf() pkt-line: add PACKET_READ_GENTLE_ON_READ_ERROR option pkt-line: do not issue flush packets in write_packetized_*() pkt-line: eliminate the need for static buffer in packet_write_gently()
- Loading branch information
Showing
21 changed files
with
3,315 additions
and
52 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,105 @@ | ||
Simple-IPC API | ||
============== | ||
|
||
The Simple-IPC API is a collection of `ipc_` prefixed library routines | ||
and a basic communication protocol that allow an IPC-client process to | ||
send an application-specific IPC-request message to an IPC-server | ||
process and receive an application-specific IPC-response message. | ||
|
||
Communication occurs over a named pipe on Windows and a Unix domain | ||
socket on other platforms. IPC-clients and IPC-servers rendezvous at | ||
a previously agreed-to application-specific pathname (which is outside | ||
the scope of this design) that is local to the computer system. | ||
|
||
The IPC-server routines within the server application process create a | ||
thread pool to listen for connections and receive request messages | ||
from multiple concurrent IPC-clients. When received, these messages | ||
are dispatched up to the server application callbacks for handling. | ||
IPC-server routines then incrementally relay responses back to the | ||
IPC-client. | ||
|
||
The IPC-client routines within a client application process connect | ||
to the IPC-server and send a request message and wait for a response. | ||
When received, the response is returned back the caller. | ||
|
||
For example, the `fsmonitor--daemon` feature will be built as a server | ||
application on top of the IPC-server library routines. It will have | ||
threads watching for file system events and a thread pool waiting for | ||
client connections. Clients, such as `git status` will request a list | ||
of file system events since a point in time and the server will | ||
respond with a list of changed files and directories. The formats of | ||
the request and response are application-specific; the IPC-client and | ||
IPC-server routines treat them as opaque byte streams. | ||
|
||
|
||
Comparison with sub-process model | ||
--------------------------------- | ||
|
||
The Simple-IPC mechanism differs from the existing `sub-process.c` | ||
model (Documentation/technical/long-running-process-protocol.txt) and | ||
used by applications like Git-LFS. In the LFS-style sub-process model | ||
the helper is started by the foreground process, communication happens | ||
via a pair of file descriptors bound to the stdin/stdout of the | ||
sub-process, the sub-process only serves the current foreground | ||
process, and the sub-process exits when the foreground process | ||
terminates. | ||
|
||
In the Simple-IPC model the server is a very long-running service. It | ||
can service many clients at the same time and has a private socket or | ||
named pipe connection to each active client. It might be started | ||
(on-demand) by the current client process or it might have been | ||
started by a previous client or by the OS at boot time. The server | ||
process is not associated with a terminal and it persists after | ||
clients terminate. Clients do not have access to the stdin/stdout of | ||
the server process and therefore must communicate over sockets or | ||
named pipes. | ||
|
||
|
||
Server startup and shutdown | ||
--------------------------- | ||
|
||
How an application server based upon IPC-server is started is also | ||
outside the scope of the Simple-IPC design and is a property of the | ||
application using it. For example, the server might be started or | ||
restarted during routine maintenance operations, or it might be | ||
started as a system service during the system boot-up sequence, or it | ||
might be started on-demand by a foreground Git command when needed. | ||
|
||
Similarly, server shutdown is a property of the application using | ||
the simple-ipc routines. For example, the server might decide to | ||
shutdown when idle or only upon explicit request. | ||
|
||
|
||
Simple-IPC protocol | ||
------------------- | ||
|
||
The Simple-IPC protocol consists of a single request message from the | ||
client and an optional response message from the server. Both the | ||
client and server messages are unlimited in length and are terminated | ||
with a flush packet. | ||
|
||
The pkt-line routines (Documentation/technical/protocol-common.txt) | ||
are used to simplify buffer management during message generation, | ||
transmission, and reception. A flush packet is used to mark the end | ||
of the message. This allows the sender to incrementally generate and | ||
transmit the message. It allows the receiver to incrementally receive | ||
the message in chunks and to know when they have received the entire | ||
message. | ||
|
||
The actual byte format of the client request and server response | ||
messages are application specific. The IPC layer transmits and | ||
receives them as opaque byte buffers without any concern for the | ||
content within. It is the job of the calling application layer to | ||
understand the contents of the request and response messages. | ||
|
||
|
||
Summary | ||
------- | ||
|
||
Conceptually, the Simple-IPC protocol is similar to an HTTP REST | ||
request. Clients connect, make an application-specific and | ||
stateless request, receive an application-specific | ||
response, and disconnect. It is a one round trip facility for | ||
querying the server. The Simple-IPC routines hide the socket, | ||
named pipe, and thread pool details and allow the application | ||
layer to focus on the application at hand. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
#include "cache.h" | ||
#include "simple-ipc.h" | ||
#include "strbuf.h" | ||
#include "pkt-line.h" | ||
#include "thread-utils.h" | ||
|
||
#ifdef SUPPORTS_SIMPLE_IPC | ||
|
||
int ipc_server_run(const char *path, const struct ipc_server_opts *opts, | ||
ipc_server_application_cb *application_cb, | ||
void *application_data) | ||
{ | ||
struct ipc_server_data *server_data = NULL; | ||
int ret; | ||
|
||
ret = ipc_server_run_async(&server_data, path, opts, | ||
application_cb, application_data); | ||
if (ret) | ||
return ret; | ||
|
||
ret = ipc_server_await(server_data); | ||
|
||
ipc_server_free(server_data); | ||
|
||
return ret; | ||
} | ||
|
||
#endif /* SUPPORTS_SIMPLE_IPC */ |
Oops, something went wrong.