pub struct Run<M: Client> { /* private fields */ }Expand description
A cloneable handle to one admitted Run.
A Run exists only because Agent::start
admitted a Session, so by the time you hold one the input is already recorded
and the loop is already running. There are exactly three things to do with
it: take its take_events once, ask it to stop, and wait for its
Terminal.
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 = agent
.start(session.clone(), vec![content::Part::text("Hi.".to_owned())], cancel::Token::new())
.await
.unwrap();
// Events are single-consumer: the second take fails, on this handle or any
// clone of it.
let mut events = started.take_events().unwrap();
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 has already been taken — by an earlier
call, or through any other clone of this handle. 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.
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.