ringkernel-derive 0.2.0

Procedural macros 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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# ringkernel-derive

Procedural macros for RingKernel.

## Overview

This crate provides derive macros and attribute macros for defining RingKernel messages, handlers, and GPU kernels.

## Macros

### `#[derive(RingMessage)]`

Implements the `RingMessage` trait for message types:

```rust
use ringkernel_derive::RingMessage;

#[derive(RingMessage)]
#[message(type_id = 1)]
struct MyMessage {
    #[message(id)]
    id: MessageId,
    #[message(correlation)]
    correlation: CorrelationId,
    #[message(priority)]
    priority: Priority,
    payload: Vec<f32>,
}
```

**Struct attributes:**
- `#[message(type_id = N)]` - Explicit message type ID (optional, auto-generated from name hash if omitted)

**Field attributes:**
- `#[message(id)]` - Mark as message ID field
- `#[message(correlation)]` - Mark as correlation ID field
- `#[message(priority)]` - Mark as priority field

### `#[ring_kernel]`

Defines a ring kernel handler with metadata:

```rust
use ringkernel_derive::ring_kernel;

#[ring_kernel(id = "processor", mode = "persistent", block_size = 128)]
async fn handle(ctx: &mut RingContext, msg: MyMessage) -> MyResponse {
    MyResponse {
        id: MessageId::generate(),
        result: msg.a + msg.b,
    }
}
```

**Attributes:**
- `id` (required) - Unique kernel identifier
- `mode` - `"persistent"` (default) or `"event_driven"`
- `grid_size` - Number of blocks (default: 1)
- `block_size` - Threads per block (default: 256)
- `publishes_to` - Comma-separated list of target kernel IDs

### `#[derive(GpuType)]`

Marks a type as GPU-compatible for direct transfer:

```rust
use ringkernel_derive::GpuType;

#[derive(Copy, Clone, GpuType)]
#[repr(C)]
struct Matrix4x4 {
    data: [f32; 16],
}
```

Generates compile-time assertions for `Copy` and implements `bytemuck::Pod` and `bytemuck::Zeroable`.

### `#[stencil_kernel]`

Defines a stencil kernel that transpiles to CUDA (requires `cuda-codegen` feature):

```rust
use ringkernel_derive::stencil_kernel;

#[stencil_kernel(id = "fdtd", grid = "2d", tile_size = 16, halo = 1)]
fn fdtd(p: &[f32], p_prev: &mut [f32], c2: f32, pos: GridPos) {
    let curr = p[pos.idx()];
    let lap = pos.north(p) + pos.south(p) + pos.east(p) + pos.west(p) - 4.0 * curr;
    p_prev[pos.idx()] = 2.0 * curr - p_prev[pos.idx()] + c2 * lap;
}

// Access generated CUDA source:
assert!(FDTD_CUDA_SOURCE.contains("__global__"));
```

**Attributes:**
- `id` (required) - Kernel identifier
- `grid` - `"1d"`, `"2d"` (default), or `"3d"`
- `tile_size` - Square tile size (default: 16)
- `tile_width` / `tile_height` - Non-square tile dimensions
- `halo` - Stencil radius (default: 1)

## Generated Code

The macros generate:
- Trait implementations (`RingMessage`)
- Handler wrapper functions
- Kernel registration via `inventory`
- CUDA source constants (for `stencil_kernel`)

## Testing

```bash
cargo test -p ringkernel-derive
```

The crate includes 14 tests covering all macro functionality.

## License

Apache-2.0