/ 
Unblock-HTTP3-0.10
/ 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 ordinary Perl API remains the portable interface. A native integration can keep one persistent context for an exact Unblock::HTTP3::Client or Unblock::HTTP3::Server and avoid repeated Perl method lookup on the common connection and transaction path.

The ABI does not expose libnghttp3 structures or take ownership of the QUIC transport.

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 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/HTTP3/NativeABI/unblock_http3_consumer.h

Its include directory is available through:

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

The complete installed path is available through:

Unblock::HTTP3::NativeABI::header_path()

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

ABI VERSION 1

ABI version 1 accepts exact Unblock::HTTP3::Client, Unblock::HTTP3::Server, and Unblock::HTTP3::Transaction objects. Subclasses and adapters use the portable Perl API.

It provides native operations to:

create and destroy a Client or Server context
service the Client or Server
submit a normal client request
poll ready Transactions
poll informational responses
inspect Transaction Request and Response objects
inspect Transaction stream ID and state
send normal and informational server responses
inspect connection failure state

Callback configuration and advanced body objects remain on the portable Perl 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 normal 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.

SEE ALSO

Unblock::HTTP3, Unblock::HTTP3::Client, Unblock::HTTP3::Server, Unblock::HTTP3::Transaction

LICENSE

MIT License.