Struct Queue 

pub struct Queue { /* private fields */ }

A queue on disk.

Implementations

impl Queue

pub fn open() -> Self

The operator’s queue, <home>/queue.

pub fn at(root: PathBuf) -> Self

A queue at an explicit root. Tests use this; so could an operator who wants a queue per project.

pub fn root(&self) -> &Path

Directory holding the task files.

pub fn path_of(&self, id: &str) -> PathBuf

Path for one task id.

pub fn put(&self, task: &mut Task) -> Result<()>

Write a task, atomically, so a daemon killed mid-write leaves the previous state readable rather than a truncated file.

pub fn get(&self, id: &str) -> Result<Task>

Load a task by id or unambiguous id prefix.

pub fn remove(&self, id: &str, in_flight: bool) -> Result<String>

Remove a task, and the claim lock that belongs to it.

in_flight comes from the caller — a live daemon’s heartbeat naming this task — because the task’s own running status cannot answer the question. A daemon killed mid-competition leaves the status at running and an orphaned .lock behind, and a guard that trusted either would make the task undeletable for good: the phone showed exactly that, refusing a task whose daemon had been gone for an hour.

So the lock is removed with the task rather than respected. Any lock still there once no live daemon claims the task is by definition stale, and leaving it would make a deleted task look claimed to Queue::claim and to whoever reads the directory.

pub fn list(&self) -> Vec<Task>

Every task on disk, highest priority first and newest first within a priority. This is what magi task list and GET /api/queue print, so a raised priority has to move a task here the moment it is saved, not only in Queue::next_runnable’s own ordering - the operator reading the backlog and the loop about to drain it must agree on what “first” means. Every existing task defaults to priority 0, so this is a no-op change from the old newest-first order for a queue nobody has reprioritised.

Unreadable files are skipped rather than fatal: one corrupt task must not take the queue - or the web UI, or an unattended daemon - down with it.

pub fn next_runnable(&self) -> Option<Task>

The task a daemon should run next, or None when the queue is idle.

Highest priority first, oldest first within a priority, so a burst of agent-filed work cannot starve the task a human filed this morning.

pub fn claim(&self, id: &str) -> Result<Claim>

Take exclusive ownership of a task.

The lock is a create_new file next to the task, which is atomic on every platform magi targets. It exists so two daemons - or a daemon and a human running magi run - cannot drive one task into two competing runs. The returned guard releases on drop, including on panic.

pub fn resolve_id(&self, prefix: &str) -> Result<String>

Expand an id prefix to exactly one task id.

pub fn revision(&self) -> u64

Change detection token for the queue.

Combines file names and modification times of all task files in the queue, so adding, modifying, or deleting any task — even an older one — moves the revision and notifies connected clients via the change stream. Returns 0 when the queue is completely empty.

Trait Implementations

impl Clone for Queue

fn clone(&self) -> Queue

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Queue

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

Formats the value using the given formatter.