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

-----------------------------------------------------