|
| 1 | +//! Cooperative cancellation + progress observation for long-running boolean evaluations. |
| 2 | +//! |
| 3 | +//! Manifold operations are lazy: building a CSG tree is cheap, and the |
| 4 | +//! actual evaluation happens when you query results (e.g., via |
| 5 | +//! [`Manifold::status_with_context`](crate::Manifold::status_with_context), |
| 6 | +//! `num_tri`, mesh extraction, etc.). An [`ExecutionContext`] lets you |
| 7 | +//! observe an in-flight evaluation from another thread and ask it to stop |
| 8 | +//! early. |
| 9 | +//! |
| 10 | +//! Cancellation is **sticky** (once cancelled, stays cancelled) and granular |
| 11 | +//! per-boolean (the upstream kernel checks the cancel flag at boolean |
| 12 | +//! boundaries; it doesn't interrupt a single boolean mid-flight). Progress |
| 13 | +//! is reported as a fraction in `[0.0, 1.0]`. |
| 14 | +//! |
| 15 | +//! The C API documents the underlying `ExecutionContext` as safe to read |
| 16 | +//! and write from any thread, so [`ExecutionContext`] is `Send` + `Sync` |
| 17 | +//! and can be wrapped in [`Arc`](std::sync::Arc) to share between the |
| 18 | +//! evaluator thread and a controller/observer thread. |
| 19 | +//! |
| 20 | +//! ```no_run |
| 21 | +//! use std::sync::Arc; |
| 22 | +//! use std::thread; |
| 23 | +//! use std::time::Duration; |
| 24 | +//! use manifold_csg::{ExecutionContext, Manifold}; |
| 25 | +//! |
| 26 | +//! let ctx = Arc::new(ExecutionContext::new()); |
| 27 | +//! let cancel = Arc::clone(&ctx); |
| 28 | +//! |
| 29 | +//! // Cancel the evaluation if it takes longer than 100ms. |
| 30 | +//! thread::spawn(move || { |
| 31 | +//! thread::sleep(Duration::from_millis(100)); |
| 32 | +//! cancel.cancel(); |
| 33 | +//! }); |
| 34 | +//! |
| 35 | +//! let result = Manifold::cube(1.0, 1.0, 1.0, true); |
| 36 | +//! let status = result.status_with_context(&ctx); |
| 37 | +//! // `status` will be `NoError` for trivial work that finishes before |
| 38 | +//! // cancel fires; for a heavy boolean tree it would surface cancellation. |
| 39 | +//! # let _ = status; |
| 40 | +//! ``` |
| 41 | +//! |
| 42 | +//! Available since manifold3d's `5f95a3a` master commit (post-v3.4.1). |
| 43 | +
|
| 44 | +use manifold_csg_sys::{ |
| 45 | + ManifoldExecutionContext, manifold_alloc_execution_context, manifold_delete_execution_context, |
| 46 | + manifold_execution_context, manifold_execution_context_cancel, |
| 47 | + manifold_execution_context_cancelled, manifold_execution_context_progress, |
| 48 | +}; |
| 49 | + |
| 50 | +/// Observes progress and allows cooperative cancellation of long-running |
| 51 | +/// boolean evaluations. See the [module docs](self) for usage. |
| 52 | +pub struct ExecutionContext { |
| 53 | + ptr: *mut ManifoldExecutionContext, |
| 54 | +} |
| 55 | + |
| 56 | +// SAFETY: The C API explicitly documents `ExecutionContext` as safe to |
| 57 | +// read/write from any thread; the upstream C++ implementation |
| 58 | +// synchronizes the cancel flag and progress counter internally. |
| 59 | +unsafe impl Send for ExecutionContext {} |
| 60 | +// SAFETY: Same justification as `Send` — all accessors (`cancel`, |
| 61 | +// `cancelled`, `progress`) are documented thread-safe at the C boundary. |
| 62 | +unsafe impl Sync for ExecutionContext {} |
| 63 | + |
| 64 | +impl ExecutionContext { |
| 65 | + /// Create a fresh, un-cancelled context with zero progress. |
| 66 | + #[must_use] |
| 67 | + pub fn new() -> Self { |
| 68 | + // SAFETY: alloc returns a valid handle; the constructor takes that |
| 69 | + // raw memory and constructs an ExecutionContext into it (returning |
| 70 | + // the same pointer). |
| 71 | + let mem = unsafe { manifold_alloc_execution_context() }; |
| 72 | + // SAFETY: mem is a valid, freshly-allocated handle. |
| 73 | + let ptr = unsafe { manifold_execution_context(mem) }; |
| 74 | + Self { ptr } |
| 75 | + } |
| 76 | + |
| 77 | + /// Request cancellation of any in-flight evaluation observing this |
| 78 | + /// context. Sticky: once called, [`is_cancelled`](Self::is_cancelled) |
| 79 | + /// returns `true` for the rest of the context's lifetime. |
| 80 | + pub fn cancel(&self) { |
| 81 | + // SAFETY: self.ptr is a valid handle for the lifetime of self; |
| 82 | + // upstream documents thread-safe access. |
| 83 | + unsafe { manifold_execution_context_cancel(self.ptr) }; |
| 84 | + } |
| 85 | + |
| 86 | + /// Returns `true` if [`cancel`](Self::cancel) has been called. |
| 87 | + #[must_use] |
| 88 | + pub fn is_cancelled(&self) -> bool { |
| 89 | + // SAFETY: self.ptr is a valid handle; upstream documents thread-safe access. |
| 90 | + unsafe { manifold_execution_context_cancelled(self.ptr) != 0 } |
| 91 | + } |
| 92 | + |
| 93 | + /// Progress of an in-flight evaluation as a fraction in `[0.0, 1.0]`. |
| 94 | + /// Reads `0.0` before any evaluation has started and `1.0` after one |
| 95 | + /// has finished. |
| 96 | + #[must_use] |
| 97 | + pub fn progress(&self) -> f64 { |
| 98 | + // SAFETY: self.ptr is a valid handle; upstream documents thread-safe access. |
| 99 | + unsafe { manifold_execution_context_progress(self.ptr) } |
| 100 | + } |
| 101 | + |
| 102 | + /// Raw pointer for FFI calls that take an `ExecutionContext`. Crate-local |
| 103 | + /// so the safe wrapper retains exclusive control of the lifetime. |
| 104 | + pub(crate) fn as_ptr(&self) -> *mut ManifoldExecutionContext { |
| 105 | + self.ptr |
| 106 | + } |
| 107 | +} |
| 108 | + |
| 109 | +impl Default for ExecutionContext { |
| 110 | + fn default() -> Self { |
| 111 | + Self::new() |
| 112 | + } |
| 113 | +} |
| 114 | + |
| 115 | +impl Drop for ExecutionContext { |
| 116 | + fn drop(&mut self) { |
| 117 | + if !self.ptr.is_null() { |
| 118 | + // SAFETY: ptr was returned by alloc + construct; not freed since. |
| 119 | + unsafe { manifold_delete_execution_context(self.ptr) }; |
| 120 | + self.ptr = std::ptr::null_mut(); |
| 121 | + } |
| 122 | + } |
| 123 | +} |
0 commit comments