ringkernel_core/
lib.rs

1//! # RingKernel Core
2//!
3//! Core traits and types for the RingKernel GPU-native persistent actor system.
4//!
5//! This crate provides the foundational abstractions for building GPU-accelerated
6//! actor systems with persistent kernels, lock-free message passing, and hybrid
7//! logical clocks for temporal ordering.
8//!
9//! ## Core Abstractions
10//!
11//! - [`RingMessage`] - Trait for messages between kernels
12//! - [`MessageQueue`] - Lock-free ring buffer for message passing
13//! - [`RingKernelRuntime`] - Backend-agnostic runtime management
14//! - [`RingContext`] - GPU intrinsics facade for kernel handlers
15//! - [`HlcTimestamp`] - Hybrid Logical Clock for causal ordering
16//!
17//! ## Example
18//!
19//! ```ignore
20//! use ringkernel_core::prelude::*;
21//!
22//! #[derive(RingMessage)]
23//! struct MyMessage {
24//!     #[message(id)]
25//!     id: MessageId,
26//!     payload: Vec<f32>,
27//! }
28//! ```
29
30#![warn(missing_docs)]
31#![warn(clippy::all)]
32#![deny(unsafe_op_in_unsafe_fn)]
33
34pub mod audit;
35pub mod checkpoint;
36
37/// Cloud storage backends for checkpoints (requires `cloud-storage` feature).
38#[cfg(feature = "cloud-storage")]
39pub mod cloud_storage;
40
41pub mod config;
42pub mod context;
43pub mod control;
44pub mod domain;
45pub mod error;
46pub mod health;
47pub mod hlc;
48pub mod k2k;
49pub mod memory;
50pub mod message;
51pub mod multi_gpu;
52pub mod observability;
53pub mod pubsub;
54pub mod queue;
55pub mod runtime;
56pub mod runtime_context;
57pub mod security;
58pub mod state;
59pub mod telemetry;
60pub mod telemetry_pipeline;
61pub mod types;
62
63/// Private module for proc macro integration.
64/// Not part of the public API - exposed for macro-generated code only.
65#[doc(hidden)]
66pub mod __private;
67
68/// Prelude module for convenient imports
69pub mod prelude {
70    pub use crate::audit::{
71        AuditConfig, AuditEvent, AuditEventType, AuditLevel, AuditLogger, AuditLoggerBuilder,
72        AuditSink, FileSink, MemorySink,
73    };
74    pub use crate::config::{
75        CheckpointStorageType, CloudStorageConfig, ConfigBuilder, Environment, GeneralConfig,
76        GeneralConfigBuilder, HealthConfig, HealthConfigBuilder, LogLevel, MigrationConfig,
77        MigrationConfigBuilder, MultiGpuConfig, MultiGpuConfigBuilder, ObservabilityConfig,
78        ObservabilityConfigBuilder, RetryConfig, RingKernelConfig,
79    };
80    pub use crate::context::*;
81    pub use crate::control::*;
82    pub use crate::domain::{Domain, DomainMessage, DomainParseError};
83    pub use crate::error::*;
84    pub use crate::health::{
85        BackoffStrategy, CircuitBreaker, CircuitBreakerConfig, CircuitBreakerStats, CircuitState,
86        DegradationLevel, DegradationManager, DegradationStats, HealthCheck, HealthCheckResult,
87        HealthChecker, HealthStatus, KernelHealth, KernelWatchdog, LoadSheddingPolicy, RetryPolicy,
88    };
89    pub use crate::hlc::*;
90    pub use crate::k2k::{
91        DeliveryStatus, K2KBroker, K2KBuilder, K2KConfig, K2KEndpoint, K2KMessage,
92        K2KMessageRegistration, K2KTypeRegistry,
93    };
94    pub use crate::memory::*;
95    pub use crate::message::{
96        priority, CorrelationId, MessageEnvelope, MessageHeader, MessageId, Priority, RingMessage,
97    };
98    pub use crate::multi_gpu::{
99        CrossGpuK2KRouter, CrossGpuRouterStatsSnapshot, DeviceInfo, DeviceStatus,
100        DeviceUnregisterResult, GpuConnection, GpuTopology, HotReloadConfig, HotReloadManager,
101        HotReloadRequest, HotReloadResult, HotReloadState, HotReloadStatsSnapshot,
102        HotReloadableKernel, InterconnectType, KernelCodeFormat, KernelCodeSource,
103        KernelMigrationPlan, KernelMigrator, LoadBalancingStrategy, MigratableKernel,
104        MigrationPriority, MigrationRequest, MigrationResult, MigrationState,
105        MigrationStatsSnapshot, MultiGpuBuilder, MultiGpuCoordinator, PendingK2KMessage,
106        RoutingDecision,
107    };
108    pub use crate::observability::{
109        GpuDeviceMemoryStats, GpuMemoryAllocation, GpuMemoryDashboard, GpuMemoryPoolStats,
110        GpuMemoryThresholds, GpuMemoryType, GrafanaDashboard, GrafanaPanel, MemoryPressureLevel,
111        ObservabilityContext, PanelType, PrometheusCollector, PrometheusExporter,
112        RingKernelCollector, Span, SpanBuilder, SpanEvent, SpanId, SpanKind, SpanStatus, TraceId,
113    };
114    pub use crate::pubsub::{PubSubBroker, PubSubBuilder, Publication, QoS, Subscription, Topic};
115    pub use crate::queue::*;
116    pub use crate::runtime::*;
117    pub use crate::runtime_context::{
118        AppInfo, BackgroundTaskStatus, CircuitGuard, ContextMetrics, DegradationGuard,
119        HealthCycleResult, LifecycleState, MonitoringConfig, MonitoringHandles, OperationPriority,
120        RingKernelContext, RuntimeBuilder, RuntimeStatsSnapshot, ShutdownReport, WatchdogResult,
121    };
122    pub use crate::security::{
123        AccessLevel, ComplianceCheck, ComplianceReport, ComplianceReporter, ComplianceStandard,
124        ComplianceStatus, ComplianceSummary, EncryptedRegion, EncryptionAlgorithm,
125        EncryptionConfig, EncryptionKey, EncryptionStats, KernelSandbox, KeyDerivation,
126        MemoryEncryption, ReportFormat, ResourceLimits, SandboxPolicy, SandboxStats,
127        SandboxViolation, ViolationType,
128    };
129    pub use crate::state::{
130        ControlBlockStateHelper, EmbeddedState, EmbeddedStateSize, GpuState, StateDescriptor,
131        StateSnapshot, CONTROL_BLOCK_STATE_SIZE, STATE_DESCRIPTOR_MAGIC,
132    };
133    pub use crate::telemetry::*;
134    pub use crate::telemetry_pipeline::{
135        MetricsCollector, MetricsSnapshot, TelemetryAlert, TelemetryConfig, TelemetryEvent,
136        TelemetryPipeline,
137    };
138    pub use crate::types::*;
139
140    // Cloud storage types (feature-gated)
141    #[cfg(feature = "cloud-storage")]
142    pub use crate::cloud_storage::{AsyncCheckpointStorage, CloudProvider, S3Config, S3Storage};
143}
144
145// Re-exports for convenience
146pub use context::RingContext;
147pub use control::ControlBlock;
148pub use domain::{Domain, DomainMessage};
149pub use error::{Result, RingKernelError};
150pub use hlc::HlcTimestamp;
151pub use memory::{DeviceMemory, GpuBuffer, MemoryPool, PinnedMemory};
152pub use message::{priority, MessageHeader, MessageId, Priority, RingMessage};
153pub use queue::{MessageQueue, QueueStats};
154pub use runtime::{
155    Backend, KernelHandle, KernelId, KernelState, KernelStatus, LaunchOptions, RingKernelRuntime,
156};
157pub use telemetry::TelemetryBuffer;
158pub use types::{BlockId, GlobalThreadId, ThreadId, WarpId};
ringkernel_core/lib.rs

ringkernel_core/
lib.rs
