856f865cf98d
jobs.rs
//! Background jobs: long commands run on a worker thread, report progress and can be cancelled
//! (#210).
//!
//! A command opts in by doing its heavy work through [`run`] (or [`edit_job`] for a plain document
//! edit). The work closure gets a [`JobCtx`] (progress plus a cancellation flag) and runs against
//! a snapshot: documents are copy-on-write, so cloning one is O(layers). Its result is applied on
//! the UI thread as one undo step, through the same path as [`Session::execute`], so the journal,
//! history, damage and post-command hooks all behave as for a synchronous command.
//!
//! - [`Session::execute`] runs everything inline, as before: tests, the CLI and scripts see no
//! difference.
//! - [`Session::start`] runs a job-capable command on a worker thread and returns its
//! [`JobId`]; [`Session::poll_jobs`] (called every frame by the UI) applies finished jobs.
//! On wasm `start` runs inline (same API, written once).
//! - Work that is written as [`StepWork`] (Place) also runs where there are no threads: with
//! [`Session::set_cooperative_jobs`] (the web build's default) [`run_stepped`] registers the job
//! without a worker, and [`Session::poll_jobs`] runs one slice of it, about 8 ms, per call. The
//! UI stays responsive between slices, and the result is the same as on a worker.
//! - [`Session::cancel_job`] sets the flag; the algorithms check it per tile, row band or
//! iteration, and the result is discarded. The document is never touched by a worker.
//! - A job with an effect outside the session (a save replacing its file) calls
//! [`JobCtx::commit`] right before it. From then on it can't be cancelled: every cancel
//! path ([`Session::try_cancel_job`], [`Session::cancel_all_jobs`], closing its document,
//! `jobs.cancel`) leaves it running and says so ([`CancelRefused::Committing`]), so nothing
//! reports a job as cancelled after its effect has happened.
//! - A panic in the worker becomes an error; the document is unchanged.
//! - While a job runs on a document, commands that would edit that document are disabled with a
//! message naming the job (queries and document-independent commands still run).
use std::any::Any;
use std::sync::atomic::{AtomicU8, AtomicU32, Ordering};
use std::sync::{Arc, Condvar, Mutex, PoisonError, Weak};
use photocraft_doc::{DocId, Document, LayerId};
use photocraft_raster::Interrupt;
use serde::Serialize;
use serde_json::{Value, json};
use crate::{EngineError, Result, Session};
const MAX_BACKGROUND_JOBS: usize = 16;
type Authorization = fn(&str, &Value) -> Result<()>;
thread_local! {
// Smart-filter rendering has no Session argument. Carry the requesting session's gate
// through synchronous rendering and explicitly reinstall it on background workers.
static RENDER_AUTHORIZATION: std::cell::Cell<Option<Authorization>> = const { std::cell::Cell::new(None) };
}
pub(crate) struct AuthorizationScope(Option<Authorization>);
impl AuthorizationScope {
fn enter(gate: Option<Authorization>) -> Self {
Self(RENDER_AUTHORIZATION.with(|current| current.replace(gate.or(current.get()))))
}
}
impl Drop for AuthorizationScope {
fn drop(&mut self) {
RENDER_AUTHORIZATION.with(|current| current.set(self.0));
}
}
/// [`AuthorizationScope`] entered with `gate` (or the one already installed, so trusted work on
/// this thread keeps ambient paths usable). [`Session::edit`] and the job paths use this to carry
/// the requesting session's authority into every smart-object re-render.
pub(crate) fn render_authorization_scope(gate: Option<Authorization>) -> AuthorizationScope {
AuthorizationScope::enter(gate)
}
/// Recheck a stored filter's command and parameters before evaluating it or using its cache.
pub(crate) fn authorize_render_command(id: &str, params: &Value) -> Result<()> {
match RENDER_AUTHORIZATION.with(std::cell::Cell::get) {
Some(gate) => gate(id, params),
None => Ok(()),
}
}
/// Whether the work on this thread is done for an untrusted session (a gate is installed).
pub(crate) fn authorization_installed() -> bool {
RENDER_AUTHORIZATION.with(std::cell::Cell::get).is_some()
}
/// Identifies one background job for the session's lifetime.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, serde::Deserialize)]
pub struct JobId(pub u64);
/// What a job's work closure sees: report progress, check for cancellation. Cheap to clone; all
/// clones share the same state.
#[derive(Clone, Default)]
pub struct JobCtx {
shared: Arc<Shared>,
}
#[derive(Default)]
struct Shared {
/// [`CANCEL_REQUESTED`], [`WORK_FINISHED`] and [`COMMITTED`] bits. One atomic orders a cancel
/// against [`JobCtx::commit`] and against the worker finishing, so exactly one of them wins.
state: AtomicU8,
/// `f32` bits of the progress fraction. Non-negative floats order like their bits, so
/// `fetch_max` keeps progress monotonic even with several reporting threads.
progress: AtomicU32,
message: Mutex<String>,
batch: Mutex<BatchInterrupt>,
batch_decision: Condvar,
batch_preview: Mutex<Option<BatchPreview>>,
batch_preview_generation: std::sync::atomic::AtomicU64,
}
/// The current folder Batch input, published as an immutable snapshot for the desktop canvas.
/// It is never added to the live session and cannot receive commands or saves.
#[derive(Clone, Debug)]
pub struct BatchPreview {
pub path: String,
pub document: Arc<Document>,
pub generation: u64,
}
/// The desktop Batch Esc handshake. The worker alone enters `Waiting` at a pre-save
/// checkpoint; only the UI supplies a decision. Programmatic cancellation uses the separate
/// atomic flag above and wakes a waiting worker without asking a question.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
enum BatchInterrupt {
#[default]
Processing,
Requested,
Waiting,
Continue,
Stop,
Saving,
/// Every input has been handled; Esc is no longer accepted.
Closed,
}
/// Cancelled before it committed.
const CANCEL_REQUESTED: u8 = 1;
/// The worker has sent its result; a Batch no longer accepts a cancel.
const WORK_FINISHED: u8 = 2;
/// Past [`JobCtx::commit`]: the job runs to the end and can no longer be cancelled.
const COMMITTED: u8 = 4;
impl std::fmt::Debug for JobCtx {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("JobCtx").field("progress", &self.fraction()).field("cancelled", &self.cancelled()).finish()
}
}
impl JobCtx {
pub fn new() -> Self {
Self::default()
}
/// Report progress in `0.0..=1.0` with a short status (empty keeps the previous one).
/// Progress never goes backwards: a lower value than already reported is ignored.
pub fn progress(&self, fraction: f32, message: &str) {
if fraction.is_finite() {
self.shared.progress.fetch_max(fraction.clamp(0.0, 1.0).to_bits(), Ordering::Relaxed);
}
if !message.is_empty() {
let mut m = self.shared.message.lock().unwrap_or_else(PoisonError::into_inner);
if *m != message {
message.clone_into(&mut m);
}
}
}
/// Has the job been cancelled? Long loops check this and stop early.
pub fn cancelled(&self) -> bool {
self.shared.state.load(Ordering::Acquire) & CANCEL_REQUESTED != 0
}
/// Ask the job to stop (idempotent). Does nothing once it has [committed](Self::commit).
pub fn cancel(&self) {
let _ = self.try_cancel();
}
/// Cancel unless the job has [committed](Self::commit): true if it is cancelled (now or
/// before), false if it is past its point of no return and will run to the end.
pub fn try_cancel(&self) -> bool {
let r = self.shared.state.try_update(Ordering::AcqRel, Ordering::Acquire, |state| (state & COMMITTED == 0).then_some(state | CANCEL_REQUESTED));
if r.is_ok() {
self.wake_batch_worker();
}
r.is_ok()
}
/// The job's point of no return, for work with an effect outside the session (a save calls
/// it right before replacing the file). `Ok`: no cancel can stop the job any more; it must
/// run to the end, and its result is applied even if its document was closed meanwhile.
/// `Err(Cancelled)`: it was cancelled first, and nothing may be done.
pub fn commit(&self) -> Result<()> {
self.check()?;
self.shared
.state
.try_update(Ordering::AcqRel, Ordering::Acquire, |state| (state & CANCEL_REQUESTED == 0).then_some(state | COMMITTED))
.map(|_| ())
.map_err(|_| EngineError::Cancelled)
}
/// Has the job passed [`Self::commit`]?
pub fn committed(&self) -> bool {
self.shared.state.load(Ordering::Acquire) & COMMITTED != 0
}
/// Wake a Batch worker waiting for the Esc decision, so it sees a cancel.
fn wake_batch_worker(&self) {
let _phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
self.shared.batch_decision.notify_all();
}
/// Accept a cancellation only while the worker has not finished its result. One atomic state
/// orders a late cancel against completion, including the interval before the UI polls.
fn cancel_if_running(&self) -> bool {
let accepted = self
.shared
.state
.try_update(Ordering::AcqRel, Ordering::Acquire, |state| {
(state & (CANCEL_REQUESTED | WORK_FINISHED | COMMITTED) == 0).then_some(state | CANCEL_REQUESTED)
})
.is_ok();
if accepted {
self.wake_batch_worker();
}
accepted
}
/// Request the reference application's Esc decision for an interactive Batch. A save that
/// passed its final write checkpoint cannot be interrupted; the caller may try the next
/// input. This does not affect the direct `jobs.cancel` automation API.
pub fn request_batch_interrupt(&self) -> bool {
if self.cancelled() || self.shared.state.load(Ordering::Acquire) & WORK_FINISHED != 0 {
return false;
}
let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
if *phase != BatchInterrupt::Processing {
return false;
}
*phase = BatchInterrupt::Requested;
true
}
/// The worker has stopped before writing the current input and awaits Continue or Stop.
pub fn batch_waiting_for_decision(&self) -> bool {
*self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner) == BatchInterrupt::Waiting
}
/// Answer a waiting interactive Batch question. `continue_next` skips the current input.
pub fn decide_batch_interrupt(&self, continue_next: bool) -> bool {
let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
if *phase != BatchInterrupt::Waiting {
return false;
}
*phase = if continue_next { BatchInterrupt::Continue } else { BatchInterrupt::Stop };
self.shared.batch_decision.notify_all();
true
}
/// Whether an action should stop before its next step because Esc was requested.
pub fn batch_interrupt_requested(&self) -> bool {
*self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner) == BatchInterrupt::Requested
}
/// Move an accepted Esc request to the question at a worker checkpoint.
pub fn batch_take_interrupt(&self) -> bool {
let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
if *phase != BatchInterrupt::Requested {
return *phase == BatchInterrupt::Waiting;
}
*phase = BatchInterrupt::Waiting;
true
}
/// Wait for the UI decision without polling. Closing the session or `jobs.cancel` wakes this
/// worker; the caller then reports its partial result.
pub fn batch_wait_for_decision(&self) -> bool {
let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
while *phase == BatchInterrupt::Waiting && !self.cancelled() {
phase = self.shared.batch_decision.wait(phase).unwrap_or_else(PoisonError::into_inner);
}
let continue_next = *phase == BatchInterrupt::Continue && !self.cancelled();
*phase = BatchInterrupt::Processing;
continue_next
}
/// Mark the start of an input's output write. The same lock orders Esc against this
/// checkpoint: a requested interruption never writes that input.
pub(crate) fn batch_before_write(&self) -> Result<()> {
self.check()?;
let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
if *phase == BatchInterrupt::Requested {
*phase = BatchInterrupt::Waiting;
return Err(EngineError::Cancelled);
}
if self.cancelled() {
return Err(EngineError::Cancelled);
}
*phase = BatchInterrupt::Saving;
Ok(())
}
/// The worker has passed its last checkpoint. A pending request is dropped (nothing is left to
/// interrupt) and later requests return false.
pub(crate) fn batch_close_interrupts(&self) {
*self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner) = BatchInterrupt::Closed;
self.shared.batch_decision.notify_all();
}
/// A completed write allows Esc on the next input.
pub(crate) fn batch_after_write(&self) {
let mut phase = self.shared.batch.lock().unwrap_or_else(PoisonError::into_inner);
if *phase == BatchInterrupt::Saving {
*phase = BatchInterrupt::Processing;
}
}
/// Publish the current input's document after it opens or an action step changes it.
pub fn publish_batch_preview(&self, path: &str, document: Option<Arc<Document>>) {
let mut preview = self.shared.batch_preview.lock().unwrap_or_else(PoisonError::into_inner);
if preview.as_ref().zip(document.as_ref()).is_some_and(|(shown, next)| shown.path == path && Arc::ptr_eq(&shown.document, next))
|| (preview.is_none() && document.is_none())
{
return;
}
let generation = self.shared.batch_preview_generation.fetch_add(1, Ordering::AcqRel).wrapping_add(1);
*preview = document.map(|document| BatchPreview { path: path.to_string(), document, generation });
}
/// A snapshot for rendering, if the current input still has a document open.
pub fn batch_preview(&self) -> Option<BatchPreview> {
self.shared.batch_preview.lock().unwrap_or_else(PoisonError::into_inner).clone()
}
#[cfg(not(target_arch = "wasm32"))]
fn finish_work(&self) {
self.shared.state.fetch_or(WORK_FINISHED, Ordering::Release);
}
/// `Err(Cancelled)` once cancelled, for `?` between stages.
pub fn check(&self) -> Result<()> {
if self.cancelled() { Err(EngineError::Cancelled) } else { Ok(()) }
}
/// Progress reported so far (`0.0..=1.0`).
pub fn fraction(&self) -> f32 {
f32::from_bits(self.shared.progress.load(Ordering::Relaxed))
}
/// The latest status message.
pub fn message(&self) -> String {
self.shared.message.lock().unwrap_or_else(PoisonError::into_inner).clone()
}
/// Run `f` with an algorithm-level [`Interrupt`] whose progress maps onto `lo..hi` of this
/// job (with `message`) and whose cancellation is this job's.
pub fn stage<R>(&self, lo: f32, hi: f32, message: &str, f: impl FnOnce(&Interrupt) -> R) -> R {
self.progress(lo, message);
let cancel = || self.cancelled();
let progress = |p: f32| self.progress(lo + (hi - lo) * p, "");
f(&Interrupt::new(&cancel, &progress))
}
}
/// Why [`Session::try_cancel_job`] left a job running.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum CancelRefused {
/// No such job is running.
NotRunning,
/// A print belongs to the system print queue once it has started.
Printing,
/// Past its [commit](JobCtx::commit): it is writing its result (a save replacing its file)
/// and will report its real outcome when it ends.
Committing,
/// A Batch already asked to stop, or past its last input: it ends on its own and reports
/// the outputs it wrote.
Finishing,
}
impl CancelRefused {
/// The scripting name (`jobs.cancel`'s `notCancelled[].reason`).
pub fn as_str(self) -> &'static str {
match self {
Self::NotRunning => "notRunning",
Self::Printing => "printing",
Self::Committing => "committing",
Self::Finishing => "finishing",
}
}
}
/// What a cancel of several jobs did ([`Session::cancel_all_jobs`]).
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct CancelReport {
pub cancelled: Vec<JobId>,
/// The jobs left running, and why.
pub refused: Vec<(JobId, CancelRefused)>,
}
impl CancelReport {
/// The `jobs.cancel` reply: `{cancelled: n}`, with `notCancelled: [{job, reason}]` when a
/// job was left running.
pub fn to_json(&self) -> Value {
let mut v = json!({"cancelled": self.cancelled.len()});
if !self.refused.is_empty() {
v["notCancelled"] = self.refused.iter().map(|(id, why)| json!({"job": id.0, "reason": why.as_str()})).collect();
}
v
}
}
/// Final state of a job.
#[derive(Clone, Debug, PartialEq)]
pub enum JobOutcome {
/// Applied; the command's result.
Done(Value),
/// Failed (including a panic in the worker); the document is unchanged.
Failed(String),
/// Cancelled; the result (if any) was discarded and the document is unchanged.
Cancelled,
}
/// A job that has ended, as reported by [`Session::poll_jobs`].
#[derive(Clone, Debug, PartialEq)]
pub struct JobEvent {
pub id: JobId,
pub command: String,
pub label: String,
pub document: Option<DocId>,
pub outcome: JobOutcome,
/// The typed failure behind a failed `outcome`: a hard-budget refusal keeps its
/// name/required/limit, an approval request keeps its limits, a changed source keeps its
/// kind. `None` for done, cancelled and panics without a typed error. Not serialized;
/// `JobInfo::error` remains the display string on the wire.
pub error: Option<EngineError>,
}
/// A job's state for the UI, the control channel and MCP (`jobs.list`).
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct JobInfo {
pub id: JobId,
pub command: String,
/// Shown in the progress UI ("Gaussian Blur").
pub label: String,
/// The document the job edits (and locks), if any.
pub document: Option<DocId>,
/// `running`, `done`, `failed` or `cancelled`.
pub state: &'static str,
pub progress: f32,
pub message: String,
pub elapsed_ms: f64,
/// The command's result (done), including partial outputs from a cancelled batch.
#[serde(skip_serializing_if = "Option::is_none")]
pub result: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub error: Option<String>,
/// The typed failure behind `error`, for callers in this process (not serialized: the wire
/// form is the message, as before).
#[serde(skip)]
pub error_kind: Option<EngineError>,
}
type Payload = Box<dyn Any + Send>;
type Apply = Box<dyn FnOnce(&mut Session, Payload) -> Result<Value> + Send>;
/// Milliseconds on the monotonic clock since some fixed point (`web_time` reads the browser's on wasm).
fn now_ms() -> f64 {
static START: std::sync::OnceLock<web_time::Instant> = std::sync::OnceLock::new();
START.get_or_init(web_time::Instant::now).elapsed().as_secs_f64() * 1000.0
}
/// How much of a frame [`Session::poll_jobs`] gives a [`StepWork`] job, unless
/// [`Session::set_job_step_budget`] says otherwise.
const STEP_BUDGET: std::time::Duration = std::time::Duration::from_millis(8);
/// A deadline no job reaches, for running [`StepWork`] to the end in one go.
fn no_deadline() -> web_time::Instant {
let now = web_time::Instant::now();
now.checked_add(std::time::Duration::from_secs(1 << 30)).unwrap_or(now)
}
/// Work a job does a slice at a time (see [`run_stepped`]).
pub trait StepWork<T>: Send + 'static {
/// Does some of the work and returns `Ok(None)` for "not finished, call again", or the result.
/// It should return soon after `deadline` passes (checking it between units of work), but
/// always does at least one unit, so that calling it again makes progress. `ctx` reports
/// progress and tells of cancellation, as for a worker.
fn step(&mut self, ctx: &JobCtx, deadline: web_time::Instant) -> Result<Option<T>>;
}
/// Runs `work` to the end, as a worker does.
fn drive<T>(mut work: impl StepWork<T>, ctx: &JobCtx) -> Result<T> {
loop {
ctx.check()?;
if let Some(t) = work.step(ctx, no_deadline())? {
return Ok(t);
}
}
}
/// Runs one slice of a cooperative job: `Ok(None)` when it has more to do.
type Stepper = Box<dyn FnMut(&JobCtx, web_time::Instant) -> Result<Option<Payload>> + Send>;
struct Running {
id: JobId,
command: String,
label: String,
params: Value,
journal: bool,
/// The take active at dispatch, including strokes started with tool recording off.
started_in_take: Option<u64>,
/// The take eligible to receive this job's step under the mode at dispatch.
recorded_by: Option<u64>,
/// The request that started the job ran under an automation gate (`Session::authorize`, set
/// by `dispatch`). Applied, its step marks the recording that owns it as automation's,
/// whoever polls the job then (`actions_cmds::note_step_origin`).
automation: bool,
pre_selected: Option<Vec<LayerId>>,
before: crate::actions_record::Before,
doc: Option<DocId>,
/// The document as the job saw it: applying fails if it was edited meanwhile.
snapshot: Option<Weak<Document>>,
ctx: JobCtx,
started_ms: f64,
coalesce: Option<String>,
color_restrict: Option<crate::color_channels::Restriction>,
filter_mask_layer: Option<LayerId>,
/// The document's layer selection when the job started: applying targets it, not whatever
/// got selected meanwhile (a Type click does that without editing the document, #7366).
layers: Option<LayerSelection>,
/// Where the worker thread sends its result. A cooperative job has none: [`Session::poll_jobs`]
/// runs its `stepper` instead.
rx: Option<std::sync::mpsc::Receiver<Result<Payload>>>,
stepper: Option<Stepper>,
apply: Option<Apply>,
#[cfg(not(target_arch = "wasm32"))]
handle: Option<std::thread::JoinHandle<()>>,
}
/// A document's active layer, selected layers and selection anchor.
#[derive(Clone, PartialEq)]
struct LayerSelection {
active: Option<LayerId>,
selected: Vec<LayerId>,
anchor: Option<LayerId>,
}
impl LayerSelection {
fn of(st: &crate::DocState) -> Self {
Self { active: st.active_layer, selected: st.selected_layers.clone(), anchor: st.layer_anchor }
}
fn set(self, st: &mut crate::DocState) {
st.active_layer = self.active;
st.selected_layers = self.selected;
st.layer_anchor = self.anchor;
crate::channel_cmds::fix_view(st);
}
}
impl Running {
/// Runs a slice of a cooperative job until `deadline`: `Ok(None)` when it has more to do.
/// A cancelled job ends with `Err(Cancelled)` before doing more.
fn step(&mut self, deadline: web_time::Instant) -> Result<Option<Payload>> {
self.ctx.check()?;
match self.stepper.as_mut() {
Some(stepper) => stepper(&self.ctx, deadline),
None => Err(EngineError::Other(format!("`{}` has nothing to run", self.label))),
}
}
fn info(&self) -> JobInfo {
JobInfo {
id: self.id,
command: self.command.clone(),
label: self.label.clone(),
document: self.doc,
state: "running",
progress: self.ctx.fraction(),
message: self.ctx.message(),
elapsed_ms: now_ms() - self.started_ms,
result: None,
error: None,
error_kind: None,
}
}
}
/// A cancelled job's worker that may still be unwinding.
#[cfg(not(target_arch = "wasm32"))]
struct Draining {
handle: std::thread::JoinHandle<()>,
doc: Option<DocId>,
/// Its document closed: the worker still holds that document's snapshot, so the scratch
/// pool is released again once it exits (the release at close came too early, #10479).
release: bool,
}
#[cfg(not(target_arch = "wasm32"))]
fn reap_draining(draining: &mut Vec<Draining>) -> bool {
let mut release = false;
draining.retain(|d| {
let done = d.handle.is_finished();
release |= done && d.release;
!done
});
release
}
/// The session's job table (see the module docs).
pub struct Jobs {
next: u64,
/// Set while [`Session::start`] runs a command: [`run`] spawns instead of running inline.
spawn: bool,
/// The job a command registered while `spawn` was set (picked up by `start`).
pending: Option<Running>,
running: Vec<Running>,
/// Ended jobs not yet collected by [`Session::poll_jobs`].
events: Vec<JobEvent>,
/// The last few ended jobs, for `jobs.list`.
recent: Vec<JobInfo>,
/// Workers of cancelled jobs that may still be unwinding (native).
#[cfg(not(target_arch = "wasm32"))]
draining: Vec<Draining>,
/// The context inline job work runs under (see [`Session::set_inline_job_ctx`]).
inline: Option<JobCtx>,
/// No worker threads: [`StepWork`] jobs are stepped by [`Session::poll_jobs`], everything else
/// runs inline. On for wasm; see [`Session::set_cooperative_jobs`].
cooperative: bool,
/// How long [`Session::poll_jobs`] runs a cooperative job per call.
step_budget: std::time::Duration,
}
// Derivable on a desktop, where `cooperative` starts off; wasm starts it on.
#[allow(clippy::derivable_impls)]
impl Default for Jobs {
/// No jobs, spawning off; a session steps its jobs itself (cooperative) on wasm only.
fn default() -> Self {
Self {
next: 0,
spawn: false,
pending: None,
running: Vec::new(),
events: Vec::new(),
recent: Vec::new(),
#[cfg(not(target_arch = "wasm32"))]
draining: Vec::new(),
inline: None,
cooperative: cfg!(target_arch = "wasm32"),
step_budget: STEP_BUDGET,
}
}
}
impl Jobs {
/// Does a job started now run on a worker thread? (Not inline, and not stepped on this thread.)
fn threaded(&self) -> bool {
self.spawn && !self.cooperative && !cfg!(target_arch = "wasm32")
}
}
const RECENT: usize = 16;
impl Drop for Jobs {
fn drop(&mut self) {
// Workers own snapshots only; stop them so they don't burn CPU for a closed session.
for r in self.running.iter().chain(self.pending.iter()) {
r.ctx.cancel();
}
}
}
impl std::fmt::Debug for Jobs {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Jobs").field("running", &self.running.len()).finish()
}
}
/// How [`Session::start`] ended.
#[derive(Clone, Debug, PartialEq)]
pub enum Started {
/// The command ran to completion inline (it isn't a job, or this is wasm).
Done(Value),
/// The command is running in the background.
Job(JobId),
}
/// Commands that never edit the active document, allowed while a job runs on it.
fn independent_of_document(id: &str) -> bool {
const PREFIXES: &[&str] = &["jobs.", "tools.", "view.", "window.", "help.", "brush.presets.", "gradient.presets."];
const IDS: &[&str] = &["file.new", "file.close", "file.closeAll", "edit.preferences", "edit.colorSettings", "edit.keyboardShortcuts", "edit.menus"];
PREFIXES.iter().any(|p| id.starts_with(p)) || IDS.contains(&id)
}
/// Imports the file at `path`, taking its identity from the very handle it decodes.
///
/// `expected` is the identity approved for this file, if any. It is checked against the opened
/// handle before decoding and again when the memory preflight pauses for approval, so the
/// document opened is the approved file even if the path is replaced meanwhile. `opened` receives
/// the handle's identity as soon as it is known, including when the import stops for approval.
#[cfg(not(target_arch = "wasm32"))]
fn import_path(
name: &str,
path: &str,
opts: &photocraft_io::ImportOptions,
expected: Option<&SourceFingerprint>,
ctl: &photocraft_raster::Interrupt,
opened: &mut Option<photocraft_io::FileIdentity>,
) -> std::result::Result<(photocraft_io::ImportResult, bool), photocraft_io::IoError> {
let expected = match expected {
None => None,
Some(SourceFingerprint::Path { identity, .. }) => Some(identity),
Some(SourceFingerprint::Bytes { .. }) => return Err(photocraft_io::IoError::SourceChanged),
};
// Bounded reads, and a clear error for a file larger than memory (#375); a PSD/PSB is
// streamed from the open file instead of being read whole.
photocraft_io::import_file_for_open_verified(name, std::path::Path::new(path), expected, opts, ctl, opened)
}
#[cfg(target_arch = "wasm32")]
fn import_path(
_: &str,
path: &str,
_: &photocraft_io::ImportOptions,
_: Option<&SourceFingerprint>,
_: &photocraft_raster::Interrupt,
_: &mut Option<photocraft_io::FileIdentity>,
) -> std::result::Result<(photocraft_io::ImportResult, bool), photocraft_io::IoError> {
Err(photocraft_io::IoError::Read(format!("cannot open paths on the web: {path}")))
}
/// Run a job-capable command's heavy part. `work` runs on a worker thread when the command was
/// started with [`Session::start`] (inline otherwise, and always on wasm); `apply` then runs on
/// the calling thread with its output and returns the command's result. With `lock_document`,
/// the active document is locked against other edits while the job runs, and applying fails if
/// it was edited anyway.
///
/// `work` must only read what it captured (clone the document `Arc` first): it never sees the
/// session.
pub fn run<T: Send + 'static>(
s: &mut Session,
label: &str,
lock_document: bool,
work: impl FnOnce(&JobCtx) -> Result<T> + Send + 'static,
apply: impl FnOnce(&mut Session, T) -> Result<Value> + Send + 'static,
) -> Result<Value> {
// The job reads the active document it captured; only that document's pixels gate it.
let source = s.active().map(|d| d.doc.clone());
let work = move |ctx: &JobCtx| -> Result<T> {
photocraft_compose::discard_unreadable_pixel_caches();
let health = || source.as_deref().map_or(Ok(()), photocraft_doc::Document::scratch_health).map_err(EngineError::Other);
health()?;
let generation = photocraft_raster::spill::read_error_generation();
let value = work(ctx)?;
photocraft_raster::spill::check_since(generation).map_err(EngineError::Other)?;
health()?;
Ok(value)
};
let authorization = s.authorize.or_else(|| RENDER_AUTHORIZATION.with(std::cell::Cell::get));
let _authorization = AuthorizationScope::enter(authorization);
// The job's document: stored paths it follows are resolved against it on any thread.
let document = s.active().and_then(|d| d.path.as_deref()).map(std::path::PathBuf::from);
let _document = crate::doc_path::scope(document.as_deref());
if !s.jobs.threaded() {
let t = work(&s.jobs.inline.clone().unwrap_or_default())?;
return apply(s, t);
}
let mut job = new_job(s, label, lock_document, authorization, document.clone(), apply)?;
let (tx, rx) = std::sync::mpsc::channel::<Result<Payload>>();
#[cfg(not(target_arch = "wasm32"))]
{
let wctx = job.ctx.clone();
let label_w = label.to_string();
// The work closure is moved into the thread. If spawning fails (thread limits), there is
// no way to get it back, so the error is reported instead.
let spawned = std::thread::Builder::new().name(format!("photocraft-job-{}", job.id.0)).spawn(move || {
let _authorization = AuthorizationScope::enter(authorization);
let _document = crate::doc_path::scope(document.as_deref());
let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| work(&wctx).map(|t| Box::new(t) as Payload)))
.unwrap_or_else(|_| Err(EngineError::Other(format!("`{label_w}` failed with an internal error (logged); the document is unchanged"))));
wctx.finish_work();
// The receiver is gone when the job was cancelled: nothing to report.
let _ = tx.send(r);
});
job.handle = Some(spawned.map_err(|e| EngineError::Other(format!("could not start a background job: {e}")))?);
}
#[cfg(target_arch = "wasm32")]
{
// Unreachable (wasm runs inline above); keep the types used.
drop((work, tx));
}
job.rx = Some(rx);
let id = job.id;
s.jobs.pending = Some(job);
Ok(json!({"job": id.0}))
}
/// [`run`] for work done a slice at a time ([`StepWork`]): where the session has no worker threads
/// ([`Session::set_cooperative_jobs`], the web build) the job runs on the UI thread, a slice of
/// about 8 ms per [`Session::poll_jobs`], so the window keeps repainting meanwhile. Elsewhere it
/// is [`run`] with `work` driven to the end: on a worker thread for [`Session::start`], inline for
/// [`Session::execute`]. The result is the same either way.
pub fn run_stepped<T: Send + 'static>(
s: &mut Session,
label: &str,
lock_document: bool,
work: impl StepWork<T>,
apply: impl FnOnce(&mut Session, T) -> Result<Value> + Send + 'static,
) -> Result<Value> {
if !(s.jobs.spawn && s.jobs.cooperative) {
return run(s, label, lock_document, move |ctx| drive(work, ctx), apply);
}
let authorization = s.authorize.or_else(|| RENDER_AUTHORIZATION.with(std::cell::Cell::get));
let document = s.active().and_then(|d| d.path.as_deref()).map(std::path::PathBuf::from);
let mut job = new_job(s, label, lock_document, authorization, document.clone(), apply)?;
let (label_w, mut work) = (label.to_string(), work);
// The slices run under the requesting session's authority and document, as a worker would.
job.stepper = Some(Box::new(move |ctx, deadline| {
let _authorization = AuthorizationScope::enter(authorization);
let _document = crate::doc_path::scope(document.as_deref());
std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| work.step(ctx, deadline)))
.unwrap_or_else(|_| Err(EngineError::Other(format!("`{label_w}` failed with an internal error (logged); the document is unchanged"))))
.map(|done| done.map(|t| Box::new(t) as Payload))
}));
let id = job.id;
s.jobs.pending = Some(job);
Ok(json!({"job": id.0}))
}
/// A job for [`run`] and [`run_stepped`] to start, without its worker.
fn new_job<T: Send + 'static>(
s: &mut Session,
label: &str,
lock_document: bool,
authorization: Option<Authorization>,
document: Option<std::path::PathBuf>,
apply: impl FnOnce(&mut Session, T) -> Result<Value> + Send + 'static,
) -> Result<Running> {
if s.jobs.pending.is_some() {
return Err(EngineError::Other(format!("`{label}` started a second background job in one command")));
}
#[cfg(not(target_arch = "wasm32"))]
s.reap_draining_jobs();
let admitted = s.jobs.running.len();
#[cfg(not(target_arch = "wasm32"))]
let admitted = admitted.saturating_add(s.jobs.draining.len());
if admitted >= MAX_BACKGROUND_JOBS {
return Err(EngineError::Other(format!(
"too many background jobs ({MAX_BACKGROUND_JOBS}); wait for a running or cancelling job to finish before starting another"
)));
}
let (doc, snapshot, layers) = match (lock_document, s.active()) {
(true, Some(st)) => (Some(st.doc.id), Some(Arc::downgrade(&st.doc)), Some(LayerSelection::of(st))),
(true, None) => return Err(EngineError::NoDocument),
(false, _) => (None, None, None),
};
let erased: Apply = Box::new(move |s, any| {
let _authorization = AuthorizationScope::enter(authorization);
let _document = crate::doc_path::scope(document.as_deref());
let t = any.downcast::<T>().map_err(|_| EngineError::Other("internal error: job result type mismatch".into()))?;
apply(s, *t)
});
s.jobs.next = s.jobs.next.checked_add(1).ok_or_else(|| EngineError::Other("background job identifier space exhausted".into()))?;
Ok(Running {
id: JobId(s.jobs.next),
command: String::new(),
label: label.to_string(),
params: Value::Null,
journal: true,
started_in_take: None,
recorded_by: None,
automation: false,
pre_selected: None,
before: crate::actions_record::Before::capture(s),
doc,
snapshot,
ctx: JobCtx::new(),
started_ms: now_ms(),
coalesce: s.coalesce_request.clone(),
color_restrict: s.color_restrict,
filter_mask_layer: s.filter_mask_layer,
layers,
rx: None,
stepper: None,
apply: Some(erased),
#[cfg(not(target_arch = "wasm32"))]
handle: None,
})
}
/// A document edit whose body is the job: like [`Session::edit`] (one undo step named `label`),
/// but `f` runs on a worker against a copy of the active document when started in the
/// background. `finish` turns `f`'s output into the command's result.
pub fn edit_job<R: Send + 'static>(
s: &mut Session,
label: &str,
f: impl FnOnce(&mut Document, &mut Option<LayerId>, &JobCtx) -> Result<R> + Send + 'static,
finish: impl FnOnce(R) -> Value + Send + 'static,
) -> Result<Value> {
if !s.jobs.threaded() {
// Inline: exactly `Session::edit`, as before jobs existed.
let ctx = s.jobs.inline.clone().unwrap_or_default();
let r = s.edit(label, |doc, active| f(doc, active, &ctx))?;
return Ok(finish(r));
}
let st = s.active().ok_or(EngineError::NoDocument)?;
let (base, active) = (st.doc.clone(), st.active_layer);
let label_owned = label.to_string();
run(
s,
label,
true,
move |ctx| {
let mut doc = (*base).clone();
let mut active = active;
let r = f(&mut doc, &mut active, ctx)?;
Ok((doc, active, r))
},
move |s, (doc, new_active, r)| {
s.edit(&label_owned, move |d, active| {
*d = doc;
*active = new_active;
Ok(())
})?;
Ok(finish(r))
},
)
}
/// Scan every layer surface's content bounds into the shared tile bounds cache, so the first
/// draw of a document opened in the background doesn't do it on the UI thread: GPU planning
/// asks each layer for its bounds, a multi-second scan on a multi-gigabyte PSB (#4024).
/// `check` runs between layers (cancellation).
pub fn warm_layer_bounds(doc: &Document, mut check: impl FnMut() -> Result<()>) -> Result<()> {
let mut pending: Vec<&photocraft_doc::Layer> = doc.layers.iter().collect();
while let Some(layer) = pending.pop() {
check()?;
if let Some(children) = layer.children() {
pending.extend(children);
}
if let Some(surface) = layer.surface() {
photocraft_compose::bounds::content_bounds(surface);
}
}
Ok(())
}
/// Where a background open reads its file from.
#[derive(Clone, Debug)]
pub enum OpenSource {
/// File contents already in memory (web pickers, drops, automation).
Bytes(Arc<Vec<u8>>),
/// A path the worker reads itself (native), so even the read stays off the UI thread.
Path(String),
}
/// The command id open jobs report (there is no engine command: opening is the shell's).
pub const OPEN_JOB: &str = "file.open";
/// The import settings files are opened and placed with.
pub fn import_options(prefs: &crate::prefs::Preferences) -> photocraft_io::ImportOptions {
photocraft_io::ImportOptions {
max_group_depth: prefs.file_handling.rasterize_svg_groups_deeper_than as usize,
demosaic: prefs.raw_defaults.demosaic.method(),
keep_raw: false,
pdf_dpi: prefs.file_handling.pdf_dpi,
pdf_pages: match (prefs.file_handling.pdf_first_page, prefs.file_handling.pdf_last_page) {
(0, 0) => None,
(first, last) => {
let first = first.max(1);
Some((first, if last == 0 { u32::MAX } else { last.max(first) }))
}
},
..Default::default()
}
}
/// Fingerprint verifying that a source has not changed between preflight and approval.
///
/// A path's fingerprint is the [`photocraft_io::FileIdentity`] of an opened handle, never a path
/// stat made before a separate open: the importer takes it from the very handle it decodes
/// (`photocraft_io::import_file_for_open_verified`), so a path replaced or rewritten between
/// the estimate and the approval is refused with [`EngineError::SourceChanged`]. The Unix
/// identity includes the inode change time and nanoseconds, so restoring a modification time
/// cannot hide a same-size rewrite.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum SourceFingerprint {
Bytes { len: usize, identity: usize },
Path { path: String, identity: photocraft_io::FileIdentity },
}
impl SourceFingerprint {
/// Fingerprint of `source`.
///
/// An in-memory source's identity is its shared buffer. A path is inspected here for
/// discovery only; the decode path re-reads its identity from the handle it opens. Fails
/// closed when the identity data cannot be read.
pub fn of(source: &OpenSource) -> Result<Self> {
match source {
OpenSource::Bytes(b) => Ok(SourceFingerprint::Bytes { len: b.len(), identity: Arc::as_ptr(b) as usize }),
OpenSource::Path(p) => {
Ok(Self::path(p.clone(), photocraft_io::FileIdentity::of_path(std::path::Path::new(p)).map_err(|e| EngineError::Other(format!("{p}: {e}")))?))
}
}
}
/// Fingerprint of the file identity read from an opened handle for `path`.
pub fn path(path: String, identity: photocraft_io::FileIdentity) -> Self {
SourceFingerprint::Path { path, identity }
}
/// The handle identity a path fingerprint compares against, if this is one.
pub fn file_identity(&self) -> Option<&photocraft_io::FileIdentity> {
match self {
SourceFingerprint::Path { identity, .. } => Some(identity),
SourceFingerprint::Bytes { .. } => None,
}
}
/// Whether both fingerprints capture the same source identity (and, for a path, the same path).
pub fn matches(&self, other: &Self) -> bool {
self == other
}
/// Re-reads `source`'s fingerprint and compares it with this one; an unreadable source does not match.
pub fn matches_source(&self, source: &OpenSource) -> bool {
match Self::of(source) {
Ok(cur) => self.matches(&cur),
Err(_) => false,
}
}
}
/// A pending high-memory PSD preflight request waiting for user confirmation before pixel decoding.
#[derive(Clone, Debug)]
pub struct PendingPsdPreflight {
pub id: u64,
pub name: String,
pub source: OpenSource,
pub fingerprint: SourceFingerprint,
pub required: u64,
pub soft_limit: u64,
pub hard_limit: u64,
pub available_ram: Option<u64>,
pub confirm_damage: bool,
}
impl Session {
/// A recording mode change must not reclassify an in-flight stroke from this take.
pub(crate) fn tool_stroke_job_running(&self) -> bool {
self.jobs.running.iter().any(|job| job.started_in_take == Some(self.actions.take) && crate::actions_cmds::tool_stroke(&job.command))
}
/// Run the heavy part of inline (not background) job commands under `ctx`, so another thread
/// can cancel them: a live preview whose parameters changed stops its stale computation
/// (`Err(Cancelled)`, the document unchanged) instead of finishing it. `None` restores the
/// default, a context nothing can cancel.
pub fn set_inline_job_ctx(&mut self, ctx: Option<JobCtx>) {
self.jobs.inline = ctx;
}
/// Run a command, in the background when it supports it (see [`jobs`](crate::jobs)). Errors
/// like [`Session::execute`] for unknown, disabled or failing commands.
pub fn start(&mut self, id: &str, params: Value) -> Result<Started> {
let before = self.active_layer_stamp();
let started = self.dispatch(id, params, true);
self.note_layer_change(before);
started
}
pub const MAX_PENDING_PREFLIGHTS: usize = 32;
/// Most bytes of file data pending approvals may keep alive together.
///
/// This is a retention bound for the *sources* of files waiting for an answer, not a pixel
/// budget and not an admission limit: only an [`OpenSource::Bytes`] source holds data (a path
/// streams from its file once opened), the allocation's capacity is charged rather than its
/// contents, and one shared buffer counts once however many preflights refer to it. 1 GiB is
/// chosen conservatively: it is below the 2 GiB web hard
/// product cap, so even a web session that queues several large dropped files cannot spend
/// the whole hard budget on data it has not decoded, and a native session keeps a comparable
/// amount out of the adaptive allowance. A file that would exceed the cap cannot become
/// pending: it is refused with an error instead of being decoded, and the caller can answer
/// or cancel queued prompts and try again, rather than holding an unbounded amount of memory
/// for unanswered prompts. The record count
/// ([`Self::MAX_PENDING_PREFLIGHTS`]) stays as a separate bound, so many small files are
/// bounded too.
pub const MAX_PENDING_PREFLIGHT_BYTES: u64 = 1 << 30;
/// Queues an approval prompt, assigning its id, and enforces both the pending-count and
/// retained-byte limits.
pub fn store_pending_preflight(&mut self, preflight: PendingPsdPreflight) -> Result<u64> {
self.store_pending_preflight_with_limit(preflight, Self::MAX_PENDING_PREFLIGHT_BYTES)
}
/// [`Self::store_pending_preflight`] with an explicit retention cap (tests use a tiny one so
/// the boundary is exercised without holding a gigabyte).
pub(crate) fn store_pending_preflight_with_limit(&mut self, mut preflight: PendingPsdPreflight, byte_limit: u64) -> Result<u64> {
if self.pending_preflights.len() >= Self::MAX_PENDING_PREFLIGHTS {
return Err(EngineError::Other("too many pending high-memory preflights waiting for confirmation".into()));
}
let held = self.pending_preflight_bytes_with(&preflight.source)?;
if held > byte_limit {
return Err(EngineError::Other(format!(
"too much memory is already held by files waiting for a memory approval ({held} bytes, limit {byte_limit}); answer or cancel one of them and try again"
)));
}
loop {
self.next_pending_preflight = self.next_pending_preflight.checked_add(1).unwrap_or(1);
if self.next_pending_preflight != 0 && !self.pending_preflights.iter().any(|p| p.id == self.next_pending_preflight) {
break;
}
}
preflight.id = self.next_pending_preflight;
self.pending_preflights.push(preflight);
Ok(self.next_pending_preflight)
}
/// Bytes held alive by the queued preflights, counting an `Arc<Vec<u8>>` shared by several of
/// them once. Computed from the queue, so approving, cancelling, refusing or clearing always
/// releases the charge; a rejected preflight never adds one.
pub fn pending_preflight_bytes(&self) -> Result<u64> {
Self::retained_source_bytes(self.pending_preflights.iter().map(|p| &p.source))
}
/// [`Self::pending_preflight_bytes`] as if `incoming` were queued too, so accepting it can be
/// checked before the list is changed.
fn pending_preflight_bytes_with(&self, incoming: &OpenSource) -> Result<u64> {
let mut sources: Vec<&OpenSource> = self.pending_preflights.iter().map(|p| &p.source).collect();
sources.push(incoming);
Self::retained_source_bytes(sources)
}
/// Total retained capacity of distinct in-memory sources, counting a shared buffer once.
///
/// Capacity, not length, is charged because a truncated `Vec` keeps its allocation; overflow
/// is an error rather than a wrapped total.
fn retained_source_bytes<'a>(sources: impl IntoIterator<Item = &'a OpenSource>) -> Result<u64> {
let mut seen: Vec<usize> = Vec::new();
let mut total: u64 = 0;
for source in sources {
let OpenSource::Bytes(bytes) = source else { continue };
let identity = Arc::as_ptr(bytes) as usize;
// Distinct live allocations cannot share an address, so identity dedupes clones of
// one buffer without under-counting two different files with equal contents.
if seen.contains(&identity) {
continue;
}
seen.push(identity);
// The allocation is what stays resident, not its contents: a `Vec` that once held a
// large file keeps that capacity after being truncated, so charging `len()` would
// under-count the memory a pending prompt holds. Overflow is an error, never a wrap.
let held = u64::try_from(bytes.capacity()).unwrap_or(u64::MAX);
total = total.checked_add(held).ok_or_else(|| EngineError::Other("held file size overflow while counting pending memory approvals".into()))?;
}
Ok(total)
}
/// Removes and returns the pending preflight with `id`, releasing the source it held.
pub fn take_pending_preflight(&mut self, id: u64) -> Option<PendingPsdPreflight> {
let i = self.pending_preflights.iter().position(|p| p.id == id)?;
Some(self.pending_preflights.remove(i))
}
/// Cancels the pending preflight with `id` by removing it; `None` means no such prompt.
pub fn cancel_pending_preflight(&mut self, id: u64) -> Option<PendingPsdPreflight> {
self.take_pending_preflight(id)
}
/// Drops every pending preflight, releasing all retained source buffers.
pub fn clear_pending_preflights(&mut self) {
self.pending_preflights.clear();
}
/// Starts an open with high-memory approval already granted, on a background worker.
/// `expected_fingerprint`, when given, must still match the decoded source.
pub fn start_open_approved(
&mut self,
name: &str,
source: OpenSource,
confirm_damage: bool,
approved_estimate: Option<u64>,
expected_fingerprint: Option<SourceFingerprint>,
) -> Result<Started> {
self.start_open_approved_with_background(name, source, confirm_damage, approved_estimate, expected_fingerprint, true)
}
/// [`Self::start_open_approved`] with an explicit choice between a background worker and
/// inline work.
pub fn start_open_approved_with_background(
&mut self,
name: &str,
source: OpenSource,
confirm_damage: bool,
approved_estimate: Option<u64>,
expected_fingerprint: Option<SourceFingerprint>,
background: bool,
) -> Result<Started> {
self.start_open_inner(name, source, confirm_damage, true, approved_estimate, expected_fingerprint, background)
}
/// Open a file in the background: read (for a path) and decode on a worker, with progress
/// (per layer for PSD/PSB) and cancellation, then add the document like
/// [`Session::open_document`] (Color Settings policies apply). `name` names the document.
/// The job's result is `{document, docId, name, warnings, color}`; on wasm it runs inline.
/// `document` is the tab index at apply time; resolve `docId` before handling a delayed
/// completion, since earlier handlers may have moved or closed tabs. When
/// Color Settings ask about the file's profile, the document is held back instead and the
/// result is `{held, name, warnings, color}` (`color` the question): take it with
/// [`Session::take_held_open`] once answered.
pub fn start_open(&mut self, name: &str, source: OpenSource) -> Result<Started> {
self.start_open_inner(name, source, false, false, None, None, true)
}
/// Interactive opening: hold a damaged PSD until the user answers a damage
/// confirmation, without changing import or subsequent save behaviour.
/// Headless callers keep using [`Self::start_open`].
pub fn start_open_for_user(&mut self, name: &str, source: OpenSource) -> Result<Started> {
self.start_open_for_user_with_background(name, source, true)
}
/// Interactive open with an explicit background/inline choice: damaged PSD content and
/// high-memory preflights wait for the user instead of opening non-interactively.
pub fn start_open_for_user_with_background(&mut self, name: &str, source: OpenSource, background: bool) -> Result<Started> {
self.start_open_inner(name, source, true, false, None, None, background)
}
/// Place a file's bytes in the background, like `file.placeEmbedded` (`linked`: `file.placeLinked`
/// to that path) for bytes that have no path to read: decode, flatten and fit on a worker, then
/// insert the layer as one undo step when [`Session::poll_jobs`] applies it. `name` names the
/// layer and the file; `params` are the command's (`scale`, `center`, `fit`, `smartObject`).
/// The job's result is the command's: `{layer, frame, scale, bounds, smartObject}`. The active
/// document is locked meanwhile, so this is refused while another job runs on it. On wasm (and
/// in a [cooperative](Session::set_cooperative_jobs) session) it is not a worker's job but
/// one [`Session::poll_jobs`] runs a slice of per call.
pub fn start_place_bytes(&mut self, name: &str, bytes: Vec<u8>, linked: Option<String>, params: Value) -> Result<Started> {
let input = crate::file_cmds::PlaceInput::new(self, name, bytes, linked, ¶ms)?;
let (command, label) = (input.command(), input.job_label());
if let Some(conflict) = self.job_conflict(command, true) {
return Err(EngineError::Other(conflict));
}
let work = crate::file_cmds::PlaceSteps::new(input, self.cooperative_jobs());
self.start_job_stepped(command, json!({"name": name}), &label, true, work, crate::file_cmds::apply_place)
}
/// Decodes a file in a job and optionally holds damaged PSD content for
/// interactive confirmation while leaving headless opens non-interactive.
// Keep the worker and apply closures together with their execution options.
#[allow(clippy::too_many_arguments)]
fn start_open_inner(
&mut self,
name: &str,
source: OpenSource,
confirm_damage: bool,
approve_high_memory: bool,
approved_estimate: Option<u64>,
expected_fingerprint: Option<SourceFingerprint>,
background: bool,
) -> Result<Started> {
let label = format!("Opening {name}");
let name_w = name.to_string();
let name_a = name.to_string();
let mut opts = import_options(self.prefs());
// An interactive raw open keeps its sensor data for the Camera Raw dialog it may show.
opts.keep_raw = confirm_damage && self.prefs().raw_defaults.open_in_camera_raw;
opts.psd_high_memory_approved = approve_high_memory;
opts.psd_approved_estimate = approved_estimate;
let test_memory_scope = photocraft_io::memory::TestMemoryScope::capture();
enum WorkResult {
Decoded(Box<(photocraft_io::ImportResult, bool)>),
PreflightNeeded { required: u64, soft_limit: u64, hard_limit: u64, available_ram: Option<u64>, source: OpenSource, fingerprint: SourceFingerprint },
}
self.start_job_with_spawn(
OPEN_JOB,
json!({"name": name}),
&label,
false,
background,
move |ctx| {
let _test_memory = test_memory_scope.enter();
ctx.progress(0.0, "Reading");
// An in-memory source's identity is its shared buffer, known before decoding. A
// path's identity can only come from the handle the verified import opens, so
// that import compares it against `expected_fingerprint` itself, before reading
// any pixel and again after its memory preflight.
let initial_fingerprint = match &source {
OpenSource::Bytes(_) => Some(SourceFingerprint::of(&source)?),
OpenSource::Path(_) => None,
};
if let Some(expected) = &expected_fingerprint
&& let Some(current) = &initial_fingerprint
&& !expected.matches(current)
{
return Err(EngineError::SourceChanged { name: name_w.clone() });
}
let outcome = match source {
OpenSource::Bytes(bytes) => {
ctx.check()?;
ctx.progress(0.02, "Decoding");
let res = ctx.stage(0.02, 0.95, "Decoding", |ctl| photocraft_io::import_for_open_with(&name_w, &bytes, &opts, ctl));
match res {
Ok(imported) => WorkResult::Decoded(Box::new(imported)),
Err(photocraft_io::IoError::PsdApprovalRequired { required, soft_limit, hard_limit, available_ram }) if confirm_damage => {
// The buffer cannot change while it is decoded, so the identity
// captured before reading is still exact.
let fingerprint = initial_fingerprint.clone().ok_or_else(|| EngineError::Other("missing source identity".into()))?;
WorkResult::PreflightNeeded { required, soft_limit, hard_limit, available_ram, source: OpenSource::Bytes(bytes), fingerprint }
}
Err(photocraft_io::IoError::PsdApprovalRequired { required, soft_limit, hard_limit, available_ram }) => {
return Err(EngineError::PsdApprovalRequired { name: name_w.clone(), required, soft_limit, hard_limit, available_ram });
}
Err(photocraft_io::IoError::Cancelled) => return Err(EngineError::Cancelled),
Err(e) => return Err(crate::error::io_open_error(&name_w, e)),
}
}
OpenSource::Path(p) => {
let mut opened = None;
let res = ctx.stage(0.0, 0.95, "Decoding", |ctl| import_path(&name_w, &p, &opts, expected_fingerprint.as_ref(), ctl, &mut opened));
match res {
Ok(imported) => WorkResult::Decoded(Box::new(imported)),
Err(photocraft_io::IoError::PsdApprovalRequired { required, soft_limit, hard_limit, available_ram }) if confirm_damage => {
// This identity is the one read from the handle that was
// estimated, and the verified import refused a handle that is
// not the approved file or changed while preflighting.
let identity = opened.ok_or_else(|| EngineError::Other(format!("{p}: the file's identity could not be read")))?;
let fingerprint = SourceFingerprint::path(p.clone(), identity);
WorkResult::PreflightNeeded { required, soft_limit, hard_limit, available_ram, source: OpenSource::Path(p), fingerprint }
}
Err(photocraft_io::IoError::PsdApprovalRequired { required, soft_limit, hard_limit, available_ram }) => {
return Err(EngineError::PsdApprovalRequired { name: name_w.clone(), required, soft_limit, hard_limit, available_ram });
}
Err(photocraft_io::IoError::Cancelled) => return Err(EngineError::Cancelled),
Err(e) => return Err(crate::error::io_open_error(&name_w, e)),
}
}
};
match &outcome {
WorkResult::PreflightNeeded { .. } => Ok(outcome),
WorkResult::Decoded(imported) => {
ctx.progress(0.95, "Preparing layers");
warm_layer_bounds(&imported.0.document, || ctx.check())?;
if crate::type_extra_cmds::has_type_layers(&imported.0.document) {
ctx.progress(0.97, "Loading fonts");
let _ = photocraft_text::shared();
ctx.check()?;
}
Ok(outcome)
}
}
},
move |s, outcome| match outcome {
WorkResult::PreflightNeeded { required, soft_limit, hard_limit, available_ram, source, fingerprint } => {
// The warning follows the capacity measured for this estimate: an unknown
// capacity carries no fabricated number, and above the threshold it also
// says the process or tab may run out of memory. The UI shows both.
let capacity_unknown = available_ram.is_none();
let uncertain_capacity = photocraft_io::memory::uncertain_capacity_warning(required, available_ram);
let id = s.store_pending_preflight(PendingPsdPreflight {
id: 0,
name: name_a.clone(),
source,
fingerprint,
required,
soft_limit,
hard_limit,
available_ram,
confirm_damage,
})?;
Ok(json!({
"pendingPreflight": id,
"name": name_a,
"estimated": required,
"softLimit": soft_limit,
"hardLimit": hard_limit,
"availableRam": available_ram,
"capacityUnknown": capacity_unknown,
"uncertainCapacityWarning": uncertain_capacity,
}))
}
WorkResult::Decoded(imported) => {
let (mut r, damaged) = *imported;
crate::file_cmds::tag_exr_colorspace(s, &name_a, &mut r.document);
crate::file_cmds::raw_defaults(s, &r.warnings, &mut r.document);
let raw = r.warnings.iter().any(|w| w.contains(photocraft_io::raw::DEVELOPED_NOTE));
let damaged = confirm_damage && damaged;
let question = s.color.open_question(&r.document).filter(|_| !raw);
if damaged || question.is_some() {
let held = s.hold_open(r.document, r.source_read_only);
return Ok(json!({"held": held, "name": name_a, "warnings": r.warnings, "color": question, "damaged": damaged}));
}
let (index, color) = s.open_document(r.document, None);
let id = s.documents().get(index).ok_or(EngineError::NoDocument)?.doc.id;
if let Some(st) = s.active_mut() {
st.source_read_only = r.source_read_only;
}
Ok(json!({"document": index, "docId": id.0, "name": name_a, "warnings": r.warnings, "color": color}))
}
},
)
}
/// Start a job that isn't an engine command (opening a file, a shell operation, a test's fake
/// job): `work` runs on a worker, `apply` on this thread when [`Session::poll_jobs`] or
/// [`Session::wait_job`] picks the result up. `command` and `params` identify it in
/// [`JobInfo`]; it is not journaled. With `lock_document` the active document is locked as
/// for a command. Runs inline on wasm.
pub fn start_job<T: Send + 'static>(
&mut self,
command: &str,
params: Value,
label: &str,
lock_document: bool,
work: impl FnOnce(&JobCtx) -> Result<T> + Send + 'static,
apply: impl FnOnce(&mut Session, T) -> Result<Value> + Send + 'static,
) -> Result<Started> {
self.start_job_with_spawn(command, params, label, lock_document, true, work, apply)
}
// Keep the worker and apply closures together with their execution options.
/// [`Self::start_job`] with an explicit `spawn` flag: when false (or on wasm) the work runs
/// inline and its result is returned directly; otherwise it becomes a background job.
#[allow(clippy::too_many_arguments)]
pub fn start_job_with_spawn<T: Send + 'static>(
&mut self,
command: &str,
params: Value,
label: &str,
lock_document: bool,
spawn: bool,
work: impl FnOnce(&JobCtx) -> Result<T> + Send + 'static,
apply: impl FnOnce(&mut Session, T) -> Result<Value> + Send + 'static,
) -> Result<Started> {
self.start_registered(command, params, spawn, |s| run(s, label, lock_document, work, apply))
}
/// [`Session::start_job`] for [`StepWork`]: on a worker, or where the session is cooperative
/// (see [`Session::set_cooperative_jobs`]) a slice per [`Session::poll_jobs`] on this thread.
pub fn start_job_stepped<T: Send + 'static>(
&mut self,
command: &str,
params: Value,
label: &str,
lock_document: bool,
work: impl StepWork<T>,
apply: impl FnOnce(&mut Session, T) -> Result<Value> + Send + 'static,
) -> Result<Started> {
self.start_registered(command, params, true, |s| run_stepped(s, label, lock_document, work, apply))
}
/// Runs `register` (which calls [`run`] or [`run_stepped`]) with background jobs allowed when
/// `spawn` (the jobs then run on a worker, or on wasm inline or in slices, see
/// `Jobs::threaded`), and files the job it started under `command`.
fn start_registered(&mut self, command: &str, params: Value, spawn: bool, register: impl FnOnce(&mut Session) -> Result<Value>) -> Result<Started> {
let prev_spawn = self.jobs.spawn;
self.jobs.spawn = spawn;
let r = register(self);
self.jobs.spawn = prev_spawn;
let pending = self.jobs.pending.take();
match (r, pending) {
(Err(e), Some(job)) => {
job.ctx.cancel();
Err(e)
}
(Err(e), None) => Err(self.explain_missing_layer(e)),
(Ok(_), Some(mut job)) => {
job.command = command.to_string();
job.params = params;
job.journal = false;
let id = job.id;
self.jobs.running.push(job);
Ok(Started::Job(id))
}
(Ok(v), None) => Ok(Started::Done(v)),
}
}
/// Whether this session has no worker threads: [`StepWork`] jobs are run a slice at a time by
/// [`Session::poll_jobs`] on the UI thread, and every other command runs inline. The web
/// build (wasm) is always like this; tests turn it on to run that path on a desktop.
pub fn cooperative_jobs(&self) -> bool {
self.jobs.cooperative
}
/// How long one [`Session::poll_jobs`] runs a cooperative job (8 ms by default, a share of a
/// frame). A slice always does one unit of work, so zero makes every poll do just that: tests
/// use it to count polls without depending on the machine's speed.
pub fn set_job_step_budget(&mut self, budget: std::time::Duration) {
self.jobs.step_budget = budget;
}
/// Turn [`Session::cooperative_jobs`] on or off. Jobs already running keep running as they
/// started.
pub fn set_cooperative_jobs(&mut self, on: bool) {
self.jobs.cooperative = on;
}
/// Apply finished background jobs (on this thread) and return every job that ended since
/// the last call. Also runs one slice (about 8 ms) of a cooperative job, if there is one. Cheap
/// when nothing runs; the UI calls it every frame.
pub fn poll_jobs(&mut self) -> Vec<JobEvent> {
let mut i = 0;
let mut stepped = false;
let budget = self.jobs.step_budget;
while i < self.jobs.running.len() {
let Some(job) = self.jobs.running.get_mut(i) else { break };
let finished = match &job.rx {
Some(rx) => match rx.try_recv() {
Ok(r) => Some(r),
Err(std::sync::mpsc::TryRecvError::Empty) => None,
Err(std::sync::mpsc::TryRecvError::Disconnected) => {
Some(Err(EngineError::Other(format!("`{}` stopped unexpectedly; the document is unchanged", job.label))))
}
},
// One cooperative job gets the frame's budget; any others wait for the next poll.
None if !stepped => {
stepped = true;
// An absurd budget (`Duration::MAX` through `set_job_step_budget`) must not
// overflow the deadline: fall back to one no job reaches.
job.step(web_time::Instant::now().checked_add(budget).unwrap_or_else(no_deadline)).transpose()
}
None => None,
};
match finished {
Some(r) => {
let job = self.jobs.running.remove(i);
self.finish_job(job, r);
}
None => i += 1,
}
}
#[cfg(not(target_arch = "wasm32"))]
self.reap_draining_jobs();
std::mem::take(&mut self.jobs.events)
}
#[cfg(not(target_arch = "wasm32"))]
fn reap_draining_jobs(&mut self) {
if reap_draining(&mut self.jobs.draining) {
photocraft_raster::scratch::release();
}
}
/// Block until job `id` ends, apply it, and return its result (the control channel's and
/// MCP's default `wait`, and the CLI). `Err(Cancelled)` if it was cancelled. A cooperative job
/// is run to the end here.
pub fn wait_job(&mut self, id: JobId) -> Result<Value> {
if let Some(i) = self.jobs.running.iter().position(|r| r.id == id) {
let mut job = self.jobs.running.remove(i);
let r = match &job.rx {
Some(rx) => rx.recv().unwrap_or_else(|_| Err(EngineError::Other(format!("`{}` stopped unexpectedly", job.label)))),
None => loop {
if let Some(r) = job.step(no_deadline()).transpose() {
break r;
}
},
};
self.finish_job(job, r);
}
match self.jobs.recent.iter().rev().find(|j| j.id == id) {
Some(j) if j.state == "done" => Ok(j.result.clone().unwrap_or(Value::Null)),
Some(j) if j.state == "cancelled" => Err(EngineError::Cancelled),
// A typed failure keeps its fields for a caller that answers or explains it; the
// display string stays available through `jobs.list`.
Some(j) => Err(j.error_kind.clone().unwrap_or_else(|| EngineError::Other(j.error.clone().unwrap_or_else(|| "the job failed".into())))),
None => Err(EngineError::Other(format!("no job {}", id.0))),
}
}
/// Cancel job `id`: ordinary jobs stop at their next check, discard their result and leave
/// the document unchanged; the document is unlocked at once. A batch finishes the current
/// input and reports outputs already written. False if no such job is running or it
/// can't be cancelled (see [`Self::try_cancel_job`]).
pub fn cancel_job(&mut self, id: JobId) -> bool {
self.try_cancel_job(id).is_ok()
}
/// [`Self::cancel_job`], saying why a job was not cancelled.
pub fn try_cancel_job(&mut self, id: JobId) -> std::result::Result<(), CancelRefused> {
let Some(i) = self.jobs.running.iter().position(|r| r.id == id) else { return Err(CancelRefused::NotRunning) };
// Earlier batch outputs are already on disk. Let the worker stop after its current
// input and return the completed and skipped lists.
if self.jobs.running[i].command == "file.automate.batch" {
return if self.jobs.running[i].ctx.cancel_if_running() { Ok(()) } else { Err(CancelRefused::Finishing) };
}
// A print worker can already have handed the job to the OS. Discarding its result
// would falsely report cancellation; removal belongs to the system print queue.
if matches!(self.jobs.running[i].command.as_str(), "file.print" | "file.printOneCopy") {
return Err(CancelRefused::Printing);
}
// Past its commit (a save replacing its file) the job runs to the end and reports its
// real outcome; calling it cancelled would be false.
if !self.jobs.running[i].ctx.try_cancel() {
return Err(CancelRefused::Committing);
}
let job = self.jobs.running.remove(i);
self.end_job(&job, JobOutcome::Cancelled);
#[cfg(not(target_arch = "wasm32"))]
if let Some(handle) = job.handle {
self.jobs.draining.push(Draining { handle, doc: job.doc, release: false });
}
Ok(())
}
/// Ask an interactive Batch worker to stop its current input at the next safe checkpoint.
/// Headless clients keep using [`Self::cancel_job`] for a direct partial result.
pub fn request_batch_interrupt_job(&self, id: JobId) -> bool {
self.jobs.running.iter().find(|job| job.id == id && job.command == "file.automate.batch").is_some_and(|job| job.ctx.request_batch_interrupt())
}
/// Whether a Batch worker has acknowledged Esc and is waiting for the desktop decision.
pub fn batch_interrupt_waiting(&self, id: JobId) -> bool {
self.jobs.running.iter().find(|job| job.id == id && job.command == "file.automate.batch").is_some_and(|job| job.ctx.batch_waiting_for_decision())
}
/// Continue with the next input or stop a Batch paused by the desktop Esc key.
pub fn decide_batch_interrupt_job(&self, id: JobId, continue_next: bool) -> bool {
self.jobs
.running
.iter()
.find(|job| job.id == id && job.command == "file.automate.batch")
.is_some_and(|job| job.ctx.decide_batch_interrupt(continue_next))
}
/// The current read-only folder Batch document shown by the desktop while work runs.
pub fn batch_preview(&self, id: JobId) -> Option<BatchPreview> {
self.jobs.running.iter().find(|job| job.id == id && job.command == "file.automate.batch").and_then(|job| job.ctx.batch_preview())
}
/// Cancel every running job (e.g. before quitting). Prints and jobs past their commit keep
/// running; the report lists them.
pub fn cancel_all_jobs(&mut self) -> CancelReport {
let ids: Vec<JobId> = self.jobs.running.iter().map(|r| r.id).collect();
self.cancel_each(ids)
}
fn cancel_each(&mut self, ids: Vec<JobId>) -> CancelReport {
let mut report = CancelReport::default();
for id in ids {
match self.try_cancel_job(id) {
Ok(()) => report.cancelled.push(id),
Err(why) => report.refused.push((id, why)),
}
}
report
}
/// Is any job running? (Cheap: the UI asks every frame.)
pub fn has_jobs(&self) -> bool {
!self.jobs.running.is_empty()
}
/// Running job `id`.
pub fn job(&self, id: JobId) -> Option<JobInfo> {
self.jobs.running.iter().find(|r| r.id == id).map(Running::info)
}
/// Running jobs.
pub fn jobs(&self) -> Vec<JobInfo> {
self.jobs.running.iter().map(Running::info).collect()
}
/// Running jobs followed by the last few that ended (newest last), for `jobs.list`.
pub fn jobs_with_recent(&self) -> Vec<JobInfo> {
self.jobs().into_iter().chain(self.jobs.recent.iter().cloned()).collect()
}
/// The running job that locks document `doc`, if any.
pub fn job_on(&self, doc: DocId) -> Option<JobInfo> {
self.jobs.running.iter().find(|r| r.doc == Some(doc)).map(Running::info)
}
/// The running job that locks the active document, if any.
pub fn active_job(&self) -> Option<JobInfo> {
self.active().and_then(|st| self.job_on(st.doc.id))
}
/// Wait for background workers of cancelled jobs to exit (tests and benchmarks measure
/// cancel latency with it). Native only; returns at once on wasm.
pub fn join_cancelled_jobs(&mut self) {
#[cfg(not(target_arch = "wasm32"))]
{
let mut release = false;
for d in self.jobs.draining.drain(..) {
let _ = d.handle.join();
release |= d.release;
}
if release {
photocraft_raster::scratch::release();
}
}
}
/// Why command `id` can't run now because of a background job (None = no conflict).
pub(crate) fn job_conflict(&self, id: &str, journal: bool) -> Option<String> {
if !journal || independent_of_document(id) {
return None;
}
let job = self.active_job()?;
Some(format!("“{}” is still running on this document; wait for it to finish or cancel it (Esc)", job.label))
}
/// Cancel the jobs editing document `doc` (it is closing). A job past its commit keeps
/// running and its result is still applied (see [`JobCtx::commit`]).
pub(crate) fn cancel_jobs_on(&mut self, doc: DocId) -> CancelReport {
let ids: Vec<JobId> = self.jobs.running.iter().filter(|r| r.doc == Some(doc)).map(|r| r.id).collect();
let report = self.cancel_each(ids);
// Workers cancelled now, or earlier and still unwinding, hold the closing document.
#[cfg(not(target_arch = "wasm32"))]
for d in self.jobs.draining.iter_mut().filter(|d| d.doc == Some(doc)) {
d.release = true;
}
report
}
/// Run the command `id`: inline, or (with `background`) as a job when it is one.
pub(crate) fn dispatch(&mut self, id: &str, params: Value, background: bool) -> Result<Started> {
// The offer belongs to this one dispatch. Early errors drop it locally, including
// authorization, validation, floating-selection and admission failures.
let live_commit = self.live_commit.take();
self.sync_scratch_state();
let spec = crate::commands::find(id).ok_or_else(|| EngineError::UnknownCommand(id.to_string()))?;
// Params are named fields: anything but an object (or null, meaning none) is a caller
// mistake, not "use every default".
if !(params.is_object() || params.is_null()) {
return Err(EngineError::BadParams { cmd: id.to_string(), msg: "params must be a JSON object".into() });
}
let params = crate::file_cmds::batch_open_params(self, id, ¶ms).unwrap_or(params);
// Untrusted sessions gate every command, including the ones a command runs on its own
// behalf (`file.automate.conditionalModeChange` runs `image.mode.*`), before any side
// effect.
if let Some(gate) = self.authorize {
gate(id, ¶ms)?;
}
// Whether this request runs under automation's gate: its step, journaled now or when its
// job is applied, marks the recording that owns it as automation's.
let automation = self.authorize.is_some();
let _authorization = AuthorizationScope::enter(self.authorize);
let _document = crate::doc_path::scope(self.active().and_then(|d| d.path.as_deref()).map(std::path::Path::new));
// Last Filter runs as the filter it repeats: journaled, recorded in an action, faded and
// run as a job like that filter, so a recorded step replays the same filter anywhere
// (#3089), as Transform Again records its transform (#1440). With no filter yet it falls
// through to its own precondition.
if id == "filter.lastFilter"
&& let Some((filter, mut p)) = crate::filters::last_filter(self).filter(|(f, _)| f != id)
{
for key in ["target", "layer"] {
if let Some(value) = params.get(key) {
if p.is_null() {
p = serde_json::json!({});
}
if let Some(object) = p.as_object_mut() {
object.insert(key.into(), value.clone());
}
}
}
return self.dispatch(&filter, p, background);
}
if id == "file.new" {
crate::document_preset_cmds::validate_new_params(self, ¶ms)?;
}
crate::param_check::check(spec, ¶ms)?;
crate::filters::validate_params(id, ¶ms)?;
// A floating selection drops before any other command (Undo puts it back instead).
if let Some(v) = crate::float_cmds::before_command(self, id)? {
return Ok(Started::Done(v));
}
// Pixel commands follow the Channels panel target unless the caller names one.
let run_params = self.admit(id, spec, ¶ms)?;
// This UI-only disclosure preference applies to both `execute` and `start`:
// desktop UI normally calls `start`, even for synchronous Layer Style commands.
// The layer the command will change, named as the command accepts it (id or name), else the
// active one. `layer.layerStyle.clear` needs no case: it leaves no effects, so nothing expands.
// Transfer Effects changes its destination (`to`), not the layer it takes the effects from.
let new_fx_target = if id.starts_with("layer.layerStyle.") {
let target = if id == "layer.layerStyle.transferEffects" {
crate::commands::layer_param(self, &json!({"layer": params.get("to").cloned().unwrap_or(Value::Null)}))
} else {
crate::commands::layer_param(self, ¶ms)
}
.ok();
self.active().and_then(|st| {
let target = target?;
(st.doc.layer(target)?.effects.items.is_empty()).then_some((st.doc.id, target))
})
} else {
None
};
let expand_new_fx = crate::commands::layer_panel_option(self, "expandNewEffects", true);
self.coalesce_request = params.get("coalesce").and_then(Value::as_str).map(str::to_string);
self.color_restrict = crate::channel_cmds::color_restriction(self, id, &run_params);
self.filter_mask_layer = crate::channel_cmds::filter_mask_layer(self, id, &run_params);
self.jobs.spawn = background;
// Commands this one runs on its own behalf journal after this mark (#3067).
let nested_from = self.journal.len();
let pre_selected = if self.actions.recording.is_some() { self.active().map(|st| st.selected_layers()) } else { None };
let mut record_before = crate::actions_record::Before::capture(self);
// A replayable command is recorded as one step, so recording pauses while it runs: an
// action it plays (a script step) must not flush the steps it ran so far into the action
// being recorded, nor move the recording mark past the entries it is about to replace.
let recording = if spec.journal && crate::actions_cmds::replayable(id) { self.actions.recording.take() } else { None };
let before = self.active().map(|st| (st.doc.clone(), st.revision));
let docs_before: Vec<_> = self.docs.iter().map(|st| st.doc.id).collect();
// Last-resort guard (AGENTS.md, Never crash): a command that panics anyway fails with an
// error instead of taking the app down. `edit` only commits a document after its closure
// returns, so the documents are unchanged.
self.live_commit = live_commit.filter(|live| live.cmd == id);
let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| (spec.run)(self, &run_params)))
.unwrap_or_else(|_| Err(EngineError::Other(format!("`{id}` failed with an internal error (logged); the document is unchanged"))));
self.live_commit = None;
if self.actions.recording.is_none() {
self.actions.recording = recording;
}
self.jobs.spawn = false;
self.coalesce_request = None;
self.color_restrict = None;
self.filter_mask_layer = None;
#[cfg(any(test, debug_assertions))]
{
self.hint_before = None;
}
let pending = self.jobs.pending.take();
if pending.is_none()
&& let Some((doc, revision)) = &before
{
self.note_command_damage(id, doc, *revision);
self.note_pixel_change(doc.id, *revision);
}
// Shape Blur by an installed shape's id or name records the geometry it ran with, as the
// filter's own prepared params carry it: the journal (Last Filter, recorded actions)
// replays where that shape is not installed. The run resolved it already, so it can't fail.
let mut params = params;
if r.is_ok() {
let _ = crate::filters_ext::resolve_shape_path(self, id, &mut params);
}
let out = match (r, pending) {
(Err(e), Some(job)) => {
job.ctx.cancel();
Err(e)
}
(Err(e), None) => Err(self.explain_missing_layer(e)),
(Ok(_), Some(mut job)) => {
job.command = id.to_string();
job.params = params;
job.journal = spec.journal;
job.started_in_take = self.actions.recording.map(|_| self.actions.take);
job.recorded_by = job.started_in_take.filter(|_| self.actions.record_tools || !crate::actions_cmds::tool_stroke(id));
job.automation = automation;
job.pre_selected = pre_selected.clone();
job.before = std::mem::take(&mut record_before);
let jid = job.id;
self.jobs.running.push(job);
Ok(Started::Job(jid))
}
(Ok(v), None) => {
if let Some((before, _)) = &before {
self.add_relayout_damage(before);
}
if let Some((doc_id, layer_id)) = new_fx_target
&& let Some(st) = self.active_mut()
&& st.doc.id == doc_id
&& st.doc.layer(layer_id).is_some_and(|l| !l.effects.items.is_empty())
{
if expand_new_fx {
st.fx_collapsed.retain(|id| *id != layer_id);
} else if !st.fx_collapsed.contains(&layer_id) {
st.fx_collapsed.push(layer_id);
}
}
self.after_command(id, params, spec.journal, automation, Some(nested_from), pre_selected.as_deref(), &record_before);
Ok(Started::Done(v))
}
};
// A closed document's freed buffers went to the scratch pool (`before` and the action
// recording snapshot kept it alive until here). Drop both before handing the pool back
// to the OS (#10479). Compare ids since Split/Merge Channels open replacement documents.
if docs_before.iter().any(|id| !self.docs.iter().any(|st| st.doc.id == *id)) {
drop(before);
drop(record_before);
photocraft_raster::scratch::release();
}
out
}
/// The one place a command's redraw area spans more than one revision. A command that moved
/// the active document's revision more than once (Paste Into, Stroke Path, a compound, a
/// script) reports what changed since it began, [`layer_multi_cmds::step_damage`] of the
/// document before and after, measured from the revision before it. A single-revision command
/// keeps the damage it reported. Debug and test builds also count a whole-document redraw of
/// a small change ([`Session::whole_redraws`]).
pub(crate) fn note_command_damage(&mut self, id: &str, before: &Arc<Document>, from: u64) {
let Some(st) = self.active_mut().filter(|st| st.doc.id == before.id && st.revision > from) else { return };
if st.revision - from > 1 {
st.last_damage = crate::layer_multi_cmds::step_damage(before, &st.doc);
st.damage_span = Some((from, st.revision));
}
#[cfg(any(test, debug_assertions))]
if st.last_damage.is_none()
&& let Some(pct) = crate::layer_multi_cmds::small_change_pct(before, &st.doc)
{
eprintln!("warning: {id}: redraws the whole document but changed {pct}% of it");
self.whole_redraws += 1;
}
#[cfg(not(any(test, debug_assertions)))]
let _ = id;
}
/// Counts the step that moved document `doc` past revision `from` in `DocState::pixel_revision` when its damage
/// is not empty (`None` is everything). A selection-only or view-only step reports empty damage and keeps it.
fn note_pixel_change(&mut self, doc: DocId, from: u64) {
if let Some(st) = self.docs.iter_mut().find(|st| st.doc.id == doc)
&& st.revision > from
&& st.last_damage != Some(photocraft_geom::Rect::EMPTY)
{
st.pixel_revision += 1;
}
}
/// Grows the damage a command reported for the pixels it changed by what effects laid out
/// over a layer's frame repaint when it moved ([`photocraft_compose::relayout_damage`]): a
/// stroke on a layer with a Gradient Overlay reports the stroke, but the gradient is laid out
/// again over the whole grown layer (#4053). `before` is the active document before.
fn add_relayout_damage(&mut self, before: &Arc<Document>) {
let Some(st) = self.active_mut().filter(|st| st.doc.id == before.id && !Arc::ptr_eq(&st.doc, before)) else { return };
let Some(d) = st.last_damage.filter(|d| !d.is_empty()) else { return };
let extra = photocraft_compose::relayout_damage(before, &st.doc);
if !extra.is_empty() {
st.last_damage = Some(d.union(&extra));
}
}
/// A command that failed on a layer id the document doesn't have says which ids it does have
/// (#5058): ids are not positions (an opened PNG's Background is not layer 1), and an agent
/// should not need `document.inspect` to recover.
fn explain_missing_layer(&self, e: EngineError) -> EngineError {
match (e, self.active()) {
(EngineError::NoLayer(id), Some(st)) if st.doc.layer(id).is_none() => {
EngineError::UnknownLayer { id, known: crate::commands::layer_listing(&st.doc) }
}
(e, _) => e,
}
}
/// Bookkeeping after a command (or a job's apply) succeeded.
///
/// `nested_from` is the journal length when the command started. A replayable command stands
/// for the commands it ran itself (Straighten runs Image Rotation and Crop): their entries are
/// dropped, so a recorded action replays the command once, not its steps as well (#3067).
/// Edit › Transform › Again (and Again on a Copy) is not replayable and keeps the concrete
/// steps it ran instead. `automation` says the step is automation's (its request ran under an
/// automation gate), which marks the action being recorded.
#[allow(clippy::too_many_arguments)]
fn after_command(
&mut self,
id: &str,
params: Value,
journal: bool,
automation: bool,
nested_from: Option<usize>,
pre_selected: Option<&[LayerId]>,
before: &crate::actions_record::Before,
) {
// A layer-mask view ends when another layer becomes active (#196).
if let Some(st) = self.active_mut() {
crate::mask_view_cmds::fix(st);
}
crate::edit_menu_cmds::after_command(self, id, ¶ms);
crate::automate_cmds::after_command(self, id);
self.sync_preset_store();
if !journal {
return;
}
if let Some(from) = nested_from.filter(|_| crate::actions_cmds::replayable(id)) {
self.journal.truncate(from);
}
let typed = crate::actions_record::typed_layer(self, id, ¶ms);
let params = match id {
_ if self.actions.recording.is_none() => params,
"layer.duplicate" => crate::artboard_cmds::recorded_duplicate(self, crate::layer_multi_cmds::recorded_step(self, id, params, pre_selected)),
"layerComp.apply" => crate::comps_cmds::recorded_apply(self, params),
"edit.checkSpelling" if crate::type_spell_cmds::records(¶ms) => crate::type_spell_cmds::recorded_step(¶ms),
_ => crate::layer_multi_cmds::recorded_step(self, id, params, pre_selected),
};
let params = crate::actions_cmds::recorded_params(self, id, params);
let params = crate::actions_record::portable(self, id, params, before);
// A step a control client runs while the user records keeps automation's gate.
crate::actions_cmds::note_step_origin(self, automation, id, ¶ms);
match crate::actions_record::fold_keystroke(self, id, ¶ms, self.typed_layer) {
crate::actions_record::Keystroke::Folded => {}
crate::actions_record::Keystroke::None => {
if !crate::brush_cmds::coalesce_journal(self, id, ¶ms) {
self.journal.push((id.to_string(), params));
}
}
}
self.typed_layer = typed;
}
/// Apply (or report the failure of) a job whose worker has delivered `r`.
fn finish_job(&mut self, job: Running, r: Result<Payload>) {
let before = self.active_layer_stamp();
self.finish_job_step(job, r);
self.note_layer_change(before);
}
fn finish_job_step(&mut self, mut job: Running, r: Result<Payload>) {
let apply = job.apply.take();
// Keep the typed error beside its display text, so `wait_job` and `JobEvent` can still
// report a hard budget's required/limit or an approval request's limits.
let (outcome, error) = match r {
Err(EngineError::Cancelled) => (JobOutcome::Cancelled, None),
Err(e) => (JobOutcome::Failed(e.to_string()), Some(e)),
Ok(_) if job.ctx.cancelled() && job.command != "file.automate.batch" => (JobOutcome::Cancelled, None),
Ok(payload) => match self.apply_job(&job, apply, payload) {
Ok(mut v) => {
// A batch may take its final cancellation snapshot before the worker
// finishes. A cancellation accepted during that interval still counts.
if job.command == "file.automate.batch"
&& job.ctx.cancelled()
&& let Some(result) = v.as_object_mut()
{
result.insert("cancelled".into(), Value::Bool(true));
}
(JobOutcome::Done(v), None)
}
Err(EngineError::Cancelled) => (JobOutcome::Cancelled, None),
Err(e) => (JobOutcome::Failed(e.to_string()), Some(e)),
},
};
self.end_job_with_error(&job, outcome, error);
}
/// Apply a finished job's `payload` on this thread and do the command's bookkeeping, journaling
/// its step into the recording that owns it with the origin the job was admitted with.
fn apply_job(&mut self, job: &Running, apply: Option<Apply>, payload: Payload) -> Result<Value> {
let Running {
label,
doc,
snapshot,
coalesce,
color_restrict,
filter_mask_layer,
layers,
command,
params,
journal,
recorded_by,
automation,
pre_selected,
before,
..
} = job;
// A recording started after the job (#7289) keeps what it has so far, and the job's step
// goes into the journal past its start, so that recording doesn't get it.
let foreign = self.actions.recording.is_some() && *recorded_by != Some(self.actions.take);
if foreign {
crate::actions_cmds::flush_recording(self)?;
}
let prev_active = self.active;
let target = match doc {
// A job past its commit has done its work outside the session (a save wrote its
// file); a closed document doesn't undo that, so its result still applies, to no
// document.
Some(d) if job.ctx.committed() && !self.documents().iter().any(|st| st.doc.id == *d) => None,
Some(d) => {
let i =
self.documents().iter().position(|st| st.doc.id == *d).ok_or_else(|| EngineError::Other(format!("`{label}`: the document was closed")))?;
let unchanged = snapshot.as_ref().is_some_and(|w| self.documents().get(i).is_some_and(|st| Weak::ptr_eq(w, &Arc::downgrade(&st.doc))));
if !unchanged {
return Err(EngineError::Other(format!("`{label}`: the document changed while it ran; the result was discarded")));
}
self.active = Some(i);
self.note_active_change();
Some(i)
}
None => None,
};
// Selecting a layer doesn't change the document, so the snapshot check above lets it
// through. Apply against the layers the job started on: the colour restriction and any
// `active`-based edit land on them (#7366). The user's selection is put back below.
let user_layers = match (target, layers) {
(Some(i), Some(started)) => self.docs.get_mut(i).and_then(|st| {
let now = LayerSelection::of(st);
(now != *started).then(|| {
started.clone().set(st);
now
})
}),
_ => None,
};
self.coalesce_request = coalesce.clone();
self.color_restrict = *color_restrict;
self.filter_mask_layer = *filter_mask_layer;
// Apply-time hooks can dispatch commands too. Keep the same single-step recording
// contract as synchronous dispatch without truncating work done while the worker ran.
let nested_from = self.journal.len();
let recording = if *journal && crate::actions_cmds::replayable(command) { self.actions.recording.take() } else { None };
let applied_from = target.and_then(|i| self.docs.get(i)).map(|st| (st.doc.id, st.revision));
let r = match apply {
Some(f) => std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(self, payload)))
.unwrap_or_else(|_| Err(EngineError::Other(format!("`{label}` failed with an internal error (logged); the document is unchanged")))),
None => Err(EngineError::Other("internal error: job applied twice".into())),
};
if self.actions.recording.is_none() {
self.actions.recording = recording;
}
self.coalesce_request = None;
self.color_restrict = None;
self.filter_mask_layer = None;
// Finish successful command bookkeeping on the document the job edited.
// Restoring the viewed document first would attribute Fade and slice updates
// to that document instead, when the user switched tabs mid-job.
if r.is_ok() {
if let Some((doc_id, from)) = applied_from {
self.note_pixel_change(doc_id, from);
}
// The step is automation's when the job's own request was gated, not the caller
// polling it now, and only for the recording that owns it: a foreign recording does
// not get the step.
self.after_command(command, params.clone(), *journal, *automation && !foreign, Some(nested_from), pre_selected.as_deref(), before);
if foreign && let Some((start, _)) = self.actions.recording.as_mut() {
*start = self.journal.len();
}
}
// Give the user back the layers they selected while the job ran, unless the job chose a
// selection itself (a new layer, say) or one of their layers is gone.
if let (Some(started), Some(user), Some(st)) = (layers, user_layers, target.and_then(|i| self.docs.get_mut(i))) {
let kept = LayerSelection::of(st) == *started;
let exist = user.active.iter().chain(&user.selected).all(|id| st.doc.layer(*id).is_some());
if (r.is_err() || kept) && exist {
user.set(st);
}
}
// Keep the user's active document unless the job opened a new one.
// This also restores the selection when the apply step returned an error.
if target.is_some() && self.active == target {
self.active = prev_active.filter(|i| *i < self.docs.len()).or(self.active);
self.note_active_change();
}
r
}
fn end_job(&mut self, job: &Running, outcome: JobOutcome) {
self.end_job_with_error(job, outcome, None);
}
/// Records a finished job's terminal state (done, failed or cancelled) and optional typed
/// error in the recent-job list, invalidating any live preview.
fn end_job_with_error(&mut self, job: &Running, outcome: JobOutcome, error_kind: Option<EngineError>) {
// Every terminal path invalidates a preview, including worker errors, cancellation
// and discarded results whose document was closed or changed.
self.live_commit = None;
let (state, result, error) = match &outcome {
JobOutcome::Done(v) if job.command == "file.automate.batch" && v.get("cancelled").and_then(Value::as_bool) == Some(true) => {
("cancelled", Some(v.clone()), None)
}
JobOutcome::Done(v) => ("done", Some(v.clone()), None),
JobOutcome::Failed(e) => ("failed", None, Some(e.clone())),
JobOutcome::Cancelled => ("cancelled", None, None),
};
let mut info = job.info();
info.state = state;
info.result = result;
info.error = error;
info.error_kind = error_kind.clone();
if state == "done" {
info.progress = 1.0;
}
self.jobs.recent.push(info);
if self.jobs.recent.len() > RECENT {
let extra = self.jobs.recent.len() - RECENT;
self.jobs.recent.drain(..extra);
}
self.jobs.events.push(JobEvent { id: job.id, command: job.command.clone(), label: job.label.clone(), document: job.doc, outcome, error: error_kind });
}
}
/// Engine commands for the job table (the control channel and MCP use them too).
pub fn specs() -> Vec<crate::commands::CommandSpec> {
use crate::commands::CommandSpec;
vec![
CommandSpec {
id: "jobs.list",
label: "List Background Jobs",
menu: &[],
shortcut: None,
params: "{}",
enabled: |_| Ok(()),
run: |s, _| Ok(json!({"jobs": s.jobs_with_recent()})),
journal: false,
},
CommandSpec {
id: "jobs.cancel",
label: "Cancel Background Job",
menu: &[],
shortcut: None,
params: r##"{"job":u64? (default: every running job)}"##,
enabled: |_| Ok(()),
run: |s, p| match p.get("job") {
None | Some(Value::Null) => Ok(s.cancel_all_jobs().to_json()),
Some(v) => {
let id = v.as_u64().ok_or_else(|| EngineError::BadParams { cmd: "jobs.cancel".into(), msg: "`job` must be a job id".into() })?;
match s.try_cancel_job(JobId(id)) {
Ok(()) => Ok(json!({"cancelled": 1})),
// Not an error: the job is fine and will report how it ended.
Err(why @ (CancelRefused::Committing | CancelRefused::Finishing)) => {
Ok(CancelReport { cancelled: Vec::new(), refused: vec![(JobId(id), why)] }.to_json())
}
Err(CancelRefused::Printing) => Err(EngineError::Other("printing cannot be cancelled here; use the system print queue".into())),
Err(CancelRefused::NotRunning) => Err(EngineError::Other(format!("no running job {id}"))),
}
}
},
journal: false,
},
]
}
#[cfg(test)]
mod tests;
#[cfg(test)]
#[path = "../../io/tests/support/recovery_psd.rs"]
pub(crate) mod psd_open_fixture;
#[cfg(test)]
mod psd_open_confirmation_tests {
use super::*;
/// Collects either an inline open result or the completed background-job result.
fn result(s: &mut Session, started: Started) -> Value {
match started {
Started::Done(v) => v,
Started::Job(id) => s.wait_job(id).unwrap(),
}
}
/// Verifies headless opens return readable PSD content and warnings without a held prompt.
#[test]
fn headless_open_keeps_best_effort_psd_import() {
let mut s = Session::new();
let started = s.start_open("damaged.psd", OpenSource::Bytes(Arc::new(super::psd_open_fixture::make_psd(true)))).unwrap();
let v = result(&mut s, started);
assert!(v.get("document").is_some(), "{v}");
assert!(v.get("held").is_none(), "no new prompt for a headless caller");
assert!(!s.active().unwrap().source_read_only);
assert!(v["warnings"].as_array().unwrap().iter().any(|w| w.as_str().unwrap().contains("could not be decoded")));
}
/// Verifies interactive opens hold damaged PSD files but admit valid files immediately.
#[test]
fn interactive_open_holds_only_a_damaged_psd() {
for corrupt in [false, true] {
let mut s = Session::new();
let started = s.start_open_for_user("file.psd", OpenSource::Bytes(Arc::new(super::psd_open_fixture::make_psd(corrupt)))).unwrap();
let v = result(&mut s, started);
if corrupt {
assert_eq!(v["damaged"], true);
assert!(s.documents().is_empty());
let held = v["held"].as_u64().unwrap();
let (doc, read_only) = s.take_held_open(held).unwrap();
assert_eq!(doc.layers.len(), 2);
assert!(!read_only);
} else {
assert!(v.get("document").is_some(), "{v}");
assert!(!s.active().unwrap().source_read_only);
}
}
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.