Skip to main content

SimpleTaskQueue

Struct SimpleTaskQueue 

Source
pub struct SimpleTaskQueue<T, K = String> { /* private fields */ }
Expand description

A bounded, thread-safe, in-memory task queue.

The queue uses a background thread to expire finished status records and to mark tasks that run for too long as failed. Dropping the queue stops and joins that background thread.

Implementations§

Source§

impl<T, K> SimpleTaskQueue<T, K>
where K: Eq + Hash + Clone + Send + Sync + 'static,

Source

pub fn new_with_capacity(capacity: usize) -> SimpleTaskQueue<T, K>

Creates a queue with the given bounded capacity and default maintenance settings.

Finished tasks are retained for 60 seconds, running tasks time out after 60 seconds, and background maintenance runs every 60 seconds.

§Panics

Panics if capacity is zero.

Source

pub fn new_with_config( capacity: usize, finished_task_ttl: Duration, running_task_timeout: Duration, background_task_interval: Duration, ) -> SimpleTaskQueue<T, K>

Creates a queue with explicit capacity and background maintenance settings.

  • finished_task_ttl controls how long terminal task statuses and their idempotency keys remain retained.
  • running_task_timeout controls how long a task may remain TaskState::Running before being marked TaskState::Failed.
  • background_task_interval controls how often both checks run.

Cleanup and timeout transitions can occur up to one maintenance interval after the configured duration has elapsed.

§Panics

Panics if capacity is zero.

Source

pub fn new() -> SimpleTaskQueue<T, K>

Creates a queue with capacity 1024 and default maintenance settings.

See SimpleTaskQueue::new_with_capacity for the default retention, timeout, and maintenance interval.

Source

pub fn submit_task(&self, payload: T) -> Result<TaskId, TaskError>

Submits a task without an idempotency key.

Every successful call allocates a new TaskId, even when the payload is equal to a previously submitted payload.

§Errors

Returns TaskError::QueueFull when the bounded queue is full, TaskError::Disconnected when its channel is closed, or TaskError::TaskIdExhausted when no further task IDs can be allocated.

Source

pub fn submit_task_with_key( &self, task_key: impl Into<TaskKey<K>>, payload: T, ) -> Result<TaskId, TaskError>

Submits a task with an idempotency key.

The key is reserved until the task’s terminal status expires. Submitting the same key during that period returns TaskError::DuplicateTaskKey. The key can be supplied as any value convertible into K.

§Examples
use taskq::{SimpleTaskQueue, TaskError};

let queue = SimpleTaskQueue::<&str, u64>::new();
queue.submit_task_with_key(42_u64, "first")?;
assert!(matches!(
    queue.submit_task_with_key(42_u64, "duplicate"),
    Err(TaskError::DuplicateTaskKey)
));
§Errors

Returns TaskError::DuplicateTaskKey for a retained key. It can also return any error documented by SimpleTaskQueue::submit_task.

Source

pub fn get_task_status(&self, task_id: TaskId) -> Result<TaskStatus, TaskError>

Returns a snapshot of the status associated with task_id.

§Errors

Returns TaskError::NotFound when the ID is unknown or its finished status has expired.

Source

pub fn try_pop_task(&self) -> Option<Task<T, K>>

Attempts to receive the next task without waiting.

Receiving a task changes its status to TaskState::Running. Returns None if the queue is empty or disconnected.

Source

pub async fn pop_task(&self) -> Result<Task<T, K>, TaskError>

Waits asynchronously for the next task.

Waiting does not block an async runtime worker. Receiving a task changes its status to TaskState::Running.

§Examples
use taskq::{SimpleTaskQueue, TaskError};

let queue = SimpleTaskQueue::<u32>::new();
queue.submit_task(7)?;

let task = queue.pop_task().await?;
assert_eq!(task.payload(), &7);
queue.mark_task_success(task.id())?;
§Errors

Returns TaskError::Disconnected when the queue channel closes.

Source

pub fn mark_task_success(&self, task_id: TaskId) -> Result<(), TaskError>

Marks a running task as successfully completed.

§Errors

Returns TaskError::NotFound when the task is unknown and TaskError::InvalidTaskState when it is not currently running.

Source

pub fn mark_task_failed(&self, task_id: TaskId) -> Result<(), TaskError>

Marks a running task as failed.

§Errors

Returns TaskError::NotFound when the task is unknown and TaskError::InvalidTaskState when it is not currently running.

Trait Implementations§

Source§

impl<T, K> Default for SimpleTaskQueue<T, K>
where K: Eq + Hash + Clone + Send + Sync + 'static,

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl<T, K> Drop for SimpleTaskQueue<T, K>

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

impl<T, K> TaskQueue<T, K> for SimpleTaskQueue<T, K>
where K: Eq + Hash + Clone + Send + Sync + 'static,

Source§

fn submit_task(&self, payload: T) -> Result<TaskId, TaskError>

Submits a task without an idempotency key.
Source§

fn submit_task_with_key( &self, task_key: TaskKey<K>, payload: T, ) -> Result<TaskId, TaskError>

Submits a task with an idempotency key.
Source§

fn get_task_status(&self, task_id: TaskId) -> Result<TaskStatus, TaskError>

Returns a snapshot of the status associated with task_id.
Source§

fn try_pop_task(&self) -> Option<Task<T, K>>

Attempts to receive a task without waiting. Read more
Source§

fn pop_task(&self) -> impl Future<Output = Result<Task<T, K>, TaskError>> + Send
where T: Send, K: Send,

Waits asynchronously until a task is available.
Source§

fn mark_task_success(&self, task_id: TaskId) -> Result<(), TaskError>

Marks a running task as successfully completed.
Source§

fn mark_task_failed(&self, task_id: TaskId) -> Result<(), TaskError>

Marks a running task as failed.

Auto Trait Implementations§

§

impl<T, K = String> !Freeze for SimpleTaskQueue<T, K>

§

impl<T, K = String> !RefUnwindSafe for SimpleTaskQueue<T, K>

§

impl<T, K = String> !Unpin for SimpleTaskQueue<T, K>

§

impl<T, K = String> !UnsafeUnpin for SimpleTaskQueue<T, K>

§

impl<T, K = String> !UnwindSafe for SimpleTaskQueue<T, K>

§

impl<T, K> Send for SimpleTaskQueue<T, K>
where Arc<DashMap<K, i64>>: Send, Sender<Task<T, K>>: Send, Receiver<Task<T, K>>: Send,

§

impl<T, K> Sync for SimpleTaskQueue<T, K>
where Arc<DashMap<K, i64>>: Sync, Sender<Task<T, K>>: Sync, Receiver<Task<T, K>>: Sync,

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> 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, 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.