Skip to main content

rayengine_core/
jobs.rs

1//! Optional bounded CPU jobs. Native GPU resources remain on their owning thread.
2//!
3//! Capacity counts queued, running, and unconsumed completed jobs together.
4//! Submissions never wait for room. Cancellation is cooperative; shutdown drops
5//! queued work, signals running work, and joins workers without requiring the
6//! caller to drain completions. Jobs must check cancellation if they may run
7//! for a long time. A job that ignores it can delay shutdown indefinitely.
8
9use std::{
10    collections::VecDeque,
11    fmt,
12    panic::{AssertUnwindSafe, catch_unwind},
13    sync::{
14        Arc, Condvar, Mutex, MutexGuard,
15        atomic::{AtomicBool, AtomicU64, Ordering},
16    },
17    thread::{self, JoinHandle},
18};
19
20static NEXT_JOB: AtomicU64 = AtomicU64::new(0);
21
22/// Process-unique job identity. IDs are never reused, including across pools.
23#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
24pub struct JobId(u64);
25
26/// Cooperative cancellation signal supplied to a running CPU job.
27#[derive(Clone, Debug)]
28pub struct Cancellation {
29    cancelled: Arc<AtomicBool>,
30    stopping: Arc<AtomicBool>,
31}
32
33impl Cancellation {
34    /// Whether this job was cancelled or its pool is shutting down.
35    pub fn is_cancelled(&self) -> bool {
36        self.cancelled.load(Ordering::Acquire) || self.stopping.load(Ordering::Acquire)
37    }
38}
39
40/// Identity and cancellation handle. Dropping a handle does not cancel its job.
41#[derive(Clone, Debug)]
42pub struct JobHandle {
43    id: JobId,
44    cancellation: Cancellation,
45}
46
47impl JobHandle {
48    /// Identity used to match a completion with the current game request.
49    pub fn id(&self) -> JobId {
50        self.id
51    }
52
53    /// Signals cancellation; does not preempt running Rust code.
54    pub fn cancel(&self) {
55        self.cancellation.cancelled.store(true, Ordering::Release);
56    }
57
58    /// Whether cancellation or pool shutdown has been signalled.
59    pub fn is_cancelled(&self) -> bool {
60        self.cancellation.is_cancelled()
61    }
62
63    /// Whether this completion belongs to a still-current, uncancelled request.
64    /// Store the newest handle in game state and reject older completions here.
65    pub fn accepts<R>(&self, completion: &Completion<R>) -> bool {
66        self.id == completion.id && !self.is_cancelled()
67    }
68}
69
70/// Outcome of one CPU job. Job panics do not terminate a worker.
71#[derive(Debug)]
72pub enum JobOutcome<R> {
73    /// Job returned a CPU payload.
74    Ready(R),
75    /// Job was cancelled before its completion was received.
76    Cancelled,
77    /// Job panicked. The normal panic hook still runs.
78    Panicked,
79}
80
81/// Completion received in finish order, rather than submission order.
82#[derive(Debug)]
83pub struct Completion<R> {
84    /// Identity of the request that produced this completion.
85    pub id: JobId,
86    /// CPU result or cancellation/panic outcome.
87    pub outcome: JobOutcome<R>,
88}
89
90/// Rejected submission, preserving the closure and its captured inputs for retry.
91pub enum SubmitError<F> {
92    /// Queued, running, and completed work already fills the configured capacity.
93    Full(F),
94    /// The pool has shut down.
95    Stopped(F),
96    /// The process exhausted the job ID space; identities cannot safely wrap.
97    IdExhausted(F),
98}
99
100impl<F> SubmitError<F> {
101    /// Recovers the unexecuted closure, including all captured inputs.
102    pub fn into_inner(self) -> F {
103        match self {
104            Self::Full(work) | Self::Stopped(work) | Self::IdExhausted(work) => work,
105        }
106    }
107}
108
109impl<F> fmt::Debug for SubmitError<F> {
110    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
111        f.write_str(match self {
112            Self::Full(_) => "Full",
113            Self::Stopped(_) => "Stopped",
114            Self::IdExhausted(_) => "IdExhausted",
115        })
116    }
117}
118
119impl<F> fmt::Display for SubmitError<F> {
120    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
121        fmt::Debug::fmt(self, f)
122    }
123}
124
125impl<F> std::error::Error for SubmitError<F> {}
126
127/// Invalid pool settings or a failure to create a worker thread.
128#[derive(Debug)]
129pub enum JobPoolError {
130    /// Worker count and outstanding capacity must both be positive.
131    InvalidConfig,
132    /// The operating system rejected thread creation.
133    Spawn(std::io::Error),
134}
135
136impl fmt::Display for JobPoolError {
137    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
138        match self {
139            Self::InvalidConfig => f.write_str("workers and capacity must be positive"),
140            Self::Spawn(error) => write!(f, "worker creation failed: {error}"),
141        }
142    }
143}
144
145impl std::error::Error for JobPoolError {
146    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
147        match self {
148            Self::Spawn(error) => Some(error),
149            _ => None,
150        }
151    }
152}
153
154type Work<R> = Box<dyn FnOnce(Cancellation) -> R + Send + 'static>;
155struct Job<R> {
156    handle: JobHandle,
157    work: Work<R>,
158}
159struct Finished<R> {
160    cancellation: Cancellation,
161    completion: Completion<R>,
162}
163struct State<R> {
164    queued: VecDeque<Job<R>>,
165    completed: VecDeque<Finished<R>>,
166    outstanding: usize,
167    closed: bool,
168}
169struct Shared<R> {
170    state: Mutex<State<R>>,
171    available: Condvar,
172    stopping: Arc<AtomicBool>,
173}
174
175impl<R> Shared<R> {
176    fn lock(&self) -> MutexGuard<'_, State<R>> {
177        self.state
178            .lock()
179            .unwrap_or_else(|poisoned| poisoned.into_inner())
180    }
181}
182
183/// Fixed workers with one bound on all outstanding CPU work/results.
184///
185/// `R` and closures must be `Send + 'static`. Capacity bounds job/result counts,
186/// not payload bytes; game code must bound its own inputs/results too. Polling
187/// releases a slot. Unconsumed cancelled completions still occupy slots until
188/// received, so cancellation cannot silently grow the completion queue.
189pub struct JobPool<R: Send + 'static> {
190    shared: Arc<Shared<R>>,
191    workers: Vec<JoinHandle<()>>,
192    capacity: usize,
193}
194
195impl<R: Send + 'static> JobPool<R> {
196    /// Starts `workers` threads and permits at most `capacity` outstanding jobs.
197    pub fn new(workers: usize, capacity: usize) -> Result<Self, JobPoolError> {
198        if workers == 0 || capacity == 0 {
199            return Err(JobPoolError::InvalidConfig);
200        }
201        let shared = Arc::new(Shared {
202            state: Mutex::new(State {
203                queued: VecDeque::new(),
204                completed: VecDeque::new(),
205                outstanding: 0,
206                closed: false,
207            }),
208            available: Condvar::new(),
209            stopping: Arc::new(AtomicBool::new(false)),
210        });
211        let mut pool = Self {
212            shared,
213            workers: Vec::new(),
214            capacity,
215        };
216        for index in 0..workers {
217            let shared = Arc::clone(&pool.shared);
218            let worker = thread::Builder::new()
219                .name(format!("rayengine-job-{index}"))
220                .spawn(move || worker_loop(shared))
221                .map_err(JobPoolError::Spawn)?;
222            pool.workers.push(worker);
223        }
224        Ok(pool)
225    }
226
227    /// Bound shared by queued, running, and unconsumed completed jobs.
228    pub fn capacity(&self) -> usize {
229        self.capacity
230    }
231
232    /// Current outstanding count. This is a momentary snapshot with multiple callers.
233    pub fn pending(&self) -> usize {
234        self.shared.lock().outstanding
235    }
236
237    /// Attempts submission without waiting for capacity. Errors retain `work`.
238    pub fn try_submit<F>(&self, work: F) -> Result<JobHandle, SubmitError<F>>
239    where
240        F: FnOnce(Cancellation) -> R + Send + 'static,
241    {
242        let mut state = self.shared.lock();
243        if state.closed {
244            return Err(SubmitError::Stopped(work));
245        }
246        if state.outstanding == self.capacity {
247            return Err(SubmitError::Full(work));
248        }
249        let Ok(id) =
250            NEXT_JOB.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |id| id.checked_add(1))
251        else {
252            return Err(SubmitError::IdExhausted(work));
253        };
254        let handle = JobHandle {
255            id: JobId(id),
256            cancellation: Cancellation {
257                cancelled: Arc::new(AtomicBool::new(false)),
258                stopping: Arc::clone(&self.shared.stopping),
259            },
260        };
261        state.queued.push_back(Job {
262            handle: handle.clone(),
263            work: Box::new(work),
264        });
265        state.outstanding += 1;
266        drop(state);
267        self.shared.available.notify_one();
268        Ok(handle)
269    }
270
271    /// Receives one completion without waiting, releasing one capacity slot.
272    /// Cancelled payloads are dropped before returning, including cancellation
273    /// after the worker finished. Cancellation after receipt cannot revoke data.
274    pub fn try_recv(&self) -> Option<Completion<R>> {
275        let finished = {
276            let mut state = self.shared.lock();
277            let finished = state.completed.pop_front()?;
278            state.outstanding -= 1;
279            finished
280        };
281        let mut completion = finished.completion;
282        if finished.cancellation.is_cancelled() {
283            completion.outcome = JobOutcome::Cancelled;
284        }
285        Some(completion)
286    }
287
288    /// Drops queued/completed work, signals running jobs, and joins workers.
289    /// Idempotent. Running jobs must cooperate or finish before this returns.
290    /// If the pool's last owner is dropped by its own job, that worker exits
291    /// after the job returns instead of attempting to join itself.
292    pub fn shutdown(&mut self) {
293        self.shared.stopping.store(true, Ordering::Release);
294        let discarded = {
295            let mut state = self.shared.lock();
296            state.closed = true;
297            state.outstanding = 0;
298            (
299                std::mem::take(&mut state.queued),
300                std::mem::take(&mut state.completed),
301            )
302        };
303        self.shared.available.notify_all();
304        // Captured inputs/results can have arbitrary destructors. Drop them
305        // outside the mutex so reentrant cleanup cannot deadlock the pool.
306        drop(discarded);
307        for worker in self.workers.drain(..) {
308            if worker.thread().id() != thread::current().id() {
309                let _ = worker.join();
310            }
311            // A last owner dropped by its own job cannot join itself. Its
312            // worker exits as soon as that job returns, holding Shared alive.
313        }
314    }
315}
316
317impl<R: Send + 'static> Drop for JobPool<R> {
318    fn drop(&mut self) {
319        self.shutdown();
320    }
321}
322
323fn worker_loop<R: Send + 'static>(shared: Arc<Shared<R>>) {
324    loop {
325        let job = {
326            let mut state = shared.lock();
327            loop {
328                if state.closed {
329                    return;
330                }
331                if let Some(job) = state.queued.pop_front() {
332                    break job;
333                }
334                state = shared
335                    .available
336                    .wait(state)
337                    .unwrap_or_else(|poisoned| poisoned.into_inner());
338            }
339        };
340        let Job { handle, work } = job;
341        let cancellation = handle.cancellation;
342        let outcome = match catch_unwind(AssertUnwindSafe(|| {
343            if cancellation.is_cancelled() {
344                // Cancellation still runs captured inputs' destructors. Keep
345                // that cleanup inside the same panic boundary as execution.
346                drop(work);
347                JobOutcome::Cancelled
348            } else {
349                JobOutcome::Ready(work(cancellation.clone()))
350            }
351        })) {
352            Ok(outcome) => outcome,
353            Err(payload) => {
354                // panic_any payloads can themselves panic when dropped. Catch
355                // cleanup too, so a recovered job cannot terminate its worker.
356                if let Err(nested) = catch_unwind(AssertUnwindSafe(|| drop(payload))) {
357                    // A second payload may repeat the same failing destructor;
358                    // retaining it is the only way to guarantee recovery.
359                    std::mem::forget(nested);
360                }
361                JobOutcome::Panicked
362            }
363        };
364        let finished = Finished {
365            cancellation,
366            completion: Completion {
367                id: handle.id,
368                outcome,
369            },
370        };
371        let mut state = shared.lock();
372        if !state.closed {
373            // Total outstanding capacity guarantees completion room. Workers
374            // never wait on a full completion queue during shutdown.
375            state.completed.push_back(finished);
376        } else {
377            drop(state);
378            drop(finished);
379        }
380    }
381}
382
383#[cfg(test)]
384mod tests;