Struct KernelRoutingTable

Namespace

DotCompute.Backends.CUDA.RingKernels

Assembly

DotCompute.Backends.CUDA.dll

GPU-resident routing table for kernel-to-kernel message passing.

public struct KernelRoutingTable : IEquatable<KernelRoutingTable>

Implements

IEquatable<KernelRoutingTable>

Inherited Members

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

This structure enables efficient message routing between ring kernels with minimal latency. Uses a hash table with linear probing for collision resolution.

Memory Layout (32 bytes, cache-line sub-aligned): - KernelCount: 4 bytes - KernelControlBlocksPtr: 8 bytes - OutputQueuesPtr: 8 bytes - RoutingHashTablePtr: 8 bytes - HashTableCapacity: 4 bytes

Hash Table Entry Format (32-bit): - Bits 31-16: Kernel ID (16-bit hash of kernel name) - Bits 15-0: Queue index (0-65535)

Performance Characteristics: - Lookup: O(1) average, O(n) worst case (linear probing) - Target latency: < 1μs per message route - Throughput: 1M+ messages/sec sustained

Fields

HashTableCapacity

Hash table capacity (must be power of 2 for fast modulo).

public int HashTableCapacity

Field Value

int

Remarks

Recommended: 2x KernelCount for <50% load factor. Valid range: 16-65536 (must be power of 2). Used for hash computation: hash % capacity.

KernelControlBlocksPtr

Device pointer to array of RingKernelControlBlock structures.

public long KernelControlBlocksPtr

Field Value

long

Remarks

Array size: KernelCount elements. Used for health monitoring and control flow.

KernelCount

Number of active kernels registered in the routing table.

public int KernelCount

Field Value

int

Remarks

Valid range: 1-65535 Used for bounds checking and iteration.

OutputQueuesPtr

Device pointer to array of output queue pointers (one per kernel).

public long OutputQueuesPtr

Field Value

long

Remarks

Array size: KernelCount elements. Each element is a device pointer to an output queue buffer. Format: unsigned char* queues[KernelCount]

RoutingHashTablePtr

Device pointer to routing hash table (kernel ID → queue index mapping).

public long RoutingHashTablePtr

Field Value

long

Remarks

Array size: HashTableCapacity entries (32-bit each). Entry format: (kernel_id << 16) | queue_index Empty entries: 0x00000000 Collision resolution: Linear probing

Methods

CalculateCapacity(int)

Calculates the recommended hash table capacity for a given kernel count.

public static int CalculateCapacity(int kernelCount)

Parameters

kernelCount int

Number of kernels to route between.

Returns

int

Next power of 2 that is at least 2x the kernel count.

Remarks

Targets ~50% load factor for optimal performance. Minimum capacity: 16 (even for 1-8 kernels). Maximum capacity: 65536.

CreateEmpty()

Creates an uninitialized routing table (all pointers null, counts zero).

public static KernelRoutingTable CreateEmpty()

Returns

KernelRoutingTable

Empty routing table suitable for GPU allocation.

Equals(KernelRoutingTable)

Indicates whether the current object is equal to another object of the same type.

public readonly bool Equals(KernelRoutingTable other)

Parameters

other KernelRoutingTable

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override readonly bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetHashCode()

Returns the hash code for this instance.

public override readonly int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

Validate()

Validates the routing table structure for correctness.

public readonly bool Validate()

Returns

bool

True if valid, false if any invariant is violated.

Remarks

Checks:

• KernelCount in valid range [1, 65535]
• HashTableCapacity is power of 2
• HashTableCapacity >= KernelCount
• All device pointers are non-zero (if KernelCount > 0)

Operators

operator ==(KernelRoutingTable, KernelRoutingTable)

Equality operator.

public static bool operator ==(KernelRoutingTable left, KernelRoutingTable right)

Parameters

left KernelRoutingTable

right KernelRoutingTable

Returns

bool

operator !=(KernelRoutingTable, KernelRoutingTable)

Inequality operator.

public static bool operator !=(KernelRoutingTable left, KernelRoutingTable right)

Parameters

left KernelRoutingTable

right KernelRoutingTable

Returns

bool