Skip to main content

Run

Struct Run 

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

Source

pub fn revision(&self) -> Revision<M>

Returns the immutable Agent revision frozen for this Run.

Source

pub fn session(&self) -> Session

Returns the Session owned by this Run.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub async fn close(&self) -> Arc<Terminal> ⓘ

Abandons an untaken event consumer, requests stop, and waits for cleanup.

§Panics

If a Run or event-control lock is poisoned, per the crate-level lock-poisoning contract.

Trait Implementations§

Source§

impl<M: Client> Clone for Run<M>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<M: Client> Debug for Run<M>

Source§

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.

Source§

impl<M: Client> Drop for Run<M>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

§

impl<M> !RefUnwindSafe for Run<M>

§

impl<M> !UnwindSafe for Run<M>

§

impl<M> Freeze for Run<M>
where Arc<RunInner<M>>: Freeze,

§

impl<M> Send for Run<M>
where Arc<RunInner<M>>: Send,

§

impl<M> Sync for Run<M>
where Arc<RunInner<M>>: Sync,

§

impl<M> Unpin for Run<M>
where Arc<RunInner<M>>: Unpin,

§

impl<M> UnsafeUnpin for Run<M>
where Arc<RunInner<M>>: UnsafeUnpin,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.