]>
Commit | Line | Data |
---|---|---|
066d5234 JH |
1 | Simple-IPC API |
2 | ============== | |
3 | ||
4 | The Simple-IPC API is a collection of `ipc_` prefixed library routines | |
ce14cc0b | 5 | and a basic communication protocol that allows an IPC-client process to |
066d5234 JH |
6 | send an application-specific IPC-request message to an IPC-server |
7 | process and receive an application-specific IPC-response message. | |
8 | ||
9 | Communication occurs over a named pipe on Windows and a Unix domain | |
10 | socket on other platforms. IPC-clients and IPC-servers rendezvous at | |
11 | a previously agreed-to application-specific pathname (which is outside | |
12 | the scope of this design) that is local to the computer system. | |
13 | ||
14 | The IPC-server routines within the server application process create a | |
15 | thread pool to listen for connections and receive request messages | |
16 | from multiple concurrent IPC-clients. When received, these messages | |
17 | are dispatched up to the server application callbacks for handling. | |
18 | IPC-server routines then incrementally relay responses back to the | |
19 | IPC-client. | |
20 | ||
21 | The IPC-client routines within a client application process connect | |
22 | to the IPC-server and send a request message and wait for a response. | |
89363522 | 23 | When received, the response is returned back to the caller. |
066d5234 JH |
24 | |
25 | For example, the `fsmonitor--daemon` feature will be built as a server | |
26 | application on top of the IPC-server library routines. It will have | |
27 | threads watching for file system events and a thread pool waiting for | |
4d542687 | 28 | client connections. Clients, such as `git status`, will request a list |
066d5234 JH |
29 | of file system events since a point in time and the server will |
30 | respond with a list of changed files and directories. The formats of | |
31 | the request and response are application-specific; the IPC-client and | |
32 | IPC-server routines treat them as opaque byte streams. | |
33 | ||
34 | ||
35 | Comparison with sub-process model | |
36 | --------------------------------- | |
37 | ||
38 | The Simple-IPC mechanism differs from the existing `sub-process.c` | |
39 | model (Documentation/technical/long-running-process-protocol.txt) and | |
4d542687 | 40 | used by applications like Git-LFS. In the LFS-style sub-process model, |
066d5234 JH |
41 | the helper is started by the foreground process, communication happens |
42 | via a pair of file descriptors bound to the stdin/stdout of the | |
43 | sub-process, the sub-process only serves the current foreground | |
44 | process, and the sub-process exits when the foreground process | |
45 | terminates. | |
46 | ||
47 | In the Simple-IPC model the server is a very long-running service. It | |
48 | can service many clients at the same time and has a private socket or | |
49 | named pipe connection to each active client. It might be started | |
50 | (on-demand) by the current client process or it might have been | |
51 | started by a previous client or by the OS at boot time. The server | |
52 | process is not associated with a terminal and it persists after | |
53 | clients terminate. Clients do not have access to the stdin/stdout of | |
54 | the server process and therefore must communicate over sockets or | |
55 | named pipes. | |
56 | ||
57 | ||
58 | Server startup and shutdown | |
59 | --------------------------- | |
60 | ||
61 | How an application server based upon IPC-server is started is also | |
62 | outside the scope of the Simple-IPC design and is a property of the | |
63 | application using it. For example, the server might be started or | |
64 | restarted during routine maintenance operations, or it might be | |
65 | started as a system service during the system boot-up sequence, or it | |
66 | might be started on-demand by a foreground Git command when needed. | |
67 | ||
68 | Similarly, server shutdown is a property of the application using | |
69 | the simple-ipc routines. For example, the server might decide to | |
70 | shutdown when idle or only upon explicit request. | |
71 | ||
72 | ||
73 | Simple-IPC protocol | |
74 | ------------------- | |
75 | ||
76 | The Simple-IPC protocol consists of a single request message from the | |
77 | client and an optional response message from the server. Both the | |
78 | client and server messages are unlimited in length and are terminated | |
79 | with a flush packet. | |
80 | ||
5db92105 | 81 | The pkt-line routines (linkgit:gitprotocol-common[5]) |
066d5234 JH |
82 | are used to simplify buffer management during message generation, |
83 | transmission, and reception. A flush packet is used to mark the end | |
84 | of the message. This allows the sender to incrementally generate and | |
85 | transmit the message. It allows the receiver to incrementally receive | |
86 | the message in chunks and to know when they have received the entire | |
87 | message. | |
88 | ||
89 | The actual byte format of the client request and server response | |
90 | messages are application specific. The IPC layer transmits and | |
91 | receives them as opaque byte buffers without any concern for the | |
92 | content within. It is the job of the calling application layer to | |
93 | understand the contents of the request and response messages. | |
94 | ||
95 | ||
96 | Summary | |
97 | ------- | |
98 | ||
99 | Conceptually, the Simple-IPC protocol is similar to an HTTP REST | |
100 | request. Clients connect, make an application-specific and | |
101 | stateless request, receive an application-specific | |
102 | response, and disconnect. It is a one round trip facility for | |
103 | querying the server. The Simple-IPC routines hide the socket, | |
104 | named pipe, and thread pool details and allow the application | |
cf6cac20 | 105 | layer to focus on the task at hand. |