Crate ringkernel

Expand description

§RingKernel

GPU-native persistent actor model framework for Rust.

RingKernel is a Rust port of DotCompute’s Ring Kernel system, enabling GPU-accelerated actor systems with persistent kernels, lock-free message passing, and hybrid logical clocks for causal ordering.

§Features

Persistent GPU-resident state across kernel invocations
Lock-free message passing between kernels (K2K messaging)
Hybrid Logical Clocks (HLC) for temporal ordering
Multiple backends: CUDA (NVIDIA GPUs), CPU (testing/fallback)
Type-safe serialization via rkyv/zerocopy

§Quick Start

use ringkernel::prelude::*;

#[derive(RingMessage)]
struct AddRequest {
    #[message(id)]
    id: MessageId,
    a: f32,
    b: f32,
}

#[tokio::main]
async fn main() -> Result<()> {
    // Create runtime with auto-detected backend
    let runtime = RingKernel::builder()
        .backend(Backend::Auto)
        .build()
        .await?;

    // Launch a kernel
    let kernel = runtime.launch("adder", LaunchOptions::default()).await?;
    kernel.activate().await?;

    // Send a message
    kernel.send(AddRequest {
        id: MessageId::generate(),
        a: 1.0,
        b: 2.0,
    }).await?;

    // Receive response
    let response = kernel.receive().await?;
    println!("Result: {:?}", response);

    kernel.terminate().await?;
    Ok(())
}

§Backends

RingKernel supports the following backends:

CPU - Testing and fallback (always available)
CUDA - NVIDIA GPUs (requires cuda feature)

Enable the CUDA backend via Cargo features:

[dependencies]
ringkernel = { version = "1.0", features = ["cuda"] }

§Architecture

┌─────────────────────────────────────────────────────────┐
│                    Host (CPU)                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │ Application │──│   Runtime   │──│  Message Bridge │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└──────────────────────────┬──────────────────────────────┘
                           │ DMA Transfers
┌──────────────────────────┴──────────────────────────────┐
│                   Device (GPU)                          │
│  ┌───────────┐  ┌───────────────┐  ┌───────────────┐    │
│  │ Control   │  │ Input Queue   │  │ Output Queue  │    │
│  │ Block     │  │ (lock-free)   │  │ (lock-free)   │    │
│  └───────────┘  └───────────────┘  └───────────────┘    │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Persistent Kernel (your code)          │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

Re-exports§

pub use ringkernel_codegen as codegen;

Modules§

actor: GPU Actor Lifecycle Model
alerting: Alert routing system for enterprise monitoring.
analytics_context: Analytics context for grouped buffer lifecycle management.
audit: Audit logging for enterprise security and compliance.
auth: Authentication framework for RingKernel.
availability: Check availability of backends at runtime.
backend_stub: Macro for generating unavailable backend stubs.
backpressure: Credit-Based Backpressure & Flow Control — FR-003
checkpoint: Kernel checkpointing for persistent state snapshot and restore.
config: Unified configuration for RingKernel enterprise features.
context: Ring context providing GPU intrinsics facade for kernel handlers.
control: Control block for kernel state management.
dispatcher: Multi-Kernel Message Dispatcher
dlq: Dead Letter Queue — FR-004
domain: Business domain classification for kernel messages.
drain: Graceful Shutdown with Drain Mode — FR-010
error: Error types for RingKernel operations.
health: Health monitoring and resilience infrastructure for RingKernel.
hlc: Hybrid Logical Clock (HLC) implementation for causal ordering.
hot_reload: Configuration Hot Reload — FR-008
hybrid: Hybrid CPU-GPU Processing
idempotency: Message Idempotency & Deduplication — FR-006
introspection: Per-Actor Introspection API — FR-015
k2k: Kernel-to-Kernel (K2K) direct messaging.
logging: Structured logging with trace correlation.
memory: GPU and host memory management abstractions.
memory_pressure: GPU Memory Pressure Handling — FR-005
message: Message types and traits for kernel-to-kernel communication.
multi_gpu: Multi-GPU coordination, topology discovery, and cross-GPU messaging.
observability: Observability infrastructure for RingKernel.
persistent_message: Persistent Message Traits for Type-Based Kernel Dispatch
prelude: Prelude module for convenient imports.
provenance: PROV-O provenance attribution for message envelopes.
pubsub: Topic-based publish/subscribe messaging.
queue: Lock-free message queue implementation.
rate_limiting: Rate limiting for enterprise workloads.
rbac: Role-Based Access Control (RBAC) for RingKernel.
reduction: Global Reduction Primitives
registry: Named Actor Registry — FR-002
resource: Resource guard module for preventing system overload.
rules: Hot-swappable compiled rule artifacts.
runtime: Runtime traits and types for kernel management.
runtime_context: Unified runtime context for RingKernel enterprise features.
scheduling: Dynamic Actor Scheduling — Work Stealing Protocol
secrets: Secrets management for secure key storage and retrieval.
security: Security features for GPU kernel protection and compliance.
shutdown: Graceful shutdown and signal handling for persistent GPU kernels.
state: Control block state helpers for GPU-compatible kernel state.
telemetry: Telemetry and metrics collection for kernel monitoring.
telemetry_pipeline: Real-time telemetry pipeline for streaming metrics.
tenancy: Multi-tenancy support for RingKernel.
timeout: Operation-level timeouts and deadline management.
types: Core type definitions for GPU thread identification and coordination.
vector: Vector Store / Embedding Index — FR-013

