facil.io
API Reference

#./fio-stl/401 io api.h

104 public symbols.

#Macros

#FIO_IO_BUFFER_PER_WRITE

c
#define FIO_IO_BUFFER_PER_WRITE 65536U

Control the size of the on-stack buffer used for write events.

Symbol type: macro

#FIO_IO_THROTTLE_LIMIT

c
#define FIO_IO_THROTTLE_LIMIT 2097152U

IO will be throttled (no on_data events) if outgoing buffer is large.

Symbol type: macro

#FIO_IO_TIMEOUT_MAX

c
#define FIO_IO_TIMEOUT_MAX 300000

Controls the maximum and default timeout in milliseconds (5 minutes).

Symbol type: macro

#FIO_IO_SHUTDOWN_TIMEOUT

c
#define FIO_IO_SHUTDOWN_TIMEOUT 15000

Symbol type: macro

#FIO_IO_COUNT_STORAGE

c
#define FIO_IO_COUNT_STORAGE 1

Symbol type: macro

#FIO_IO_ASYN_INIT

c
#define FIO_IO_ASYN_INIT ((fio_io_async_s){0})

Initializes an IO Async Queue (multi-threaded task queue).

The queue automatically spawns threads and shuts down as the IO reactor starts or stops.

It is recommended that the fio_io_async_s be allocated as a static variable, as its memory must remain valid throughout the lifetime of the IO reactor's app.

Symbol type: macro

#Types

#fio_io_protocol_s

c
struct fio_io_protocol_s

The main protocol object type. See struct fio_io_protocol_s.

Symbol type: type

#fio_io_functions_s

c
struct fio_io_functions_s

The IO functions used by the protocol object.

Symbol type: type

#fio_io_s

c
struct fio_io_s

The main IO object type. Should be treated as an opaque pointer.

Symbol type: type

#fio_io_tls_s

c
struct fio_io_tls_s

An opaque type used for the SSL/TLS helper functions.

Symbol type: type

#fio_pubsub_msg_s

c
struct fio_pubsub_msg_s

Message structure, as received by the on_message subscription callback.

Symbol type: type

#fio_io_async_s

c
struct fio_io_async_s

The IO Async Queue type.

Symbol type: type

#fio_io_listen_args_s

c
struct fio_io_listen_args_s {
/**
* The binding address in URL format. Defaults to: tcp://0.0.0.0:3000
*
* Note: `.url` accept an optional query for building a TLS context.
*
* Possible query values include:
*
* - `tls` or `ssl` (no value): sets TLS as active, possibly self-signed.
* - `tls=` or `ssl=`: value is a prefix for "key.pem" and "cert.pem".
* - `key=` and `cert=`: file paths for ".pem" files.
*
* i.e.:
*
* fio_io_listen(.url = "0.0.0.0:3000/?tls", ...);
* fio_io_listen(.url = "0.0.0.0:3000/?tls=./", ...);
* // same as:
* fio_io_listen(.url = "0.0.0.0:3000/"
* "?key=./key.pem"
* "&cert=./cert.pem", ...);
*/
const char *url;
/** The `fio_io_protocol_s` that will be assigned to incoming
* connections. */
fio_io_protocol_s *protocol;
/** The default `udata` set for (new) incoming connections. */
void *udata;
/** TLS object used for incoming connections (ownership moved to listener). */
fio_io_tls_s *tls;
/**
* Called when the a listening socket starts to listen.
*
* May be called multiple times (i.e., if the IO reactor stops and restarts).
*/
void (*on_start)(fio_io_protocol_s *protocol, void *udata);
/**
* Called during listener cleanup.
*
* This will be called separately for every process before exiting.
*/
void (*on_stop)(fio_io_protocol_s *protocol, void *udata);
/**
* Selects a queue that will be used to schedule a pre-accept task.
* May be used to test user thread stress levels before accepting connections.
*/
fio_io_async_s *queue_for_accept;
/** When forking the IO reactor - limits `listen` to the root process. */
uint8_t on_root;
/** Hides "started/stopped listening" messages from log (if set). */
uint8_t hide_from_log;
}

