# `./fio-stl/422 redis.h`

10 public symbols.

### Macros

#### `FIO_REDIS_READ_BUFFER`

```c
#define FIO_REDIS_READ_BUFFER 65536
```

Size of the read buffer for the Redis connection.
NOTE: must fit fio_redis_connection_s.buf_pos (uint32_t).

_Symbol type:_ `macro`

#### `FIO_REDIS_MAX_BATCH`

```c
#define FIO_REDIS_MAX_BATCH 128
```

Maximum number of complete messages processed per `on_data` event.

When the cap is reached with more data buffered, processing continues in a
deferred task. This keeps any single event-loop callback small - downstream
work per message is limited to scheduling (defer / publish), never I/O.

_Symbol type:_ `macro`

### Types

#### `fio_redis_args_s`

```c
typedef struct {
/**
* Redis server URL.
*
* Supported formats:
* - "redis://host:port"
* - "redis://host" (default port 6379)
* - "host:port" (no scheme)
* - "host" (no scheme, default port 6379)
* - NULL or empty → defaults to "localhost:6379"
*/
const char *url;
/** Redis server's password, if any (folded into the HELLO 3 handshake) */
const char *auth;
/** Length of auth string (0 = auto-detect with strlen) */
size_t auth_len;
/** Ping interval in seconds (0 = default 300 seconds) */
uint8_t ping_interval;
/**
* Cumulative payload budget per top-level Redis message, in bytes.
*
* Budget = Σ(all string payload bytes) + 32 × (count of ALL objects -
* String, Array, Map, Bool, Number, etc.). Checked BEFORE allocating or
* appending; a breach logs an error and disconnects.
*
* 0 = default (16MB). Protects against hostile / corrupt servers declaring
* huge `$<len>` allocations or oversized replies.
*/
size_t payload_limit;
} fio_redis_args_s
```

Arguments for creating a Redis engine

_Symbol type:_ `type`

#### `fio_redis_state_e`

```c
typedef enum {
/** The engine stopped after a failed HELLO handshake (or NULL was queried). */
FIO_REDIS_STATE_ERROR,
/** No socket is attached, or the RESP3 HELLO handshake is still pending. */
FIO_REDIS_STATE_CONNECTING,
/** A socket is attached and its RESP3 HELLO handshake completed. */
FIO_REDIS_STATE_CONNECTED,
} fio_redis_state_e
```

Redis connection state, observed from the IO thread.

_Symbol type:_ `type`

### Functions

#### `fio_redis_new`

```c
fio_pubsub_engine_s *fio_redis_new(fio_redis_args_s args)
```

Creates a Redis pub/sub engine with reference count = 1.

The engine is active only after the IO reactor starts running.

The caller owns the returned reference and must call fio_redis_free()
when done. Attaching to pub/sub does NOT transfer ownership.

Returns a pointer to the engine or NULL on error.

_Symbol type:_ `function`

#### `fio_redis_new`

```c
#define fio_redis_new(...) fio_redis_new((fio_redis_args_s){__VA_ARGS__})
```

Creates a Redis pub/sub engine (named arguments helper macro).

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

_Symbol type:_ `macro`

#### `fio_redis_dup`

```c
fio_pubsub_engine_s *fio_redis_dup(fio_pubsub_engine_s *engine)
```

Increments the reference count and returns the engine.

Use this when you need to share the engine across multiple owners.
Each call to fio_redis_dup() must be balanced with fio_redis_free().

_Symbol type:_ `function`

#### `fio_redis_free`

```c
void fio_redis_free(fio_pubsub_engine_s *engine)
```

Releases the caller's reference to the engine.

This function simply decrements the reference count. If the ref reaches 0
(no other refs held), fio___redis_destroy() fires immediately:
sets running=0, closes connections, drains the command queue, frees memory.

The engine stays alive as long as any other ref is held (e.g. the pub/sub
system's ref taken via subscribe/psubscribe). The pub/sub system releases
its ref via the on_detached callback when fio_pubsub_engine_detach() fires.

The caller does NOT need to call fio_pubsub_engine_detach() before freeing.
Calling fio_pubsub_engine_detach() before fio_redis_free() is also safe
(detach releases the system ref; free releases the caller ref).

Safe to call with NULL (no-op).

_Symbol type:_ `function`

#### `fio_redis_state`

```c
fio_redis_state_e fio_redis_state(fio_pubsub_engine_s const *engine)
```

Returns the current Redis connection state.

This function must be called from the IO thread. Commands can be sent in
every state: they queue until the RESP3 HELLO handshake completes.

_Symbol type:_ `function`

#### `fio_redis_send`

```c
int fio_redis_send(fio_pubsub_engine_s *engine, FIOBJ command, void (*callback)(fio_pubsub_engine_s *e, FIOBJ reply, void *udata), void *udata)
```

Sends a Redis command through the engine's connection.

The response will be sent back using the optional callback. `udata` is passed
along untouched.

The `command` should be a FIOBJ array containing the command and arguments.

Note: NEVER call Pub/Sub commands (SUBSCRIBE, PSUBSCRIBE, UNSUBSCRIBE,
PUNSUBSCRIBE) using this function, as it will violate the Redis connection's
protocol.

Returns 0 on success, -1 on error.

_Symbol type:_ `function`

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