Struct JobHandle 

pub struct JobHandle { /* private fields */ }

A job-handle enables cancelling a job and awaiting results

A JobHandle can be awaited directly. It returns a Result<JobCompletion, JobHandleError>

See JobCompletion and JobHandleError for details.

When the JobHandle is dropped a cancellation message is sent to the job task.

Implementations

impl JobHandle

pub fn is_finished(&self) -> bool

pub fn cancel(&self) -> Result<(), JobHandleError>

sends cancel message to job and returns immediately.

note: await the JobHandle after calling cancel() to ensure the job has ended and obtain a JobCompletion

Basic example:

use neptune_job_queue::JobQueue;
use neptune_job_queue::JobCompletion;
use neptune_job_queue::traits::Job;
use neptune_job_queue::errors::JobHandleError;

async fn add_and_cancel_job(job_queue: &mut JobQueue<u8>, job: Box<dyn Job>) -> Result<JobCompletion, JobHandleError> {

    let job_priority: u8 = 10;
    let job_handle = job_queue.add_job(job, job_priority).unwrap();

    // some time later...
    tokio::time::sleep(std::time::Duration::from_secs(5)).await;

    job_handle.cancel()?;

    let job_completion_result = job_handle.await;
    assert!(matches!(job_completion_result, Ok(JobCompletion::Cancelled)));

    job_completion_result
}

Sometimes it is necessary to listen for an application message that the job needs to cancel. This can be achieved with tokio::select!{}

Example:

use neptune_job_queue::JobQueue;
use neptune_job_queue::JobCompletion;
use neptune_job_queue::traits::Job;
use neptune_job_queue::errors::JobHandleError;

async fn do_some_work(
    job_queue: &mut JobQueue<u8>,
    job: Box<dyn Job>,
    cancel_work_rx: tokio::sync::oneshot::Receiver<()>,
) -> Result<JobCompletion, JobHandleError> {

    // add the job to queue
    let job_priority: u8 = 10;
    let job_handle = job_queue.add_job(job, job_priority).unwrap();

    // pin job_handle, so borrow checker knows the address can't change
    // and it is safe to use in both select branches
    tokio::pin!(job_handle);

    // execute job and simultaneously listen for cancel msg from elsewhere
    let job_completion_result = tokio::select! {
        // case: job completion.
        completion = &mut job_handle => completion,

        // case: sender cancelled, or sender dropped.
        _ = cancel_work_rx => {
            job_handle.cancel()?;
            job_handle.await
        }
    };
    job_completion_result
}

pub fn job_id(&self) -> JobId

obtain the job identifier

Trait Implementations

impl Debug for JobHandle

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

Formats the value using the given formatter.

impl Drop for JobHandle

fn drop(&mut self)

Executes the destructor for this type.

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.

impl Future for JobHandle

type Output = Result<JobCompletion, JobHandleError>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.