Arguments for the fio_io_listen function

Symbol type: type

#fio_io_listener_s

c
struct fio_io_listener_s

Symbol type: type

#fio_io_connect_args_s

c
typedef struct {
/** The URL to connect to (may contain TLS hints in query / `tls` scheme). */
const char *url;
/** Connection protocol (once connection established). */
fio_io_protocol_s *protocol;
/** Called in case of a failed connection, use for cleanup. */
void (*on_failed)(fio_io_protocol_s *protocol, void *udata);
/** Opaque user data (set only once connection was established). */
void *udata;
/** TLS builder object for TLS connections. */
fio_io_tls_s *tls;
/** Connection timeout in milliseconds (defaults to 30 seconds). */
uint32_t timeout;
} fio_io_connect_args_s

Named arguments for fio_io_connect

Symbol type: type

#fio_io_write_args_s

c
typedef struct {
/** The buffer with the data to send (if no file descriptor) */
void *buf;
/** The file descriptor to send (if no buffer) */
intptr_t fd;
/** The length of the data to be sent. On files, 0 = the whole file. */
size_t len;
/** The length of the data to be sent. On files, 0 = the whole file. */
size_t offset;
/**
* If this is a buffer, the de-allocation function used to free it.
*
* If `copy == 0`, and `dealloc` is set, `write` will take ownership.
*
* If NULL, the buffer will NOT be de-allocated.
*/
void (*dealloc)(void *);
/** If non-zero, makes a copy of the buffer or keeps a file open. */
uint8_t copy;
} fio_io_write_args_s

Symbol type: type

#fio_io_env_set_args_s

c
typedef struct {
/** A numerical type filter. Defaults to 0. Negative values are reserved. */
intptr_t type;
/** The name for the link. The name and type uniquely identify the object. */
fio_buf_info_s name;
/** The object being linked to the connection. */
void *udata;
/** A callback that will be called once the connection is closed. */
void (*on_close)(void *data);
/** Set to true (1) if the name string's life lives as long as the `env` . */
uint8_t const_name;
} fio_io_env_set_args_s

Named arguments for the fio_io_env_set function.

Symbol type: type

#fio_io_env_get_args_s

c
typedef struct {
/** A numerical type filter. Should be the same as used with
* `fio_io_env_set` */
intptr_t type;
/** The name of the object. Should be the same as used with `fio_io_env_set`
*/
fio_buf_info_s name;
} fio_io_env_get_args_s

Named arguments for the fio_io_env_unset function.

Symbol type: type

#fio_io_tls_each_s

c
struct fio_io_tls_each_s {
fio_io_tls_s *tls;
void *udata;
void *udata2;
int (*each_cert)(struct fio_io_tls_each_s *,
const char *server_name,
const char *public_cert_file,
const char *private_key_file,
const char *pk_password);
int (*each_alpn)(struct fio_io_tls_each_s *,
const char *protocol_name,
void (*on_selected)(fio_io_s *));
int (*each_trust)(struct fio_io_tls_each_s *, const char *public_cert_file);
}

Arguments (and info) for fio_io_tls_each.

Symbol type: type

#Functions

#fio_io_stop

c
void fio_io_stop(void)

Stopping the IO reactor.

Symbol type: function

#fio_io_add_workers

c
void fio_io_add_workers(int workers)

Adds workers amount of workers to the root IO reactor process.

Symbol type: function

#fio_io_start

c
void fio_io_start(int workers)

Starts the IO reactor, using optional workers processes. Will BLOCK!

Symbol type: function

#fio_io_restart

c
void fio_io_restart(int workers)

Retiers all existing workers and restarts with the number of workers.

Symbol type: function

#fio_io_restart_on_signal

c
void fio_io_restart_on_signal(int signal)

Sets a signal to listen to for a hot restart (see fio_io_restart).

Symbol type: function

#fio_io_shutdown_timeout

c
size_t fio_io_shutdown_timeout(void)

Returns the shutdown timeout for the reactor.

Symbol type: function

#fio_io_shutdown_timeout_set

c
size_t fio_io_shutdown_timeout_set(size_t milliseconds)

