writer_fast.h File Reference

Zero-latency speculative fast-path writer and P2C worker scheduler. More...

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <sys/types.h>
#include <cwist/sys/platform.h>
#include <sys/uio.h>

Include dependency graph for writer_fast.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	cwist_write_status_t { CWIST_WRITE_DONE , CWIST_WRITE_PENDING , CWIST_WRITE_ERR = -1 }

Functions
cwist_write_status_t	cwist_http_send_speculative (int fd, const void *buf, size_t len, size_t *sent_out)
	Speculative non-blocking direct sender.
cwist_write_status_t	cwist_http_sendmsg_speculative (int fd, struct iovec *iov, int iovcnt, int flags, size_t *total_sent)
	Speculative scatter/gather sendmsg without blocking poll().
uint32_t	cwist_sched_p2c_select_worker (const _Atomic uint32_t *worker_loads, uint32_t num_workers)
	Select worker using Power of Two Random Choices (P2C).
uint32_t	cwist_fast_monotonic_sec (void)
	Fast monotonic clock in seconds (vDSO coarse where available).

Detailed Description

Zero-latency speculative fast-path writer and P2C worker scheduler.

Definition in file writer_fast.h.

Enumeration Type Documentation

cwist_write_status_t

enum cwist_write_status_t

Enumerator
CWIST_WRITE_DONE	Complete buffer was written on the first pass (0 latency overhead).
CWIST_WRITE_PENDING	Socket buffer saturated (EAGAIN/EWOULDBLOCK) - hand off to reactor.
CWIST_WRITE_ERR	Fatal socket error or connection reset.

Definition at line 24 of file writer_fast.h.

Function Documentation

cwist_fast_monotonic_sec()

uint32_t cwist_fast_monotonic_sec

(

void

)

Fast monotonic clock in seconds (vDSO coarse where available).

Uses CLOCK_MONOTONIC_COARSE on Linux (1-4ns vDSO read) and falls back to CLOCK_MONOTONIC on BSD/macOS.

Fast monotonic clock in seconds (vDSO coarse where available).

Uses CLOCK_MONOTONIC_COARSE when available for speed, falling back to CLOCK_MONOTONIC. Intended for coarse-grained elapsed-time checks, not sub-second precision.

Returns

Monotonic time in seconds, truncated to uint32_t.

Definition at line 200 of file writer_fast.c.

References cap.

Referenced by cwist_http_async_rearm(), cwist_http_coalesce_append(), cwist_http_pool_submit_async(), cwist_http_receive_request_nb(), cwist_http_send_response_coalesced(), and cwist_websocket_async_attach_ex().

cwist_http_send_speculative()

cwist_write_status_t cwist_http_send_speculative	(	int	fd,
		const void *	buf,
		size_t	len,
		size_t *	sent_out
	)

Speculative non-blocking direct sender.

Attempts an immediate non-blocking send without context switching or event loop queuing. Fast clients finish synchronously (0 ms jitter). Slow clients immediately return CWIST_WRITE_PENDING instead of blocking worker threads in a synchronous poll() loop.

Parameters

fd	Target client socket file descriptor.
buf	Pointer to the contiguous buffer to send.
len	Total length of the buffer in bytes.
sent_out	Optional pointer to store the number of bytes successfully sent.

Returns

cwist_write_status_t status indicating completion, pending state, or fatal error.

Speculative non-blocking direct sender.

Performs one best-effort send() with MSG_DONTWAIT (plus MSG_NOSIGNAL when available). Never blocks: if the socket buffer is full, the write is left pending for the caller's blocking drain path.

Parameters

fd	Connected socket descriptor.
buf	Data to send; must not be NULL unless len is 0.
len	Number of bytes to send.
sent_out	Optional output; receives the number of bytes accepted by the socket (0 on EAGAIN or when nothing was sent).

Return values

CWIST_WRITE_DONE	The whole buffer was sent.
CWIST_WRITE_PENDING	Partial progress or the socket would block.
CWIST_WRITE_ERR	A hard send error occurred.

Definition at line 31 of file writer_fast.c.

References cap, CWIST_WRITE_DONE, CWIST_WRITE_ERR, CWIST_WRITE_PENDING, and MSG_DONTWAIT.

cwist_http_sendmsg_speculative()

cwist_write_status_t cwist_http_sendmsg_speculative	(	int	fd,
		struct iovec *	iov,
		int	iovcnt,
		int	flags,
		size_t *	total_sent
	)

Speculative scatter/gather sendmsg without blocking poll().

Attempts an immediate sendmsg with MSG_DONTWAIT. If the socket cannot accept all data, returns CWIST_WRITE_PENDING or advances iov cursor without blocking the reactor.

Speculative scatter/gather sendmsg without blocking poll().

Like cwist_http_send_speculative(), but sends a scatter/gather buffer. Under CWIST_WASI_SOCKETS (no sendmsg(2) in wasi:sockets 0.2) the iovecs are coalesced into one heap allocation (owned and freed here) and sent with a single send(); the blocking drain in cwist_http_sendmsg_all() re-drives whatever remains.

Parameters

fd	Connected socket descriptor.
iov	Array of iovec entries; must not be NULL unless iovcnt <= 0.
iovcnt	Number of entries in iov.
flags	Extra send flags ORed into MSG_DONTWAIT/MSG_NOSIGNAL.
total_sent	Optional output; receives total bytes accepted by the socket (0 on EAGAIN or when nothing was sent).

Return values

CWIST_WRITE_DONE	The entire payload was sent.
CWIST_WRITE_PENDING	Partial progress or the socket would block.
CWIST_WRITE_ERR	Allocation or hard send error occurred.

Definition at line 83 of file writer_fast.c.

References cap, cwist_alloc(), cwist_free(), CWIST_WRITE_DONE, CWIST_WRITE_ERR, CWIST_WRITE_PENDING, and MSG_DONTWAIT.

Referenced by cwist_http_async_send_response(), cwist_http_coalesce_flush(), cwist_http_send_response_async(), and cwist_http_send_response_coalesced().

cwist_sched_p2c_select_worker()

uint32_t cwist_sched_p2c_select_worker	(	const _Atomic uint32_t *	worker_loads,
		uint32_t	num_workers
	)

Select worker using Power of Two Random Choices (P2C).

Samples two random worker slots and assigns the connection to the one with lower active count. Avoids cache bouncing caused by reactive work-stealing while providing O(1) lockless balance.

Parameters

worker_loads	Array of atomic load counters for each worker.
num_workers	Total number of active worker threads/processes.

Returns

Index of the selected worker.

Select worker using Power of Two Random Choices (P2C).

Draws two distinct worker indices using a thread-local xorshift32 PRNG, reads their current loads with a relaxed atomic load, and returns the index of the worker with the smaller load. Thread-safe: the PRNG seed is _Thread_local and the load array is only read.

Parameters

worker_loads	Array of per-worker load counters (atomic uint32_t).
num_workers	Number of workers in the array.

Returns

Index of the selected worker; 0 if worker_loads is NULL or num_workers <= 1.

Definition at line 161 of file writer_fast.c.

References cap.

Referenced by cwist_http_pool_submit_async().