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

ringkernel_core/
lib.rs
