TSP(1)

📦
version 1.0.3 · 5 versions
, in ubuntu questing, ubuntu resolute, ubuntu stonking

💖 TSP(1) 💖

okay bestie, so this is the manual for tsp, from the General Commands Manual section. yes we're doing manpage reading, it's giving study date energy, and honestly? you're gonna eat this up. 🍓

✨ NAME ✨

tsp — task spooler. A simple unix batch system. 🫶

🌈 SYNOPSIS 🌈

tsp [actions] [options] [command...]

Actions: [-KClhV] [-t [id]] [-c [id]] [-p [id]] [-o [id]] [-s [id]] [-r
[id]] [-w [id]] [-k [id]] [-u [id]] [-i [id]] [-U <id-id>] [-S [num]]

Options: [-nfgmd] [-L <label>] [-D <id>]

like, that's the whole vibe of how you talk to it 💅

🦋 DESCRIPTION 🦋

so by default, tsp runs a per user unix task queue. that's it, that's the whole personality. you can:

  • add commands to the queue ✨
  • watch that queue whenever you want, at any moment, no cap 👀
  • look at the task results (which is literally the standard output and the exit error) 💖

🎀 SIMPLE USE 🎀

  • call tsp with a command → that command gets added to the queue
  • call it without commands or parameters → you get the task list

that's it. iconic. main character energy fr fr. 👑

💅 COMMAND OPTIONS 💅

when you're adding a job to ts, you get to pick how it runs and how the results get collected. obsessed with the customization tbh:

  • -n — do not store the standard output/error in a file at $TMPDIR; let it use the file descriptors decided by the calling process instead. if you don't use this, the jobid for the new task gets output to stdout. 🫶
  • -g — pass the output through gzip (only if -n). heads up bestie: the output files will not have a .gz extension. sneaky!
  • -f — do not put the task into background. wait for the queue and the command to run without getting detached from the terminal. the exit code will be that of the command, and if you use it together with -n, no result will be stored in the queue. 🧚
  • -m — mail the results of the command (output and exit code) to $TS_MAILTO, or to the $USER using /usr/sbin/sendmail. look at ENVIRONMENT, i linked it below like a good bestie 💌
  • -L <label> — add a label to the task, and it'll show up next to its command when you list the queue. makes distinguishing similar commands with different goals way comfier. so cute. 🏷️
  • -d — run the command only if the command before it finished well (errorlevel = 0). this new enqueued task depends on the result of the previous command. if the task is not run, it's considered as failed for further dependencies. 😭
  • -D <id> — run the command only if the job of the given id finished well (errorlevel = 0). this new enqueued task depends on the result of the previous command. if the task is not run, it is considered as failed for further dependencies. and if the server doesn't have the job id in its list, it'll be considered as if the job failed. 💀
  • -B — in the case the queue is full (due to TS_MAXCONN or system limits), by default ts will block the enqueuing command. with -B, if the queue is full it exits returning the value 2 instead of blocking. bye bestie 👋
  • -E — keep two different output files for the command stdout and stderr. stdout goes to the file announced by ts (look at -o), and stderr goes to the stdout file with an additional ".e". for example, /tmp/ts-out.SKsDw8 and /tmp/ts-out.SKsDw8.e. only the stdout file gets created with mkstemp, ensuring it doesn't overwrite any other; the ".e" will be overwritten if it existed. 🙈
  • -N <num> — run the command only if there are num slots free in the queue. without it, the job will run if there's one slot free. like, if you use the queue to feed cpu cores and you know a job is gonna take two cores, -N lets you tell ts that. so considerate. 🧠

⭐ ACTIONS ⭐

instead of giving a new command, you can use the parameters for other purposes. multitasking queen:

  • -K — kill the tsp server for the calling client. this removes the unix socket and all the tsp processes related to the queue. it will not kill the command being run at that time.
also, do not trust that tsp -K will finish when the server is really killed. by now it's a race condition. we're just living with it bestie 😭
  • -C — clear the results of finished jobs from the queue. clean girl aesthetic 🧼
  • -l — show the list of jobs — to be run, running, and finished — for the current queue. this is the default behaviour if tsp is called without options. the default! iconic.
  • -t [id] — show the last ten lines of the output file of the named job, or the last running/run one if you don't specify. if the job is still running, it keeps showing the additional output until the job finishes. on exit, it returns the errorlevel of the job, as in -c. 👀
  • -c [id] — run the system's cat to the output file of the named job, or the last running/run if not specified. it will block until all the output can be sent to standard output, and will exit with the job errorlevel as in -c. 😌
  • -p [id] — show the pid of the named job, or the last running/run if not specified. 🆔
  • -o [id] — show the output file name of the named job, or the last running/run if not specified. 📄
  • -s [id] — show the job state of the named job, or the last in the queue. 🚦
  • -r [id] — remove the named job, or the last in the queue. 🗑️
  • -w [id] — wait for the named job, or for the last in the queue. ⏳
  • -k [id] — kill the process group of the named job (SIGTERM), or the last running/run job if not specified. equivalent to kill -- -ts -p`` 💀
  • -u [id] — make the named job (or the last in the queue) urgent — this means it goes forward in the queue so it can run as soon as possible. skip the line, princess treatment 💅
  • -i [id] — show information about the named job (or the last run). it'll show the command line, some times related to the task, and also any information resulting from TS_ENV (look at ENVIRONMENT). 🕵️
  • -U <id-id> — interchange the queue positions of the named jobs (separated by a hyphen and no spaces). 🔄
  • -h — show help on standard output. 🆘
  • -V — show the program version. ✨

