Struct RingContext 

pub struct RingContext<'a> {
    pub thread_id: ThreadId,
    pub block_id: BlockId,
    pub block_dim: Dim3,
    pub grid_dim: Dim3,
    /* private fields */
}

GPU intrinsics facade for kernel handlers.

This struct provides access to GPU-specific operations like thread identification, synchronization, and atomic operations. The actual implementation varies by backend.

Lifetime

The context is borrowed for the duration of the kernel handler execution.

Fields

thread_id: ThreadId

Thread identity within block.

block_id: BlockId

Block identity within grid.

block_dim: Dim3

Block dimensions.

grid_dim: Dim3

Grid dimensions.

Implementations

impl<'a> RingContext<'a>

pub fn new( thread_id: ThreadId, block_id: BlockId, block_dim: Dim3, grid_dim: Dim3, clock: &'a HlcClock, kernel_id: u64, backend: ContextBackend, ) -> RingContext<'a>

Create a new context with basic configuration.

For domain-aware contexts, use new_with_options instead.

pub fn new_with_options( thread_id: ThreadId, block_id: BlockId, block_dim: Dim3, grid_dim: Dim3, clock: &'a HlcClock, kernel_id: u64, backend: ContextBackend, domain: Option<Domain>, metrics_capacity: usize, alert_sender: Option<UnboundedSender<KernelAlert>>, ) -> RingContext<'a>

Create a new context with full configuration (FR-2).

Arguments

• thread_id - Thread identity within block
• block_id - Block identity within grid
• block_dim - Block dimensions
• grid_dim - Grid dimensions
• clock - HLC clock instance
• kernel_id - Unique kernel identifier
• backend - Backend implementation
• domain - Optional domain for this kernel
• metrics_capacity - Metrics buffer capacity
• alert_sender - Optional channel for emitting alerts

pub fn thread_id(&self) -> ThreadId

Get thread ID within block.

pub fn block_id(&self) -> BlockId

Get block ID within grid.

pub fn global_thread_id(&self) -> GlobalThreadId

Get global thread ID across all blocks.

pub fn warp_id(&self) -> WarpId

Get warp ID within block.

pub fn lane_id(&self) -> u32

Get lane ID within warp (0-31).

pub fn block_dim(&self) -> Dim3

Get block dimensions.

pub fn grid_dim(&self) -> Dim3

Get grid dimensions.

pub fn kernel_id(&self) -> u64

Get kernel ID.

pub fn sync_threads(&self)

Synchronize all threads in the block.

All threads in the block must reach this barrier before any thread can proceed past it.

pub fn sync_grid(&self)

Synchronize all threads in the grid (cooperative groups).

Requires cooperative kernel launch support.

pub fn sync_warp(&self)

Synchronize threads within a warp.

pub fn thread_fence(&self, scope: FenceScope)

Memory fence at the specified scope.

pub fn fence_thread(&self)

Thread-scope fence (compiler barrier).

pub fn fence_block(&self)

Block-scope fence.

pub fn fence_device(&self)

Device-scope fence.

pub fn fence_system(&self)

System-scope fence (CPU+GPU visible).

pub fn now(&self) -> HlcTimestamp

Get current HLC timestamp.

pub fn tick(&self) -> HlcTimestamp

Generate a new HLC timestamp (advances clock).

pub fn update_clock( &self, received: &HlcTimestamp, ) -> Result<HlcTimestamp, RingKernelError>

Update clock with received timestamp.

pub fn atomic_add(&self, ptr: &AtomicU64, val: u64, order: MemoryOrder) -> u64

Atomic add and return old value.

pub fn atomic_cas( &self, ptr: &AtomicU64, expected: u64, desired: u64, success: MemoryOrder, failure: MemoryOrder, ) -> Result<u64, u64>

Atomic compare-and-swap.

pub fn atomic_exchange( &self, ptr: &AtomicU64, val: u64, order: MemoryOrder, ) -> u64

Atomic exchange.

pub fn warp_shuffle<T>(&self, value: T, src_lane: u32) -> T

where T: Copy,

Warp shuffle - get value from another lane.

Returns the value from the specified source lane.

pub fn warp_shuffle_down<T>(&self, value: T, delta: u32) -> T

where T: Copy,

Warp shuffle down - get value from lane + delta.

pub fn warp_shuffle_up<T>(&self, value: T, delta: u32) -> T

where T: Copy,

Warp shuffle up - get value from lane - delta.

pub fn warp_shuffle_xor<T>(&self, value: T, mask: u32) -> T

where T: Copy,

Warp shuffle XOR - get value from lane XOR mask.

pub fn warp_ballot(&self, predicate: bool) -> u32

Warp ballot - get bitmask of lanes where predicate is true.

pub fn warp_all(&self, predicate: bool) -> bool

Warp all - check if predicate is true for all lanes.

pub fn warp_any(&self, predicate: bool) -> bool

Warp any - check if predicate is true for any lane.

pub fn k2k_send( &self, _target_kernel: u64, _envelope: &MessageEnvelope, ) -> Result<(), RingKernelError>

Send message to another kernel (K2K).

This is a placeholder; actual implementation requires runtime support.

pub fn k2k_try_recv(&self) -> Result<MessageEnvelope, RingKernelError>

Try to receive message from K2K queue.

pub fn domain(&self) -> Option<&Domain>

Get the domain this kernel operates in.

Returns None if no domain was configured.

pub fn set_domain(&mut self, domain: Domain)

Set the domain for this kernel context.

This allows runtime domain assignment for kernels that process messages from multiple domains.

pub fn clear_domain(&mut self)

Clear the domain setting.

pub fn record_latency(&mut self, operation: &str, latency_us: u64)

Record a latency metric in microseconds.

Arguments

• operation - Name of the operation (e.g., “process_order”)
• latency_us - Latency in microseconds

Example

let start = std::time::Instant::now();
// ... process message ...
ctx.record_latency("process", start.elapsed().as_micros() as u64);

pub fn record_throughput(&mut self, operation: &str, count: u64)

Record a throughput metric (count per time period).

Arguments

• operation - Name of the operation (e.g., “messages_processed”)
• count - Number of items processed

pub fn record_counter(&mut self, operation: &str, increment: u64)

Record a counter increment.

Counters are monotonically increasing values (e.g., total orders received).

pub fn record_gauge(&mut self, operation: &str, value: u64)

Record a gauge value (absolute measurement).

Gauges represent point-in-time values that can go up or down (e.g., queue depth, memory usage).

pub fn flush_metrics(&mut self) -> Vec<MetricsEntry>

Flush and return all buffered metrics.

After calling this method, the metrics buffer will be empty. This is typically called by the runtime when transferring metrics to the host telemetry pipeline.

pub fn metrics_count(&self) -> usize

Get the number of buffered metrics entries.

pub fn metrics_buffer_full(&self) -> bool

Check if the metrics buffer is full.

pub fn emit_alert(&self, alert: impl Into<KernelAlert>)

Emit an alert from this kernel.

Alerts are sent to the configured alert channel (if any). The alert is enriched with kernel ID, domain, and timestamp.

Arguments

• alert - The alert to emit (can be created via KernelAlert::new() helpers)

Example

ctx.emit_alert(KernelAlert::high_latency("Slow processing", 500));
ctx.emit_alert(KernelAlert::error("Processing failed"));

pub fn has_alert_channel(&self) -> bool

Check if alert sending is configured.

pub fn alert_if_slow(&self, operation: &str, latency_us: u64, threshold_us: u64)

Emit a high-latency alert if latency exceeds threshold.

Convenience method that only emits an alert when latency exceeds the specified threshold.

Arguments

• operation - Name of the operation
• latency_us - Actual latency in microseconds
• threshold_us - Threshold above which to emit alert

Trait Implementations

impl<'a> Debug for RingContext<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.