Sets the shutdown timeout for the reactor, returning the new value.

Symbol type: function

#fio_io_is_running

c
int fio_io_is_running(void)

Returns true if IO reactor running and 0 if stopped or shutting down.

Symbol type: function

#fio_io_is_master

c
int fio_io_is_master(void)

Returns true if the current process is the IO reactor's master process.

Symbol type: function

#fio_io_is_worker

c
int fio_io_is_worker(void)

Returns true if the current process is an IO reactor's worker process.

Symbol type: function

#fio_io_workers

c
uint16_t fio_io_workers(int workers_requested)

Returns the number or workers the IO reactor will actually run.

Symbol type: function

#fio_io_pid

c
int fio_io_pid(void)

Returns current process id.

Symbol type: function

#fio_io_root_pid

c
int fio_io_root_pid(void)

Returns the root / master process id.

Symbol type: function

#fio_io_last_tick

c
int64_t fio_io_last_tick(void)

Returns the last millisecond when the IO reactor polled for events.

Symbol type: function

#fio_io_last_tick_time

c
int64_t fio_io_last_tick_time(void)

Returns a cached real-time (wall-clock) timestamp in milliseconds, updated each IO tick alongside fio_io_last_tick. Use this to avoid repeated clock_gettime syscalls when an approximate wall-clock ms is sufficient (e.g., HTTP Date headers, access-log timestamps).

Symbol type: function

#fio_io_listen

c
fio_io_listener_s *fio_io_listen(fio_io_listen_args_s args)

Sets up a network service on a listening socket.

Returns a self-destructible listener handle on success or NULL on error.

NOTE: this schedules a task and should NOT be called within a PRE_START or ON_START state callback.

NOTE: the returned listener is valid until fio_io_listen_stop is called.

Symbol type: function

#fio_io_listen

c
#define fio_io_listen(...) fio_io_listen((fio_io_listen_args_s){__VA_ARGS__})

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_listen_stop

c
void fio_io_listen_stop(fio_io_listener_s *l)

Notifies a listener to stop listening and destroys it.

Symbol type: function

#fio_io_listener_protocol

c
fio_io_protocol_s *fio_io_listener_protocol(fio_io_listener_s *l)

Returns the listener's associated protocol.

Symbol type: function

#fio_io_listener_udata

c
void *fio_io_listener_udata(fio_io_listener_s *l)

Returns the listener's associated udata.

Symbol type: function

#fio_io_listener_udata_set

c
void *fio_io_listener_udata_set(fio_io_listener_s *l, void *new_udata)

Sets the listener's associated udata, returning the old value.

Symbol type: function

#fio_io_listener_url

c
fio_buf_info_s fio_io_listener_url(fio_io_listener_s *l)

Returns the URL on which the listener is listening.

Symbol type: function

#fio_io_listener_is_tls

c
int fio_io_listener_is_tls(fio_io_listener_s *l)

Returns true if the listener protocol has an attached TLS context.

Symbol type: function

#fio_io_connect

c
fio_io_s *fio_io_connect(fio_io_connect_args_s args)

Connects to a specific URL, returning the fio_io_s IO object or NULL.

Note: The IO object returned is owned by the reactor. The copy returned is valid only until the next event is processed.

Symbol type: function

#fio_io_connect

c
#define fio_io_connect(url_, ...)   \
  fio_io_connect((fio_io_connect_args_s){.url = url_, __VA_ARGS__})

Connects to a specific URL, returning the fio_io_s IO object or NULL.

Note: The IO object returned is owned by the reactor. The copy returned is valid only until the next event is processed.

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_attach_fd

c
fio_io_s *fio_io_attach_fd(fio_socket_i fd, fio_io_protocol_s *protocol, void *udata, void *tls)

Attaches the socket in fd to the facio.io engine (reactor).

  • fd should point to a valid socket.

  • protocol may be the existing protocol or NULL (for partial hijack).

  • udata is opaque user data and may be any value, including NULL.

  • tls is a context for Transport Layer (Security) and can be used to redirect read/write operations, as set by the protocol.

Returns NULL on error. the fio_io_s pointer must NOT be used except within proper callbacks.

