CounterBasedGenerator64<TEngine> Structure

public struct CounterBasedGenerator64<TEngine> : IBlockRandomGenerator, 
	IRandomGenerator, IStateful, ICounterBased<ulong>, IAdvanceable
where TEngine : struct, new(), ICounterBased<ulong>, IBlockEngine<ulong>, IStateful

Public Structure CounterBasedGenerator64(Of TEngine As {Structure, New, ICounterBased(Of ULong), IBlockEngine(Of ULong), IStateful})
	Implements IBlockRandomGenerator, IRandomGenerator, IStateful, ICounterBased(Of ULong), 
	IAdvanceable

generic<typename TEngine>
where TEngine : value class, gcnew(), ICounterBased<unsigned long long>, IBlockEngine<unsigned long long>, IStateful
public value class CounterBasedGenerator64 : IBlockRandomGenerator, 
	IRandomGenerator, IStateful, ICounterBased<unsigned long long>, 
	IAdvanceable

[<SealedAttribute>]
type CounterBasedGenerator64<'TEngine when 'TEngine : struct, new() and ICounterBased<uint64> and IBlockEngine<uint64> and IStateful> = 
    struct
        inherit ValueType
        interface IBlockRandomGenerator
        interface IRandomGenerator
        interface IStateful
        interface ICounterBased<uint64>
        interface IAdvanceable
    end

Inheritance

Object  →  ValueType  →  CounterBasedGenerator64<TEngine>

Implements

ICounterBased<UInt64>, IAdvanceable, IBlockRandomGenerator, IRandomGenerator, IStateful

Type Parameters

TEngine

The engine type, which must be a struct implementing ICounterBased<T> and IBlockEngine<T> for UInt64, and IStateful.

CounterBasedGenerator64<TEngine> wraps a counter-based 64-bit engine (e.g., Philox-4x64) and provides:

• NextUInt64(): Returns the next word from the current block via engine.Output(index).
• NextUInt32(): Uses caching to split 64-bit words into two 32-bit words.
• NextBytes(Span<Byte>): Writes bytes via NextUInt32() in 4-byte chunks (little-endian), with tail handling.

Refill Policy (Advance-on-Empty, Consistent-by-Contract):

When the block is exhausted (_index == BlockLength), the generator calls engine.AdvanceBlock(1) which advances the counter by one block and establishes a consistent state for the new block coordinates. The generator then resets _index = 0. This ensures the engine is always in a consistent state when Output is called.

Consistency Guarantee:

All generator methods guarantee that whenever they produce output from the engine, the engine is in a consistent state. AdvanceBlock(UInt64) is guaranteed by Layer 1 to leave the engine consistent, so Layer 2 does not need to call GenerateBlock() in the normal refill path.

Uint Caching:

When NextUInt32() is called, if no cached value exists, the generator calls NextUInt64(), returns the low 32 bits, and caches the high 32 bits for the next call.

State Persistence:

Layer 2 state includes engine state (including any engine-owned cached block material), cursor index (4 bytes LE), cached uint (4 bytes LE), and cache flag (1 byte).

Reference