Documentation/technical/api-simple-ipc.txt

   1 Simple-IPC API
   2 ==============
   3
   4 The Simple-IPC API is a collection of `ipc_` prefixed library routines
   5 and a basic communication protocol that allows an IPC-client process to
   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.
  23 When received, the response is returned back to the caller.
  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
  28 client connections.  Clients, such as `git status`, will request a list
  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
  40 used by applications like Git-LFS.  In the LFS-style sub-process model,
  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
  81 The pkt-line routines (linkgit:gitprotocol-common[5])
  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
 105 layer to focus on the task at hand.