Concurrency API

The concurrency module provides tools for parallel execution and task management.

Functions

These functions are available under httpx.concurrency.* and also as top-level helpers:

• httpx.all
• httpx.any
• httpx.race
• httpx.allSettled

Additional top-level aliases:

• httpx.first (alias for httpx.any)
• httpx.fastest (alias for httpx.race)
• httpx.settled (alias for httpx.allSettled)
• httpx.successfulCount (count RequestResult.success items)
• httpx.errorCount (count RequestResult.err items)

all

Executes multiple requests in parallel and waits for all to complete.

pub fn all(allocator: Allocator, client: *Client, specs: []const RequestSpec) ![]RequestResult

allSettled

Executes multiple requests in parallel and returns a result for each request.

• Successful requests are returned as RequestResult.success.
• Failed requests are returned as RequestResult.err.

pub fn allSettled(allocator: Allocator, client: *Client, specs: []const RequestSpec) ![]RequestResult

any

Executes multiple requests and returns the first successful (2xx) response.

pub fn any(allocator: Allocator, client: *Client, specs: []const RequestSpec) !?Response

race

Executes multiple requests and returns the result of the first one to complete (success or error).

pub fn race(allocator: Allocator, client: *Client, specs: []const RequestSpec) !RequestResult

Top-Level Alias Signatures

pub fn first(allocator: Allocator, client: *Client, specs: []const RequestSpec) !?Response
pub fn fastest(allocator: Allocator, client: *Client, specs: []const RequestSpec) !RequestResult
pub fn settled(allocator: Allocator, client: *Client, specs: []const RequestSpec) ![]RequestResult
pub fn successfulCount(results: []const RequestResult) usize
pub fn errorCount(results: []const RequestResult) usize

BatchBuilder

Use httpx.BatchBuilder to compose request batches fluently.

var builder = httpx.BatchBuilder.init(allocator);
defer builder.deinit();

_ = try builder.get("https://api.example.com/users");
_ = try builder.post("https://api.example.com/users", "{\"name\":\"demo\"}");
_ = try builder.postJson("https://api.example.com/users", "{\"name\":\"json\"}");

Method	Description
get(url)	Add GET request
post(url, body)	Add POST request
postJson(url, json)	Add POST request with JSON body
put(url, body)	Add PUT request
delete(url)	Add DELETE request
add(spec)	Add explicit RequestSpec
count()	Number of queued requests
clear()	Remove queued requests

Executor

A thread-pool based task executor.

const httpx = @import("httpx");
var executor = httpx.Executor.init(allocator);
defer executor.deinit();

Configuration

pub const ExecutorConfig = struct {
    num_threads: u32 = 0,       // 0 = auto-detect
    task_queue_size: usize = 1024,
    idle_timeout_ms: u64 = 60_000,
};

Methods

execute

Submits a function for execution.

pub fn execute(self: *Self, func: TaskFn, context: ?*anyopaque) !void

submit

Submits a Task struct.

pub fn submit(self: *Self, task: Task) !void

trySubmit

Submits a Task struct without blocking. Returns error.WouldBlock if the queue mutex is currently locked, or error.TaskQueueFull if the task queue has reached its maximum size.

pub fn trySubmit(self: *Self, task: Task) !void

submitWithCallback

Submits a Task and registers a callback to be run on completion of the task.

pub fn submitWithCallback(
    self: *Self,
    task: Task,
    callback: *const fn (?*anyopaque) void,
    cb_context: ?*anyopaque,
) !void

runAll

Runs all pending tasks synchronously (useful for testing).

pub fn runAll(self: *Self) void

executeAll

Submits a slice of Task values in order.

pub fn executeAll(self: *Self, tasks: []const Task) !void

start / stop

Start and stop worker threads explicitly.

pub fn start(self: *Self) !void
pub fn stop(self: *Self) void

pendingCount

Returns a snapshot count of queued tasks.

pub fn pendingCount(self: *const Self) usize

isRunning and queueCapacity

Inspect executor thread state and configured queue limit.

pub fn isRunning(self: *const Self) bool
pub fn queueCapacity(self: *const Self) usize

Types

Task

represents a unit of work.

pub const Task = struct {
    func: TaskFn,
    context: ?*anyopaque = null,
    priority: u8 = 0,
};

TaskFn

pub const TaskFn = *const fn (?*anyopaque) void;

RequestSpec

Specification for a request in a batch operation.

pub const RequestSpec = struct {
    method: Method = .GET,
    url: []const u8,
    body: ?[]const u8 = null,
    json: ?[]const u8 = null,
    headers: ?[]const [2][]const u8 = null,
    timeout_ms: ?u64 = null,
    follow_redirects: ?bool = null,
    version: ?Version = null,
};

All RequestSpec fields beyond url are optional customizations.

When timeout_ms is set, it overrides the client connect/read/write timeout budget for that batch entry. Use short values in tests and batch jobs against unreachable hosts to avoid waiting on the default 30 second socket limits.

RequestResult

Result wrapper for parallel requests.

pub const RequestResult = union(enum) {
    success: Response,
    err: anyerror,
    
    // Helper methods
    pub fn isSuccess(self: RequestResult) bool
    pub fn getResponse(self: *RequestResult) ?*Response
    pub fn deinit(self: *RequestResult) void
};