Synchronous byte-range source. More...

#include <fcb/range_reader.hpp>

Inheritance diagram for fcb::RangeReader:

Public Member Functions
virtual	~RangeReader ()=default

virtual std::uint64_t	total_size ()=0
	Total byte length of the resource.

virtual std::vector< std::uint8_t >	read (std::uint64_t offset, std::uint64_t length)=0
	Read `length` bytes at `offset`, subject to the contract above.

virtual void	read_batch (std::vector< RangeRequest > &requests)
	Fill every request, preserving order.

Detailed Description

Synchronous byte-range source.

Implement this to plug in any transport (file, HTTP, memory, engine VFS). The core never assumes asynchrony; batching, not async, is the concurrency primitive. This is the whole point of the native port: a blocking interface is trivially wrapped by any host application's threading model, whereas forcing our async model on callers is exactly the tokio-over-FFI problem we are escaping.

CONTRACT – implementors must honour all of it:

read(offset, length) returns EXACTLY length bytes unless the range crosses the end of the resource, in which case it returns exactly the bytes that exist (possibly zero). It must never return a short buffer for any other reason; a truncated network response is an error, not a short read, and must throw fcb::Error{HttpError}.
offset >= total_size() returns empty; that is not an error.
length == 0 returns empty WITHOUT contacting the transport.
Errors are reported by throwing fcb::Error. Returning garbage is not an option – the core cannot distinguish it from data.
read_batch fills every element's data in place. Request ORDER IS PRESERVED: the i-th request's bytes land in the i-th element. An implementation may reorder its internal fetches freely.
Partial batch failure is all-or-nothing: if any request cannot be satisfied, read_batch throws and the caller must not inspect data.
The resource must be STABLE for the reader's lifetime. The core issues many ranges against one logical file and assumes they come from the same bytes; HTTP implementations must pin the representation.
THREAD SAFETY: instances are NOT thread-safe. One RangeReader serves one query at a time; concurrent queries need separate instances.
There is no cancellation mechanism. A transport needing one should implement it out-of-band (e.g. a flag its read() checks and throws on).

Definition at line 50 of file range_reader.hpp.

Constructor & Destructor Documentation

◆ ~RangeReader()

virtual fcb::RangeReader::~RangeReader ( )

virtualdefault

Member Function Documentation

◆ read()

virtual std::vector< std::uint8_t > fcb::RangeReader::read	(	std::uint64_t	offset,
		std::uint64_t	length
	)

pure virtual

Read length bytes at offset, subject to the contract above.

Implemented in fcb::CurlRangeReader, fcb::FileRangeReader, and fcb::BufferedRangeReader.

Referenced by read_batch(), and fcb::rtree_search_bbox().

◆ read_batch()

void fcb::RangeReader::read_batch ( std::vector< RangeRequest > & requests )

virtual

Fill every request, preserving order.

Transports that can pipeline or multiplex should override this; the default is a sequential loop.

Reimplemented in fcb::BufferedRangeReader.

Definition at line 9 of file range_reader.cpp.

References read().

◆ total_size()

virtual std::uint64_t fcb::RangeReader::total_size ( )

pure virtual

Total byte length of the resource.

This is a REQUIRED bounds/security contract, not a convenience: every computed section offset and range request is validated against it, so a corrupt header cannot make the core read or allocate out of bounds. (It is NOT needed to size the last feature – every feature carries its own 4-byte size prefix.)