Struct KernelMessage<T>

Namespace

DotCompute.Abstractions.RingKernels

Assembly

DotCompute.Abstractions.dll

Represents a message passed between ring kernels.

public struct KernelMessage<T> : IEquatable<KernelMessage<T>> where T : unmanaged

Type Parameters

T

The payload type. Must be an unmanaged type (blittable) for GPU transfer.

Implements

IEquatable<KernelMessage<T>>

Inherited Members

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Remarks

KernelMessage is designed for efficient GPU memory transfers and atomic operations. The structure is carefully laid out to avoid padding and ensure efficient memory access.

Message size should be kept small (typically 64-128 bytes) for optimal performance. Large payloads should use indirect references (buffer indices) rather than embedding data.

Properties

Payload

Application-specific payload data.

public T Payload { readonly get; init; }

Property Value

T

Remarks

The payload type T must be unmanaged (no managed references). Common payload types:

• Primitive types (int, float, etc.)
• Small structs (Vector3, Matrix4x4)
• Fixed-size arrays using 'fixed' keyword
• Indirect references (buffer indices, offsets)

ReceiverId

ID of the intended receiver kernel instance.

public int ReceiverId { readonly get; init; }

Property Value

int

Remarks

Used for message routing. A value of -1 indicates broadcast to all kernels. Specific IDs route to individual kernel instances.

SenderId

ID of the sender kernel instance.

public int SenderId { readonly get; init; }

Property Value

int

Remarks

Used for routing replies and tracking message origin. Sender IDs are assigned by the runtime when kernels are launched.

SequenceNumber

Sequence number for ordering and duplicate detection.

public ulong SequenceNumber { readonly get; init; }

Property Value

ulong

Remarks

Monotonically increasing sequence number per sender. Enables detection of message reordering and lost messages.

Timestamp

Timestamp when the message was sent (microseconds since epoch).

public long Timestamp { readonly get; init; }

Property Value

long

Remarks

Used for latency measurements, message ordering, and timeout detection. Set automatically by the message queue on enqueue.

Type

Message type (Data, Control, Terminate, etc.).

public MessageType Type { readonly get; init; }

Property Value

MessageType

Remarks

Receivers can filter messages by type for priority handling. Control and lifecycle messages typically have priority over data messages.

Methods

Create(int, int, MessageType, T)

Creates a new message with specified properties.

public static KernelMessage<T> Create(int senderId, int receiverId, MessageType type, T payload)

Parameters

senderId int

Sender kernel ID.

receiverId int

Receiver kernel ID (-1 for broadcast).

type MessageType

Message type.

payload T

Application payload.

Returns

KernelMessage<T>

A new KernelMessage instance.

CreateControl(int, int, T)

Creates a control message.

public static KernelMessage<T> CreateControl(int senderId, int receiverId, T payload)

Parameters

senderId int

Sender kernel ID.

receiverId int

Receiver kernel ID.

payload T

Control payload.

Returns

KernelMessage<T>

A new control message.

CreateData(int, int, T)

Creates a data message with simplified parameters.

public static KernelMessage<T> CreateData(int senderId, int receiverId, T payload)

Parameters

senderId int

Sender kernel ID.

receiverId int

Receiver kernel ID.

payload T

Application payload.

Returns

KernelMessage<T>

A new data message.

CreateTerminate(int, int)

Creates a termination message.

public static KernelMessage<T> CreateTerminate(int senderId, int receiverId)

Parameters

senderId int

Sender kernel ID.

receiverId int

Receiver kernel ID (-1 for all).

Returns

KernelMessage<T>

A new termination message.

Equals(KernelMessage<T>)

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

public bool Equals(KernelMessage<T> other)

Parameters

other KernelMessage<T>

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 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 int GetHashCode()

Returns

int

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

Operators

operator ==(KernelMessage<T>, KernelMessage<T>)

Determines whether two instances are equal.

public static bool operator ==(KernelMessage<T> left, KernelMessage<T> right)

Parameters

left KernelMessage<T>

right KernelMessage<T>

Returns

bool

operator !=(KernelMessage<T>, KernelMessage<T>)

Determines whether two instances are not equal.

public static bool operator !=(KernelMessage<T> left, KernelMessage<T> right)

Parameters

left KernelMessage<T>

right KernelMessage<T>

Returns

bool