Protocol Headers

TaskHeader

class TaskHeader : public Header

Header for task offload packets.

TaskHeader serializes task metadata for transmission between clients and backends. It provides:

  • Message type identification (request vs response)

  • Task identification for routing and correlation

  • Payload size calculation for TCP stream reassembly

Implementations MUST serialize messageType (1 byte) followed by taskId (8 bytes, network byte order) as the first 9 bytes. This common prefix enables the Orchestrator to peek the taskId for response routing without knowing the concrete header type.

Example usage: 

TaskHeader header;
header.SetMessageType(TaskHeader::TASK_REQUEST);
header.SetTaskId(42);
header.SetComputeDemand(1e12);
header.SetInputSize(1024);

Ptr<Packet> packet = Create<Packet>();
packet->AddHeader(header);

Public Types

enum MessageType

Message types for task-based protocols.

Values:

enumerator TASK_REQUEST

Request message.

enumerator TASK_RESPONSE

Response message.

Public Functions

TaskHeader()

Default constructor.

~TaskHeader() override

Virtual destructor.

MessageType GetMessageType() const

Get the message type.

Returns TASK_REQUEST or TASK_RESPONSE for standard messages. Derived classes may define additional message types beyond these.

Returns:

The message type.

void SetMessageType(MessageType messageType)

Set the message type.

Parameters:

messageType – The message type.

uint64_t GetTaskId() const

Get the task identifier.

The task ID uniquely identifies a task for routing responses back to the originating client.

Returns:

The unique task ID.

void SetTaskId(uint64_t taskId)

Set the task identifier.

Parameters:

taskId – The unique task ID.

uint64_t GetRequestPayloadSize() const

Get the payload size for a request message.

Used for TCP stream reassembly. The payload size is the number of bytes following the header in a request message.

Returns:

Payload size in bytes.

uint64_t GetResponsePayloadSize() const

Get the payload size for a response message.

Used for TCP stream reassembly. The payload size is the number of bytes following the header in a response message.

Returns:

Payload size in bytes.

bool IsRequest() const

Check if this is a request message.

Returns:

True if message type equals TASK_REQUEST.

bool IsResponse() const

Check if this is a response message.

Returns:

True if message type equals TASK_RESPONSE.

void SetComputeDemand(double computeDemand)

Set the compute demand in FLOPS.

Parameters:

computeDemand – The compute demand.

double GetComputeDemand() const

Get the compute demand in FLOPS.

Returns:

The compute demand.

void SetInputSize(uint64_t inputSize)

Set the input data size in bytes.

Parameters:

inputSize – The input size.

uint64_t GetInputSize() const

Get the input data size in bytes.

Returns:

The input size.

void SetOutputSize(uint64_t outputSize)

Set the output data size in bytes.

Parameters:

outputSize – The output size.

uint64_t GetOutputSize() const

Get the output data size in bytes.

Returns:

The output size.

bool HasDeadline() const

Check if the header has a deadline set.

Returns:

true if deadline >= 0, false otherwise.

int64_t GetDeadlineNs() const

Get the task deadline.

Returns:

The deadline as nanoseconds. Returns -1 if no deadline.

void SetDeadlineNs(int64_t deadlineNs)

Set the task deadline.

Parameters:

deadlineNs – The deadline in nanoseconds. Use -1 for no deadline.

uint32_t GetPriority() const

Get the task priority.

Returns:

The priority value. Higher value = higher priority.

void SetPriority(uint32_t priority)

Set the task priority.

Parameters:

priority – The priority value. Higher value = higher priority.

std::string GetAcceleratorType() const

Get the required accelerator type.

Returns:

The accelerator type string (e.g., “GPU”, “TPU”). Empty means any.

void SetAcceleratorType(const std::string &type)

Set the required accelerator type.

Parameters:

type – The accelerator type (max 16 chars, will be truncated if longer).

std::string ToString() const

Get a string representation of the header.

Returns:

String representation.

Public Static Functions

static TypeId GetTypeId()

Get the type ID.

Returns:

The object TypeId.

Public Static Attributes

static constexpr uint32_t ACCEL_TYPE_SIZE = 16

Fixed size for accelerator type string.

static constexpr uint32_t SERIALIZED_SIZE = 61

Serialized size of the header in bytes.

The header consists of:

  • messageType: 1 byte

  • taskId: 8 bytes

  • computeDemand: 8 bytes

  • inputSize: 8 bytes

  • outputSize: 8 bytes

  • deadline: 8 bytes (int64_t nanoseconds, -1 = no deadline)

  • priority: 4 bytes

  • acceleratorType: 16 bytes

OrchestratorHeader

class OrchestratorHeader : public Header

Minimal header for orchestrator admission protocol.

OrchestratorHeader implements the admission phase of the two-phase protocol. After admission is granted, normal Task serialization (TaskHeader with TASK_REQUEST/TASK_RESPONSE) is used for execution.

Wire format (18 bytes):

  • messageType: 1 byte

  • dagId: 8 bytes (DAG identifier, echoed in response for correlation)

  • admitted: 1 byte (for ADMISSION_RESPONSE: 0=rejected, 1=admitted)

  • payloadSize: 8 bytes (size of following data for header-agnostic parsing)

