.\" Copyright Lluís Batlle i Rossell

.\"

.\" This file may be copied under the conditions described

.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998

.\" that should have been distributed together with this file.

.\" 

.\" Note: I took the gnu 'ls' man page as an example.

.TH TS 1 2020-12 "Task Spooler 1.0.3"

.SH NAME

ts \- task spooler. A simple unix batch system

.SH SYNOPSIS

.BI "ts [" actions "] [" options "] [" command... ]

.sp

Actions:

.BI "[\-KClhV]

.BI "[\-t ["id ]]

.BI "[\-c ["id ]]

.BI "[\-p ["id ]]

.BI "[\-o ["id ]]

.BI "[\-s ["id ]]

.BI "[\-r ["id ]]

.BI "[\-w ["id ]]

.BI "[\-k ["id ]]

.BI "[\-u ["id ]]

.BI "[\-i ["id ]]

.BI "[\-U <"id - id >]

.BI "[\-S ["num ]]

.sp

Options:

.BI "[\-nfgmd]"

.BI "[\-L <"label >]

.BI "[\-D <"id >]

.SH DESCRIPTION

.B 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).

.SH SIMPLE USE

Calling

.B ts

with a command will add that command to the queue, and calling it without

commands or parameters will show the task list.

.SH COMMAND OPTIONS

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

results be collected:

.TP

.B "\-n"

Do not store the standard output/error in a file at

.B $TMPDIR

- let it use the

file descriptors decided by the calling process. If it is not used, the

.B jobid

for the new task will be outputed to stdout.

.TP

.B "\-g"

Pass the output through gzip (only if

.B \-n

). Note that the output files will not

have a .gz extension.

.TP

.B "\-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.

.TP

.B "\-m"

Mail the results of the command (output and exit code) to

.B $TS_MAILTO

, or to the

.B $USER

using

.B /usr/sbin/sendmail.

Look at

.B ENVIRONMENT.

.TP

.B "\-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.

.TP

.B "\-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.

.TP

.B "\-D <id>"

Run the command only if the job of given id 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.

If the server doesn't have the job id in its list, it will be considered

as if the job failed.

.TP

.B "\-B"

In the case the queue is full (due to \fBTS_MAXCONN\fR or system limits),

by default ts will block the enqueuing command. Using \fB\-B\fR,

if the queue is full it will exit returning the value 2 instead of blocking.

.TP

.B "\-E"

Keep two different output files for the command stdout and stderr. stdout goes to

the file announced by ts (look at \fB\-o\fR), 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 \fBmkstemp\fR, ensuring it does not overwrite

any other; the ".e" will be overwritten if it existed.

.TP

.B "\-N <num>"

Run the command only if there are \fbnum\fB slots free in the queue. Without it,

the job will run if there is one slot free. For example, if you use the

queue to feed cpu cores, and you know that a job will take two cores, with \fB\-N\fB

you can let ts know that.

.SH ACTIONS

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

.TP

.B "\-K"

Kill the

.B ts

server for the calling client. This will remove the unix socket and

all the

.B ts

processes related to the queue. This will not kill the command being

run at that time.

It is not reliable to think that

.B ts -K

will finish when the server is really killed. By now it is a race condition.

.TP

.B "\-C"

Clear the results of finished jobs from the queue.

.TP

.B "\-l"

Show the list of jobs - to be run, running and finished - for the current queue.

This is the default behaviour if

.B ts

is called without options.

.TP

.B "\-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 \fB\-c\fR.

.TP

.B "\-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

\fB\-c\fR.

.TP

.B "\-p [id]"

Show the pid of the named job, or the last running/run if not specified.

.TP

.B "\-o [id]"

Show the output file name of the named job, or the last running/run 

if not specified.

.TP

.B "\-s [id]"

Show the job state of the named job, or the last in the queue.

.TP

.B "\-r [id]"

Remove the named job, or the last in the queue.

.TP

.B "\-w [id]"

Wait for the named job, or for the last in the queue.

.TP

.B "\-k [id]"

Kill the process group of the named job (SIGTERM),

or the last running/run job if not specified.

Equivalent to

.B kill -- -`ts -p`

.TP

.B "\-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.

.TP

.B "\-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

\fBTS_ENV\fR (Look at \fBENVIRONMENT\fR).

.TP

.B "\-U <id-id>"

Interchange the queue positions of the named jobs (separated by a hyphen and no

spaces).

.TP

.B "\-h"

Show help on standard output.

.TP

.B "\-V"

Show the program version.

.SH MULTI-SLOT

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

.B "\-S [num]"

parameter. We call that number the

\fIamount of slots\fR. You can also set the initial number of jobs with

the environment variable

.B "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.

.BR

When using an amount of slots greater than 1, the action of some commands

may change a bit. For example, \fB\-t\fR without \fIjobid\fR will tail the first

job running, and \fB\-d\fR will try to set the dependency with the last job added.

.TP

.B "\-S [num]"

Set the maximum amount of running jobs at once. If you don't specify

.B num

it will return the maximum amount of running jobs set.

.SH ENVIRONMENT

.TP

.B "TS_MAXFINISHED"

Limit the number of job results (finished tasks) you want in the queue. Use this

option if you are tired of

.B \-C.

.TP

.B "TS_MAXCONN"

The maximum number of ts server connections to clients. This will make the ts clients

block until connections are freed. This 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.

.TP

.B "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

.B PATH

is used if there are no slashes in the variable content. The executable is run

with four parameters:

.B jobid

.B errorlevel

.B output_filename

and

.B command.

.TP

.B "TMPDIR"

As the program output and the unix socket are thought to be stored in a

temporary directory, 

.B TMPDIR

will be used if defined, or

.B /tmp

otherwise.

.TP

.B "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

.B $TMPDIR/socket-ts.[uid].

.TP

.B "TS_SLOTS"

Set the number of slots at the start of the server, similar to

.B \-S,

but the contents of the variable are read only when running

the first instance of

.B ts.

.TP

.B "TS_MAILTO"

Send the letters with job results to the address specified in this variable.

Otherwise, they are sent to

.B $USER

or if not defined,

.B nobody.

The system

.B /usr/sbin/sendmail

is used. The

job outputs are not sent as an attachment, so understand the consequences if you

use the

.B \-gm

flags together.

.TP

.B "USER"

As seen above, it is used for the mail destination if

.B TS_MAILTO

is not specified.

.TP

.B "TS_SAVELIST"

If it is defined when starting the queue server (probably the first

.B ts

command run), on SIGTERM the queue status will be saved to the file pointed

by this environment variable - for example, at system shutdown.

.TP

.B "TS_ENV"

This has a command to be run at enqueue time through

\fB/bin/sh\fR. The output of the command will be readable through the option

\fB\-i\fR. You can use a command which shows relevant environment for the command run.

For example, you may use \fBTS_ENV='pwd;set;mount'\fR.

.SH FILES

.TP

.B /tmp/ts.error

if

.B ts

finds any internal problem, you should find an error report there.

Please send this to the author as part of the bug report.

.SH BUGS

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

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

.B sh -c

in order to set redirections to the command run.

If an internal problem is found in runtime, a file

.B /tmp/ts.error

is created, which you can submit to the developer in order to fix the bug.

.SH SEE ALSO

.BR at (1)

.SH AUTHOR

Lluis Batlle i Rossell

.SH NOTES

This page describes

.B ts

as in version 1.0. Other versions may differ. The file

.B TRICKS

found in the distribution package can show some ideas on special uses of

.B ts.