Struct Pending 

pub struct Pending<T> {
    pub id: InvocationId,
    /* private fields */
}

Outcome of an actor-bound mutation. Wraps a oneshot receiver so the caller can await (or block on) the result.

Pending is neither Clone nor Copy – the receiver is single-use, matching the “one response per request” contract. Dropping a Pending cancels the wait but does not interrupt the actor; the response is silently discarded.

Fields

id: InvocationId

Implementations

impl<T> Pending<T>

pub fn map_ok<F>(self, f: F) -> Self

where F: FnOnce(T) -> T + Send + 'static,

2026-06-02: attach an on-success transform that runs when the inner result resolves. The transform runs on the consumer’s polling thread, NOT in a separately spawned task — critical when the producer is inside a current_thread runtime that’s about to block in block_on. Use this instead of Pending::spawn for purely synchronous result-shape adaptation (e.g. translating coordinate spaces).

map_ok may be called only once per Pending. A second call replaces the prior transform (last-write-wins).

pub fn ready(result: Result<T, RuntimeError>) -> Self

M.1 (2026-05-31): build a Pending<T> that resolves immediately with result. Used by read-only impls of crate::Document (MultibufferDocumentHandle) to reject writes without ever spawning an actor — every mutating method returns Pending::ready(Err( RuntimeError::ReadOnly)).

pub fn from_channel(rx: Receiver<Result<T, RuntimeError>>) -> Self

OA.23b: wrap a channel that a task ALREADY RUNNING will complete.

The peer of Self::spawn for producers that have no task to spawn — the work is already queued somewhere else and all they hold is the reply end. MultibufferDocumentHandle:: apply_to_source is the case: the edit rides the view’s source-forwarder FIFO (spawned once, on the shared runtime, at view construction) and the forwarder answers this channel.

Not a stylistic preference over spawn. spawn calls tokio::spawn and so needs a runtime in scope at the point of construction; this path is reached from the editor actor — a current_thread runtime about to block_on the result — where spawning the awaiter onto the caller’s own runtime is the deadlock map_ok was added to avoid.

A dropped sender resolves to ActorGone, as with any other Pending.

pub fn spawn<F>(future: F) -> Self

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

M.3 (2026-06-01): build a Pending<T> that resolves when the spawned future completes. Lets callers compose multiple Pendings into one without blocking the runtime (used by MultibufferDocumentHandle::apply_edit_batch to fan a translated batch across N source handles, await each source’s Pending asynchronously, and combine the results).

Spawns on the SHARED runtime, never on the ambient one, and that is the whole of its correctness.

It used to call bare tokio::spawn, which lands the task on whatever runtime happens to be in scope at the point of construction. Every consumer of a Pending is a document operation, and the host reaches those from the editor actor — a current_thread runtime that then blocks itself awaiting the result (block_on(document.save())). The task is queued on the one thread that is now blocked, so nothing drives it and the editor wedges permanently, with the operation never performed.

That is not a hypothetical. It shipped three times: the pre-M.11 apply_edit freeze, the undo freeze, and MultibufferDocument::save — the user-visible form of the last being “:w on the agenda hangs forever and the change is not on disk”. The first two were fixed by making those paths synchronous, which left this constructor still carrying the trap for the one caller that genuinely needs async work.

Naming the target runtime fixes the class rather than the instance: document actors all live on the shared runtime, so it is where a composition over them belongs. It also drops the old “requires a current tokio runtime context” requirement — there is nothing left to get wrong at a call site.

Self::map_ok and Self::from_channel remain the right tools for their own cases (a synchronous transform, and a task that is already running); they are no longer workarounds for this hazard.

pub fn blocking_recv(self) -> Result<T, RuntimeError>

Block the current thread until the actor responds. Used by the TUI input loop and by tests that don’t drive a tokio reactor explicitly. Panics only if the oneshot’s internal invariants are violated, which can’t happen in safe code.

Trait Implementations

impl<T> Debug for Pending<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Future for Pending<T>

type Output = Result<T, RuntimeError>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.