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

ringkernel_core/
lib.rs
