/ 
Hypersonic-0.11
/ Hypersonic::UA

NAME

Hypersonic::UA - High-performance JIT-compiled HTTP user agent

SYNOPSIS

use Hypersonic::UA;

# Compile with minimal features (blocking only)
Hypersonic::UA->compile();

# Or compile with async support
Hypersonic::UA->compile(async => 1);

# Or compile with all features
Hypersonic::UA->compile(full => 1);

# Create UA instance
my $ua = Hypersonic::UA->new();

# Blocking requests
my $res = $ua->get('http://example.com/api');
my $res = $ua->post('http://example.com/api', '{"data":"value"}');
my $res = $ua->put('http://example.com/api', $body);
my $res = $ua->delete('http://example.com/api');

# Response is a hashref
print $res->{status};   # 200
print $res->{body};     # Response body

# Async requests (requires async => 1)
# No manual tick() needed - event loop runs automatically!
my $future = $ua->get_async('http://example.com/api');

# Chain with callbacks
$future->then(sub {
    my ($response) = @_;
    print $response;
});

# Or fetch multiple URLs concurrently
my @futures = map { $ua->get_async($_) } @urls;
my $all = Hypersonic::Future->needs_all(@futures);
my @results = $all->result;  # Automatically completes all requests

DESCRIPTION

Hypersonic::UA is a high-performance HTTP client using JIT-compiled XS code. It supports both blocking and async operations with connection pooling and keep-alive support.

COMPILATION OPTIONS

Hypersonic::UA->compile(%options);
async => 1

Enable async methods: get_async, post_async, tick, run, pending.

parallel => 1

Enable parallel methods: parallel, race. Implies async.

tls => 1

Enable HTTPS/TLS support.

http2 => 1

Enable HTTP/2 protocol support.

compression => 1

Enable gzip/deflate response decompression.

Enable automatic cookie handling.

redirects => 1

Enable automatic redirect following.

full => 1

Enable all features.

cache_dir => $path

Directory for caching compiled XS code.

METHODS

new

my $ua = Hypersonic::UA->new(%options);

Create a new UA instance.

get

my $res = $ua->get($url);

Perform a blocking GET request.

post

my $res = $ua->post($url, $body);

Perform a blocking POST request.

put

my $res = $ua->put($url, $body);

Perform a blocking PUT request.

delete

my $res = $ua->delete($url);

Perform a blocking DELETE request.

my $res = $ua->head($url);

Perform a blocking HEAD request.

patch

my $res = $ua->patch($url, $body);

Perform a blocking PATCH request.

options

my $res = $ua->options($url);

Perform a blocking OPTIONS request.

request

my $res = $ua->request($method, $url, $body);

Perform a generic blocking request.

ASYNC METHODS

These require async => 1 at compile time.

Note: Async requests are automatically processed - you do NOT need to call tick() manually. The event loop runs automatically when you:

  • Start a new async request (get_async, post_async, etc.)

  • Access a Future (is_ready, result, then, etc.)

get_async

my $future = $ua->get_async($url);

# Requests are processed automatically!
# Just use the Future when you need the result:
$future->then(sub {
    my ($response) = @_;
    print $response;
});

Start an async GET request. Returns a Future that resolves with the response.

post_async

my $future = $ua->post_async($url, $body);

Start an async POST request. Returns a Future.

tick

$ua->tick();

Manually process pending async requests. Usually not needed - the event loop runs automatically. Returns remaining pending count (0 when all complete).

This method now loops internally until all requests complete or no progress is made, so a single call is sufficient.

run

$ua->run();

Run event loop until all pending requests complete. Usually not needed - prefer using Futures directly which auto-tick.

pending

my $count = $ua->pending();

Return count of pending async requests.

PARALLEL METHODS

These require parallel => 1 at compile time.

parallel

my @results = $ua->parallel(@urls);

Fetch multiple URLs in parallel, wait for all to complete.

race

my $result = $ua->race(@urls);

Fetch multiple URLs, return first to complete.

PERFORMANCE

Hypersonic::UA is designed for high-throughput async HTTP operations. Key performance features:

Connection Pooling

Connections are automatically pooled and reused with HTTP keep-alive. This eliminates the TCP handshake overhead for subsequent requests to the same host, significantly improving throughput.

Event-Driven I/O

Uses the best available event backend (kqueue on macOS/BSD, epoll on Linux) for efficient non-blocking I/O with minimal syscall overhead.

JIT-Compiled XS

All hot paths are JIT-compiled to XS/C code, avoiding Perl interpreter overhead in the request processing loop.

Benchmark Example

use Hypersonic::Future;
use Hypersonic::UA;
use Time::HiRes qw(time);

Hypersonic::Future->compile;
Hypersonic::UA->compile(async => 1);

my $ua = Hypersonic::UA->new();
my @urls = ('http://127.0.0.1:8080/') x 1000;

my $start = time();

# Start all requests - event loop runs automatically!
my @futures = map { $ua->get_async($_) } @urls;

# Combine futures - when accessed, remaining requests complete
my $all = Hypersonic::Future->needs_all(@futures);

# Get results - this triggers any remaining processing
my @responses = $all->result;

my $elapsed = time() - $start;
printf "%d requests in %.3fs (%.0f req/sec)\n",
    scalar(@responses), $elapsed, scalar(@responses) / $elapsed;

Typical results on modern hardware:

  • 100,000+ requests/sec to localhost

  • Connection reuse via keep-alive pooling

  • Minimal memory overhead with slot-based context management

AUTHOR

lnation <email@lnation.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.