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 #if defined(GIT_WINDOWS_NATIVE)
   9 #define SUPPORTS_SIMPLE_IPC
  10 #endif
  11
  12 #ifdef SUPPORTS_SIMPLE_IPC
  13 #include "pkt-line.h"
  14
  15 /*
  16  * Simple IPC Client Side API.
  17  */
  18
  19 enum ipc_active_state {
  20         /*
  21          * The pipe/socket exists and the daemon is waiting for connections.
  22          */
  23         IPC_STATE__LISTENING = 0,
  24
  25         /*
  26          * The pipe/socket exists, but the daemon is not listening.
  27          * Perhaps it is very busy.
  28          * Perhaps the daemon died without deleting the path.
  29          * Perhaps it is shutting down and draining existing clients.
  30          * Perhaps it is dead, but other clients are lingering and
  31          * still holding a reference to the pathname.
  32          */
  33         IPC_STATE__NOT_LISTENING,
  34
  35         /*
  36          * The requested pathname is bogus and no amount of retries
  37          * will fix that.
  38          */
  39         IPC_STATE__INVALID_PATH,
  40
  41         /*
  42          * The requested pathname is not found.  This usually means
  43          * that there is no daemon present.
  44          */
  45         IPC_STATE__PATH_NOT_FOUND,
  46
  47         IPC_STATE__OTHER_ERROR,
  48 };
  49
  50 struct ipc_client_connect_options {
  51         /*
  52          * Spin under timeout if the server is running but can't
  53          * accept our connection yet.  This should always be set
  54          * unless you just want to poke the server and see if it
  55          * is alive.
  56          */
  57         unsigned int wait_if_busy:1;
  58
  59         /*
  60          * Spin under timeout if the pipe/socket is not yet present
  61          * on the file system.  This is useful if we just started
  62          * the service and need to wait for it to become ready.
  63          */
  64         unsigned int wait_if_not_found:1;
  65 };
  66
  67 #define IPC_CLIENT_CONNECT_OPTIONS_INIT { \
  68         .wait_if_busy = 0, \
  69         .wait_if_not_found = 0, \
  70 }
  71
  72 /*
  73  * Determine if a server is listening on this named pipe or socket using
  74  * platform-specific logic.  This might just probe the filesystem or it
  75  * might make a trivial connection to the server using this pathname.
  76  */
  77 enum ipc_active_state ipc_get_active_state(const char *path);
  78
  79 struct ipc_client_connection {
  80         int fd;
  81 };
  82
  83 /*
  84  * Try to connect to the daemon on the named pipe or socket.
  85  *
  86  * Returns IPC_STATE__LISTENING and a connection handle.
  87  *
  88  * Otherwise, returns info to help decide whether to retry or to
  89  * spawn/respawn the server.
  90  */
  91 enum ipc_active_state ipc_client_try_connect(
  92         const char *path,
  93         const struct ipc_client_connect_options *options,
  94         struct ipc_client_connection **p_connection);
  95
  96 void ipc_client_close_connection(struct ipc_client_connection *connection);
  97
  98 /*
  99  * Used by the client to synchronously send and receive a message with
 100  * the server on the provided client connection.
 101  *
 102  * Returns 0 when successful.
 103  *
 104  * Calls error() and returns non-zero otherwise.
 105  */
 106 int ipc_client_send_command_to_connection(
 107         struct ipc_client_connection *connection,
 108         const char *message, struct strbuf *answer);
 109
 110 /*
 111  * Used by the client to synchronously connect and send and receive a
 112  * message to the server listening at the given path.
 113  *
 114  * Returns 0 when successful.
 115  *
 116  * Calls error() and returns non-zero otherwise.
 117  */
 118 int ipc_client_send_command(const char *path,
 119                             const struct ipc_client_connect_options *options,
 120                             const char *message, struct strbuf *answer);
 121
 122 /*
 123  * Simple IPC Server Side API.
 124  */
 125
 126 struct ipc_server_reply_data;
 127
 128 typedef int (ipc_server_reply_cb)(struct ipc_server_reply_data *,
 129                                   const char *response,
 130                                   size_t response_len);
 131
 132 /*
 133  * Prototype for an application-supplied callback to process incoming
 134  * client IPC messages and compose a reply.  The `application_cb` should
 135  * use the provided `reply_cb` and `reply_data` to send an IPC response
 136  * back to the client.  The `reply_cb` callback can be called multiple
 137  * times for chunking purposes.  A reply message is optional and may be
 138  * omitted if not necessary for the application.
 139  *
 140  * The return value from the application callback is ignored.
 141  * The value `SIMPLE_IPC_QUIT` can be used to shutdown the server.
 142  */
 143 typedef int (ipc_server_application_cb)(void *application_data,
 144                                         const char *request,
 145                                         ipc_server_reply_cb *reply_cb,
 146                                         struct ipc_server_reply_data *reply_data);
 147
 148 #define SIMPLE_IPC_QUIT -2
 149
 150 /*
 151  * Opaque instance data to represent an IPC server instance.
 152  */
 153 struct ipc_server_data;
 154
 155 /*
 156  * Control parameters for the IPC server instance.
 157  * Use this to hide platform-specific settings.
 158  */
 159 struct ipc_server_opts
 160 {
 161         int nr_threads;
 162 };
 163
 164 /*
 165  * Start an IPC server instance in one or more background threads
 166  * and return a handle to the pool.
 167  *
 168  * Returns 0 if the asynchronous server pool was started successfully.
 169  * Returns -1 if not.
 170  * Returns -2 if we could not startup because another server is using
 171  * the socket or named pipe.
 172  *
 173  * When a client IPC message is received, the `application_cb` will be
 174  * called (possibly on a random thread) to handle the message and
 175  * optionally compose a reply message.
 176  */
 177 int ipc_server_run_async(struct ipc_server_data **returned_server_data,
 178                          const char *path, const struct ipc_server_opts *opts,
 179                          ipc_server_application_cb *application_cb,
 180                          void *application_data);
 181
 182 /*
 183  * Gently signal the IPC server pool to shutdown.  No new client
 184  * connections will be accepted, but existing connections will be
 185  * allowed to complete.
 186  */
 187 int ipc_server_stop_async(struct ipc_server_data *server_data);
 188
 189 /*
 190  * Block the calling thread until all threads in the IPC server pool
 191  * have completed and been joined.
 192  */
 193 int ipc_server_await(struct ipc_server_data *server_data);
 194
 195 /*
 196  * Close and free all resource handles associated with the IPC server
 197  * pool.
 198  */
 199 void ipc_server_free(struct ipc_server_data *server_data);
 200
 201 /*
 202  * Run an IPC server instance and block the calling thread of the
 203  * current process.  It does not return until the IPC server has
 204  * either shutdown or had an unrecoverable error.
 205  *
 206  * The IPC server handles incoming IPC messages from client processes
 207  * and may use one or more background threads as necessary.
 208  *
 209  * Returns 0 after the server has completed successfully.
 210  * Returns -1 if the server cannot be started.
 211  * Returns -2 if we could not startup because another server is using
 212  * the socket or named pipe.
 213  *
 214  * When a client IPC message is received, the `application_cb` will be
 215  * called (possibly on a random thread) to handle the message and
 216  * optionally compose a reply message.
 217  *
 218  * Note that `ipc_server_run()` is a synchronous wrapper around the
 219  * above asynchronous routines.  It effectively hides all of the
 220  * server state and thread details from the caller and presents a
 221  * simple synchronous interface.
 222  */
 223 int ipc_server_run(const char *path, const struct ipc_server_opts *opts,
 224                    ipc_server_application_cb *application_cb,
 225                    void *application_data);
 226
 227 #endif /* SUPPORTS_SIMPLE_IPC */
 228 #endif /* GIT_SIMPLE_IPC_H */