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>
impl<T, K> SimpleTaskQueue<T, K>
Sourcepub fn new_with_capacity(capacity: usize) -> SimpleTaskQueue<T, K>
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.
Sourcepub fn new_with_config(
capacity: usize,
finished_task_ttl: Duration,
running_task_timeout: Duration,
background_task_interval: Duration,
) -> SimpleTaskQueue<T, K>
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_ttlcontrols how long terminal task statuses and their idempotency keys remain retained.running_task_timeoutcontrols how long a task may remainTaskState::Runningbefore being markedTaskState::Failed.background_task_intervalcontrols 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.
Sourcepub fn new() -> SimpleTaskQueue<T, K>
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.
Sourcepub fn submit_task(&self, payload: T) -> Result<TaskId, TaskError>
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.
Sourcepub fn submit_task_with_key(
&self,
task_key: impl Into<TaskKey<K>>,
payload: T,
) -> Result<TaskId, TaskError>
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.
Sourcepub fn get_task_status(&self, task_id: TaskId) -> Result<TaskStatus, TaskError>
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.
Sourcepub fn try_pop_task(&self) -> Option<Task<T, K>>
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.
Sourcepub async fn pop_task(&self) -> Result<Task<T, K>, TaskError>
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.
Sourcepub fn mark_task_success(&self, task_id: TaskId) -> Result<(), TaskError>
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.
Sourcepub fn mark_task_failed(&self, task_id: TaskId) -> Result<(), TaskError>
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>
impl<T, K> Default for SimpleTaskQueue<T, K>
Source§impl<T, K> Drop for SimpleTaskQueue<T, K>
impl<T, K> Drop for SimpleTaskQueue<T, K>
Source§impl<T, K> TaskQueue<T, K> for SimpleTaskQueue<T, K>
impl<T, K> TaskQueue<T, K> for SimpleTaskQueue<T, K>
Source§fn submit_task(&self, payload: T) -> Result<TaskId, TaskError>
fn submit_task(&self, payload: T) -> Result<TaskId, TaskError>
Source§fn submit_task_with_key(
&self,
task_key: TaskKey<K>,
payload: T,
) -> Result<TaskId, TaskError>
fn submit_task_with_key( &self, task_key: TaskKey<K>, payload: T, ) -> Result<TaskId, TaskError>
Source§fn get_task_status(&self, task_id: TaskId) -> Result<TaskStatus, TaskError>
fn get_task_status(&self, task_id: TaskId) -> Result<TaskStatus, TaskError>
task_id.