Macros§

gpu_profile: Macro for scoped GPU profiling.
unavailable_backend: Generate a stub runtime for an unavailable backend.

Structs§

BlockId: Block ID within a grid (0 to grid_size - 1).
ControlBlock: Kernel control block (128 bytes, cache-line aligned).
CpuRuntime: CPU-based implementation of RingKernelRuntime.
GlobalThreadId: Global thread ID across all blocks.
HlcTimestamp: Hybrid Logical Clock timestamp.
KernelHandle: Handle to a launched kernel.
KernelId: Unique kernel identifier.
KernelStatus: Kernel status including state and metrics.
LaunchOptions: Options for launching a kernel.
MemoryPool: Memory pool for efficient allocation/deallocation.
MessageHeader: Fixed-size message header (256 bytes, cache-line aligned).
MessageId: Unique message identifier.
PinnedMemory: Pinned (page-locked) host memory for efficient DMA transfers.
ProvRelation: A single PROV-O relation edge (kind + target node ID).
ProvenanceBuilder: Builder for ProvenanceHeader.
ProvenanceHeader: PROV-O attribution metadata attached to a message envelope.
QueueStats: Statistics for a message queue.
RingContext: GPU intrinsics facade for kernel handlers.
RingKernel: Main RingKernel runtime facade.
RingKernelBuilder: Builder for RingKernel runtime.
TelemetryBuffer: Telemetry buffer (64 bytes, cache-line aligned).
ThreadId: Thread ID within a block (0 to block_size - 1).
WarpId: Warp ID within a block.

Enums§

Backend: GPU backend type.
Domain: Business domain classification for kernel messages.
KernelState: Kernel lifecycle state.
Priority: Message priority levels.
ProvNodeType: Classification of a PROV-O node.
ProvRelationKind: PROV-O relation kind (edge label).
ProvenanceError: Errors raised when constructing or validating provenance headers.
RingKernelError: Comprehensive error type for RingKernel operations.

Traits§

DeviceMemory: Trait for device memory allocation.
DomainMessage: Trait for messages that belong to a specific business domain.
GpuBuffer: Trait for GPU buffer operations.
MessageQueue: Trait for message queue implementations.
RingKernelRuntime: Backend-agnostic runtime trait for kernel management.
RingMessage: Trait for types that can be sent as kernel messages.

Functions§

registered_kernels: Get list of registered kernels from the inventory.

Type Aliases§

Result: Result type alias for RingKernel operations.

Attribute Macros§

gpu_kernel: Attribute macro for defining multi-backend GPU kernels.
ring_kernel: Attribute macro for defining ring kernel handlers.
stencil_kernel: Attribute macro for defining stencil kernels that transpile to CUDA.

Derive Macros§

ControlBlockState: Derive macro for implementing EmbeddedState trait.
GpuType: Derive macro for GPU-compatible types.
PersistentMessage: Derive macro for implementing the PersistentMessage trait.
RingMessage: Derive macro for implementing the RingMessage trait.

Crate ringkernel

Crate ringkernel Copy item path

§RingKernel

§Features

§Quick Start

§Backends

§Architecture

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate ringkernel