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