SYNOPSIS

DESCRIPTION

ts
will run by default a per user unix task queue. The user can add commands to
the queue, watch that queue at any moment, and look at the task results
(actually, standard output and exit error).

SIMPLE USE

Calling
ts
with a command will add that command to the queue, and calling it without
commands or parameters will show the task list.

COMMAND OPTIONS

When adding a job to ts, we can specify how it will be run and how will the
results be collected:

-n

Do not store the standard output/error in a file at
$TMPDIR
- let it use the
file descriptors decided by the calling process. If it is not used, the
jobid
for the new task will be outputed to stdout.

-g

Pass the output through gzip (only if
-n
). Note that the output files will not
have a .gz extension.

-f

Don not put the task into background. Wait the queue and the command run without
getting detached of the terminal. The exit code will be that of the command, and
if used 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.

-L <label>

Add a label to the task, which will appear next to its command when listing
the queue. It makes more comfortable distinguishing similar commands with
different goals.

-d

Run the command only if the command before finished well (errorlevel = 0). This new
task enqueued depends on the result of the previous command. If the task is not run,
it is considered as failed for further dependencies.

ACTIONS

Instead of giving a new command, we can use the parameters for other purposes:

-K

Kill the
ts
server for the calling client. This will remove the unix socket and
all the
ts
processes related to the queue. This will not kill the command being
run at that time.

It is not reliable to think that
ts -K
will finish when the server is really killed. By now it is a race condition.

-C

Clear the results of finished jobs from the queue.

-l

Show the list of jobs - to be run, running and finished - for the current queue.
This is the default behaviour if
ts
is called without options.

-t [id]

Show the last ten lines of the output file of the named job, or the last
running/run if not specified. If the job is still running, it will keep on
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.

-u [id]

Make the named job (or the last in the queue) urgent - this means that it goes
forward in the queue so it can run as soon as possible.

-i [id]

Show information about the named job (or the last run). It will 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

ts
by default offers a queue where each job runs only after the previous finished.
Nevertheless, 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 increasing this setting, queued waiting jobs will be run
at once until reaching the maximum set. When decreasing this setting, no other
job will be run until it can meet the amount of running jobs set.
Whenusinganamountofslotsgreaterthan1,theactionofsomecommands
may change a bit. For example, -t without jobid will tail the first
job running, and -d will try to set the dependency with the last job added.

-S <num>

Set the maximum amount of running jobs at once.

ENVIRONMENT

TS_MAXFINISHED

Limit the number of job results (finished tasks) you want in the queue. Use this
option if you are tired of
-C.

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:
jobiderrorleveloutput_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 is not specified, it will be
$TMPDIR/socket-ts.[uid].

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
ts.

TS_MAILTO

Send the letters with job results to the address specified in this variable.
Otherwise, they are 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 is used for the mail destination if
TS_MAILTO
is not specified.

TS_SAVELIST

If it is defined when starting the queue server (probably the first
ts
command run), on SIGTERM the queue status will be saved to the file pointed
by this environment variable - for example, at system shutdown.

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
ts
finds any internal problem, you should find an error report there.
Please send this to the author as part of the bug report.

BUGS

ts
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.

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.