#![forbid(unsafe_code)]
#![deny(missing_docs)]
mod entry;
mod lifecycle;
mod metrics;
mod observer;
mod queue;
mod registry;
mod route;
mod route_hash;
mod runner;
mod shutdown;
mod slot;
mod timer;
mod tunnel;
use std::future::Future;
use std::hash::Hash;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use std::task::{Context, Poll, Wake, Waker};
use std::time::{Duration, Instant};
pub use entry::{Submission, TaskStatus};
pub use metrics::{FrozenEvidence, FrozenEvidenceSnapshot, MetricsSnapshot, RunnerMetricsSnapshot};
pub use registry::{
PartitionRunnerRegistry, PartitionRunnerRegistryBuilder, RunnerConfig, RunnerName,
RunnerRegistryError, StopAllEntry, StopAllReport, DEFAULT_RUNNER,
};
pub use route::{TaskOrdering, TaskSpec, TaskType};
pub use route_hash::RouteHash;
pub use runner::{PartitionRunner, RunnerHealth, RunnerPhase, SubmitError, SubmitRejection};
pub use shutdown::{ForceStopError, ShutdownReport, StartError, StopError};
const DEFAULT_QUEUE_CAPACITY: usize = 65_536;
const DEFAULT_MAX_TYPES: usize = 4_096;
const DEFAULT_STOP_TIMEOUT: Duration = Duration::from_secs(2);
const MAX_STOP_TIMEOUT: Duration = Duration::from_secs(31_536_000);
static NEXT_STANDALONE_ID: AtomicU64 = AtomicU64::new(1_u64 << 63);
pub struct PartitionExecutor {
runner: PartitionRunner,
stop_timeout: Duration,
}
impl PartitionExecutor {
pub fn new() -> Self {
Self::with_partitions(default_partitions())
}
pub fn with_partitions(partitions: usize) -> Self {
Self::with_partitions_and_capacity(partitions, DEFAULT_QUEUE_CAPACITY)
}
pub fn with_partitions_and_capacity(partitions: usize, queue_capacity: usize) -> Self {
let partitions = normalize_partitions(partitions);
let capacity = queue_capacity.max(1);
let global = partitions.saturating_mul(capacity.saturating_add(1));
Self::with_limits(partitions, capacity, global)
}
pub fn with_limits(partitions: usize, queue_capacity: usize, global_inflight: usize) -> Self {
let partitions = normalize_partitions(partitions);
let queue_capacity = queue_capacity.clamp(1, u32::MAX as usize);
let global_inflight = global_inflight.clamp(1, tokio::sync::Semaphore::MAX_PERMITS);
let config = RunnerConfig {
partitions,
queue_capacity_per_type: queue_capacity,
global_inflight,
max_type_states: DEFAULT_MAX_TYPES.max(partitions),
load_observer_interval: Duration::from_millis(10),
..RunnerConfig::default()
}
.validated()
.expect("standalone partition runner config is normalized");
let id = NEXT_STANDALONE_ID
.fetch_update(Ordering::AcqRel, Ordering::Acquire, |value| {
value.checked_add(1)
})
.expect("standalone partition runner id space is exhausted");
let runner = PartitionRunner::standalone(id, config)
.expect("PartitionExecutor must be constructed inside a Tokio runtime");
Self {
runner,
stop_timeout: DEFAULT_STOP_TIMEOUT,
}
}
pub fn with_stop_timeout(mut self, timeout: Duration) -> Self {
self.stop_timeout = timeout.min(MAX_STOP_TIMEOUT);
self
}
pub fn with_max_lanes(self, max_lanes: usize) -> Self {
self.runner.set_standalone_type_limit(max_lanes);
self
}
pub fn submit<K, F, Fut>(&self, key: K, task: F) -> Result<(), SubmitError>
where
K: Hash,
F: FnOnce() -> Fut + Send + 'static,
Fut: Future<Output = ()> + Send + 'static,
{
self.runner.submit_legacy(key, task)
}
pub fn submit_sync<K, F>(&self, key: K, task: F) -> Result<(), SubmitError>
where
K: Hash,
F: FnOnce() + Send + 'static,
{
self.runner
.submit_legacy(key, move || async move { task() })
}
pub async fn submit_async<K, F, Fut>(&self, key: K, task: F) -> Result<(), SubmitError>
where
K: Hash,
F: FnOnce() -> Fut + Send + 'static,
Fut: Future<Output = ()> + Send + 'static,
{
self.runner.submit_legacy_waiting(key, task).await
}
pub fn submit_typed<K, F, Fut>(
&self,
key: K,
spec: TaskSpec,
task: F,
) -> Result<Submission, SubmitRejection>
where
K: Hash,
F: FnOnce() -> Fut + Send + 'static,
Fut: Future<Output = ()> + Send + 'static,
{
self.runner.submit_typed(key, spec, task)
}
pub fn exec_typed<K, F, Fut>(
&self,
key: K,
spec: TaskSpec,
task: F,
) -> Result<(), SubmitRejection>
where
K: Hash,
F: FnOnce() -> Fut + Send + 'static,
Fut: Future<Output = ()> + Send + 'static,
{
self.runner.exec_typed(key, spec, task)
}
pub fn submit_after<K, F, Fut>(
&self,
key: K,
delay: Duration,
spec: TaskSpec,
task: F,
) -> Result<Submission, SubmitRejection>
where
K: Hash,
F: FnOnce() -> Fut + Send + 'static,
Fut: Future<Output = ()> + Send + 'static,
{
self.runner.submit_after(key, delay, spec, task)
}
pub fn is_started(&self) -> bool {
self.runner.phase() == RunnerPhase::Accepting
}
pub fn is_healthy(&self) -> bool {
self.runner.health() == RunnerHealth::Healthy
}
pub fn partitions(&self) -> usize {
self.runner.config().partitions
}
pub fn dead_partitions(&self) -> i64 {
self.runner.metrics_snapshot().dead_workers
}
pub fn lanes(&self) -> usize {
self.runner.metrics_snapshot().lanes as usize
}
pub fn failed_lanes(&self) -> u64 {
self.runner.metrics_snapshot().failed_lanes
}
pub fn metrics_snapshot(&self) -> MetricsSnapshot {
self.runner.metrics_snapshot()
}
pub fn frozen_evidence(&self) -> Vec<FrozenEvidence> {
self.runner.frozen_evidence().recent
}
pub async fn shutdown_with_report(&self) -> ShutdownReport {
self.shutdown_with_report_timeout(self.stop_timeout).await
}
pub async fn shutdown_with_report_timeout(&self, timeout: Duration) -> ShutdownReport {
let graceful_deadline = Instant::now()
.checked_add(timeout.min(MAX_STOP_TIMEOUT))
.unwrap_or_else(Instant::now);
match self.runner.stop(graceful_deadline).await {
Ok(report) => report,
Err(_) => {
let force_budget = timeout.max(Duration::from_secs(2));
let force_deadline = Instant::now()
.checked_add(force_budget.min(MAX_STOP_TIMEOUT))
.unwrap_or_else(Instant::now);
self.runner
.force_stop(force_deadline)
.await
.unwrap_or_else(|_| self.runner.metrics_snapshot().into())
}
}
}
pub async fn shutdown(&self) {
let _ = self.shutdown_with_report().await;
}
}
impl Default for PartitionExecutor {
fn default() -> Self {
Self::new()
}
}
impl From<RunnerMetricsSnapshot> for ShutdownReport {
fn from(snapshot: RunnerMetricsSnapshot) -> Self {
Self {
aborted: snapshot.aborted,
frozen: snapshot.frozen,
unconverged_slots: snapshot.partitions as u32,
..Self::default()
}
}
}
pub(crate) fn run_isolated(context: &str, action: impl FnOnce()) {
let Err(payload) = std::panic::catch_unwind(std::panic::AssertUnwindSafe(action)) else {
return;
};
let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(move || {
tracing::error!(context, "napart 隔离了外部回调展开");
drop(payload);
}));
}
struct ShieldWake {
downstream: Mutex<Option<Waker>>,
}
impl ShieldWake {
fn new(downstream: Waker) -> Arc<Self> {
Arc::new(Self {
downstream: Mutex::new(Some(downstream)),
})
}
}
impl Wake for ShieldWake {
fn wake(self: Arc<Self>) {
let downstream = self
.downstream
.lock()
.unwrap_or_else(|e| e.into_inner())
.take();
run_isolated("外部 Waker 消费式唤醒", move || {
if let Some(downstream) = downstream {
downstream.wake();
}
});
}
fn wake_by_ref(self: &Arc<Self>) {
let downstream = self.downstream.lock().unwrap_or_else(|e| e.into_inner());
run_isolated("外部 Waker 借用式唤醒", || {
if let Some(downstream) = downstream.as_ref() {
downstream.wake_by_ref();
}
});
}
}
impl Drop for ShieldWake {
fn drop(&mut self) {
let downstream = self
.downstream
.get_mut()
.unwrap_or_else(|e| e.into_inner())
.take();
run_isolated("外部 Waker 隔离析构", move || drop(downstream));
}
}
pub(crate) async fn shield_future<F: Future>(future: F) -> F::Output {
let mut future = std::pin::pin!(future);
std::future::poll_fn(move |context| {
let downstream = match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
context.waker().clone()
})) {
Ok(waker) => waker,
Err(payload) => {
run_isolated("外部 Waker 克隆", move || drop(payload));
Waker::noop().clone()
}
};
let shield = Waker::from(ShieldWake::new(downstream));
let mut context = Context::from_waker(&shield);
match future.as_mut().poll(&mut context) {
Poll::Ready(output) => Poll::Ready(output),
Poll::Pending => Poll::Pending,
}
})
.await
}
fn default_partitions() -> usize {
let parallelism = std::thread::available_parallelism()
.map(std::num::NonZeroUsize::get)
.unwrap_or(1);
normalize_partitions(parallelism.saturating_mul(2))
}
fn normalize_partitions(partitions: usize) -> usize {
partitions
.max(1)
.checked_next_power_of_two()
.unwrap_or(65_536)
.min(65_536)
}