Struct Poller 

pub struct Poller<M, F = JsonFormat>
where
    M: StatusMonitor,
    F: Format,
{ /* private fields */ }

Represents a long-running operation (LRO)

A Poller implements both IntoFuture and Stream. You can await a Poller to get the final model upon successful completion; or, you can call next or try_next on a mutable Poller to poll status manually.

Examples

For clients that return a Poller, you can await it to get the final result:

let client = CertificateClient::new(
    "https://my-vault.vault.azure.net",
    credential.clone(),
    None,
)?;

let params = CreateCertificateParameters::default();

// Await the poller to get the final certificate.
let certificate = client
    .begin_create_certificate("my-cert", params.try_into()?, None)?
    .await?
    .into_model()?;

If you want to manually poll status updates, you can use the Poller as a stream:

let client = CertificateClient::new(
    "https://my-vault.vault.azure.net",
    credential.clone(),
    None,
)?;

let params = CreateCertificateParameters::default();

// Manually poll status updates.
let mut poller = client
    .begin_create_certificate("my-cert", params.try_into()?, None)?;

while let Some(status) = poller.try_next().await? {
    let status = status.into_model()?;
    println!("Status: {:?}", status.status);
}

// After the stream ends, await to get the final certificate.
let certificate = poller.await?.into_model()?;

Implementations

impl<M, F> Poller<M, F>

where M: StatusMonitor, F: Format + Send,

pub fn new<Fun>( make_request: Fun, options: Option<PollerOptions<'static>>, ) -> Self

where M: Send + 'static, M::Output: Send + 'static, M::Format: Send + 'static, Fun: Fn(PollerState, PollerOptions<'static>) -> PollerResultFuture<M, F> + Send + 'static,

Creates a Poller from a callback that will be called repeatedly to monitor a long-running operation (LRO).

This method expects a callback that accepts a single PollerState parameter, and returns a PollerResult value asynchronously. The N type parameter is the type of the next link/continuation token. It may be any Sendable type. The M type parameter must implement StatusMonitor.

The stream will yield Response values for each intermediate response while the operation is in progress i.e., while M::status() returns PollerStatus::InProgress. The stream ends when the operation completes successfully, fails, or is canceled.

Panics

Panics if PollerOptions::frequency is less than 1 second.

Examples

To poll a long-running operation:

#[derive(Deserialize)]
struct OperationResult {
    id: String,
    status: Option<PollerStatus>,
    result: Option<String>,
}

impl StatusMonitor for OperationResult {
    type Output = OperationResult;
    type Format = JsonFormat;

    fn status(&self) -> PollerStatus {
        self.status.clone().unwrap_or_default()
    }
}

let url = "https://example.com/my_operation".parse().unwrap();
let mut req = Request::new(url, Method::Post);

let poller = Poller::new(move |operation_state: PollerState, poller_options| {
    // The callback must be 'static, so you have to clone and move any values you want to use.
    let pipeline = pipeline.clone();
    let api_version = api_version.clone();
    let mut req = req.clone();
    Box::pin(async move {
        if let PollerState::More(continuation) = operation_state {
            // Use the continuation to get the next URL for polling
            let next_link = match continuation {
                PollerContinuation::Links { next_link, .. } => next_link,
                _ => unreachable!(),
            };
            *req.url_mut() = next_link.clone();
            req.set_method(Method::Get);
        }

        req.url_mut()
            .query_pairs_mut()
            .append_pair("api-version", &api_version);

        let resp = pipeline
            .send(&poller_options.context, &mut req, None)
            .await?;
        let (status, headers, body) = resp.deconstruct();
        let result: OperationResult = json::from_json(&body)?;
        let final_body = body.clone(); // Clone before moving into Response
        let resp: Response<OperationResult> = RawResponse::from_bytes(status, headers, body).into();

        match result.status() {
            PollerStatus::InProgress => {
                // Continue polling with the operation URL from the response
                let next_link = format!("https://example.com/operations/{}", result.id).parse()?;
                Ok(PollerResult::InProgress {
                    response: resp,
                    retry_after: poller_options.frequency,
                    continuation: PollerContinuation::Links { next_link, final_link: None },
                })
            }
            PollerStatus::Succeeded => {
                // The result is in the operation response; otherwise, get the target URL
                // from the response headers or body and asynchronously fetch the operation target.
                Ok(PollerResult::Succeeded {
                    response: resp,
                    target: Box::new(move || {
                        Box::pin(async move {
                            // In this example, the final result is already in the status response
                            // In other cases, you might fetch from a target URL
                            use azure_core::http::headers::Headers;
                            Ok(RawResponse::from_bytes(status, Headers::new(), final_body).into())
                        })
                    }),
                })
            }
            _ => Ok(PollerResult::Done { response: resp })
        }
    })
}, None);

Trait Implementations

impl<M, F> Debug for Poller<M, F>

where M: StatusMonitor, F: Format,

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

Formats the value using the given formatter.

impl<M, F> IntoFuture for Poller<M, F>

where M: StatusMonitor + 'static, M::Output: Send + 'static, M::Format: Send + 'static, F: Format + 'static,

type Output = Result<Response<<M as StatusMonitor>::Output, <M as StatusMonitor>::Format>, Error>

The output that the future will produce on completion.

type IntoFuture = Pin<Box<dyn Future<Output = <Poller<M, F> as IntoFuture>::Output> + Send>>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.

impl<M, F> Stream for Poller<M, F>

where M: StatusMonitor, F: Format,

type Item = Result<Response<M, F>, Error>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut TaskContext<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<'pin, M, F> Unpin for Poller<M, F>

where M: StatusMonitor, F: Format, PinnedFieldsOf<__Poller<'pin, M, F>>: Unpin,