NAME

Unblock::HTTP1::NativeABI - Borrowed native input ABI for Unblock::HTTP1

DESCRIPTION

This module exposes the optional native input ABI used by event frameworks and other XS transports.

The ordinary input() API remains the portable interface. Native integrations may instead pass a borrowed C buffer directly to the HTTP engine.

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

DEFINITION

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

The returned hash contains:

provider
abi_version
operations_address

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

C ABI

c_header() returns the ABI version 1 C declaration. Build-time adapters may write this text to a generated header rather than carrying a private copy of the ABI layout.

The operations table contains abi_version, struct_size, name, create, input, eof, and destroy. Consumers must check both the ABI version and structure size before dereferencing operations.

create receives the Unblock::HTTP1 Client or Server object and returns one connection-local native context. Keep that context for the lifetime of the HTTP connection instead of creating it for every read.

INPUT RESULTS

ABI version 1 uses these 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.

LIFETIME

The native C input operation receives:

const char *data
size_t length
size_t *consumed

data is borrowed. It must remain readable until the operation returns. Unblock::HTTP1 reports the permanently consumed prefix through consumed.

The host may release or reuse the input storage immediately after the call has returned, subject to preserving any unconsumed tail required by INPUT_MORE or INPUT_SWITCH.

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 call input().