Xi-Batch User Priority Ranges

Understanding Job Priorities

Every job carries a priority. The priority decides where the job sits in the queue, and so the order in which ready jobs are considered for starting when the load level allows another one to run.

• Priority range: 1 to 255
• Higher number, higher priority
• A job is placed ahead of every queued job with a lower priority and behind those with the same or higher

Priority governs order. It does not reserve resources and it does not override the load level ceiling - a high-priority job still waits if starting it would take the system over its load level.

User Priority Settings

Each user has three priority settings, held in the Xi-Batch user file:

Default priority

Given to a job whose submission does not specify one

Minimum priority

The lowest priority this user may ask for

Maximum priority

The highest priority this user may ask for

Values Xi-Batch ships with:

Default: 150
Minimum: 100
Maximum: 200

These are the values written into the default record when the user file is first created, and every user without an entry of their own runs on them. Changing the default record therefore moves every such user - the change is not confined to users added afterwards.

What the Range Constrains

The minimum and maximum are checked in two places:

• At submission - btr, bts, the interactive screens and the network interface all validate the priority before the job reaches the queue
• At change - btjchange -p and the priority field in btq apply the same test

A priority outside the range is refused and nothing is queued or changed. The range belongs to the user making the request, so a job may be given a priority its owner could not have asked for, by an administrator whose own range is wider.

# jsmith has minimum 100, maximum 200

btr -p 90 script.sh
# Refused - invalid priority

btr -p 210 script.sh
# Refused - invalid priority

btr -p 150 script.sh
# Queued

btjchange -p 250 15033
# Refused - invalid priority

Two Deliberate Misconfigurations

Xi-Batch recognises two settings that look like mistakes and treats them as instructions.

Force the user to state a priority

Default: 50   (below the minimum)
Minimum: 100
Maximum: 200

A submission with no -p picks up the default, fails the range test, and is refused with a message telling the user to specify a priority. A submission that names a priority in range succeeds as usual. Setting the default above the maximum has the same effect.

Use case: a production environment where the priority of every job is to be a deliberate choice.

Stop the user submitting at all

Minimum: 200
Maximum: 100

With the minimum above the maximum no priority can satisfy both, and every submission is refused with a message saying the user cannot use Xi-Batch.

The clearer way is to remove the create entry privilege, which refuses the submission on its own terms and shows in the privilege column:

btuchange -u -p -CR jsmith

Viewing Priority Settings

Your own:

btuser -d

Prints your minimum, maximum and default priorities along with your load levels, privileges and default modes. No privilege is required.

All users (requires the read admin file privilege):

# The default listing includes the three priorities
btulist -H

# Just the priorities
btulist -H -F "%u %g %d %l %m"

The format letters are %d default, %l minimum ("lower") and %m maximum. The listing opens with a DEFAULT line giving the settings inherited by users with no entry of their own; -s suppresses it.

User    Group  Defp Minp Maxp
DEFAULT         150  100  200
jsmith  staff   150  100  200
prodops ops     200  180  220

Interactively:

# Read-only, requires read admin file
btuser -v

# Editable, requires write admin file
btuser -i

Setting Priorities

Requires: write admin file privilege

Command line:

# One user
btuchange -u -d 175 jsmith

# Whole range at once, several users
btuchange -u -d 200 -l 180 -m 220 prodops nightops

-u takes no value - it means "act on users", and the user names follow the options. Omitting the names applies the change to every user. The three options are -l minimum, -d default and -m maximum, and each takes a value from 1 to 255.

Interactively, in btuser -i:

1. Move to the user with j and k
2. Press l for the minimum, u for the maximum, d for the default
3. Type the value and press Return

The capitals L, U and D edit the same three settings on the DEFAULT line instead.

Changing the Defaults

# Change the default record only
btuchange -D -d 150 -l 100 -m 200

# Change it and copy the whole default record over every user
btuchange -D -A -d 150 -l 100 -m 200

-D edits the default record and cannot be combined with user names. -A overwrites every user's priorities, load levels, privileges and default modes with the defaults - it is not confined to the priorities. In btuser -i the same operations are a (copy the defaults to the user under the cursor) and A (copy them to every user).

Priority Tiers

Priorities mean whatever a site decides they mean; Xi-Batch attaches no significance to any particular number. A worked example, using the shipped 100-200 as the middle of the road:

btuchange -u -d 200 -l 180 -m 220 prodops
btuchange -u -d 150 -l 120 -m 180 appteam
btuchange -u -d 120 -l 100 -m 140 devteam

Overlapping ranges let a user reach into the next tier when they need to; disjoint ranges stop them. Which you want is a policy question, and the only technical consequence is that a job cannot be given a priority its submitter's range excludes.

Monitoring

Jobs in priority order:

btjlist lists the queue in queue order, which is priority order, so the highest-priority jobs are already at the top. To see the priorities alongside:

btjlist -H -F "%N %p %U %H"

Users whose range reaches high:

btulist -N -s -F "%m %u" | sort -rn

-N drops the header and -s the DEFAULT line, so the sort sees user rows only.

Good Practice

Set the default record first. Most users have no entry of their own, so the default record is the setting that is actually in force for them.

Use load levels for resources and priorities for order. A priority never stops a job from loading the machine; only the load level does that.

Leave room at both ends. The scale runs to 255, and a range that already touches 1 or 255 leaves nowhere to put an exception.

Say what the numbers mean. Xi-Batch enforces the range and nothing else; the meaning of "180" is a local convention and needs writing down.

Check the effect as the user. btuser -d run from their account shows the range they are actually working under.