/ 
Unblock-HTTP3-0.03
/ Unblock::HTTP3::NativeABI

NAME

Unblock::HTTP3::NativeABI - Native consumer ABI for Unblock::HTTP3

DESCRIPTION

This module exposes the optional native consumer ABI for XS event frameworks and HTTP libraries.

The normal Perl API remains the portable interface. Native consumers may keep one persistent ABI context for a Unblock::HTTP3::Connection and use C function pointers for the common connection and transaction path.

The ABI does not expose libnghttp3 structures or private Unblock::HTTP3 storage. QUIC transport ownership remains with Net::QUIC.

DISCOVERY

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

The returned hash contains:

provider
abi_version
struct_size
operations_address

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

Consumers must check both abi_version and struct_size before dereferencing operations.

ABI version 1 accepts exact Unblock::HTTP3::Connection and Unblock::HTTP3::Transaction objects. Subclasses should use the portable Perl API.

HEADER

The installed header is:

Unblock/HTTP3/NativeABI/unblock_http3_consumer.h

Its include directory is available through:

Unblock::HTTP3::NativeABI::native_include_dir()

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

ABI VERSION 1

ABI version 1 provides operations to:

create and destroy a persistent Connection context
service a Connection
submit a normal client request
poll ready Transactions
poll informational response events
access canonical Request and Response objects
access Transaction stream ID and state
send normal and informational server responses
inspect Connection failure state

request() uses the normal request defaults. Advanced Perl-only request options such as streaming body configuration remain available through the portable API.

OWNERSHIP

request(), next_transaction(), next_informational(), and transaction_next_informational() return owned SV pointers with one caller reference. The consumer must mortalize or decrement them.

transaction_request(), transaction_response(), and error() return borrowed SV pointers. They remain valid only while the owning object remains alive and unchanged.

request() returns NULL when the ordinary request path returns undef, including temporary QUIC stream-credit backpressure. Poll operations return NULL when no item is ready. transaction_response() returns NULL until a response exists.

Canonical Request and Response objects may be inspected with the Uniform::HTTP 0.06 native FastPath.

THREADS

Create one ABI context per Perl interpreter. Do not share a context across ithreads. Create a fresh context after an interpreter clone.

FALLBACK

The native ABI is an optimization. Consumers that cannot use ABI version 1 should continue to use the ordinary Perl API.