Class CommandBufferPool

Namespace

KeenEyes

Assembly

KeenEyes.Core.dll

Provides per-system isolated command buffers for parallel system execution.

public sealed class CommandBufferPool

Inheritance

object

CommandBufferPool

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

var pool = new CommandBufferPool();

// In parallel systems
var buffer1 = pool.Rent(systemId: 0);
var buffer2 = pool.Rent(systemId: 1);

// Systems queue commands to their respective buffers
buffer1.Spawn().With(new Position { X = 0, Y = 0 });
buffer2.Spawn().With(new Position { X = 10, Y = 10 });

// After parallel execution, merge and flush all buffers
var entityMap = pool.FlushAll(world);

Remarks

In parallel system execution, each system needs its own KeenEyes.CommandBuffer to avoid contention. The CommandBufferPool manages buffer allocation and provides deterministic merging across multiple buffers.

Thread Safety: This class is thread-safe. Multiple threads can safely rent and return buffers concurrently.

Placeholder Resolution: When merging buffers, placeholder IDs are remapped to avoid conflicts between buffers. Cross-buffer entity references are resolved during the merge operation.

Properties

ActiveBufferCount

Gets the number of command buffers currently rented.

public int ActiveBufferCount { get; }

Property Value

int

TotalCommandCount

Gets the total number of commands across all active buffers.

public int TotalCommandCount { get; }

Property Value

int

Methods

Clear()

Clears all active buffers without executing commands.

public void Clear()

Remarks

All buffers are cleared and returned to the pool.

FlushAll(IWorld)

Flushes all active command buffers to the world in a deterministic order.

public Dictionary<long, Entity> FlushAll(IWorld world)

Parameters

world IWorld

The world to execute commands on.

Returns

Dictionary<long, Entity>

A dictionary mapping placeholder IDs (prefixed with system ID) to created entities.

Remarks

Buffers are flushed in system ID order to ensure deterministic execution. Placeholder IDs are prefixed with the buffer ID to ensure uniqueness across buffers.

After flushing, all buffers are cleared and returned to the pool.

FlushBatches(IWorld, IEnumerable<IEnumerable<int>>)

Flushes command buffers in batches for staged parallel execution.

public Dictionary<long, Entity> FlushBatches(IWorld world, IEnumerable<IEnumerable<int>> systemIdBatches)

Parameters

world IWorld

The world to execute commands on.

systemIdBatches IEnumerable<IEnumerable<int>>

Batches of system IDs. Each batch is flushed in order, enabling cross-batch placeholder resolution.

Returns

Dictionary<long, Entity>

A dictionary mapping global placeholder IDs to created entities.

Remarks

Use this method when parallel systems are executed in batches (sequential batches of parallel systems). Systems in later batches can reference entities created in earlier batches.

Within each batch, systems are flushed in system ID order for determinism.

GetBufferId(int)

Gets the buffer ID for a rented buffer.

public int GetBufferId(int systemId)

Parameters

systemId int

The system ID used when renting.

Returns

int

The buffer ID, or -1 if no buffer is rented for this system.

GetGlobalPlaceholderId(int, int)

Gets the global placeholder ID for cross-buffer entity reference.

public static long GetGlobalPlaceholderId(int bufferId, int localPlaceholderId)

Parameters

bufferId int

The buffer ID that created the placeholder.

localPlaceholderId int

The local placeholder ID within that buffer.

Returns

long

A globally unique placeholder ID.

Remarks

Use this method to create entity references that can be resolved after FlushAll or FlushBatches is called.

ParseGlobalPlaceholderId(long)

Parses a global placeholder ID back to buffer ID and local placeholder ID.

public static (int BufferId, int LocalPlaceholderId) ParseGlobalPlaceholderId(long globalId)

Parameters

globalId long

The global placeholder ID.

Returns

(int ChunkIndex, int IndexInChunk)

A tuple of (bufferId, localPlaceholderId).

Rent(int)

Rents a command buffer for a specific system.

public CommandBuffer Rent(int systemId)

Parameters

systemId int

A unique identifier for the system (used for deterministic ordering).

Returns

CommandBuffer

A command buffer for the system to use.

Remarks

The systemId is used to ensure deterministic merge ordering. Systems with lower IDs have their commands executed first.

Exceptions

InvalidOperationException

Thrown if a buffer is already rented for the specified system ID.

Return(int)

Returns a rented command buffer to the pool.

public void Return(int systemId)

Parameters

systemId int

The system ID used when renting the buffer.

Remarks

The buffer is cleared and returned to the pool for reuse. Call this after flushing the buffer or if the buffer is no longer needed.