/ 
Unblock-HTTP1-0.10
/ Unblock::HTTP1::NativeABI

NAME

Unblock::HTTP1::NativeABI - Native transport ABI for Unblock::HTTP1

DESCRIPTION

This module exposes the optional native transport ABI used by XS-backed transports and event frameworks.

The ordinary input() method remains the portable interface. A native integration can instead feed borrowed input buffers directly to the HTTP/1 engine.

The ABI works with both Unblock::HTTP1::Client and Unblock::HTTP1::Server.

DISCOVERY

my $definition = Unblock::HTTP1::NativeABI::definition();

The returned hash contains:

provider
abi_version
struct_size
operations_address

provider keeps the XS provider loaded and can be called again to obtain the current operations address.

Consumers must check both abi_version and struct_size before dereferencing operations.

HEADER

The installed header is:

Unblock/HTTP1/NativeABI/unblock_http1_native_abi.h

Its include directory is available through:

Unblock::HTTP1::NativeABI::native_include_dir()

The complete installed path is available through:

Unblock::HTTP1::NativeABI::header_path()

c_header() returns the same header text for build systems that prefer to generate a private copy.

C ABI

ABI version 1 contains create, input, eof, and destroy.

create receives one Unblock::HTTP1 Client or Server object and returns a connection-local native context. Keep that context for the lifetime of the HTTP/1 connection.

BORROWED INPUT

The native input operation receives:

const char *data
size_t length
size_t *consumed

data remains owned by the caller. Unblock::HTTP1 may inspect it only during the input call and never retains the pointer after the call returns.

ABI version 1 uses these input result codes:

INPUT_OK       0
INPUT_MORE     1
INPUT_CLOSED   3
INPUT_SWITCH   4

INPUT_MORE means the unconsumed tail must be retained by the host and presented again with more contiguous bytes.

INPUT_SWITCH means HTTP parsing has ended. The unconsumed tail belongs to the protocol that takes ownership after HTTP.

FALLBACK

The native ABI is an optimization. A framework that does not use XS, cannot consume ABI version 1, or chooses not to use the fast path should continue to use input().