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

ringkernel_core/
lib.rs
