pub struct Run<M: Client> { /* private fields */ }Expand description
A cloneable handle to one admitted Run.
A Run exists only because Agent::start or
Agent::start_observed admitted a Session,
so by the time you hold one the input is already recorded and the loop is already
running. Ask it to stop and wait for its Terminal. When start constructed it,
also take its take_events once; start_observed instead returns
that unique stream atomically beside the Run.
Every clone shares one Run. Dropping the last handle asks it to stop; it does not wait, and it does not abandon work already in flight.
use reef_core::cancel;
use reef_core::runtime::{agent, hook, run, session, tool};
use reef_core::value::{content, lifecycle};
let session = session::Session::new("conversation-1".to_owned(), None);
let (started, mut events) = agent
.start_observed(session.clone(), vec![content::Part::text("Hi.".to_owned())], cancel::Token::new())
.await
.unwrap();
// Events are single-consumer: the atomic handoff means the Run and every
// clone report that its stream was already taken.
assert!(started.clone().take_events().is_err());
while let Some(delivery) = events.recv().await {
if delivery.decision_point().is_some() {
delivery.accept().unwrap();
}
}
// Every waiter gets the same terminal, and waiting again is free.
let terminal = started.wait().await;
assert_eq!(terminal.outcome(), lifecycle::Outcome::Completed);
assert_eq!(started.wait().await.outcome(), terminal.outcome());Implementations§
Source§impl<M: Client> Run<M>
impl<M: Client> Run<M>
Sourcepub fn revision(&self) -> Revision<M>
pub fn revision(&self) -> Revision<M>
Returns the immutable Agent revision frozen for this Run.
Sourcepub fn take_events(&self) -> Result<Stream, EventsTakenError>
pub fn take_events(&self) -> Result<Stream, EventsTakenError>
Takes the unique outward event consumer.
§Errors
EventsTakenError if the Stream was returned atomically by
Agent::start_observed, or has already
been taken by an earlier call through this handle or any clone. Events are
single-consumer, so this is not contention that clears: the one consumer
already exists, and whoever holds it is the only party that can observe the
Run’s events.
§Panics
If the lock guarding the not-yet-taken Stream is poisoned, per the
crate-level lock-poisoning contract. It is held
only for the take itself, so nothing a caller or a hook does runs under
it.
Sourcepub fn request_stop(&self)
pub fn request_stop(&self)
Requests a normal stop without waiting or spawning cleanup work.
§Panics
If an event-control lock is poisoned, per the crate-level lock-poisoning contract.
Sourcepub async fn stop(&self) -> Arc<Terminal> ⓘ
pub async fn stop(&self) -> Arc<Terminal> ⓘ
Requests a normal stop and waits for complete cleanup.
§Panics
If an event-control or Run terminal lock is poisoned, per the crate-level lock-poisoning contract.
Sourcepub async fn wait(&self) -> Arc<Terminal> ⓘ
pub async fn wait(&self) -> Arc<Terminal> ⓘ
Waits for the shared terminal without requesting a stop.
Every waiter, on this handle or any clone, receives the same
Terminal, and waiting again after it has resolved returns
immediately. If its outcome is
Failed, read Terminal::failure_kind and
Terminal::failure rather than reporting the outcome alone.
§Panics
If the Run terminal lock is poisoned, per the crate-level lock-poisoning contract.
Sourcepub async fn close(&self) -> Arc<Terminal> ⓘ
pub async fn close(&self) -> Arc<Terminal> ⓘ
Abandons an event consumer still owned by this Run, requests stop, and waits.
A stream returned by Agent::start_observed
is caller-owned, so this method closes the producer but cannot discard that
stream or its already queued events; the caller may drain them to EOF.
§Panics
If a Run or event-control lock is poisoned, per the crate-level lock-poisoning contract.
Trait Implementations§
Source§impl<M: Client> Debug for Run<M>
impl<M: Client> Debug for Run<M>
Source§fn fmt(&self, formatter: &mut Formatter<'_>) -> Result
fn fmt(&self, formatter: &mut Formatter<'_>) -> Result
Locates the Run by session and revision, and counts live handles.
There is no M: Debug bound: a Run would otherwise be unprintable for
every provider that has not opted in, and the model is not what
distinguishes one Run from another anyway. The three facts here are all
lock-free, so formatting a Run can never stall the Run.