filed

Job queue using FUSE

commit d9d9edd1589f9ef86205c5dd24e8c1c3c1029701
parent 02a716cdf4db6c5525a138d368b6f56ad021e186
Author: Marc Coquand <marc@coquand.email>
Date:   Sun, 14 Dec 2025 21:10:23 +0100

Docs

Diffstat:
M
README.md
 | 
21
++++++++++++---------

1 file changed, 12 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
@@ -30,18 +30,22 @@ scdoc < qj.1.scd > qj.1
 
 ## Basic Principles
 
-Below are some examples to get you started. See the [man pages](https://git.sr.ht/~marcc/qj/tree/main/item/qj.1.scd) for more complete documentation
+`qj` is a job queue that operates using files. Each job
+corresponds to one file, and the directories indicate their state
+state. Below are some examples to get you started. See the [man
+pages](https://git.sr.ht/~marcc/qj/tree/main/item/qj.1.scd) for more complete
+documentation
 
-### Creating a job
-
-In one terminal, start the process:
+`qj` requires a job directory and a location for a state file.
 
 ```
 $ mkdir /tmp/qj-jobs
 $ qj /tmp/qj-jobs /tmp/qj-state.db
 ```
 
-In terminal two, create a basic job:
+Once run, `qj` will set up a directory in `qj-jobs` that contains a few files and directories.
+
+A job can easily be added by just creating a file in the pending directory:
 
 ```
 $ printf "echo 'hello world'" > /tmp/qj-jobs/pending/1
@@ -53,9 +57,7 @@ If all went well, you can see the job output:
 $ cat /tmp/qj-jobs/complete/1
 ```
 
-### Restarting a job
-
-By default, a job retries 3 times. Afterward it is moved to the failed directory. To restart it after that, just move the job back to pending:
+By default, a job retries 3 times, and then moved to the `failed` directory. To restart a job after that, move the job back to pending:
 
 ```
 $ mv /tmp/qj-jobs/failed/1 /tmp/qj-jobs/pending
@@ -77,8 +79,9 @@ $ cat /tmp/qj-jobs/active/1
 
 - [nq] - `nq` is simpler and not a persistent process, but does not feature retries. They serve different purposes: `nq` for ad-hoc queuing of command lines. `qj` serves well as a job manager for your server, where you want admins to see jobs and be able to rerun them.
 - [task-spooler] - `ts` has better control over how you want the task executed (GPU or CPU), and a lot of other features. It does (AFAIK) not support retries, which are supported in `qj`.
+- [bull] - `bull` is only for node and javascript. It features a graphical UI, and a few other features not found in `qj`. `qj` eschews a GUI in favor of simple files, allowing it to better interoperate with other systems, and allows it to use regular unix permissions for access management.
 
 [nq]: https://github.com/leahneukirchen/nq
 [task-spooler]: https://github.com/justanhduc/task-spooler
-
+[bull]: https://www.npmjs.com/package/bull