simple-ipc.h

   1 #ifndef GIT_SIMPLE_IPC_H
   2 #define GIT_SIMPLE_IPC_H
   3
   4 /*
   5  * See Documentation/technical/api-simple-ipc.txt
   6  */
   7
   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;
  61
  62         /*
  63          * Disallow chdir() when creating a Unix domain socket.
  64          */
  65         unsigned int uds_disallow_chdir:1;
  66 };
  67
  68 #define IPC_CLIENT_CONNECT_OPTIONS_INIT { 0 }
  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;
 160
 161         /*
 162          * Disallow chdir() when creating a Unix domain socket.
 163          */
 164         unsigned int uds_disallow_chdir:1;
 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 */