Add ExecutionContext for boolean progress + cancellation

Progress towards #971. Introduces ExecutionContext for observing progress
and requesting cancellation of long-running boolean evaluations via a new
Status(ExecutionContext&) overload; no other public API is affected.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zmerlynn

bindings/c/conv.cpp

@@ -116,6 +116,9 @@ ManifoldError to_c(manifold::Manifold::Error error) {
     case Manifold::Error::InvalidTangents:
       e = MANIFOLD_INVALID_TANGENTS;
       break;
+    case Manifold::Error::Cancelled:
+      e = MANIFOLD_CANCELLED;
+      break;
   };
   return e;
 }

bindings/c/include/manifold/types.h

@@ -119,6 +119,7 @@ typedef enum ManifoldError {
   MANIFOLD_INVALID_CONSTRUCTION,
   MANIFOLD_RESULT_TOO_LARGE,
   MANIFOLD_INVALID_TANGENTS,
+  MANIFOLD_CANCELLED,
 } ManifoldError;
 
 typedef enum ManifoldFillRule {

bindings/python/manifold3d.cpp

@@ -731,7 +731,8 @@ NB_MODULE(manifold3d, m) {
       .value("FaceIDWrongLength", Manifold::Error::FaceIDWrongLength)
       .value("InvalidConstruction", Manifold::Error::InvalidConstruction)
       .value("ResultTooLarge", Manifold::Error::ResultTooLarge)
-      .value("InvalidTangents", Manifold::Error::InvalidTangents);
+      .value("InvalidTangents", Manifold::Error::InvalidTangents)
+      .value("Cancelled", Manifold::Error::Cancelled);
 
   nb::enum_<CrossSection::FillRule>(m, "FillRule")
       .value("EvenOdd", CrossSection::FillRule::EvenOdd,

bindings/wasm/bindings.cpp

@@ -83,7 +83,8 @@ EMSCRIPTEN_BINDINGS(whatever) {
       .value("FaceIDWrongLength", Manifold::Error::FaceIDWrongLength)
       .value("InvalidConstruction", Manifold::Error::InvalidConstruction)
       .value("ResultTooLarge", Manifold::Error::ResultTooLarge)
-      .value("InvalidTangents", Manifold::Error::InvalidTangents);
+      .value("InvalidTangents", Manifold::Error::InvalidTangents)
+      .value("Cancelled", Manifold::Error::Cancelled);
 
   enum_<CrossSection::FillRule>("fillrule")
       .value("EvenOdd", CrossSection::FillRule::EvenOdd)

bindings/wasm/manifold-global-types.d.ts

@@ -120,4 +120,4 @@ export type ErrorStatus = 'NoError'|'NonFiniteVertex'|'NotManifold'|
     'VertexOutOfBounds'|'PropertiesWrongLength'|'MissingPositionProperties'|
     'MergeVectorsDifferentLengths'|'MergeIndexOutOfBounds'|
     'TransformWrongLength'|'RunIndexWrongLength'|'FaceIDWrongLength'|
-    'InvalidConstruction'|'ResultTooLarge'|'InvalidTangents';
+    'InvalidConstruction'|'ResultTooLarge'|'InvalidTangents'|'Cancelled';

include/manifold/common.h

@@ -15,6 +15,7 @@
 #pragma once
 #include <cmath>
 #include <limits>
+#include <memory>
 #include <vector>
 
 #ifdef MANIFOLD_DEBUG
@@ -170,6 +171,55 @@ struct RayHit {
   vec3 normal = vec3(0.0);
 };
 
+/**
+ * @brief Observe and control a long-running Manifold evaluation.
+ *
+ * Pass to Manifold::Status(ctx) to observe progress and optionally request
+ * cancellation of the evaluation. Safe to read/write from any thread.
+ *
+ * Copyable and movable: copies share the same underlying state via a
+ * shared_ptr, so one thread can evaluate while another holds a copy and
+ * observes Progress() or calls Cancel(). Use a separate context per
+ * evaluation; passing the same context (or a copy of it) to two
+ * concurrent Status(ctx) calls produces meaningless progress values
+ * because both calls reset and mutate the same counters.
+ *
+ * Cancellation is permanent for a Manifold: once requested and detected,
+ * the Manifold's status becomes Error::Cancelled and stays Cancelled. To
+ * retry, construct a new Manifold. A context, however, is reusable: each
+ * Status(ctx) call resets the progress counters, but it does NOT clear
+ * the cancel flag — once Cancel() has been called on a context, every
+ * subsequent evaluation with that context (or any copy of it) will
+ * short-circuit to Error::Cancelled. Construct a fresh context to make a
+ * new evaluation cancellable independently.
+ *
+ * Cancellation granularity is currently per-boolean-operation; a single
+ * large boolean may run to completion before the flag is checked again.
+ * This may improve in future versions.
+ */
+class ExecutionContext {
+ public:
+  ExecutionContext();
+  ~ExecutionContext();
+  ExecutionContext(const ExecutionContext&);
+  ExecutionContext(ExecutionContext&&) noexcept;
+  ExecutionContext& operator=(const ExecutionContext&);
+  ExecutionContext& operator=(ExecutionContext&&) noexcept;
+
+  /// Request cancellation. Can be called from any thread. Idempotent.
+  void Cancel();
+  /// Has cancellation been requested?
+  bool Cancelled() const;
+  /// Normalized progress in [0, 1]. Returns 0 before any work has been
+  /// scheduled. Monotonically increases during evaluation.
+  double Progress() const;
+
+  /// @internal Opaque implementation. Defined in src/execution_impl.h;
+  /// accessible only to internal code that includes that header.
+  struct Impl;
+  std::shared_ptr<Impl> impl_;
+};
+
 /**
  * @brief Axis-aligned 3D box, primarily for bounding.
  */

include/manifold/manifold.h

@@ -371,13 +371,15 @@ class Manifold {
     InvalidConstruction,
     ResultTooLarge,
     InvalidTangents,
+    Cancelled,
   };
 
   /** @name Information
    *  Details of the manifold
    */
   ///@{
   Error Status() const;
+  Error Status(ExecutionContext& ctx) const;
   bool IsEmpty() const;
   size_t NumVert() const;
   size_t NumEdge() const;
@@ -539,7 +541,7 @@ class Manifold {
   mutable std::shared_ptr<CsgNode> pNode_;
 
   std::shared_ptr<CsgNode> LoadPNode() const;
-  CsgLeafNode& GetCsgLeafNode() const;
+  CsgLeafNode& GetCsgLeafNode(ExecutionContext::Impl* ctx = nullptr) const;
 };
 /** @} */
 
@@ -582,6 +584,8 @@ inline std::string ToString(const Manifold::Error& error) {
       return "Result Too Large";
     case Manifold::Error::InvalidTangents:
       return "Invalid Tangents";
+    case Manifold::Error::Cancelled:
+      return "Cancelled";
     default:
       return "Unknown Error";
   };

src/CMakeLists.txt

@@ -19,6 +19,7 @@ set(
   constructors.cpp
   csg_tree.cpp
   edge_op.cpp
+  execution_impl.cpp
   face_op.cpp
   impl.cpp
   manifold.cpp
@@ -40,6 +41,7 @@ set(
   boolean3.h
   collider.h
   csg_tree.h
+  execution_impl.h
   hashtable.h
   impl.h
   iters.h

src/csg_tree.cpp

@@ -20,6 +20,7 @@
 
 #include "boolean3.h"
 #include "csg_tree.h"
+#include "execution_impl.h"
 #include "impl.h"
 #include "mesh_fixes.h"
 #include "parallel.h"
@@ -96,7 +97,8 @@ std::shared_ptr<const Manifold::Impl> CsgLeafNode::GetImpl() const {
   return pImpl_;
 }
 
-std::shared_ptr<CsgLeafNode> CsgLeafNode::ToLeafNode() const {
+std::shared_ptr<CsgLeafNode> CsgLeafNode::ToLeafNode(
+    ExecutionContext::Impl*) const {
   return std::make_shared<CsgLeafNode>(*this);
 }
 
@@ -139,8 +141,19 @@ std::shared_ptr<CsgLeafNode> ImplToLeaf(Manifold::Impl&& impl) {
       std::make_shared<Manifold::Impl>(std::move(impl)));
 }
 
+// Build a leaf with the given error status — used to short-circuit boolean
+// evaluation on cancellation.
+std::shared_ptr<CsgLeafNode> ErrorLeaf(Manifold::Error err) {
+  Manifold::Impl impl;
+  impl.status_ = err;
+  return ImplToLeaf(std::move(impl));
+}
+
 std::shared_ptr<CsgLeafNode> SimpleBoolean(const Manifold::Impl& a,
-                                           const Manifold::Impl& b, OpType op) {
+                                           const Manifold::Impl& b, OpType op,
+                                           ExecutionContext::Impl* ctx) {
+  if (ctx && ctx->cancel.load(std::memory_order_relaxed))
+    return ErrorLeaf(Manifold::Error::Cancelled);
 #ifdef MANIFOLD_DEBUG
   auto dump = [&]() {
     dump_lock.lock();
@@ -170,6 +183,7 @@ std::shared_ptr<CsgLeafNode> SimpleBoolean(const Manifold::Impl& a,
       dump_lock.unlock();
       throw logicErr("self intersection detected");
     }
+    if (ctx) ctx->doneBooleans.fetch_add(1, std::memory_order_relaxed);
     return ImplToLeaf(std::move(impl));
   } catch (logicErr& err) {
     dump();
@@ -179,7 +193,9 @@ std::shared_ptr<CsgLeafNode> SimpleBoolean(const Manifold::Impl& a,
     throw err;
   }
 #else
-  return ImplToLeaf(Boolean3(a, b, op).Result(op));
+  auto leaf = ImplToLeaf(Boolean3(a, b, op).Result(op));
+  if (ctx) ctx->doneBooleans.fetch_add(1, std::memory_order_relaxed);
+  return leaf;
 #endif
 }
 
@@ -374,7 +390,8 @@ std::shared_ptr<CsgLeafNode> CsgLeafNode::Compose(
  * operation. Only supports union and intersection.
  */
 std::shared_ptr<CsgLeafNode> BatchBoolean(
-    OpType operation, std::vector<std::shared_ptr<CsgLeafNode>>& results) {
+    OpType operation, std::vector<std::shared_ptr<CsgLeafNode>>& results,
+    ExecutionContext::Impl* ctx) {
   ZoneScoped;
   DEBUG_ASSERT(operation != OpType::Subtract, logicErr,
                "BatchBoolean doesn't support Difference.");
@@ -383,7 +400,7 @@ std::shared_ptr<CsgLeafNode> BatchBoolean(
   if (results.size() == 1) return results.front();
   if (results.size() == 2)
     return SimpleBoolean(*results[0]->GetImpl(), *results[1]->GetImpl(),
-                         operation);
+                         operation, ctx);
   // apply boolean operations starting from smaller meshes
   // the assumption is that boolean operations on smaller meshes is faster,
   // due to less data being copied and processed
@@ -397,6 +414,8 @@ std::shared_ptr<CsgLeafNode> BatchBoolean(
   for (int i = 0; i < 4; i++) parallelTmp.push_back(nullptr);
 #endif
   while (results.size() > 1) {
+    if (ctx && ctx->cancel.load(std::memory_order_relaxed))
+      return ErrorLeaf(Manifold::Error::Cancelled);
     for (size_t i = 0; i < 4 && results.size() > 1; i++) {
       std::pop_heap(results.begin(), results.end(), cmpFn);
       auto a = std::move(results.back());
@@ -406,10 +425,11 @@ std::shared_ptr<CsgLeafNode> BatchBoolean(
       results.pop_back();
 #if MANIFOLD_PAR == 1
       group.run([&, i, a, b]() {
-        parallelTmp[i] = SimpleBoolean(*a->GetImpl(), *b->GetImpl(), operation);
+        parallelTmp[i] =
+            SimpleBoolean(*a->GetImpl(), *b->GetImpl(), operation, ctx);
       });
 #else
-      auto result = SimpleBoolean(*a->GetImpl(), *b->GetImpl(), operation);
+      auto result = SimpleBoolean(*a->GetImpl(), *b->GetImpl(), operation, ctx);
       tmp.push_back(result);
 #endif
     }
@@ -432,7 +452,8 @@ std::shared_ptr<CsgLeafNode> BatchBoolean(
  * possible.
  */
 std::shared_ptr<CsgLeafNode> BatchUnion(
-    std::vector<std::shared_ptr<CsgLeafNode>>& children) {
+    std::vector<std::shared_ptr<CsgLeafNode>>& children,
+    ExecutionContext::Impl* ctx) {
   ZoneScoped;
   // INVARIANT: children_ is a vector of leaf nodes
   // this kMaxUnionSize is a heuristic to avoid the pairwise disjoint check
@@ -443,6 +464,8 @@ std::shared_ptr<CsgLeafNode> BatchUnion(
   DEBUG_ASSERT(!children.empty(), logicErr,
                "BatchUnion should not have empty children");
   while (children.size() > 1) {
+    if (ctx && ctx->cancel.load(std::memory_order_relaxed))
+      return ErrorLeaf(Manifold::Error::Cancelled);
     const size_t start = (children.size() > kMaxUnionSize)
                              ? (children.size() - kMaxUnionSize)
                              : 0;
@@ -478,11 +501,16 @@ std::shared_ptr<CsgLeafNode> BatchUnion(
           tmp.push_back(children[start + j]);
         }
         impls.push_back(CsgLeafNode::Compose(tmp));
+        // Compose absorbs set.size() leaves into 1 leaf, which is
+        // set.size() - 1 leaf-reductions toward the final result.
+        if (ctx)
+          ctx->doneBooleans.fetch_add(static_cast<int>(set.size() - 1),
+                                      std::memory_order_relaxed);
       }
     }
 
     children.erase(children.begin() + start, children.end());
-    children.push_back(BatchBoolean(OpType::Add, impls));
+    children.push_back(BatchBoolean(OpType::Add, impls, ctx));
     // move it to the front as we process from the back, and the newly added
     // child should be quite complicated
     std::swap(children.front(), children.back());
@@ -563,7 +591,8 @@ struct CsgStackFrame {
         op_node(op_node) {}
 };
 
-std::shared_ptr<CsgLeafNode> CsgOpNode::ToLeafNode() const {
+std::shared_ptr<CsgLeafNode> CsgOpNode::ToLeafNode(
+    ExecutionContext::Impl* ctx) const {
   ZoneScoped;
   if (cache_ != nullptr) return cache_;
 
@@ -666,31 +695,37 @@ std::shared_ptr<CsgLeafNode> CsgOpNode::ToLeafNode() const {
   //     destination->push_back(node->cache_->Transform(transform));
   // }
   while (!stack.empty()) {
+    if (ctx && ctx->cancel.load(std::memory_order_relaxed)) {
+      cache_ = ErrorLeaf(Manifold::Error::Cancelled);
+      return cache_;
+    }
     std::shared_ptr<CsgStackFrame> frame = stack.back();
     auto impl = frame->op_node->impl_.GetGuard();
     if (frame->finalize) {
       if (!frame->op_node->cache_) {
         switch (frame->op_node->op_) {
           case OpType::Add:
-            *impl = {BatchUnion(frame->positive_children)};
+            *impl = {BatchUnion(frame->positive_children, ctx)};
             break;
           case OpType::Intersect: {
-            *impl = {BatchBoolean(OpType::Intersect, frame->positive_children)};
+            *impl = {
+                BatchBoolean(OpType::Intersect, frame->positive_children, ctx)};
             break;
           };
           case OpType::Subtract:
             if (frame->positive_children.empty()) {
               // nothing to subtract from, so the result is empty.
               *impl = {std::make_shared<CsgLeafNode>()};
             } else {
-              auto positive = BatchUnion(frame->positive_children);
+              auto positive = BatchUnion(frame->positive_children, ctx);
               if (frame->negative_children.empty()) {
                 // nothing to subtract, result equal to the LHS.
                 *impl = {frame->positive_children[0]};
               } else {
-                auto negative = BatchUnion(frame->negative_children);
+                auto negative = BatchUnion(frame->negative_children, ctx);
                 *impl = {SimpleBoolean(*positive->GetImpl(),
-                                       *negative->GetImpl(), OpType::Subtract)};
+                                       *negative->GetImpl(), OpType::Subtract,
+                                       ctx)};
               }
             }
             break;
@@ -761,4 +796,14 @@ CsgNodeType CsgOpNode::GetNodeType() const {
   return CsgNodeType::Leaf;
 }
 
+size_t CsgOpNode::NumLeaves() const {
+  // An already-evaluated CsgOpNode counts as a single leaf for the purposes
+  // of estimating remaining boolean work.
+  if (cache_ != nullptr) return 1;
+  auto impl = impl_.GetGuard();
+  size_t total = 0;
+  for (const auto& child : *impl) total += child->NumLeaves();
+  return total;
+}
+
 }  // namespace manifold