A reservation is a hold placed against an allocation. Before usage of a resource or service begins, a reservation (or hold) is made against one or more allocations within the requesting user's applicable account(s).Subsequent usage requests will also post reservations while the available balance (active allocations minus reservations) allows. When the usage ends, the reservation is removed and the actual charge is made to the allocation(s). This procedure ensures that usage will only be permitted so long as the requestors have sufficient reserves.

Associated with a reservation is the instance name (name of the item being used such as the job id), the usage record (which contains the item details), a start time and end time for the reservation and a description. The reservation will automatically expire and no longer count against the user's balance after the end time passes. Each reservation will be associated with held amounts from one or more allocations. Operations include creating, querying, modifying and deleting reservations. By default, a standard user may only query reservations attributed to them.

Reservation queries allow the specification of filter options which narrow down the reservations that will be returned. There are two reservation filter types that can be employed: AttributedTo and ImpingesUpon. If ImpingesUpon is used, the query will return all reservations associated with accounts satisfying the filters. For example, Reservation Query FilterType:=ImpingesUpon Filter:=User=scottmo will return all reservations impinging on Accounts usable by scottmo. If AttributedTo is used, the query will return all reservations associated with usage records satisfying the filters. For example, Reservation Query FilterType:=AttributedTo Filter:=User=scottmo will return all reservations for resources or services allocated to scottmo.

When a reservation is created via the UsageRecord Reserve action (e.g. greserve), if another reservation exists with the same instance name, the default behavior is to leave the old reservation in place (and create the new one along side it). This behavior assumes that the other reservation is probably a separate reservation created by a resource or service manager that reuses instance ids. However, alternate behaviors may be specified via the mutually exclusive Modify or Replace options. If the Replace option is specified, any pre-existing reservations with matching instance names will first be deleted, thereby ensuring only one reservation per instance name at a time. If the Modify option is specified, a pre-existing reservation with matching instance name will be modified to have the new properties (but keeping the same reservation id), and can be used to extend a reservation. This might be used with incremental charging to dynamically stretch reservations along a little at a time as needed. (See Making Usage Reservations for a description of the action using these options).

Reservation may be granted a grace period, which is defined as the difference between the validity period of the reservation (end time minus start time) and the expected duration of the usage. The purpose of a grace period is to account for the fact that we may not know precisely when the usage will begin and the reservation needs to be remain in force during the lifetime of the usage. One can apply a desired grace period for a reservation by setting the end time longer than the specified duration. Alternatively, a grace duration option can be specified with the duration when creating a reservation via greserve as a helper to computing a relatively adjusted end time.

10.2 Creating Reservations

Reservations are normally created by the resource management system with the greserve command (See Making Usage Reservations).

gmkres [-J instance_name|job_id] [-s start_time] {-e end_time | -t reservation_duration] [-d description] [-X, --extension property_name=property_value [,property_name=property_value...]] {-A allocation_id<-account_id=subreservation_amount[,allocation_id<-account_id=subreservation_amount...]} [--debug] [-?, --help] [--man] [—quiet] [-v, --verbose] [-V, --version]

Additional detail for this command can be found in the man page by issuing gmkres --man at the command line.

Example 1. Creating a manual reservation

$ gmkres -J weekend_run -t 84600 -A "5<-2=3600" 
Successfully created 1 reservation

Use of the gmkres command bypasses the normal mechanisms that prevent more reservations from being placed against an allocation than it can support. Use greserve instead if you wish to avoid the possibility of oversubscribing the allocations.