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        // `try_update` is newer than our Rust 1.89 minimum.
250        #[allow(deprecated)]
251        let Ok(id) =
252            NEXT_JOB.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |id| id.checked_add(1))
253        else {
254            return Err(SubmitError::IdExhausted(work));
255        };
256        let handle = JobHandle {
257            id: JobId(id),
258            cancellation: Cancellation {
259                cancelled: Arc::new(AtomicBool::new(false)),
260                stopping: Arc::clone(&self.shared.stopping),
261            },
262        };
263        state.queued.push_back(Job {
264            handle: handle.clone(),
265            work: Box::new(work),
266        });
267        state.outstanding += 1;
268        drop(state);
269        self.shared.available.notify_one();
270        Ok(handle)
271    }
272
273    /// Receives one completion without waiting, releasing one capacity slot.
274    /// Cancelled payloads are dropped before returning, including cancellation
275    /// after the worker finished. Cancellation after receipt cannot revoke data.
276    pub fn try_recv(&self) -> Option<Completion<R>> {
277        let finished = {
278            let mut state = self.shared.lock();
279            let finished = state.completed.pop_front()?;
280            state.outstanding -= 1;
281            finished
282        };
283        let mut completion = finished.completion;
284        if finished.cancellation.is_cancelled() {
285            completion.outcome = JobOutcome::Cancelled;
286        }
287        Some(completion)
288    }
289
290    /// Drops queued/completed work, signals running jobs, and joins workers.
291    /// Idempotent. Running jobs must cooperate or finish before this returns.
292    /// If the pool's last owner is dropped by its own job, that worker exits
293    /// after the job returns instead of attempting to join itself.
294    pub fn shutdown(&mut self) {
295        self.shared.stopping.store(true, Ordering::Release);
296        let discarded = {
297            let mut state = self.shared.lock();
298            state.closed = true;
299            state.outstanding = 0;
300            (
301                std::mem::take(&mut state.queued),
302                std::mem::take(&mut state.completed),
303            )
304        };
305        self.shared.available.notify_all();
306        // Captured inputs/results can have arbitrary destructors. Drop them
307        // outside the mutex so reentrant cleanup cannot deadlock the pool.
308        drop(discarded);
309        for worker in self.workers.drain(..) {
310            if worker.thread().id() != thread::current().id() {
311                let _ = worker.join();
312            }
313            // A last owner dropped by its own job cannot join itself. Its
314            // worker exits as soon as that job returns, holding Shared alive.
315        }
316    }
317}
318
319impl<R: Send + 'static> Drop for JobPool<R> {
320    fn drop(&mut self) {
321        self.shutdown();
322    }
323}
324
325fn worker_loop<R: Send + 'static>(shared: Arc<Shared<R>>) {
326    loop {
327        let job = {
328            let mut state = shared.lock();
329            loop {
330                if state.closed {
331                    return;
332                }
333                if let Some(job) = state.queued.pop_front() {
334                    break job;
335                }
336                state = shared
337                    .available
338                    .wait(state)
339                    .unwrap_or_else(|poisoned| poisoned.into_inner());
340            }
341        };
342        let Job { handle, work } = job;
343        let cancellation = handle.cancellation;
344        let outcome = match catch_unwind(AssertUnwindSafe(|| {
345            if cancellation.is_cancelled() {
346                // Cancellation still runs captured inputs' destructors. Keep
347                // that cleanup inside the same panic boundary as execution.
348                drop(work);
349                JobOutcome::Cancelled
350            } else {
351                JobOutcome::Ready(work(cancellation.clone()))
352            }
353        })) {
354            Ok(outcome) => outcome,
355            Err(payload) => {
356                // panic_any payloads can themselves panic when dropped. Catch
357                // cleanup too, so a recovered job cannot terminate its worker.
358                if let Err(nested) = catch_unwind(AssertUnwindSafe(|| drop(payload))) {
359                    // A second payload may repeat the same failing destructor;
360                    // retaining it is the only way to guarantee recovery.
361                    std::mem::forget(nested);
362                }
363                JobOutcome::Panicked
364            }
365        };
366        let finished = Finished {
367            cancellation,
368            completion: Completion {
369                id: handle.id,
370                outcome,
371            },
372        };
373        let mut state = shared.lock();
374        if !state.closed {
375            // Total outstanding capacity guarantees completion room. Workers
376            // never wait on a full completion queue during shutdown.
377            state.completed.push_back(finished);
378        } else {
379            drop(state);
380            drop(finished);
381        }
382    }
383}
384
385#[cfg(test)]
386mod tests;