(Click to open topic with navigation)
A lien is a hold placed against an allocation. Before usage of a resource or service begins, a lien is made against one or more allocations within the requesting user's applicable fund(s).Subsequent usage requests will also post liens while the available balance (active allocations minus liens) allows. When the usage ends, the lien 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 funds.
Associated with a lien 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 lien and a description. The lien will automatically expire and no longer count against the user's balance after the end time passes. Each lien will be associated with held amounts from one or more allocations. Operations include creating, querying, modifying, and deleting liens. By default, a standard user may only query liens attributed to them.
Lien queries allow the specification of filter options which narrow down the liens that will be returned. There are two lien filter types that can be employed: AttributedTo and ImpingesUpon. If ImpingesUpon is used, the query will return all liens associated with funds satisfying the filters. For example, Lien Query FilterType:=ImpingesUpon Filter:=User=scottmo will return all liens impinging on Funds usable by scottmo. If AttributedTo is used, the query will return all liens associated with usage records satisfying the filters. For example, Lien Query FilterType:=AttributedTo Filter:=User=scottmo will return all liens for resources or services allocated to scottmo.
When a lien is created via the UsageRecord Reserve action (such as via greserve), if another lien exists with the same instance name, the default behavior is to leave the old lien in place (and create the new one alongside it). This behavior assumes that the other lien is probably a separate lien 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 liens with matching instance names will first be deleted, thereby ensuring only one lien per instance name at a time. If the Modify option is specified, a pre-existing lien with matching instance name will be modified to have the new properties (but keeping the same lien id), and can be used to extend a lien. This might be used with incremental charging to dynamically stretch liens along a little at a time as needed. (See Making a usage lien for a description of the action using these options).
Liens may be granted a grace period (in seconds), which is defined as the difference between the validity period of the lien (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 lien needs to remain in force during the lifetime of the usage. One can apply a desired grace period for a lien by setting the end time longer than the specified duration. Alternatively, a grace duration option can be specified with the duration when creating a lien via greserve as a helper to computing a relatively adjusted end time.