# `./fio-stl/404 ipc.h` 41 public symbols. ### Macros #### `FIO_IPC_URL_MAX_LENGTH` ```c #define FIO_IPC_URL_MAX_LENGTH 1024 ``` _Symbol type:_ `macro` #### `FIO_IPC_MAX_LENGTH` ```c #define FIO_IPC_MAX_LENGTH (128ULL * 1024U * 1024U) ``` _Symbol type:_ `macro` #### `FIO_IPC_DATA` ```c #define FIO_IPC_DATA(...) \ (fio_buf_info_s[]) { \ __VA_ARGS__, { .len = ((size_t)-1) } \ } ``` A helper macro for composing multiple buffers into the request. Fill with fio_buf_info_s - will stop when a buffer has zero length. Use: .data = FIO_IPC_DATA(FIO_BUF_INFO1((char *)"example:"), FIO_BUF_INFO2(&number, sizeof(number))) _Symbol type:_ `macro` #### `FIO_IPC_EXCLUDE_SELF` ```c #define FIO_IPC_EXCLUDE_SELF ((fio_io_s *)((char *)-1LL)) ``` Excludes current process from fio_ipc_local (to be set in ipc->from) _Symbol type:_ `macro` #### `FIO_IPC_FLAG_ENCRYPTED` ```c #define FIO_IPC_FLAG_ENCRYPTED ((uint16_t)1UL << 0) ``` Set if message is in its encrypted state - do NOT edit manually _Symbol type:_ `macro` #### `FIO_IPC_FLAG_DONE` ```c #define FIO_IPC_FLAG_DONE ((uint16_t)1UL << 1) ``` If set, calls `on_done` rather than `call` - requires FIO_IPC_FLAG_REPLY _Symbol type:_ `macro` #### `FIO_IPC_FLAG_OPCODE` ```c #define FIO_IPC_FLAG_OPCODE ((uint16_t)1UL << 2) ``` Set if message callbacks are mapped using op-codes _Symbol type:_ `macro` #### `FIO_IPC_FLAG_WORKERS` ```c #define FIO_IPC_FLAG_WORKERS ((uint16_t)1UL << 3) ``` If set, delivered to worker processes as well as master _Symbol type:_ `macro` #### `FIO_IPC_FLAG_CLUSTER` ```c #define FIO_IPC_FLAG_CLUSTER ((uint16_t)1UL << 4) ``` If set, delivered to remote machines - requires FIO_IPC_FLAG_OPCODE _Symbol type:_ `macro` #### `FIO_IPC_FLAG_REPLY` ```c #define FIO_IPC_FLAG_REPLY ((uint16_t)1UL << 5) ``` If set, calls `on_reply` rather than `call` _Symbol type:_ `macro` #### `FIO_IPC_FLAG_PING` ```c #define FIO_IPC_FLAG_PING ((uint16_t)1UL << 6) ``` If set, this is an internal ping/keepalive message (not dispatched to user) _Symbol type:_ `macro` #### `FIO_IPC_FLAG_TEST` ```c #define FIO_IPC_FLAG_TEST(msg, flag) (((msg)->routing_flags & flag) == flag) ``` If flag is set == 1, otherwise zero _Symbol type:_ `macro` #### `FIO_IPC_FLAG_IF` ```c #define FIO_IPC_FLAG_IF(bcond, flag) (((uint16_t)0UL - (bcond)) & flag) ``` If flag is set == flag, otherwise zero _Symbol type:_ `macro` ### Types #### `fio_ipc_s` ```c struct fio_ipc_s { fio_io_s *from; /* IO to caller - set by receiver (unsent) */ /* ----- wire format starts here ----- */ uint32_t len; /* Length of data[] (AAD - authenticated, unencrypted) */ uint16_t flags; /* User settable flags (AAD - authenticated, unencrypted) */ uint16_t routing_flags; /* Internal (AAD - authenticated, unencrypted) */ uint64_t timestamp; /* timestamp (unencrypted, used for nonce) */ uint64_t id; /* 8 random bytes (unencrypted, used for nonce) */ union { void (*call)(struct fio_ipc_s *); /* function pointer to call (encrypted) */ uint32_t opcode; /* op-code to execute*/ }; void (*on_reply)(struct fio_ipc_s *); /* run on caller (encrypted) */ void (*on_done)(struct fio_ipc_s *); /* run on caller (encrypted) */ void *udata; /* opaque, valid only in caller (encrypted) */ char data[]; /* Variable-length data + 16-byte MAC at end (encrypted) */ } ``` IPC message structure (reference counted) _Symbol type:_ `type` #### `fio_ipc_args_s` ```c typedef struct { void (*call)(fio_ipc_s *); /* function to call */ void (*on_reply)(fio_ipc_s *); /* (optional) reply callback */ void (*on_done)(fio_ipc_s *); /* (optional) reply finished callback */ fio_io_s *exclude; /* (optional) IO to exclude from delivery */ uint64_t timestamp; /* (optional) to force timestamp */ uint64_t id; /* (optional) to force an id value */ uint32_t opcode; /* replaces `call` with op-code if non-zero */ uint16_t flags; /* (optional) user-opaque flags */ bool cluster; /* if set, this is intended for all machines in cluster */ bool workers; /* if set, this is intended for master + workers */ void *udata; /* opaque pointer data for reply */ fio_buf_info_s *data; /* payload (see FIO_IPC_DATA) */ } fio_ipc_args_s ``` IPC call arguments _Symbol type:_ `type` #### `fio_ipc_opcode_s` ```c struct fio_ipc_opcode_s { uint32_t opcode; /* Unique op-code value */ void (*call)(struct fio_ipc_s *); /* function to call */ void (*on_reply)(struct fio_ipc_s *); /* (optional) reply callback */ void (*on_done)(struct fio_ipc_s *); /* (optional) reply finished callback */ void *udata; /* opaque, valid only in caller (encrypted) */ } ``` _Symbol type:_ `type` #### `fio_ipc_reply_args_s` ```c typedef struct { fio_ipc_s *ipc; fio_buf_info_s *data; uint64_t timestamp; /* (optional) override timestamp, 0 = use current time */ uint64_t id; /* (optional) override id, 0 = use original request id */ uint16_t flags; /* (optional) override flags, 0 = use original request */ uint8_t done; uint8_t flags_set; /* set to 1 if flags should be used (allows flags=0) */ } fio_ipc_reply_args_s ``` IPC reply arguments _Symbol type:_ `type` ### Functions #### `fio_ipc_url` ```c const char *fio_ipc_url(void) ``` Returns the IPC url to listen to (for incoming connections). _Symbol type:_ `function` #### `fio_ipc_url_set` ```c int fio_ipc_url_set(const char *url) ``` Sets the IPC url to listen to (for incoming connections). Can only be called on the master process and only before the IO reactor. _Symbol type:_ `function` #### `fio_ipc_opcode_register` ```c int fio_ipc_opcode_register(fio_ipc_opcode_s opcode) ``` Registers an op-code for message routing. There are two types of messages: 1. Fast Path - function pointers in the message payload (local IPC only). 2. Safe Path - Op-Code in the `call` payload (multi-machine RCP). Op-Codes MUST be non-zero uint32_t values. RESERVED: op-codes >= 0xFF000000 are reserved for internal use. Note: Thread safety requires that this be called before fio_io_start. Returns -1 or failure (not on master process / already registered) _Symbol type:_ `function` #### `fio_ipc_opcode_register` ```c #define fio_ipc_opcode_register(...) \ fio_ipc_opcode_register((fio_ipc_opcode_s){__VA_ARGS__}) ``` _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_ipc_opcode` ```c const fio_ipc_opcode_s *fio_ipc_opcode(uint32_t opcode) ``` Returns a pointer to a registered op-code, or NULL if missing. _Symbol type:_ `function` #### `fio_ipc_call` ```c #define fio_ipc_call(...) fio_ipc_send(fio_ipc_new(__VA_ARGS__)) ``` Call arbitrary code in master process (worker → master / master → master). The `call` function pointer is executed on the master process. Replies are sent back to the caller via `on_reply` callback. When all replies are done, `on_done` is called. _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_ipc_local` ```c #define fio_ipc_local(...) fio_ipc_send(fio_ipc_new(.workers = 1, __VA_ARGS__)) ``` Call arbitrary code in master process and workers (all local). Replies can be sent back to the caller only from its local master process. _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_ipc_cluster` ```c #define fio_ipc_cluster(...) \ fio_ipc_send(fio_ipc_new(.cluster = 1, __VA_ARGS__)) ``` Call arbitrary code in master process of every machine in cluster. _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_ipc_broadcast` ```c #define fio_ipc_broadcast(...) \ fio_ipc_send(fio_ipc_new(.workers = 1, .cluster = 1, __VA_ARGS__)) ``` Call arbitrary code in master process of every machine in cluster. _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_ipc_reply` ```c void fio_ipc_reply(fio_ipc_reply_args_s args) ``` Send a response to the caller process (master → caller). Can be called multiple times for streaming responses. Set `done = 1` on the last reply. _Symbol type:_ `function` #### `fio_ipc_reply` ```c #define fio_ipc_reply(r, ...) \ fio_ipc_reply((fio_ipc_reply_args_s){.ipc = (r), __VA_ARGS__}) ``` _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_ipc_new` ```c fio_ipc_s *fio_ipc_new(fio_ipc_args_s args) ``` Authors a message without sending it. Used internally but available for "faking" IPC or when composing a unified code path for local execution. _Symbol type:_ `function` #### `fio_ipc_new` ```c #define fio_ipc_new(...) fio_ipc_new((fio_ipc_args_s){__VA_ARGS__}) ``` _Note:_ this may be a macro only / macro wrapper for a function. _Symbol type:_ `macro` #### `fio_ipc_dup` ```c fio_ipc_s *fio_ipc_dup(fio_ipc_s *msg) ``` Duplicate a message (increment reference count). Use when storing messages for later processing. Every dup() must be matched with a free(). _Symbol type:_ `function` #### `fio_ipc_free` ```c void fio_ipc_free(fio_ipc_s *msg) ``` Free a message (decrement reference count). Message is destroyed when reference count reaches zero. _Symbol type:_ `function` #### `fio_ipc_detach` ```c void fio_ipc_detach(fio_ipc_s *msg) ``` Detaches the IPC message from it's originating IO. Call if storing or performing non-IPC actions using the IPC message. _Symbol type:_ `function` #### `fio_ipc_send` ```c void fio_ipc_send(fio_ipc_s *ipc) ``` Encrypts the IPC message(!), sends it for execution and frees it. Message will be sent according to the flags set (see fio_ipc_new): - Only to Master (fio_ipc_call); - To Master and Workers (fio_ipc_local); - To Master on Every Machine (fio_ipc_cluster); - To Master and Workers on Every Machine (fio_ipc_broadcast); Note: Takes ownership of the message's memory. Note: overwrites after_send unless `ipc->from == FIO_IPC_EXCLUDE_SELF` Note: excludes ipc->from. Note: The message is encrypted and unusable once call returns - pass it the last reference. _Symbol type:_ `function` #### `fio_ipc_send_to` ```c void fio_ipc_send_to(fio_io_s *to, fio_ipc_s *ipc) ``` Encrypts the IPC message(!) and sends it to target IO - frees the message. Note: Takes ownership of the message's memory. Note: The message is encrypted and unusable until the message was sent and either freed or the `after_send` callback was called. _Symbol type:_ `function` #### `fio_ipc_after_send` ```c void fio_ipc_after_send(fio_ipc_s *ipc, void (*fn)(fio_ipc_s *, void *), void *udata) ``` _Symbol type:_ `function` #### `fio_ipc_encrypt` ```c void fio_ipc_encrypt(fio_ipc_s *m) ``` Encrypt IPC message before sending them anywhere. _Symbol type:_ `function` #### `fio_ipc_decrypt` ```c inline int fio_ipc_decrypt(fio_ipc_s *m) ``` Decrypt IPC message when received. _Symbol type:_ `function` #### `fio_ipc_cluster_listen` ```c fio_io_listener_s *fio_ipc_cluster_listen(uint16_t port) ``` Listens to cluster connections on the port listed, auto-connects to peers. This does NOT improve message exchange or pub/sub performance. This is designed for downtime mitigation (rotating pods) / data tunneling and client load balancing (without message load balancing). All server instances get all `cluster` messages (e.g., pub/sub cluster). Note: uses the environment's (shared) secret for rudimentary encryption without forward secrecy. Rotate secrets when possible (requires restart). Good for trusted data centers, Kubernetes pods, etc'. _Symbol type:_ `function` #### `fio_ipc_cluster_connect` ```c void fio_ipc_cluster_connect(const char *url) ``` Manually connects to cluster peers. Usually unnecessary. _Symbol type:_ `function` #### `fio_ipc_cluster_port` ```c uint16_t fio_ipc_cluster_port(void) ``` Returns the last port number passed to either fio_ipc_cluster_listen or fio_ipc_cluster_connect - zero if none. _Symbol type:_ `function` -----------------------------------------------------