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.

Errors

Returns why version names no version of this document, or that the handler has no document to read.

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 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 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.

Errors

Refuses projection drains, absent original custody or unavailable transport.

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.

Errors

Refuses absent dispatch custody or unavailable approved transport.

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 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 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.