# Memory Requirements and Limits for XQUIC Connections: A Complete Guide

> Discover XQUIC connection memory requirements and limits. Learn about default memory allocation and customize packet sizes for optimal performance. Read our complete guide.

- Repository: [Alibaba/xquic](https://github.com/alibaba/xquic)
- Tags: deep-dive
- Published: 2026-02-24

---

**XQUIC allocates a dedicated 4096-byte memory pool per connection by default, with hard limits on packet sizes up to 1420 bytes that developers can customize via the `xqc_config_t` structure before engine initialization.**

The Alibaba XQUIC library implements a specialized memory management strategy to handle high-performance QUIC connections efficiently. Understanding the memory requirements and limits for XQUIC connections is essential for optimizing server capacity and preventing resource exhaustion in production deployments. All memory configuration is controlled through the `xqc_config_t` structure defined in [`include/xquic/xquic.h`](https://github.com/alibaba/xquic/blob/main/include/xquic/xquic.h) and applied during engine creation.

## Default Connection Memory Pool Size

XQUIC uses a per-connection memory pool architecture to isolate resource usage and simplify cleanup. Each connection receives its own dedicated pool during initialization.

### The 4096-Byte Default Allocation

According to the source code in [`src/transport/xqc_engine.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_engine.c) at lines 39-40, the default connection pool size is set to 4096 bytes in both client and server configurations:

```c
/* default_client_config and default_server_config */
cfg->conn_pool_size = 4096;

```

When a new connection is established, the engine creates the pool by calling `xqc_create_pool()` in [`src/transport/xqc_conn.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_conn.c) at lines 662-664:

```c
conn->conn_pool = xqc_create_pool(engine->config->conn_pool_size, 
                                   XQC_POOL_CLASS_CONNECTION, 
                                   conn->log);

```

This pool stores all connection-level objects including congestion control structures, stream management metadata, packet buffers, and hash tables.

## Configurable Memory Limits in XQUIC

Beyond the connection pool, XQUIC enforces specific limits on packet sizes and UDP payloads to ensure protocol compliance and prevent buffer overflows.

### Maximum Packet Output Size

The `max_pkt_out_size` parameter controls the maximum size of outgoing QUIC packets. As defined in [`src/transport/xqc_conn.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_conn.c) at lines 53-55, the default value is `XQC_PACKET_OUT_SIZE` (1200 bytes), which corresponds to the QUIC minimum MSS:

```c
conn->max_pkt_out_size = XQC_PACKET_OUT_SIZE;  /* 1200 bytes */
conn->probing_pkt_out_size = XQC_MAX_PACKET_OUT_SIZE;  /* 1420 bytes */

```

However, XQUIC caps the effective maximum at `XQC_MAX_PACKET_OUT_SIZE` (1420 bytes), as enforced at lines 251-252 in the same file:

```c
if (conn->max_pkt_out_size > XQC_MAX_PACKET_OUT_SIZE) {
    conn->max_pkt_out_size = XQC_MAX_PACKET_OUT_SIZE;
}

```

### UDP Payload and Datagram Limits

The maximum UDP payload size is defined in [`src/transport/xqc_defs.h`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_defs.h) at line 25:

```c
#define XQC_CONN_MAX_UDP_PAYLOAD_SIZE 1500

```

For datagram frames (QUIC DATAGRAM extension), the `max_datagram_frame_size` defaults to 0 (disabled) in the connection settings structure at [`src/transport/xqc_conn.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_conn.c) line 55. Applications can enable this by setting a non-zero value via `xqc_engine_set_config`.

### Protected Memory Pool Option

For security-sensitive deployments, XQUIC supports protected pool memory using `mprotect`. This is controlled by the `protect_pool_mem` flag in `xqc_config_t` and implemented in [`src/common/xqc_memory_pool.h`](https://github.com/alibaba/xquic/blob/main/src/common/xqc_memory_pool.h) at lines 14-78. When enabled with the compile-time flag `XQC_PROTECT_POOL_MEM` (see [`src/transport/xqc_engine.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_engine.c) lines 90-92), the pool allocates pages with restricted permissions to detect memory corruption.

## How to Configure XQUIC Memory Requirements

Applications can customize memory limits by modifying the `xqc_config_t` structure before engine initialization.

### Increasing the Connection Pool Size

To allocate more memory per connection for high-throughput scenarios:

```c
#include <xquic/xquic.h>

int main(void) {
    xqc_config_t cfg;
    xqc_engine_get_default_config(&cfg, XQC_ENGINE_CLIENT);
    
    /* Increase pool from 4096 to 64 KB */
    cfg.conn_pool_size = 64 * 1024;
    
    /* Optional: increase packet size (must not exceed 1420) */
    cfg.max_pkt_out_size = 1400;
    
    xqc_engine_t *engine;
    xqc_int_t ret = xqc_engine_create(&engine, 
                                       XQC_ENGINE_CLIENT, 
                                       &cfg, 
                                       &engine_cb);
    if (ret != XQC_OK) {
        return -1;
    }
    
    /* ... use engine ... */
    xqc_engine_destroy(engine);
    return 0;
}

```

This example references the configuration patterns found in [`src/transport/xqc_engine.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_engine.c).

### Querying Runtime Memory Limits

To inspect the actual limits applied to a specific connection:

```c
void inspect_connection_memory(xqc_connection_t *conn) {
    printf("Pool size: %zu bytes\n", 
           conn->engine->config->conn_pool_size);
    printf("Max packet out: %zu bytes\n", 
           conn->max_pkt_out_size);
    printf("Max UDP payload: %zu bytes\n", 
           conn->max_udp_payload_size);
    printf("Datagram frame size: %zu bytes\n", 
           conn->max_datagram_frame_size);
}

```

These fields are defined in [`include/xquic/xquic.h`](https://github.com/alibaba/xquic/blob/main/include/xquic/xquic.h) and populated during connection initialization in [`src/transport/xqc_conn.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_conn.c).

### Enabling Protected Memory Pools

For debug or security builds:

```c
xqc_config_t cfg;
xqc_engine_get_default_config(&cfg, XQC_ENGINE_SERVER);
cfg.protect_pool_mem = 1;  /* Requires XQC_PROTECT_POOL_MEM compile flag */

xqc_engine_create(&engine, XQC_ENGINE_SERVER, &cfg, &callbacks);

```

The protected allocation logic resides in [`src/common/xqc_memory_pool.h`](https://github.com/alibaba/xquic/blob/main/src/common/xqc_memory_pool.h) and is conditionally compiled in [`src/transport/xqc_engine.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_engine.c) at lines 90-92.

## Summary

- **XQUIC allocates 4096 bytes per connection by default**, creating isolated memory pools during connection setup in [`src/transport/xqc_conn.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_conn.c).
- **Hard limits enforce maximum packet sizes of 1420 bytes** for standard packets and 1500 bytes for UDP payloads, defined in [`src/transport/xqc_conn.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_conn.c) and [`src/transport/xqc_defs.h`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_defs.h).
- **All memory parameters are configurable** via `xqc_config_t` before engine creation, allowing applications to scale pool sizes for high-throughput scenarios.
- **Optional protected memory mode** uses `mprotect` to guard against corruption when compiled with `XQC_PROTECT_POOL_MEM`.

## Frequently Asked Questions

### What is the default memory pool size for an XQUIC connection?

XQUIC allocates **4096 bytes** per connection by default. This value is hardcoded in the default client and server configurations in [`src/transport/xqc_engine.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_engine.c) at lines 39-40, and the pool is created via `xqc_create_pool()` in [`src/transport/xqc_conn.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_conn.c) when each connection is initialized.

### How do I increase the memory limit for XQUIC connections?

Modify the `conn_pool_size` field in the `xqc_config_t` structure before calling `xqc_engine_create()`. For example, set `cfg.conn_pool_size = 65536` to allocate 64 KB per connection instead of the default 4 KB. This configuration must be applied during engine initialization as shown in [`src/transport/xqc_engine.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_engine.c).

### What is the maximum packet size allowed in XQUIC?

XQUIC enforces a **hard limit of 1420 bytes** for outgoing packets, defined as `XQC_MAX_PACKET_OUT_SIZE` in the source. While the default `max_pkt_out_size` starts at 1200 bytes (the QUIC minimum), the library caps any user-configured value at 1420 bytes during connection initialization in [`src/transport/xqc_conn.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_conn.c) at lines 251-252.

### Does XQUIC support memory protection for security-sensitive applications?

Yes, XQUIC supports **protected pool memory** when compiled with the `XQC_PROTECT_POOL_MEM` flag. Enabling `cfg.protect_pool_mem = 1` in the configuration causes the library to allocate connection pools using `mprotect`-guarded pages, which helps detect memory corruption attempts. This implementation is found in [`src/common/xqc_memory_pool.h`](https://github.com/alibaba/xquic/blob/main/src/common/xqc_memory_pool.h) and conditionally compiled in [`src/transport/xqc_engine.c`](https://github.com/alibaba/xquic/blob/main/src/transport/xqc_engine.c).