Symbol type: function

#fio_io_protocol_set

c
fio_io_protocol_s *fio_io_protocol_set(fio_io_s *io, fio_io_protocol_s *protocol)

Sets a new protocol object. NULL is a valid "only-write" protocol.

Symbol type: function

#fio_io_protocol

c
fio_io_protocol_s *fio_io_protocol(fio_io_s *io)

Returns a pointer to the current protocol object.

If protocol wasn't properly set, the pointer might be NULL or invalid.

If protocol wasn't attached yet, may return the previous protocol.

Symbol type: function

#fio_io_buffer

c
void *fio_io_buffer(fio_io_s *io)

Returns the a pointer to the memory buffer required by the protocol.

Symbol type: function

#fio_io_buffer_len

c
size_t fio_io_buffer_len(fio_io_s *io)

Returns the length of the buf buffer.

Symbol type: function

#fio_io_udata_set

c
void *fio_io_udata_set(fio_io_s *io, void *udata)

Associates a new udata pointer with the IO, returning the old udata

Symbol type: function

#fio_io_udata

c
void *fio_io_udata(fio_io_s *io)

Returns the udata pointer associated with the IO.

Symbol type: function

#fio_io_tls_set

c
void *fio_io_tls_set(fio_io_s *io, void *tls)

Associates a new tls pointer with the IO, returning the old tls

Symbol type: function

#fio_io_tls

c
void *fio_io_tls(fio_io_s *io)

Returns the tls pointer associated with the IO.

Symbol type: function

#fio_io_fd

c
fio_socket_i fio_io_fd(fio_io_s *io)

Returns the socket file descriptor (fd) associated with the IO.

Symbol type: function

#fio_io_peer_info_next

c
int fio_io_peer_info_next(fio_io_s *io, fio_x509_cert_s *dest)

Returns the next peer information item for the connection.

Iterate to inspect the peer's certificate chain (leaf certificate first), e.g., for client certificate authentication / authorization:

fio_x509_cert_s cert = {0}; // zeroed = new loop
while (fio_io_peer_info_next(io, &cert) == 0) {
  // cert.verified != 0 if the TLS backend verified the chain
  // cert.chain_index == position in the chain (0 == leaf)
  // cert.cn, cert.fingerprint, etc.
}

The iterator is stateless — the position is identified from dest alone: a zeroed dest (der.buf == NULL) starts a new loop; otherwise iteration continues at dest->chain_index + 1. Multiple loops may iterate the same connection concurrently without interfering with each other.

Iteration is capped at 128 certificates (chain_index 0..127) as a deep-nesting / DoS guard — longer chains end the loop with -1.

A NULL dest returns -1. To restart a loop, zero the struct (e.g., FIO_MEMSET(&cert, 0, sizeof(cert))).

Returns 0 while data is available, or -1 when done / unavailable (e.g., handshake incomplete, the peer sent no certificate, or the X509 module is unavailable).

NOTE: the parsed fields point into memory owned by the TLS backend and remain valid only until the next fio_io_peer_info_next call (on ANY connection) or until the connection is closed, whichever comes first.

Symbol type: function

#fio_io_touch

c
void fio_io_touch(fio_io_s *io)

Resets a socket's timeout counter.

Symbol type: function

#fio_io_read

c
size_t fio_io_read(fio_io_s *io, void *buf, size_t len)

Reads data to the buffer, if any data exists. Returns the number of bytes read.

NOTE: zero (0) is a valid return value meaning no data was available.

Symbol type: function

#fio_io_write2

c
void fio_io_write2(fio_io_s *io, fio_io_write_args_s args)

Writes data to the outgoing buffer and schedules the buffer to be sent.

Symbol type: function

#fio_io_write2

c
#define fio_io_write2(io, ...)   \
  fio_io_write2(io, (fio_io_write_args_s){__VA_ARGS__})

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_write

c
#define fio_io_write(io, buf_, len_)   \
  fio_io_write2(io, .buf = (buf_), .len = (len_), .copy = 1)

Helper macro for a common fio_io_write2 (copies the buffer).

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_sendfile