Public Types

enum MessageType

Protocol message types.

Values are chosen to be distinct from TaskHeader message types (0, 1) so the orchestrator can distinguish admission protocol messages from task data uploads by peeking at the first byte.

Values:

enumerator ADMISSION_REQUEST

Client requests admission (serialized DAG metadata follows)

enumerator ADMISSION_RESPONSE

Server responds to admission (admit/reject)

enumerator DATA_UPLOAD

Phase 2: full DAG data upload.

Public Functions

MessageType GetMessageType() const

Get the message type.

Returns:

The message type.

void SetMessageType(MessageType type)

Set the message type.

Parameters:

type – The message type.

uint64_t GetDagId() const

Get the DAG ID.

For ADMISSION_REQUEST: identifies the DAG being submitted. For ADMISSION_RESPONSE: echoed back to correlate with the request.

Returns:

The DAG ID.

void SetDagId(uint64_t id)

Set the DAG ID.

Parameters:

id – The DAG ID.

bool IsAdmitted() const

Check if task was admitted (for ADMISSION_RESPONSE).

Returns:

true if admitted, false if rejected.

void SetAdmitted(bool admitted)

Set admission status (for ADMISSION_RESPONSE).

Parameters:

admitted – true if task should be admitted.

uint64_t GetPayloadSize() const

Get the payload size.

For ADMISSION_REQUEST: Size of following TaskHeader bytes. For ADMISSION_RESPONSE: 0 (no payload).

This enables header-agnostic parsing - the orchestrator reads exactly this many bytes and passes them to the deserializer.

Returns:

Size of data following this header in bytes.

void SetPayloadSize(uint64_t size)

Set the payload size.

Parameters:

size – Size of data following this header in bytes.

bool IsRequest() const

Check if this is a request message.

Returns:

true if ADMISSION_REQUEST.

bool IsResponse() const

Check if this is a response message.

Returns:

true if ADMISSION_RESPONSE.

bool IsDataUpload() const

Check if this is a data upload message.

Returns:

true if DATA_UPLOAD.

std::string GetMessageTypeName() const

Get string representation of message type.

Returns:

Message type name.

Public Static Functions

static TypeId GetTypeId()

Get the type ID.

Returns:

The object TypeId.

Public Static Attributes

static constexpr uint32_t SERIALIZED_SIZE = 18

Serialized size of the header in bytes.

DeviceMetricsHeader

class DeviceMetricsHeader : public Header

Header for device metrics reports sent from backend to orchestrator.

DeviceMetricsHeader carries accelerator telemetry from a backend to the Orchestrator’s DeviceManager.

Wire format (17 bytes):

  • messageType: 1 byte (uint8_t, always DEVICE_METRICS = 6)

  • utilization: 8 bytes (double as uint64_t via memcpy, network byte order)

  • currentPower: 8 bytes (double as uint64_t via memcpy, network byte order)

Public Functions

uint8_t GetMessageType() const

Get the message type.

Returns:

The message type.

void SetMessageType(uint8_t type)

Set the message type.

Parameters:

type – The message type.

double GetUtilization() const

Get the rolling compute utilization.

Returns:

Utilization in [0.0, 1.0].

void SetUtilization(double utilization)

Set the rolling compute utilization.

Parameters:

utilization – Utilization in [0.0, 1.0].

double GetCurrentPower() const

Get the current power draw.

Returns:

Power in Watts.

void SetCurrentPower(double power)

Set the current power draw.

Parameters:

power – Power in Watts.

Public Static Functions

static TypeId GetTypeId()

Get the type ID.

Returns:

The object TypeId.

Public Static Attributes

static constexpr uint8_t DEVICE_METRICS = 6

Message type value for device metrics.

static constexpr uint32_t SERIALIZED_SIZE = 17

Serialized size of the header in bytes.

ScalingCommandHeader

class ScalingCommandHeader : public Header

Header for scaling commands sent from orchestrator to backend.

ScalingCommandHeader carries a target performance state index from the Orchestrator’s DeviceManager to a backend. It is multiplexed on the same connection as task data using message type 5.

Wire format (5 bytes):

  • messageType: 1 byte (SCALING_COMMAND = 5)

  • targetStateIdx: 4 bytes (uint32_t, network byte order)

Public Functions

uint8_t GetMessageType() const

Get the message type.

Returns:

The message type byte.

void SetMessageType(uint8_t type)

Set the message type.

Parameters:

type – The message type byte.

uint32_t GetTargetStateIdx() const

Get the target performance state index.

Returns:

The target state index.

void SetTargetStateIdx(uint32_t idx)

Set the target performance state index.

Parameters:

idx – The target state index.

Public Static Functions

static TypeId GetTypeId()

Get the type ID.

Returns:

The object TypeId.

Public Static Attributes

static constexpr uint8_t SCALING_COMMAND = 5

Message type value for scaling commands.

static constexpr uint32_t SERIALIZED_SIZE = 5

Serialized size of the header in bytes.