pub struct RunHandle<O> { /* private fields */ }Expand description
A started run of a single task, and its output type.
Holding one does not hold a subscription open: the stream is opened when
result is awaited, and closed again once nothing is
waiting for anything.
It does keep a clone of the Client it was started from, which is what
lets it wait (result) and cancel
(cancel) on its own. A Client is one Arc, so
that costs a reference — and it means a handle stays usable after the
client it came from goes out of scope. There is no reference cycle: the
client’s result listener never holds a Client (see client.rs).
Implementations§
Source§impl<O> RunHandle<O>
impl<O> RunHandle<O>
Sourcepub fn id(&self) -> &str
pub fn id(&self) -> &str
The engine’s id for this run. Runs are addressed by it in the dashboard and in the REST API.
Sourcepub async fn cancel(&self) -> Result<()>
pub async fn cancel(&self) -> Result<()>
Stops this run.
One CancelTasks call naming this run. Measured on both supported
engine versions: a workflow run id cancels every task of that run that
exists when the call arrives — a task the engine has not created yet
is not covered and will still run, so a run that fans out over time
may need cancelling more than once.
Cancelling a run that is already over is not an error, and neither is cancelling one the engine has never heard of: the engine answers both by echoing the id back. There is therefore nothing to check — the answer is not proof of effect — and this hands back nothing.
The run’s own handler sees the cancellation as
Context::cancelled; a waiter on
result sees Error::RunCancelled.
let run = task.run_no_wait(client, &(), RunOpts::default()).await?;
run.cancel().await?;§Errors
Error::Grpc when the call fails.
Sourcepub async fn stream(&self) -> Result<OutputStream>
pub async fn stream(&self) -> Result<OutputStream>
The output stream of this run: the chunks its handler publishes with
Context::put_stream.
Exactly RunsClient::stream for this run’s id, which documents what
a subscription opened after the trigger can miss, what ends the stream,
and the five seconds this can spend waiting for the engine to answer
before handing back a stream that is still being opened. Nothing can be
subscribed to before the trigger, so a handler that starts publishing
at once may be a chunk ahead of this; the race-free pattern is
RunsClient::stream_by_metadata, opened before the run is
triggered.
let run = task.run_no_wait(client, &(), RunOpts::default()).await?;
let mut chunks = run.stream().await?;
while let Some(chunk) = chunks.next().await {
println!("{}", chunk?.payload);
}
// The output is separate from the result: this still waits for it.
let count = run.result().await?;§Errors
Those of RunsClient::stream.
Source§impl<O: DeserializeOwned> RunHandle<O>
impl<O: DeserializeOwned> RunHandle<O>
Sourcepub async fn result(&self) -> Result<O>
pub async fn result(&self) -> Result<O>
Waits for the run to finish and deserializes its output.
There is no time limit. A run that never finishes is waited for for
ever, which is what the official SDKs do; wrap the call in
tokio::time::timeout if that is not what you want. The wait costs
nothing while it lasts — every wait on one client shares a single
subscription — and dropping the future stops waiting without affecting
the run.
Awaiting it more than once waits again, and a run that has already finished is answered straight away.
The subscription is the client’s, and a handle holds a clone of that
client, so this goes on working after the Client the run was started
from goes out of scope.
let run = task.run_no_wait(client, &(), RunOpts::default()).await?;
println!("started {}", run.id());
// An hour is this caller's own limit, not the SDK's.
let count = tokio::time::timeout(Duration::from_secs(3600), run.result())
.await
.expect("the run took more than an hour")?;§Errors
Error::RunFailed when a task of the run reported an error,
Error::RunCancelled when the run was cancelled before it finished
— by cancel, by
RunsClient::cancel, by a Concurrency limit
that cancels rather than queues, or from the dashboard —
Error::RunOutput when the run produced no output for this task or
its output is not an O, and Error::ResultStream when the
subscription was given up on — the run itself is unaffected by that
last one, and waiting again opens a new subscription.
Trait Implementations§
Auto Trait Implementations§
impl<O> !RefUnwindSafe for RunHandle<O>
impl<O> !UnwindSafe for RunHandle<O>
impl<O> Forget for RunHandle<O>
impl<O> Freeze for RunHandle<O>
impl<O> Move for RunHandle<O>
impl<O> Send for RunHandle<O>
impl<O> Sync for RunHandle<O>
impl<O> Unpin for RunHandle<O>
impl<O> UnsafeUnpin for RunHandle<O>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> FutureExt for T
impl<T> FutureExt for T
Source§fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
fn with_context(self, otel_cx: Context) -> WithContext<Self> ⓘ
Source§fn with_current_context(self) -> WithContext<Self> ⓘ
fn with_current_context(self) -> WithContext<Self> ⓘ
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
Source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T in a tonic::Request