c
#define fio_io_sendfile(io, source_fd, offset_, bytes)   \
  fio_io_write2((io),   \
                .fd = (source_fd),   \
                .offset = (size_t)(offset_),   \
                .len = (bytes))

Sends data from a file as if it were a single atomic packet (sends up to length bytes or until EOF is reached).

Once the file was sent, the source_fd will be closed using close.

The file will be buffered to the socket chunk by chunk, so that memory consumption is capped.

offset dictates the starting point for the data to be sent and length sets the maximum amount of data to be sent.

Closes the file on error.

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_close

c
void fio_io_close(fio_io_s *io)

Marks the IO for closure as soon as scheduled data was sent.

Symbol type: function

#fio_io_close_now

c
void fio_io_close_now(fio_io_s *io)

Marks the IO for immediate closure and destruction.

Symbol type: function

#fio_io_dup

c
fio_io_s *fio_io_dup(fio_io_s *io)

Increases a IO's reference count, so it won't be automatically destroyed when all tasks have completed.

Use this function in order to use the IO outside of a scheduled task.

This function is thread-safe.

Symbol type: function

#fio_io_free

c
void fio_io_free(fio_io_s *io)

Decreases a IO's reference count, so it could be automatically destroyed when all other tasks have completed.

Use this function once finished with a IO that was dup-ed.

This function is thread-safe.

Symbol type: function

#fio_io_suspend

c
void fio_io_suspend(fio_io_s *io)

Suspends future on_data events for the IO.

Symbol type: function

#fio_io_unsuspend

c
void fio_io_unsuspend(fio_io_s *io)

Listens for future on_data events related to the IO.

Symbol type: function

#fio_io_is_suspended

c
int fio_io_is_suspended(fio_io_s *io)

Returns 1 if the IO handle was suspended.

Symbol type: function

#fio_io_on_data_schedule

c
void fio_io_on_data_schedule(fio_io_s *io)

Schedules one deferred on_data callback for already-buffered input.

Repeated calls before delivery are coalesced. This does not bypass normal suspension or throttling checks.

Symbol type: function

#fio_io_is_open

c
int fio_io_is_open(fio_io_s *io)

Returns 1 if the IO handle is marked as open.

Symbol type: function

#fio_io_backlog

c
size_t fio_io_backlog(fio_io_s *io)

Returns the approximate number of bytes in the outgoing buffer.

Symbol type: function

#fio_io_noop

c
void fio_io_noop(fio_io_s *io)

Does nothing.

Symbol type: function

#fio_io_defer

c
void fio_io_defer(void (*task)(void *, void *), void *udata1, void *udata2)

Schedules a task for delayed execution. This function is thread-safe.

Symbol type: function

#fio_io_run_every

c
void fio_io_run_every(fio_timer_schedule_args_s args)

Schedules a timer bound task, see fio_timer_schedule.

Symbol type: function

#fio_io_run_every

c
#define fio_io_run_every(...)   \
  fio_io_run_every((fio_timer_schedule_args_s){__VA_ARGS__})

Schedules a timer bound task, see fio_timer_schedule.

Possible "named arguments" (fio_timer_schedule_args_s members) include:

  • The timer function. If it returns a non-zero value, the timer stops: int (*fn)(void *, void *)
  • Opaque user data: void *udata1
  • Opaque user data: void *udata2
  • Called when the timer is done (finished): void (*on_stop)(void *, void *)
  • Timer interval, in milliseconds: uint32_t every
  • The number of times the timer should be performed. -1 == infinity: int32_t repetitions

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_queue

c
fio_queue_s *fio_io_queue(void)

Returns a pointer for the IO reactor's queue.

Symbol type: function

#fio_io_protocol_each

c
size_t fio_io_protocol_each(fio_io_protocol_s *protocol, void (*task)(fio_io_s *, void *udata2), void *udata2)

Performs a task for each IO in the stated protocol.

Call ONLY from the main IO thread (consider using fio_io_defer).

Symbol type: function

#fio_io_env_get

c
void *fio_io_env_get(fio_io_s *io, fio_io_env_get_args_s)

Returns the named udata associated with the IO object (or NULL).

