ringkernel-core 0.1.0

Core traits and types for RingKernel GPU-native actor system
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# ringkernel-core

Core traits and types for the RingKernel GPU-native actor system.

## Overview

This crate provides the foundational abstractions that all RingKernel backends implement. It defines the message passing protocols, kernel lifecycle management, and synchronization primitives.

## Core Abstractions

### Messages

```rust
use ringkernel_core::prelude::*;

// Messages must be serializable for GPU transfer
pub trait RingMessage: Archive + Serialize + Deserialize {
    fn type_id(&self) -> u32;
    fn correlation_id(&self) -> Option<CorrelationId>;
}
```

### Kernel Runtime

```rust
#[async_trait]
pub trait RingKernelRuntime: Send + Sync {
    async fn launch(&self, id: &str, options: LaunchOptions) -> Result<KernelHandle>;
    async fn shutdown(&self) -> Result<()>;
    fn is_k2k_enabled(&self) -> bool;
}
```

### Control Block

128-byte GPU-resident structure for kernel lifecycle management:

```rust
#[repr(C, align(128))]
pub struct ControlBlock {
    pub is_active: AtomicU32,
    pub should_terminate: AtomicU32,
    pub has_terminated: AtomicU32,
    pub messages_processed: AtomicU64,
    // ... HLC state, queue pointers, etc.
}
```

## Key Components

| Component | Description |
|-----------|-------------|
| `RingMessage` | Trait for GPU-transferable messages |
| `MessageQueue` | Lock-free ring buffer for message passing |
| `KernelHandle` | Handle to manage kernel lifecycle |
| `ControlBlock` | GPU-resident kernel state |
| `HlcTimestamp` | Hybrid Logical Clock for causal ordering |
| `K2KBroker` | Kernel-to-kernel messaging broker |
| `PubSubBroker` | Topic-based publish/subscribe |

## Hybrid Logical Clocks

Provides causal ordering across distributed operations:

```rust
use ringkernel_core::hlc::{HlcClock, HlcTimestamp};

let clock = HlcClock::new(node_id);
let ts1 = clock.tick();
let ts2 = clock.tick();
assert!(ts1 < ts2);

// Synchronize with remote timestamp
let synced = clock.update(&remote_ts)?;
```

## Kernel-to-Kernel Messaging

Direct communication between kernels without host involvement:

```rust
let broker = K2KBroker::new();
let endpoint = broker.register(kernel_id);
endpoint.send(destination_id, envelope).await?;
```

## Testing

```bash
cargo test -p ringkernel-core
```

The crate includes 65+ tests covering message serialization, queue operations, HLC ordering, and K2K messaging.

## License

Apache-2.0