README
¶
ByteRing
Circular source buffer with a double-mapped backing store: the allocation is
mapped twice back-to-back in the virtual address space, so a read that wraps
around the physical end of the ring comes back as one contiguous slice —
no per-character wrap logic, zero copies. This is refterm's source buffer
trick, ported to Go (Windows VirtualAlloc2 placeholder ring, memfd on
Linux, anonymous mmap elsewhere, tempfile fallback on POSIX).
The package also hosts the terminal parser's hot scan path:
ScanControlBytes finds line feeds, escape bytes, and high-bit (UTF-8) bytes
in a single pass, dispatching at startup to AVX2 or SSE2 on amd64 and to a
portable SWAR implementation elsewhere.
ring, err := ByteRing.AllocateByteRing(16 << 20)
if err != nil {
log.Fatal(err)
}
defer ring.Free()
// Producer: copy straight into the ring's write window.
w := ring.NextWriteRange(1 << 20)
n := copy(w.Data, chunk)
ring.Advance(uint64(n))
// Consumer: contiguous read even across the physical wrap.
r := ring.ReadAt(start, uint64(n))
process(r.Data[:r.Count])
// SIMD scan: first line feed / ESC / UTF-8 byte in one pass.
m := ByteRing.ScanControlBytes(r.Data[:r.Count], int(r.Count))
Typical throughput of the scan path on long plain-text lines: ~32 GB/s (AVX2), ~18 GB/s (SSE2), ~5.6 GB/s (SWAR).
Documentation
¶
Overview ¶
Package ByteRing implements the circular source buffer at the heart of thrupty's throughput story: the backing store is mapped twice back-to-back in the virtual address space, so a read that wraps around the physical end of the allocation is returned as a single contiguous slice — zero-copy ring reads, exactly like refterm's source buffer.
The package also hosts the parser's hot scan path: ScanControlBytes finds line feeds, escape bytes, and high-bit (UTF-8) bytes in one pass, with runtime dispatch to AVX2 or SSE2 on amd64 and a portable SWAR fallback elsewhere.
Index ¶
- type ByteRange
- func (br *ByteRange) AdvanceTo(toAbsoluteP uint64, count uint64)
- func (br *ByteRange) AtEscape() bool
- func (br *ByteRange) Consume(count uint64)
- func (br *ByteRange) GetToken() byte
- func (br *ByteRange) ParseNumber() uint32
- func (br *ByteRange) PeekDigit(ordinal int) bool
- func (br *ByteRange) PeekToken(ordinal int) byte
- type ByteRing
- type LineMetrics
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ByteRange ¶
type ByteRange struct {
AbsoluteP uint64 // absolute position in the conceptual byte stream
Count uint64 // number of valid bytes
Data []byte // slice alias; may be nil if Count == 0
}
ByteRange describes a contiguous run of bytes inside a ByteRing. It mirrors refterm_example_ByteRing.h exactly, including the fact that Data may point either into the circular buffer or into an ephemeral slice.
func (*ByteRange) AdvanceTo ¶
AdvanceTo returns a new range positioned at ToAbsoluteP with the given Count. Moving ranges backwards is not safe because the data may have been overwritten, so the caller must ensure ToAbsoluteP >= Source.AbsoluteP.
func (*ByteRange) AtEscape ¶
AtEscape reports whether the range begins with an ANSI escape introducer (ESC [).
func (*ByteRange) ParseNumber ¶
ParseNumber consumes consecutive ASCII digits and returns their value.
type ByteRing ¶
type ByteRing struct {
// DataSize is the physical allocation size (rounded up to the page size).
// It is the size of one view; the logical alias Data is 2*DataSize bytes.
DataSize uint64
// Data is a byte slice that aliases the combined back-to-back mapping.
// Its length is exactly 2*DataSize. Because the same physical pages are
// mapped at both Data[0:size] and Data[size:2*size], a write that wraps
// around the end of the physical buffer is still visible as a contiguous
// slice starting anywhere inside Data.
Data []byte
// RelativePoint is the write cursor within the physical buffer.
// It is always in the range [0, DataSize).
RelativePoint uint64
// AbsoluteFilledSize is the total number of bytes ever written to the
// circular buffer. It is used to compute whether a given absolute position
// is still present in the buffer.
AbsoluteFilledSize uint64
// contains filtered or unexported fields
}
ByteRing on Unix uses an anonymous file-backed shared mapping that is mapped twice back-to-back in the process virtual address space via mmap. The anonymous file itself is platform-specific: memfd_create on Linux, an unlinked temporary file on macOS and the BSDs (see anonFile).
The public fields {DataSize, Data, RelativePoint, AbsoluteFilledSize} are shared with the other builds so that the common methods in ring.go compile on every platform. The private fields below are mmap-specific.
func AllocateByteRing ¶
AllocateByteRing creates a circular source buffer of at least the requested logical size. The actual allocation is rounded up to the system page/allocation granularity.
Platform-specific implementations live in source_buffer_*.go.
func (*ByteRing) Free ¶
func (b *ByteRing) Free()
Free releases the source buffer mappings and any backing object. Platform-specific implementations live in source_buffer_*.go.
func (*ByteRing) GetCurrentAbsoluteP ¶
GetCurrentAbsoluteP returns the absolute write position.
func (*ByteRing) IsInBuffer ¶
IsInBuffer reports whether AbsoluteP is still present in the circular buffer.
func (*ByteRing) NextWriteRange ¶
NextWriteRange returns a contiguous slice into which the caller can write up to MaxCount bytes. MaxCount may be very large (math.MaxUint64) to request the largest available run.
type LineMetrics ¶
lineMetrics is the result of scanning a chunk of input: the number of bytes to advance, and whether the byte at Advance-1 is a control character.
func ScanControlBytes ¶
func ScanControlBytes(data []byte, maxAdvance int) LineMetrics
ScanControlBytes is the SIMD-shaped parser hot path. It dispatches to the widest vector implementation supported by the CPU, falling back to SWAR for short inputs or when SIMD is unavailable.
func ScanScalar ¶
func ScanScalar(data []byte, maxAdvance int) LineMetrics
scanScalar is the portable reference implementation of ScanControlBytes. It is used as the ground-truth for SIMD equivalence tests and as the fallback on platforms without a handwritten assembly path.
Source Files