Symbol type: function

#fio_io_env_get

c
#define fio_io_env_get(io, ...)   \
  fio_io_env_get(io, (fio_io_env_get_args_s){__VA_ARGS__})

Returns the named udata associated with the IO object (or NULL).

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_env_set

c
void fio_io_env_set(fio_io_s *io, fio_io_env_set_args_s)

Links an object to a connection's lifetime / environment.

The on_close callback will be called once the connection has died.

If the io is NULL, the value will be set for the global environment.

Symbol type: function

#fio_io_env_set

c
#define fio_io_env_set(io, ...)   \
  fio_io_env_set(io, (fio_io_env_set_args_s){__VA_ARGS__})

Links an object to a connection's lifetime, calling the on_close callback once the connection has died.

If the io is NULL, the value will be set for the global environment, in which case the on_close callback will only be called once the process exits.

This is a helper MACRO that allows the function to be called using named arguments.

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_env_unset

c
int fio_io_env_unset(fio_io_s *io, fio_io_env_get_args_s)

Un-links an object from the connection's lifetime, so it's on_close callback will NOT be called.

Returns 0 on success and -1 if the object couldn't be found.

Symbol type: function

#fio_io_env_unset

c
#define fio_io_env_unset(io, ...)   \
  fio_io_env_unset(io, (fio_io_env_get_args_s){__VA_ARGS__})

Un-links an object from the connection's lifetime, so it's on_close callback will NOT be called.

Returns 0 on success and -1 if the object couldn't be found.

This is a helper MACRO that allows the function to be called using named arguments.

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_env_remove

c
int fio_io_env_remove(fio_io_s *io, fio_io_env_get_args_s)

Removes an object from the connection's lifetime / environment, calling it's on_close callback as if the connection was closed.

Symbol type: function

#fio_io_env_remove

c
#define fio_io_env_remove(io, ...)   \
  fio_io_env_remove(io, (fio_io_env_get_args_s){__VA_ARGS__})

Removes an object from the connection's lifetime / environment, calling it's on_close callback as if the connection was closed.

This is a helper MACRO that allows the function to be called using named arguments.

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_tls_new

c
fio_io_tls_s *fio_io_tls_new(void)

Performs a new operation, returning a new fio_io_tls_s context.

Symbol type: function

#fio_io_tls_from_url

c
fio_io_tls_s *fio_io_tls_from_url(fio_io_tls_s *target_or_null, fio_url_s url)

Takes a parsed URL and optional TLS target and returns a TLS if needed.

Symbol type: function

#fio_io_tls_dup

c
fio_io_tls_s *fio_io_tls_dup(fio_io_tls_s *)

Performs a dup operation, increasing the object's reference count.

Symbol type: function

#fio_io_tls_free

c
void fio_io_tls_free(fio_io_tls_s *)

Performs a free operation, reducing the reference count and freeing.

Symbol type: function

#fio_io_tls_cert_add

c
fio_io_tls_s *fio_io_tls_cert_add(fio_io_tls_s *, const char *server_name, const char *public_cert_file, const char *private_key_file, const char *pk_password)

Adds a certificate a new SSL/TLS context / settings object (SNI support).

 fio_io_tls_cert_add(tls, "www.example.com",
                       "public_key.pem",
                       "private_key.pem", NULL );

NOTE: Except for the tls and server_name arguments, all arguments might be NULL, which a context builder (fio_io_functions_s) should treat as a request for a self-signed certificate. It may be silently ignored.

Symbol type: function

#fio_io_tls_alpn_add

c
fio_io_tls_s *fio_io_tls_alpn_add(fio_io_tls_s *tls, const char *protocol_name, void (*on_selected)(fio_io_s *))

Adds an ALPN protocol callback to the SSL/TLS context.

The first protocol added will act as the default protocol to be selected.

A NULL protocol name will be silently ignored.

A NULL callback (on_selected) will be silently replaced with a no-op.

Symbol type: function

#fio_io_tls_alpn_select

c
int fio_io_tls_alpn_select(fio_io_tls_s *tls, const char *protocol_name, size_t name_length, fio_io_s *)

