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;
36
37/// Benchmark framework (requires `benchmark` feature).
38#[cfg(feature = "benchmark")]
39pub mod benchmark;
40
41pub mod checkpoint;
42
43/// Cloud storage backends for checkpoints (requires `cloud-storage` feature).
44#[cfg(feature = "cloud-storage")]
45pub mod cloud_storage;
46
47pub mod config;
48pub mod context;
49pub mod control;
50pub mod dispatcher;
51pub mod domain;
52pub mod error;
53pub mod health;
54pub mod hlc;
55pub mod hybrid;
56pub mod k2k;
57pub mod memory;
58pub mod message;
59pub mod multi_gpu;
60pub mod observability;
61pub mod persistent_message;
62pub mod pubsub;
63pub mod queue;
64pub mod reduction;
65pub mod resource;
66pub mod runtime;
67pub mod runtime_context;
68pub mod security;
69pub mod state;
70pub mod telemetry;
71pub mod telemetry_pipeline;
72pub mod types;
73
74// Enterprise modules
75pub mod alerting;
76pub mod auth;
77pub mod logging;
78pub mod rate_limiting;
79pub mod rbac;
80pub mod secrets;
81pub mod tenancy;
82pub mod timeout;
83
84/// TLS support (requires `tls` feature).
85#[cfg(feature = "tls")]
86pub mod tls;
87
88/// Private module for proc macro integration.
89/// Not part of the public API - exposed for macro-generated code only.
90#[doc(hidden)]
91pub mod __private;
92
93/// Prelude module for convenient imports
94pub mod prelude {
95    pub use crate::analytics_context::{
96        AllocationHandle, AnalyticsContext, AnalyticsContextBuilder, ContextStats,
97    };
98    pub use crate::audit::{
99        AuditConfig, AuditEvent, AuditEventType, AuditLevel, AuditLogger, AuditLoggerBuilder,
100        AuditSink, CloudWatchConfig, CloudWatchSink, FileSink, MemorySink, SyslogConfig,
101        SyslogFacility, SyslogSeverity, SyslogSink,
102    };
103    #[cfg(feature = "alerting")]
104    pub use crate::audit::{ElasticsearchConfig, ElasticsearchSink};
105    pub use crate::config::{
106        CheckpointStorageType, CloudStorageConfig, ConfigBuilder, Environment, GeneralConfig,
107        GeneralConfigBuilder, HealthConfig, HealthConfigBuilder, LogLevel, MigrationConfig,
108        MigrationConfigBuilder, MultiGpuConfig, MultiGpuConfigBuilder, ObservabilityConfig,
109        ObservabilityConfigBuilder, RetryConfig, RingKernelConfig,
110    };
111    pub use crate::context::*;
112    pub use crate::control::*;
113    pub use crate::dispatcher::{
114        DispatcherBuilder, DispatcherConfig, DispatcherMetrics, KernelDispatcher,
115    };
116    pub use crate::domain::{Domain, DomainMessage, DomainParseError};
117    pub use crate::error::*;
118    pub use crate::health::{
119        BackoffStrategy, CircuitBreaker, CircuitBreakerConfig, CircuitBreakerStats, CircuitState,
120        DegradationLevel, DegradationManager, DegradationStats, FailureType, HealthCheck,
121        HealthCheckResult, HealthChecker, HealthStatus, KernelHealth, KernelWatchdog,
122        LoadSheddingPolicy, RecoveryAction, RecoveryConfig, RecoveryConfigBuilder, RecoveryManager,
123        RecoveryPolicy, RecoveryResult, RecoveryStatsSnapshot, RetryPolicy,
124    };
125    pub use crate::hlc::*;
126    pub use crate::hybrid::{
127        HybridConfig, HybridConfigBuilder, HybridDispatcher, HybridError, HybridResult,
128        HybridStats, HybridStatsSnapshot, HybridWorkload, ProcessingMode,
129    };
130    pub use crate::k2k::{
131        DeliveryStatus, K2KBroker, K2KBuilder, K2KConfig, K2KEndpoint, K2KMessage,
132        K2KMessageRegistration, K2KTypeRegistry,
133    };
134    #[cfg(feature = "crypto")]
135    pub use crate::k2k::{
136        EncryptedK2KBuilder, EncryptedK2KEndpoint, EncryptedK2KMessage, K2KEncryptionAlgorithm,
137        K2KEncryptionConfig, K2KEncryptionStatsSnapshot, K2KEncryptor, K2KKeyMaterial,
138    };
139    pub use crate::memory::*;
140    pub use crate::message::{
141        priority, CorrelationId, MessageEnvelope, MessageHeader, MessageId, Priority, RingMessage,
142    };
143    pub use crate::multi_gpu::{
144        CrossGpuK2KRouter, CrossGpuRouterStatsSnapshot, DeviceInfo, DeviceStatus,
145        DeviceUnregisterResult, GpuConnection, GpuTopology, HotReloadConfig, HotReloadManager,
146        HotReloadRequest, HotReloadResult, HotReloadState, HotReloadStatsSnapshot,
147        HotReloadableKernel, InterconnectType, KernelCodeFormat, KernelCodeSource,
148        KernelMigrationPlan, KernelMigrator, LoadBalancingStrategy, MigratableKernel,
149        MigrationPriority, MigrationRequest, MigrationResult, MigrationState,
150        MigrationStatsSnapshot, MultiGpuBuilder, MultiGpuCoordinator, PendingK2KMessage,
151        RoutingDecision,
152    };
153    pub use crate::observability::{
154        GpuDeviceMemoryStats, GpuMemoryAllocation, GpuMemoryDashboard, GpuMemoryPoolStats,
155        GpuMemoryThresholds, GpuMemoryType, GrafanaDashboard, GrafanaPanel, MemoryPressureLevel,
156        ObservabilityContext, OtlpConfig, OtlpExportResult, OtlpExporter, OtlpExporterStats,
157        OtlpTransport, PanelType, PrometheusCollector, PrometheusExporter, RingKernelCollector,
158        Span, SpanBuilder, SpanEvent, SpanId, SpanKind, SpanStatus, TraceId,
159    };
160    pub use crate::persistent_message::{
161        message_flags, DispatchTable, HandlerRegistration, PersistentMessage,
162        MAX_INLINE_PAYLOAD_SIZE,
163    };
164    pub use crate::pubsub::{PubSubBroker, PubSubBuilder, Publication, QoS, Subscription, Topic};
165    pub use crate::queue::*;
166    pub use crate::reduction::{
167        GlobalReduction, ReductionConfig, ReductionHandle, ReductionOp, ReductionScalar,
168    };
169    pub use crate::resource::{
170        global_guard, LinearEstimator, MemoryEstimate, MemoryEstimator, ReservationGuard,
171        ResourceError, ResourceGuard, ResourceResult, DEFAULT_MAX_MEMORY_BYTES,
172        SYSTEM_MEMORY_MARGIN,
173    };
174    pub use crate::runtime::*;
175    pub use crate::runtime_context::{
176        AppInfo, BackgroundTaskStatus, CircuitGuard, ContextMetrics, DegradationGuard,
177        HealthCycleResult, LifecycleState, MonitoringConfig, MonitoringHandles, OperationPriority,
178        RingKernelContext, RuntimeBuilder, RuntimeStatsSnapshot, ShutdownReport, WatchdogResult,
179    };
180    pub use crate::security::{
181        AccessLevel, ComplianceCheck, ComplianceReport, ComplianceReporter, ComplianceStandard,
182        ComplianceStatus, ComplianceSummary, EncryptedRegion, EncryptionAlgorithm,
183        EncryptionConfig, EncryptionKey, EncryptionStats, KernelSandbox, KeyDerivation,
184        MemoryEncryption, ReportFormat, ResourceLimits, SandboxPolicy, SandboxStats,
185        SandboxViolation, ViolationType,
186    };
187    pub use crate::state::{
188        ControlBlockStateHelper, EmbeddedState, EmbeddedStateSize, GpuState, StateDescriptor,
189        StateSnapshot, CONTROL_BLOCK_STATE_SIZE, STATE_DESCRIPTOR_MAGIC,
190    };
191    pub use crate::telemetry::*;
192    pub use crate::telemetry_pipeline::{
193        MetricsCollector, MetricsSnapshot, TelemetryAlert, TelemetryConfig, TelemetryEvent,
194        TelemetryPipeline,
195    };
196    pub use crate::types::*;
197
198    // Cloud storage types (feature-gated)
199    #[cfg(feature = "cloud-storage")]
200    pub use crate::cloud_storage::{AsyncCheckpointStorage, CloudProvider, S3Config, S3Storage};
201
202    // Enterprise modules
203    pub use crate::alerting::{
204        Alert, AlertRouter, AlertRouterStats, AlertSeverity, AlertSink, AlertSinkError,
205        AlertSinkResult, DeduplicationConfig, InMemorySink, LogSink,
206    };
207    #[cfg(feature = "alerting")]
208    pub use crate::alerting::{WebhookFormat, WebhookSink};
209    pub use crate::auth::{
210        ApiKeyAuth, AuthContext, AuthError, AuthProvider, AuthResult, ChainedAuthProvider,
211        Credentials, Identity,
212    };
213    #[cfg(feature = "auth")]
214    pub use crate::auth::{JwtAuth, JwtClaims, JwtConfig};
215    pub use crate::logging::{
216        ConsoleSink, FileLogSink, LogConfig as StructuredLogConfig,
217        LogConfigBuilder as StructuredLogConfigBuilder, LogEntry, LogLevel as StructuredLogLevel,
218        LogOutput, LogSink as StructuredLogSink, LogSinkError as StructuredLogSinkError, LogValue,
219        LoggerStats, MemoryLogSink, StructuredLogger, TraceContext,
220    };
221    pub use crate::rate_limiting::{
222        shared_rate_limiter, RateLimitAlgorithm, RateLimitConfig, RateLimitError, RateLimitGuard,
223        RateLimitResult, RateLimiter, RateLimiterBuilder, RateLimiterExt, RateLimiterStatsSnapshot,
224        SharedRateLimiter,
225    };
226    pub use crate::rbac::{
227        Permission, PolicyEvaluator, RbacError, RbacPolicy, RbacResult, ResourceRule, Role, Subject,
228    };
229    pub use crate::secrets::{
230        CachedSecretStore, ChainedSecretStore, EnvVarSecretStore, InMemorySecretStore,
231        KeyRotationManager, SecretError, SecretKey, SecretResult, SecretStore, SecretValue,
232    };
233    pub use crate::tenancy::{
234        QuotaUtilization, ResourceQuota, ResourceUsage, TenantContext, TenantError, TenantRegistry,
235        TenantResult,
236    };
237    pub use crate::timeout::{
238        timeout, timeout_named, with_timeout, with_timeout_named, CancellationToken, Deadline,
239        OperationContext, Timeout, TimeoutError, TimeoutStats, TimeoutStatsSnapshot,
240    };
241    #[cfg(feature = "tls")]
242    pub use crate::tls::{
243        CertificateInfo, CertificateStore, ClientAuth, SniResolver, TlsAcceptor, TlsConfig,
244        TlsConfigBuilder, TlsConnector, TlsError, TlsResult, TlsSessionInfo, TlsVersion,
245    };
246
247    // Benchmark framework (feature-gated)
248    #[cfg(feature = "benchmark")]
249    pub use crate::benchmark::{
250        BenchmarkBaseline, BenchmarkConfig, BenchmarkResult, BenchmarkSuite, Benchmarkable,
251        ConfidenceInterval, DetailedStatistics, RegressionEntry, RegressionReport,
252        RegressionStatus, ScalingMetrics, WorkloadConfig, WorkloadSize,
253    };
254}
255
256// Re-exports for convenience
257pub use context::RingContext;
258pub use control::ControlBlock;
259pub use domain::{Domain, DomainMessage};
260pub use error::{Result, RingKernelError};
261pub use hlc::HlcTimestamp;
262pub use memory::{DeviceMemory, GpuBuffer, MemoryPool, PinnedMemory};
263pub use message::{priority, MessageHeader, MessageId, Priority, RingMessage};
264pub use queue::{MessageQueue, QueueStats};
265pub use runtime::{
266    Backend, KernelHandle, KernelId, KernelState, KernelStatus, LaunchOptions, RingKernelRuntime,
267};
268pub use telemetry::TelemetryBuffer;
269pub use types::{BlockId, GlobalThreadId, ThreadId, WarpId};
ringkernel_core/lib.rs

ringkernel_core/
lib.rs
