RBULK-DISPATCHD(1)

NAME
rbulk-dispatchd - spawn parallel jobs

SYNOPSIS
rbulk-dispatchd -h
rbulk-dispatchd [-c file] [-b dir] [-s dir] [-l user] [-g group] [-d delay] [-o length] [-f]

DESCRIPTION
rbulk-dispatchd is a daemon that listens for job requests on a local domain socket. For each request, it spawns parallel jobs, according to its configuration file and the requested job. rbulk-dispatch(1) can be used to send requests from the command line in a convenient way. When rbulk-dispatchd is used in combination with rbulk-watchd(1) and rbulk-notify(1), it can spawn jobs on remote machines.

By default, the configuration file is read from /opt/openrobots/etc/rbulk-dispatch.conf. and the control socket is bound on /var/run/rbulk-dispatchd.

The following options can change the defaults:

-h  Print usage summary and exit.

-b dir
    Create the control socket in dir/rbulk-dispatchd.

-s dir
    Enable the generation of the rbulk-dispatchd.html HTML status report in dir. The file is self-contained, so that it can be browsed locally, i.e. without a web server proper. The report is updated each time a job starts or stops and when jobs produce new output.

-c file
    Read configuration from file.

-l user
    Run as the user user. Only programs initially run as root will be able to switch to a different user.

-g group
    Switch to group. See also -l.

-d delay
    Set the grace delay between the time of reception of a job request and the time when the job is actually spawned. This can be used to prevent suboptimal ordering of jobs when several of them are sent in very small amount of time.

-o length
    Keep that many jobs in the history of each run queue. This is useful only in combination with -s The default history length is 7 jobs.

-f  Run in the foreground and do not detach from the controlling terminal. Diagnostic messages are printed on stderr instead of syslog(3).

SIGNALS
Sending SIGHUP to a running rbulk-dispatchd will reload the configuration file. If an invalid parameter is found in the configuration file upon the reload, the process will exit. Any other termination signal (SIGINT, SIGQUIT, SIGTERM, ...) will stop the program.

Before stopping or restarting, any running job that is interruptible is killed, but not waited for. Waiting for running jobs may upset init(8) and rbulk-dispatchd dislikes receiving SIGKILL. The current state of all run queues is saved in /var/run/rbulk-dispatchd.save (or in dir/rbulk-dispatchd.save if -b option was used). When rbulk-dispatchd is started, or restarted, it checks for a state file and reschedules the corresponding jobs.

CONFIGURATION FILE
The configuration file is a text file with one directive per line. Empty lines are ignored and the # character defines comments that extend up to the end of the line. A \ character at the end of the line marks a continuation line.

The configuration is divided into named sections introduced by the square bracket character ([]). Two section types are recognized: groups and jobs.

  [ group name ]
A group is introduced by a section of type group and a unique name. The configuration file can define any number of groups. The following definitions are recognized within a group:

desc human readable description
    Attaches a human readable text to the group name. This is used only in displayed messages.

slot name [description]
    Defines a new slot name, optionally followed by a human readable description. A slot is a resource that can execute exactly one job at a time. Slots are purely virtual and do not map to any software or hardware like a thread or a CPU. It is up to the end user to attach a semantics to a slot.

parallel n
    Defines the number of slots that can be simultaneously active within the current group. Thus, no more that n processes will be running in parallel in that group.

  [ job name|pattern|/regex/ ]