Calls the on_selected callback for the fio_io_tls_s object.

Symbol type: function

#fio_io_tls_trust_add

c
fio_io_tls_s *fio_io_tls_trust_add(fio_io_tls_s *, const char *public_cert_file)

Adds a certificate to the "trust" list, which automatically adds a peer verification requirement.

If public_cert_file is NULL, implementation is expected to add the system's default trust registry.

Note: when the fio_io_tls_s object is used for server connections, this should limit connections to clients that connect using a trusted certificate.

 fio_io_tls_trust_add(tls, "google-ca.pem" );

Symbol type: function

#fio_io_tls_cert_count

c
uintptr_t fio_io_tls_cert_count(fio_io_tls_s *tls)

Returns the number of fio_io_tls_cert_add instructions.

This could be used when deciding if to add a NULL instruction (self-signed).

If fio_io_tls_cert_add was never called, zero (0) is returned.

Symbol type: function

#fio_io_tls_alpn_count

c
uintptr_t fio_io_tls_alpn_count(fio_io_tls_s *tls)

Returns the number of registered ALPN protocol names.

This could be used when deciding if protocol selection should be delegated to the ALPN mechanism, or whether a protocol should be immediately assigned.

If no ALPN protocols are registered, zero (0) is returned.

Symbol type: function

#fio_io_tls_trust_count

c
uintptr_t fio_io_tls_trust_count(fio_io_tls_s *tls)

Returns the number of fio_io_tls_trust_add instructions.

This could be used when deciding if to disable peer verification or not.

If fio_io_tls_trust_add was never called, zero (0) is returned.

Symbol type: function

#fio_io_tls_each

c
int fio_io_tls_each(fio_io_tls_each_s)

Calls callbacks for certificate, trust certificate and ALPN added.

Symbol type: function

#fio_io_tls_each

c
#define fio_io_tls_each(tls_, ...)   \
  fio_io_tls_each(((fio_io_tls_each_s){.tls = tls_, __VA_ARGS__}))

fio_io_tls_each helper macro, see fio_io_tls_each_s for named arguments.

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_tls_default_functions

c
fio_io_functions_s fio_io_tls_default_functions(fio_io_functions_s *)

If NULL returns current default, otherwise sets it. Set before start.

Symbol type: function

#fio_io_async_queue

c
inline fio_queue_s *fio_io_async_queue(fio_io_async_s *q)

Returns the current task queue associated with the IO Async Queue.

Symbol type: function

#fio_io_async_attach

c
void fio_io_async_attach(fio_io_async_s *q, uint32_t threads)

Attaches an IO Async Queue for use in multi-threaded (non IO) tasks.

This function can be called multiple times for the same (or other) queue, as long as the async queue (fio_io_async_s) was previously initialized using FIO_IO_ASYN_INIT or zeroed out. i.e.:

static fio_io_async_s SLOW_HTTP_TASKS = FIO_IO_ASYN_INIT;
fio_io_async_attach(&SLOW_HTTP_TASKS, 32);

Symbol type: function

#fio_io_async

c
#define fio_io_async(q_, ...) fio_queue_push((q_)->q, __VA_ARGS__)

Pushes a task to an IO Async Queue (macro helper).

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_io_async_every

c
void fio_io_async_every(fio_io_async_s *q, fio_timer_schedule_args_s)

Schedules a timer bound task for the async queue (fio_timer_schedule).

Symbol type: function

#fio_io_async_every

c
#define fio_io_async_every(async, ...)   \
  fio_io_async_every(async, (fio_timer_schedule_args_s){__VA_ARGS__})

Schedules a timer bound task, for the async queue, see fio_timer_schedule.

Possible "named arguments" (fio_timer_schedule_args_s members) include:

  • The timer function. If it returns a non-zero value, the timer stops: int (*fn)(void *, void *)
  • Opaque user data: void *udata1
  • Opaque user data: void *udata2
  • Called when the timer is done (finished): void (*on_stop)(void *, void *)
  • Timer interval, in milliseconds: uint32_t every
  • The number of times the timer should be performed. -1 == infinity: int32_t repetitions

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro