Tasker Reservations

A vovtasker may be reserved for one or more:
  • Users
  • FairShare groups
  • OS groups
  • Jobclasses
  • Job projects
  • Jobs
  • Buckets

The reservation is always for a specific period of time, starting at any time and ending some time in the future. If the end time is in the past, the reservation is ignored and removed. The reservation can be very long, for example thousands of days.

A tasker can have multiple reservations at any time. Jobs that do not match any reservation are not sent to the tasker if the tasker is reserved. For example:
  • If the tasker is reserved for a user, only jobs submitted by that user may be dispatched to that tasker.
  • If the tasker is reserved for a group, only jobs from that group may be dispatched to that tasker.
  • If the tasker is reserved for a user and a group, only jobs submitted by that user who belongs to that group may be dispatched to that tasker.

Negated Reservations

Taskers may also be reserved for a negated set, in order to prevent access to the tasker by jobs that match members of the set. To negate a tasker reservation, simply place a not symbol "!" at the beginning of the reservation expression. For example, the command vovtaskermgr reserve -user '!john,mary' -duration 1h tasker1 will allow the tasker named tasker1 to run jobs from any user except john and mary for 1 hour. Any valid reservation expression can be negated.
Note: If you are negating a list, use the not symbol ONLY at the beginning of the list; you should NOT place a "!" before every item.

Persistent Reservations

Reservations are persistent. If you stop a tasker and restart another one with the same name, the new tasker will inherit the persistent reservation of the old tasker. Expired reservations are removed frequently.

If a tasker is renamed, the corresponding reservations get updated too. So, the reservations do not get lost.
Reservation rules
Only reservations with end time later than the current time are valid.
There can be multiple reservations on a vovtasker. But there is only one active reservation. If there is already an active reservation, a new reservation overlapping time with the active reservation can be created but ignored. When the active reservation expires (end time passes current time), a new active reservation with earliest start time is picked.
Reservation only applies to normal (direct) taskers or BPS agents. Making reservations on indirect taskers is not allowed.
Duplicate reservations
A new reservation can be created if the reservation is different from existing reservations. Two reservations are the same if the following attributes of reservations are the same. All of these attributes can be specified when creating a reservation using vtk_reservation_create. If a reservation is created through vovtaskermgr, vtk_tasker_reserve, and taskers.tcl, start time and end time are not used as identifiers. The existing reservation with the same other attributes are updated with the new start time and end time. If there is no existing reservation, a new reservation is created.
type
Always tasker if the reservation is for tasker.
what
List of tasker names that this reservation is reserving
start time
Reservation start time
end time
Reservation end time
user
Reservation is for these users
group
Reservation is for these groups
osgroup
Reservation is for these osgroups
jobclass
Reservation is for these jobclasses
jobproj
Reservation is for these jobprojects
bucketid
Reservation is for these bucket IDs
id
Reservation is for these job IDs

Reserve a vovtasker

There are several ways to create a new reservation.

vovtaskermgr, taskers.tcl, and vtk_tasker_reserve creates a new reservation, but if there is an overlapping reservation with the same parameters, the existing one is updated with new start_time and end_time. These are the same with running vtk_reservation_create with the -update option.

On the Command Line: vovtaskermgr reserve

The syntax is:
% vovtaskermgr reserve [options] <taskers_list> 
where the options could be:
-user
Comma separated list of users
-group
Comma separated list of groups
-jobproj
Comma separated list of job projects
-jobclass
Comma separated list of job classes
-osgroup
Comma separated list of OS groups
bucketid
Comma separated list of bucket IDs
-id
Comma separated list of job IDs
-start
Start time
-end
End time
-cancel
<tasker_list>
List of tasker names to reserve.
For example, the following command reserves taskers jupiter and alpaca for user john for 3 hours starting from now.
% vovtaskermgr reserve -user john -duration 3h jupiter alpaca
With -cancel option, all reservations on the specified tasker(s) will be removed.
% vovtaskermgr reserve -cancel jupiter alpaca
The following command shows all reservations for taskers.
% vovtaskermgr reserveshow

In the taskers.tcl File

This is useful to reserve a tasker from the instant it is created. Use option -reserve of vtk_tasker_define.

The reservation expression argument to the -reserve option takes space-separated list of key value pairs, where the key is one of USER, GROUP, JOBCLASS, JOBPROJ, BUCKET, DUR, QUANTITY. If the key is DUR, the value is a time spec. If not specified, the default duration is 1 year. For the other keys, the value is a comma-separated list.

Examples:
vtk_tasker_define jupitar -reserve "USER john,mary JOBCLASS spectre"
vtk_tasker_define alpaca -reserve "JOBPROJ chipa,chipb DUR 3w"

The old form GROUP/USER/DURATION is accepted. The GROUP and USER parts are optional, but the separators ('/', the forward-slash character) must be present. The duration is expressed as a VOV timespec, e.g. 2d for two days. If only digits are present, the value is interpreted as seconds.

-reserve is passed to vovtasker executable as -e option. If advanced users want to run a tasker with -e option for initial reservation, the syntax is the same as vtk_tasker_define -reserve option.

Reserving a Tasker via the Browser

Open the tasker page to reserve a particular tasker. It is at the URL /tasker/taskerId. Fill out a simple form, indicating which user, group, OS group, job class, and/or job project for this tasker is to be reserved, as well as start time and duration. After you select the duration, the form will be submitted.

Click Forget to cancel the tasker reservation, if you are ADMIN.

vtk_tasker_reserve Tcl Interface

With Tcl, you can use vtk_tasker_reserve. The syntax is:
vtk_tasker_reserve taskerId [-user <user1,user2,...>]
                          [-group <group1,group2,...>] 
                          [-osgroup <osgroup1,osgroup2,...>]
                          [-jobclass <jobclass1,jobclass2,...>]
                          [-jobproj <jobproj1,jobproj2,...>]
                          [-bucketid <bucketid1,bucketid2,...>]
                          [-id <jobid1,jobid2,...>]
                          [-start <starttime>]
                          [-end <endtime>]
                          [-duration <reserved_duration>]
For example, the following line will clear (cancel) all reservations on tasker 00001230, if there is one. Otherwise, this doesn't have any effect.
vtk_tasker_reserve 00001230
The following line reserves tasker 00001230 for user john for 3 hours starting from now.
vtk_tasker_reserve 00001230 -user john -duration 3h
This reserves tasker 00001230 for user john in group alpha for 2 weeks starting from one hour from now.
vtk_tasker_reserve 00001230 -user john  -group alpha  -start [clock scan "1 hour"]  -duration 2w

vtk_reservation_create Tcl Interface

You can use vtk_reservation_create in a Tcl interface. This is a new interface introduced in 2017 version to support multiple reservations per tasker.

The syntax is:
vtk_reservation_create <type> <what> <quantity> <start_time> <end_time> [options]
where:
<what>
Comma separated list of tasker names
<quantity>
Not used for tasker reservations
<start_time>
Reservation start time
<end_time>
Reservation end time
And the options could be:
-user
Comma separated list of users
-group
Comma separated list of groups
-osgroup
Comma separated list of OS groups
-jobclass
Comma separated list of jobclasses
bucketid
Comma separated list of bucket IDs
-id
Comma separated list of job IDs
-update
For example, the following Tcl script creates a reservation for host1 and host2. It reserves 4 slots of each host. It returns ID for the reservation. The ID can be used to update and delete the reservation.
set now [clock seconds]
vtk_reservation_create tasker 'host1,host2' 1 $now [expr $now+3600] -user brian

If all attributes are the same as one of existing reservations, vtk_reservation_create will return nochange.

With -update option, it looks for a reservation which has same attributes except start_time and end_time but the reservation period is overlapping. If there is one, the existing reservation is updated with start_time and end_time.
set now [clock seconds]
set end [expr $now+3600]
set end2 [expr $now+7200]
vtk_reservation_create tasker localhost 1 $now $end -user john #creates a new reservation
vtk_reservation_create tasker localhost 1 $now $end -user john #returns "nochange"
vtk_reservation_create tasker localhost 1 $now $end -group g1  #creates a new reservation
vtk_reservation_create tasker localhost 1 $now $end2 -user john -update #updates the first

Manage Reservations

To show all existing reservations, use:
% vovshow -reservations
To forget all reservations, use:
% vovforget -allreservations
% vovforget <reservationId>
Reservations data is accessible with vovselect as well.
% vovselect id,reserveuser,reservestart,reserveend from reservations

vtk_reservation_get Tcl Interface

vtk_reservation_get <reservationId> <variable> provides the details about a reservation.
vtk_reservation_get 21673 info
parray info
Prints out the following information:
info(id)              = 21673
info(quantity)        = 1
info(reservebucketid) = 
info(reservecreated)  = 1513026518
info(reservedby)      = jin
info(reserveend)      = 1513199318
info(reservegroup)    = 
info(reserveid)       = 
info(reservejobclass) = 
info(reservejobproj)  = 
info(reserveosgroup)  = 
info(reservestart)    = 1513026518
info(reserveuser)     = jin
info(type)            = tasker
info(what)            = local2
vtk_reservation_update <reservationId> <fieldname> <new_value> updates a field of reservation with a new value. Available field names can be found by vovselect fieldname from reservations on the command line.
vtk_reservation_update 21673 RESERVEUSER robert
vtk_reservation_delete <reservationId> removes the reservation.
vtk_reservation_delete 21673 

Number of Reservations and System Performance

Many reservations on each tasker may slow down the system. Upon choosing the right tasker to run a job, the algorithm considers all reservations. It is recommended to use the limited number of reservations per tasker. By default, the maximum number of reservations per tasker is set as 10 and this is configurable through a server parameter tasker.max.reserve in policy.tcl.