A job is introduced by a section of type job and a unique name, pattern or regex. A job name may contain only characters from the range [a-zA-Z0-9_/:-]. A pattern may use the additional [], ? and * wildcards and is compared with fnmatch(3) against user submitted jobs. If the job name starts and ends with `/', it is interpreted as a regular expression conforming to re_format(7).

The configuration file can define any number of jobs. The following definitions are recognized within a job:

desc human readable description
    Attaches a human readable text to the job name. This is used only in displayed messages.

cost n
    Defines the relative cost of this job, in terms of slot allocation. This affects how many parallel slots might run with respect to each group parallel setting.

    Allowed values range from 0 to 255. A cost of 0 indicates that there is no limit on the number of slots for this job. Otherwise, the number of parallel instances times the cost must remain less that parallel on each group where the job runs. The default cost is 1.

slot pattern [prio n]
    Defines a list of target slots where the job is to be run. Each occurence of %j in pattern is replaced by the actual job name. This is useful is the job name was defined with a pattern or a regex. If the job name was defined with a regex, `%#', where `#' is a digit, is replaced by the text matched by the corresponding backreference expression (see re_format(7)). The resulting pattern is then matched with fnmatch(3) against the list of all currently defined slots.

    Any number of slot directives can be given, and the different lists are simply concatenated and uniquified. If a slot is added multiple times, only the last directive applies.

    An optional priority between 0 (highest) and 255 (lowest) can be given. This is used to prioritize different jobs, see JOB EXECUTION. The default priority is 255.

group pattern [prio n]
    This is similar to the slot directive, but it matches groups instead. All slots that belong to a matching group are added as a target for the job.

init command [args...]

exec command [args...]

fini command [args...]
    Define the commands that are run when the job is executed on a slot. Only exec is mandatory; init and fini are optional and may define initialization or finalization commands that are executed respectively before and after the exec command. If the init command fails, the whole job execution stops, while the fini command is always executed no matter the result of the exec command.

    Each occurence of `%j' in the command or its arguments is replaced by the actual job name. Similarly, each occurence of `%s' is replaced by the current slot name at the time of execution. If the job name was defined with a regex, `%#', where `#' is a digit, is replaced by the text matched by the corresponding backreference expression (see re_format(7)).

    The resulting string is then passed to sh(1) using the -c flag; interpretation, if any, is performed by the shell.

kill command [args...]
    Defines an interruption command that is assumed to be able to stop a running instance of the job. The command is run only if the job is running the exec command, and rbulk-dispatchd needs to interrupt it (for instance, if a higher priority job was requested). If the job is running the init or fini command, the kill command is not run. However, an interrupted job running the init command will stop immediately after it, and not run the exec or fini commands. In addition to the %j and %s replacements, %p strings are replaced by the pid of the running command. Jobs without a kill command are not interruptible. In a similar manner, if a kill command does not actually interrupt a running job, no further action will be taken and the job will just run as normal.

JOB EXECUTION
rbulk-dispatchd starts with all slots idle. As soon as a new job is requested, it is scheduled in the run queue of all the target slots defined in the job configuration. Each time new job requests arrive, they are pushed to the run queues of their slots according to the following rules:

•   Each instance of a job on a slot is scheduled after all jobs of higher or equal priority, delaying the jobs of lower priority.

•   If the slot is running a lower priority job with a kill switch, the running job is cancelled by spawning the kill command. The running job is considered terminated only when both the exec and kill commands have completed.

•   If the slot is running the exact same job as new requested one, the running job is also cancelled as above. This behaviour can be changed by defining a job without a kill command.

As soon as one or several slots are idle and new jobs are ready to run, rbulk-dispatchd waits for the expiration of a grace delay (-d). If no new request has been received meanwhile, new jobs are popped from the head of the run queue. The grace delay ensures a proper ordering of different jobs received in a short amount of time. The selection of the next job to run is done according to the following rules:

•   A list of cadidate jobs is poped from the run queue of all currently idle slots.

•   The list is sorted by priority. Jobs of same priority are sorted in a random order.

•   New jobs are spawned by processing the resulting list in order, and jobs are put in the run queue until the maximum number of parallel jobs is reached.

•   As soon as a jobs completes, the scheduler iterates from the first point.

Clients that have requested jobs, for instance via rbulk-dispatch(1), are terminated when all requested jobs either have completed, or have been cancelled by other requets.

FILES
/opt/openrobots/
etc/rbulk-dispatch.conf
share/examples/rbulkit/rbulk-dispatch.conf
/var/run/rbulk-dispatchd

SEE ALSO
rbulk-dispatch(1), rbulk-watchd(1).