facil.io
API Reference

#./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