From 1ba96113732edf1180c5e1601821185f606eafb3 Mon Sep 17 00:00:00 2001 From: Jacob Williamson Date: Mon, 6 Jul 2026 10:47:08 +0100 Subject: [PATCH 1/3] Add some docs --- docs/explanations/queue.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/explanations/queue.md diff --git a/docs/explanations/queue.md b/docs/explanations/queue.md new file mode 100644 index 0000000..b8c313f --- /dev/null +++ b/docs/explanations/queue.md @@ -0,0 +1,11 @@ +# Queue + +Items can be added, deleted, and moved around the queue through the REST API. The worker takes bluesky plans from the top of the queue, if one is available, and sends it to blueapi. Once this plan is in progress, it can't be moved or deleted, and no other plan can be sent to blueapi until this one has finished. An experiment's status is `In progress` if any of its underlying plans have started. It is `Complete` once all of its plans have finished. + +The queue can be paused, meaning no plan can be taken and sent to blueapi until the queue is unpaused. This will not pause a plan that is already in progress. While the queue is paused, tasks can still be added, deleted and moved around. + +If an error occurs while running a plan, the queue will be paused, and any remaining plans that need to be run as part of the current experiment will be skipped. + +Once an item is complete, it is added to a history list, which is a chronological list of completed tasks. + +See the [API reference](../reference/rest-api.rst) for how to interact with the queue. From 5c88ecbd1449ce93aa8c60e1517229e4c47e6308 Mon Sep 17 00:00:00 2001 From: Jacob Williamson Date: Mon, 6 Jul 2026 10:54:53 +0100 Subject: [PATCH 2/3] Update docs --- docs/explanations/queue.md | 2 +- docs/explanations/queue_items.md | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/explanations/queue.md b/docs/explanations/queue.md index b8c313f..ecf6807 100644 --- a/docs/explanations/queue.md +++ b/docs/explanations/queue.md @@ -1,6 +1,6 @@ # Queue -Items can be added, deleted, and moved around the queue through the REST API. The worker takes bluesky plans from the top of the queue, if one is available, and sends it to blueapi. Once this plan is in progress, it can't be moved or deleted, and no other plan can be sent to blueapi until this one has finished. An experiment's status is `In progress` if any of its underlying plans have started. It is `Complete` once all of its plans have finished. +Items can be added, deleted, and moved around the queue through the REST API. The worker takes bluesky plans from the top of the queue, if one is available, and sends it to blueapi. Once this plan is in progress, it can't be moved or deleted, and no other plan can be sent to blueapi until this one has finished. The queue can be paused, meaning no plan can be taken and sent to blueapi until the queue is unpaused. This will not pause a plan that is already in progress. While the queue is paused, tasks can still be added, deleted and moved around. diff --git a/docs/explanations/queue_items.md b/docs/explanations/queue_items.md index d0e58e3..9ab2019 100644 --- a/docs/explanations/queue_items.md +++ b/docs/explanations/queue_items.md @@ -5,3 +5,11 @@ The items inside the queue contain either an `Experiment` object or a `TaskReque Allowing both in the queue means you can queue up whole experiments as well as individual bluesky plans. The queue will convert the entire list of experiments and task requests to a list of blueapi calls (the task request objects are already in the right format). See [converters](./converters.md) on how this is done. + +A queue item's status is derived from the status of the underlying bluesky plans it has produced: + +- `Queued` - None of its bluesky plans have started +- `In progress` - At least one of its bluesky plans have started +- `Complete` - All of its bluesky plans have completed successfully +- `Error` - One of its bluesky plans failed +- `Cancelled` - The item was cancelled (removed from the queue) From bb5b1a4ff23e7ed893c5a7ea5d51910ccf8eab50 Mon Sep 17 00:00:00 2001 From: Jacob Williamson Date: Mon, 6 Jul 2026 10:58:03 +0100 Subject: [PATCH 3/3] Re-arrange docs --- docs/explanations/queue.md | 16 ++++++++++++++++ docs/explanations/queue_items.md | 15 --------------- 2 files changed, 16 insertions(+), 15 deletions(-) delete mode 100644 docs/explanations/queue_items.md diff --git a/docs/explanations/queue.md b/docs/explanations/queue.md index ecf6807..8d7c72d 100644 --- a/docs/explanations/queue.md +++ b/docs/explanations/queue.md @@ -1,3 +1,19 @@ +# Queue Items + +The items inside the queue contain either an `Experiment` object or a `TaskRequest` object. These determine which bluesky plans will run. Experiment objects match the format of an experiment in ulims, and can involve multiple bluesky plans. It always contains a sample, experiment definition and instrument session. A TaskRequest object matches the format blueapi expects to receive to run a single plan. + +Allowing both in the queue means you can queue up whole experiments as well as individual bluesky plans. + +The queue will convert the entire list of experiments and task requests to a list of blueapi calls (the task request objects are already in the right format). See [converters](./converters.md) on how this is done. + +A queue item's status is derived from the status of the underlying bluesky plans it has produced: + +- `Queued` - None of its bluesky plans have started +- `In progress` - At least one of its bluesky plans have started +- `Complete` - All of its bluesky plans have completed successfully +- `Error` - One of its bluesky plans failed +- `Cancelled` - The item was cancelled (removed from the queue) + # Queue Items can be added, deleted, and moved around the queue through the REST API. The worker takes bluesky plans from the top of the queue, if one is available, and sends it to blueapi. Once this plan is in progress, it can't be moved or deleted, and no other plan can be sent to blueapi until this one has finished. diff --git a/docs/explanations/queue_items.md b/docs/explanations/queue_items.md deleted file mode 100644 index 9ab2019..0000000 --- a/docs/explanations/queue_items.md +++ /dev/null @@ -1,15 +0,0 @@ -# Queue Items - -The items inside the queue contain either an `Experiment` object or a `TaskRequest` object. These determine which bluesky plans will run. Experiment objects match the format of an experiment in ulims, and can involve multiple bluesky plans. It always contains a sample, experiment definition and instrument session. A TaskRequest object matches the format blueapi expects to receive to run a single plan. - -Allowing both in the queue means you can queue up whole experiments as well as individual bluesky plans. - -The queue will convert the entire list of experiments and task requests to a list of blueapi calls (the task request objects are already in the right format). See [converters](./converters.md) on how this is done. - -A queue item's status is derived from the status of the underlying bluesky plans it has produced: - -- `Queued` - None of its bluesky plans have started -- `In progress` - At least one of its bluesky plans have started -- `Complete` - All of its bluesky plans have completed successfully -- `Error` - One of its bluesky plans failed -- `Cancelled` - The item was cancelled (removed from the queue)