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, questions: &Questions, ) -> Result<Removal>

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.

Anything still blocked on the id just deleted is quarantined to a machine hold in the same call - see Removal::quarantined - rather than left to wait on a dependency that no longer exists. Best-effort: a dependent claimed by something else right now, or one whose write fails, is simply left for crate::daemon::resolve_blockers’s own poll (or crate::triage::run_once) to catch on its own next pass, and does not fail this removal.

questions is the store missing_blockers checks a blocked_by id against before calling it gone - the same store the caller already resolves id’s own home from, passed in rather than reopened here so a test queue at an explicit root is never quarantined against the operator’s real questions 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 superseded(&self) -> HashMap<String, String>

Runs that a later attempt at the same task replaced, mapped to the id of the attempt that replaced them.

A task keeps its attempts in order, and the deck showed them as two cards with the same title and no hint which was which: yukimemi asked why stalled and blocked appeared twice for one task, and the answer - “those are two tries, and the second one exists because of a bug since fixed” - was not on the screen anywhere.

Read from the queue rather than stored on the run, because the ordering is the queue’s fact: a RunState has no idea another attempt happened after it.

pub fn superseded_by(&self, run: &str) -> Option<String>

Whether run is an earlier attempt a later one replaced, and if so the id of that later attempt.

Same walk as Queue::superseded, narrowed to one run: a run detail page asks about exactly one run at a time, and this keeps that call site from building (and discarding) the whole map’s HashMap just to read one entry out of it.

pub fn latest_attempt(&self, run: &str) -> Option<String>

The task’s own most recent attempt, when run belongs to that task but is not already that attempt.

Distinct from Queue::superseded_by, which names only the very next attempt: a chain of retries (A superseded by B superseded by C) leaves an older run pointing at an intermediate one that may itself be unresolved, and a run’s own detail page needs to know where the task’s story currently stands - the chain’s current head, C - not an attempt in the middle of it that a client would otherwise have to walk to by hand.

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) -> Self

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.