Struct EffectCx 

pub struct EffectCx<R: Resource, H = ()> { /* private fields */ }

What an effect handler, a job’s completion and a projection drain receive: the resource, its dispatcher, and the means to start a job.

H is what a completion gets mutable access to: the surface that handles the effect (&mut self), or () for a handler a view registered.

Implementations

impl<R: Resource, H: 'static> EffectCx<R, H>

pub fn place(&self) -> Option<&Place>

Where the invoker asked this effect to act (its #[param(place)] argument): act there instead of at their caret. Once it succeeds for a participant, they land there (Live::place_of).

pub fn document(&self) -> Option<Ref<'_, Doc>>

The resource’s document as it is now, to read what a view answers with: the state at its heads, a selection’s measurements, a picture of it. Only a surface’s handler answering an invocation has it; a job’s completion, which runs later, reads the live state instead. Changes go through the dispatcher, never here.

pub fn heads(&self) -> Vec<ChangeHash>

The heads of the document as it is now; empty without one.

pub fn version(&self, version: &str) -> Result<DocumentVersion, String>

The resource at version, as a caller names one: a change id from its history (or enough of one) or a checkpoint’s name.

pub fn dispatcher(&self) -> Dispatcher<R>

Where the effect’s document changes go: ordinary actions, checked, applied, undone and replicated like any other.

pub fn person(&self) -> Option<String>

The person this invocation runs for: its invoker, when a host delivered it for someone, else the participant the view is for. None for a bot, an agent or an app acting, and in a past version. An effect that answers or changes what is someone’s own (“my link”) reads whose it is here, never from the view.

pub fn apply(&self, action: &R::Action)

Submit one typed action, as Dispatcher::apply.

pub fn submit(&self, submit: impl Submit<R>)

Submit a field edit or a verb, as Dispatcher::submit.

pub fn live(&self) -> &Live<R>

The resource’s live state.

pub fn invocation(&self) -> Option<InvocationId>

The actual source invocation this work continues. Ordinary background projection drains have none; causal drains retain the current Document caller. Its source identity may differ from the local reply operation.

pub fn external_moderation( &self, operation: ExternalModerationOperation, ) -> Result<ExternalModerationFuture, String>

Submit the exact approved moderation operation through the record’s host. Pass the returned Send future to the action’s existing job.

pub fn attribute_writes( &self, paths: Vec<String>, ) -> Option<WriteAttributionReceipt>

Name the paths this invocation is about to write (absolute paths; a folder covers what is under it), before writing them: when an agent acting for the session’s person invoked it, the versions those writes make record that agent, for its person. The host takes who acted from its own custody of the invocation, never from here. Wait on the receipt where the writes run (a Self::thread), then write whatever it answered. None when there is nobody to name: no invocation’s custody, or one that is not an agent’s.

pub fn approved_check( &self, check_id: &str, ) -> Result<ApprovedCheckFuture, String>

Run an approved project check through this effect’s admitted host channel. Commands, source paths and resource bounds are chosen by the project host. Pass the returned future to the existing effect job with Self::spawn.

pub fn approved_check_reported( &self, check_id: &str, ) -> Result<impl FnOnce(Progress) -> ApprovedCheckFuture + Send + 'static + use<R, H>, String>

Attach approved-check reports to this action’s existing job progress. The app remains the sole publisher of invocation-update sequences.

pub fn call( &mut self, call: &Call, then: impl FnOnce(&mut H, Result<ActionOutput, String>, &mut Self) -> EffectAnswer + 'static, ) -> Effected

Call another resource’s published action, as part of this effect, then then with what it answered (or why it did not go ahead) on the UI thread.

The host decides the call as this effect’s caller: when it delivered this invocation for someone (a person at its palette, an agent, another member), the call continues it and is theirs, with their grants, in the other resource’s history and their undo there. The person at this device acting here asks as this app, which needs the workspace’s grant to it (or their answer). What the effect then submits to its own resource continues it the same way, so the whole composition is the caller’s, each part recorded once where it changed something.

let note = Call::on("so.tilo.notes", None, &notebook, "create-page")
    .with(json!({ "title": title }));
Ok(cx.call(&note, move |_, created, cx| {
    let created = created?;
    cx.submit(Tracker::LINK.with(..));
    cx.when_landed(|_, _, _| Ok(Effected::done()))
}))

pub fn waker(&self) -> WakeHandle

Wakes the app from another thread, to draw what a worker changed.

pub fn spawn<T, F>( &mut self, work: impl FnOnce(Progress) -> F, then: impl FnOnce(&mut H, T, &mut Self) -> EffectAnswer + 'static, ) -> Effected

where T: Send + 'static, F: Future<Output = T> + Send + 'static,

Run work’s future on the app runtime, then then with its output on the UI thread. The future reports through the Progress it is built with; cancelling the effect aborts it.

pub fn thread<T>( &mut self, work: impl FnOnce(Progress) -> T + Send + 'static, then: impl FnOnce(&mut H, T, &mut Self) -> EffectAnswer + 'static, ) -> Effected

where T: Send + 'static,

Run blocking work off the UI thread, then then with its result on the UI thread. work reports through its Progress and checks it for cancellation.

pub fn cancel_by(&mut self, signal: Arc<AtomicBool>)

Have the job this effect leaves to answer later stopped when signal goes off, as well as when the caller cancels it.

An effect whose answer is read from a long-lived surface (Self::reply) can lose its caller before the caller’s own cancellation reaches it: the answer is kept by the surface rather than by a job of this invocation. A handler of such an effect passes the caller’s cancellation signal (Progress::cancellation_signal) here, and the job that carries the answer stops with it: an operation nobody waits for must not run on.

pub fn reply(&mut self) -> EffectReply

Answer later, from wherever the work settles. Return Effected::Pending and keep the reply until then.

pub fn reply_then( &mut self, then: impl FnOnce(&mut H, ActionOutput, &mut Self) -> EffectAnswer + 'static, ) -> EffectReply

Answer later, then settle the successful receipt on the UI thread under this effect’s retained invocation. Refusal skips the completion and preserves its structured failure. Cancellation and current custody are checked by the same job path as Self::spawn.

pub fn when_landed( &mut self, then: impl FnOnce(&mut H, Landed, &mut Self) -> EffectAnswer + 'static, ) -> EffectAnswer

Answer once what this effect submitted through its dispatcher landed: each submission goes through the door like any other, checked again for the effect’s invoker, and then runs with the last one’s Landed — what the door answered (what an edit changed, as the resource’s surface reports it) and the items it created — to reply to the effect’s caller. A refused submission fails the effect with why. The effect must be declared job, since it answers after the edits apply.

cx.dispatcher().submit(Doc::BODY.edit(op));
cx.when_landed(|_, landed, _| Ok(Effected::value(landed.answer)))

Errors

When the effect was not invoked (a view’s own job) or submitted nothing to wait for.

pub fn choose_file( &mut self, request: PickRequest, then: impl FnOnce(&mut H, Option<ChosenFile>, &mut Self) -> EffectAnswer + 'static, ) -> Effected

Ask the person to choose a file with the host’s chooser (request is an Open request), then run then on the UI thread with its name and contents, or None when they cancelled. Works where files have no paths, such as a browser page. Bound reads with PickRequest::max_contents_bytes; an oversized selection fails the job before calling then. The effect must be declared job.

pub fn choose_files( &mut self, request: PickRequest, then: impl FnOnce(&mut H, Vec<ChosenFile>, &mut Self) -> EffectAnswer + 'static, ) -> Effected

Self::choose_file for a request that lets the person choose several files (PickRequest::open_multiple): then receives every chosen file, none when they cancelled. A request contents limit applies to the total bytes across the entire selection.

pub fn choose_path( &mut self, request: PickRequest, then: impl FnOnce(&mut H, Option<PathBuf>, &mut Self) -> EffectAnswer + 'static, ) -> Effected

Ask the person to choose a file with the host’s chooser and run then on the UI thread with its path on this device, or None when they cancelled: for a file the app reads in place rather than into memory (a disk image, a video). Only a host whose files have paths answers; elsewhere use Self::choose_file. The effect must be declared job.

pub fn save_file( &mut self, request: PickRequest, bytes: Vec<u8>, then: impl FnOnce(&mut H, bool, &mut Self) -> EffectAnswer + 'static, ) -> Effected

Ask the person where to save bytes with the host’s chooser (request is a Save request suggesting a file name; a browser page downloads them under it), then run then on the UI thread with whether they were saved: false when the person cancelled. The effect must be declared job.

pub fn choose_destination( &mut self, request: PickRequest, then: impl FnOnce(&mut H, Option<SaveDestination>, &mut Self) -> EffectAnswer + 'static, ) -> Effected

Ask the person where to save with the host’s chooser (request is a Save request suggesting a file name), then run then on the UI thread with the place, or None when they cancelled. The place takes bytes made after the choice, and can be kept to write there again on every later Save without asking: a path where files have paths, the browser’s own Save dialog file on a browser page. The effect must be declared job.

pub fn write_destination( &mut self, destination: &SaveDestination, bytes: Vec<u8>, then: impl FnOnce(&mut H, Result<(), String>, &mut Self) -> EffectAnswer + 'static, ) -> Effected

Run then on the UI thread once destination holds bytes: Ok when they were saved, the reason when not. The effect must be declared job.

pub fn open_here( &mut self, opener: &OpenHere, arguments: &[String], then: impl FnOnce(&mut H, Result<(), String>, &mut Self) -> EffectAnswer + 'static, ) -> Effected

Ask the host to show what a launch naming arguments opens in this window, in place of the record it shows (OpenHere::open), then run then on the UI thread with its answer: shown, or why not. The answer arrives even when the window shows the new record before this surface draws another frame. Cancelling the effect withdraws a request the host has not taken up yet. The effect must be declared job.