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 analytics_context;
35pub mod audit;
36pub mod checkpoint;
37
38/// Cloud storage backends for checkpoints (requires `cloud-storage` feature).
39#[cfg(feature = "cloud-storage")]
40pub mod cloud_storage;
41
42pub mod config;
43pub mod context;
44pub mod control;
45pub mod dispatcher;
46pub mod domain;
47pub mod error;
48pub mod health;
49pub mod hlc;
50pub mod k2k;
51pub mod memory;
52pub mod message;
53pub mod multi_gpu;
54pub mod observability;
55pub mod persistent_message;
56pub mod pubsub;
57pub mod queue;
58pub mod reduction;
59pub mod runtime;
60pub mod runtime_context;
61pub mod security;
62pub mod state;
63pub mod telemetry;
64pub mod telemetry_pipeline;
65pub mod types;
66
67/// Private module for proc macro integration.
68/// Not part of the public API - exposed for macro-generated code only.
69#[doc(hidden)]
70pub mod __private;
71
72/// Prelude module for convenient imports
73pub mod prelude {
74    pub use crate::analytics_context::{
75        AllocationHandle, AnalyticsContext, AnalyticsContextBuilder, ContextStats,
76    };
77    pub use crate::audit::{
78        AuditConfig, AuditEvent, AuditEventType, AuditLevel, AuditLogger, AuditLoggerBuilder,
79        AuditSink, FileSink, MemorySink,
80    };
81    pub use crate::config::{
82        CheckpointStorageType, CloudStorageConfig, ConfigBuilder, Environment, GeneralConfig,
83        GeneralConfigBuilder, HealthConfig, HealthConfigBuilder, LogLevel, MigrationConfig,
84        MigrationConfigBuilder, MultiGpuConfig, MultiGpuConfigBuilder, ObservabilityConfig,
85        ObservabilityConfigBuilder, RetryConfig, RingKernelConfig,
86    };
87    pub use crate::context::*;
88    pub use crate::control::*;
89    pub use crate::dispatcher::{
90        DispatcherBuilder, DispatcherConfig, DispatcherMetrics, KernelDispatcher,
91    };
92    pub use crate::domain::{Domain, DomainMessage, DomainParseError};
93    pub use crate::error::*;
94    pub use crate::health::{
95        BackoffStrategy, CircuitBreaker, CircuitBreakerConfig, CircuitBreakerStats, CircuitState,
96        DegradationLevel, DegradationManager, DegradationStats, HealthCheck, HealthCheckResult,
97        HealthChecker, HealthStatus, KernelHealth, KernelWatchdog, LoadSheddingPolicy, RetryPolicy,
98    };
99    pub use crate::hlc::*;
100    pub use crate::k2k::{
101        DeliveryStatus, K2KBroker, K2KBuilder, K2KConfig, K2KEndpoint, K2KMessage,
102        K2KMessageRegistration, K2KTypeRegistry,
103    };
104    pub use crate::memory::*;
105    pub use crate::message::{
106        priority, CorrelationId, MessageEnvelope, MessageHeader, MessageId, Priority, RingMessage,
107    };
108    pub use crate::multi_gpu::{
109        CrossGpuK2KRouter, CrossGpuRouterStatsSnapshot, DeviceInfo, DeviceStatus,
110        DeviceUnregisterResult, GpuConnection, GpuTopology, HotReloadConfig, HotReloadManager,
111        HotReloadRequest, HotReloadResult, HotReloadState, HotReloadStatsSnapshot,
112        HotReloadableKernel, InterconnectType, KernelCodeFormat, KernelCodeSource,
113        KernelMigrationPlan, KernelMigrator, LoadBalancingStrategy, MigratableKernel,
114        MigrationPriority, MigrationRequest, MigrationResult, MigrationState,
115        MigrationStatsSnapshot, MultiGpuBuilder, MultiGpuCoordinator, PendingK2KMessage,
116        RoutingDecision,
117    };
118    pub use crate::observability::{
119        GpuDeviceMemoryStats, GpuMemoryAllocation, GpuMemoryDashboard, GpuMemoryPoolStats,
120        GpuMemoryThresholds, GpuMemoryType, GrafanaDashboard, GrafanaPanel, MemoryPressureLevel,
121        ObservabilityContext, PanelType, PrometheusCollector, PrometheusExporter,
122        RingKernelCollector, Span, SpanBuilder, SpanEvent, SpanId, SpanKind, SpanStatus, TraceId,
123    };
124    pub use crate::persistent_message::{
125        message_flags, DispatchTable, HandlerRegistration, PersistentMessage,
126        MAX_INLINE_PAYLOAD_SIZE,
127    };
128    pub use crate::pubsub::{PubSubBroker, PubSubBuilder, Publication, QoS, Subscription, Topic};
129    pub use crate::queue::*;
130    pub use crate::reduction::{
131        GlobalReduction, ReductionConfig, ReductionHandle, ReductionOp, ReductionScalar,
132    };
133    pub use crate::runtime::*;
134    pub use crate::runtime_context::{
135        AppInfo, BackgroundTaskStatus, CircuitGuard, ContextMetrics, DegradationGuard,
136        HealthCycleResult, LifecycleState, MonitoringConfig, MonitoringHandles, OperationPriority,
137        RingKernelContext, RuntimeBuilder, RuntimeStatsSnapshot, ShutdownReport, WatchdogResult,
138    };
139    pub use crate::security::{
140        AccessLevel, ComplianceCheck, ComplianceReport, ComplianceReporter, ComplianceStandard,
141        ComplianceStatus, ComplianceSummary, EncryptedRegion, EncryptionAlgorithm,
142        EncryptionConfig, EncryptionKey, EncryptionStats, KernelSandbox, KeyDerivation,
143        MemoryEncryption, ReportFormat, ResourceLimits, SandboxPolicy, SandboxStats,
144        SandboxViolation, ViolationType,
145    };
146    pub use crate::state::{
147        ControlBlockStateHelper, EmbeddedState, EmbeddedStateSize, GpuState, StateDescriptor,
148        StateSnapshot, CONTROL_BLOCK_STATE_SIZE, STATE_DESCRIPTOR_MAGIC,
149    };
150    pub use crate::telemetry::*;
151    pub use crate::telemetry_pipeline::{
152        MetricsCollector, MetricsSnapshot, TelemetryAlert, TelemetryConfig, TelemetryEvent,
153        TelemetryPipeline,
154    };
155    pub use crate::types::*;
156
157    // Cloud storage types (feature-gated)
158    #[cfg(feature = "cloud-storage")]
159    pub use crate::cloud_storage::{AsyncCheckpointStorage, CloudProvider, S3Config, S3Storage};
160}
161
162// Re-exports for convenience
163pub use context::RingContext;
164pub use control::ControlBlock;
165pub use domain::{Domain, DomainMessage};
166pub use error::{Result, RingKernelError};
167pub use hlc::HlcTimestamp;
168pub use memory::{DeviceMemory, GpuBuffer, MemoryPool, PinnedMemory};
169pub use message::{priority, MessageHeader, MessageId, Priority, RingMessage};
170pub use queue::{MessageQueue, QueueStats};
171pub use runtime::{
172    Backend, KernelHandle, KernelId, KernelState, KernelStatus, LaunchOptions, RingKernelRuntime,
173};
174pub use telemetry::TelemetryBuffer;
175pub use types::{BlockId, GlobalThreadId, ThreadId, WarpId};
ringkernel_core/lib.rs

ringkernel_core/
lib.rs