🌸 MULTI-SLOT 🌸

okay so tsp by default gives you a queue where each job runs only after the previous one finished. but!! you can change the maximum number of jobs running at once with the -S [num] parameter. we call that number the amount of slots. you can also set the initial number of jobs with the environment variable TS_SLOTS. 🔥

  • when you increase this setting, queued waiting jobs will run at once until reaching the maximum set.
  • when you decrease this setting, no other job will be run until it can meet the amount of running jobs set.

when you use an amount of slots greater than 1, the action of some commands may change a bit. for example, -t without a jobid will tail the first job running, and -d will try to set the dependency with the last job added. lowkey a whole different vibe at that point.

  • -S [num] — set the maximum amount of running jobs at once. if you don't specify num, it will return the maximum amount of running jobs set. 🎚️

🧚 ENVIRONMENT 🧚

  • TS_MAXFINISHED — limit the number of job results (finished tasks) you want in the queue. use this if you are tired of -C. we've all been there. 😮‍💨
  • TS_MAXCONN — the maximum number of ts server connections to clients. this makes the ts clients block until connections are freed. it helps, for example, on systems with a limited number of processes, because each job waiting in the queue remains as a process. this variable has to be set at server start, and cannot be modified later. no takebacks. 🚫
  • TS_ONFINISH — if the variable exists pointing to an executable, it will be run by the client after the queued job. it uses execlp, so PATH is used if there are no slashes in the variable content. the executable is run with four parameters: jobid errorlevel output_filename and command. 🎬
  • TMPDIR — as the program output and the unix socket are thought to be stored in a temporary directory, TMPDIR will be used if defined, or /tmp otherwise. 🗂️
  • TS_SOCKET — each queue has a related unix socket. you can specify the socket path with this environment variable. this way, you can have a queue for your heavy disk operations, another for heavy use of ram., and have a simple script/alias wrapper over ts for those special queues. if it's not specified, it will be $TMPDIR/socket-ts.[uid]. multiple queues = multiple personalities, slay 🔌
  • TS_SLOTS — set the number of slots at the start of the server, similar to -S, but the contents of the variable are read only when running the first instance of tsp. 🎰
  • TS_MAILTO — send the letters with job results to the address specified in this variable. otherwise, they're sent to $USER or, if not defined, nobody. the system /usr/sbin/sendmail is used. the job outputs are not sent as an attachment, so understand the consequences if you use the -gm flags together. 📬
  • USER — as seen above, it's used for the mail destination if TS_MAILTO isn't specified. 🙋
  • TS_SAVELIST — if it's defined when starting the queue server (probably the first tsp command run), on SIGTERM the queue status will be saved to the file pointed by this environment variable — for example, at system shutdown. saving your progress, so responsible 💾
  • TS_ENV — this has a command to be run at enqueue time through /bin/sh. the output of the command will be readable through the option -i. you can use a command which shows relevant environment for the command run. for example, you may use TS_ENV='pwd;set;mount'. ✨

💜 FILES 💜

  • /tmp/ts.error — if tsp finds any internal problem, you should find an error report there. please send this to the author as part of the bug report. 🐛

💀 BUGS 💀

tsp expects a simple command line. it does not start a shell parser. if you want to run complex shell commands, you may want to run them through sh -c 'commands...'

also, remember that stdin/stdout/stderr will be detached, so do not use your shell's redirection operators when you put a job into background. you can use them inside the sh -c in order to set redirections to the command run. bestie i'm begging you 🙏

if an internal problem is found in runtime, a file /tmp/ts.error is created, which you can submit to the developer in order to fix the bug. 📮

🔍 SEE ALSO 🔍

👑 AUTHOR 👑

Lluis Batlle i Rossell

📝 NOTES 📝

this page describes tsp as in version 1.0. other versions may differ. the file TRICKS found in the distribution package can show some ideas on special uses of tsp. go read it, i know you want to 🦋

and that's the whole thing, bestie!! 💖 this page is describing Task Spooler 1.0.3, dated 2020-12 — yes, vintage, yes still iconic, we stan a classic. now go queue something up and be the main character of your own batch system 🌈✨🎀

📦 where this page comes from