Sage Modeling and Simulation Library

Highpoint.Sage.Resources Namespace

A resource is anything that is used by a process, and for which that use must be granted. If its availability can affect the progress through a process (such as a batch or campaign), it is a resource.

Resources have two orthogonal classifications. Resources are discrete or continuous, and resources are consumable or persistent.

A continuous resource is a resource that can be acquired and released fractionally, and for which the acquired resource does not have an identity separate from the whole, such as acquiring 24.5 lbs of steam from a 200 lb steam header, or 40 kg of sodium nitrite from inventory.

A discrete resource is a resource that can only be acquired 1 at a time (or 2 at a time, etc. – e.g. in integral quantities), and for which each integrally acquired resource has an identity and state, such as a piece of equipment, a barrel or a mixer.

A consumable resource is a resource for which consumption and provision events are decoupled – that is, once a consumable resource has been removed from the pool, there is no guarantee that it will be returned to the pool. Typically, consumable resources are taken from a pool, and never returned. A different entity or set of entities is typically responsible for reprovisioning the pool, and the resources with which it reprovisions are unrelated to those formerly removed from the pool. While a consumable resource is not persistent, the pool (probably an Inventory object) is persistent.

A persistent resource is a resource that is not consumed. It is taken from the pool, and later returned to the pool.

Resource Object Model

Creating and working with resources requires three types of entities – ResourceManager, Resource and ResourceRequest objects. ResourceManager objects are any that correctly implement IResourceManager, Resource objects are any that correctly implement IResource, and ResourceRequest object are any that correctly implement IResourceRequest. For convenience, the framework provides several implementations. Resource, ResourceManager and ResourceRequest are implementations of their respective interfaces, and SelfManagingResource is a class that implements both IResourceManager and IResource, and allows easy representation of an object that need not be part of a pool of related resources.

Resource Acquisition

Resources are assigned to one or more pools, which conceptually are entities that are implementers of IResourceManager. A resource pool is a resource manager, from which a resource user will request a resource, through an object (essentially an agent). The resource desirer submits a resource request to the appropriate resource pool. The resource manager begins handing the resources to the request one by one, and the request scores each one. The request may examine any attribute of the resource (in addition to anything else the request is coded to consider), but must score each object. The score is a double. Double.MinValue means "No, this is totally unsuitable," double.MaxValue means "This is perfect. Give it to me now – I don’t need to see any more." Any double in between is seen as a scalar value judgment, and if no resources received a double.MaxValue score, then after all resources have been scored, the one with the highest value is granted.

In general an intended resource user (the requester) creates a resource request and submits it to a resource manager that has responsibility for the type (or instance) of resource it desires. In processing the request, the resource manager begins handing the resources to the request one by one, and the request scores each one. The request may examine any attribute of the resource (in addition to anything else the request is coded to consider), but must score each object. The score is a double. Double.MinValue means "No, this is totally unsuitable," double.MaxValue means "This is perfect. Give it to me now – I don’t need to see any more." Any double in between is seen as a scalar value judgment. During this processing the ResourceManager reserves any suitable resources one at a time, unreserving them only after reserving the next one if a better one is found, until finally when the best one has been found, it is acquired on behalf of the requster. If no suitable resource is requested and the request was made with the blocking flag set to true, the resource manager holds the request (and the caller's thread) until the resource can be granted. If the request was made with the blocking flag set to false, the call returns with the ResourceRequest's ResourceObtained property set to null, and no further attempt is made by the ResourceManager to satisfy the request. The requester uses the resource, and when it is done doing so, may or may not (depending on if the resource is replenishable) releases the resource back to the pool.

ResourceEvents allow the application to gather information on resource acquisitions, releases, etc. ResourceEventRecords persist these events, and ResourceEventRecordFilters allow perusal of collections of ResourceEventRecords.

Access regulators may be used to allow a resource manager to require a key be submitted with a resource request, and to permit that resource manager to allow or deny access based on that key. This is useful for earmarking - a technique where resources are "earmarked" for use by a specific class of requestors. For example, a campaign ( a series of batches) begins, and all vessels that are used by that campaign are earmarked for that campaign, so that no other campaign may acquire the vessels, thereby avoiding a need to clean that vessel in the middle of a batch.

ResourceTrackers are used to track the levels and events associated with a specific resource. A ResourceTrackerAggregator collects the data from more than one resource.

Classes


  Class Description
Public class GuidSelectiveResourceRequest
A GuidSelectiveResourceRequest requests a specified quantity of a guid-specified resource from its manager. It assumes the resources to be unique to the given Guid.
Public class MultiKeyAccessRegulator
An access regulator that maintains a list of keys, the presentation of an object with a .Equals(...) match to any one of which will result in an allowed acquisition.
Public class MultiRequestProcessor
MultiRequestProcessor provides ways to manipulate multiple resource requests at the same time. All requests must have a default resource manager specified, unless otherwise indicated in the specific API.
Public class MultiResourceTracker
A MultiResourceTracker is a resource tracker (gathers copies of resource event records) that can monitor multiple resources during a simulation.
Public class Resource
A resource represents something that is used by other objects in the completion of their tasks. It can be steam pressure, with real numbers of capacity used and returned, it can be a vehicle in a motor pool which is used in toto and returned, it can be the stock of syringes in an emergency room that are used one at a time and discarded, and separately replenished, and so on.
Public class ResourceEventRecord
A record that represents the details of a transaction involving a resource. These include the various ResourceActions.
Public class ResourceEventRecord..::..RerComparer
An abstract class from which all Resource Event Record Comparers inherit.
Public class ResourceEventRecord..::..SortByAction
A comparer that can be used, for example, to sort ResourceEventRecords by their Action types.
Public class ResourceEventRecord..::..SortByResourceName
A comparer that can be used, for example, to sort ResourceEventRecords by their Resource Names.
Public class ResourceEventRecord..::..SortBySerialNumber
A comparer that can be used, for example, to sort ResourceEventRecords by their serial numbers.
Public class ResourceEventRecord..::..SortByTime
A comparer that can be used, for example, to sort ResourceEventRecords by their times of occurrence.
Public class ResourceEventRecordFilters
A static holder for some static and stateless ResourceEventRecordFilters.
Public class ResourceException
ResourceException is the base class for other resource exceptions - it simply contains the message, the manager, the request, and the resource involved.
Public class ResourceManager
Resource Manager is a class that provides reservation, acquisition and release services on instances that implement IResource. All operations are accomplished synchronously, meaning that a call to acquire a resource will either throw an exception indicating that the resource request can never be fulfilled from this pool, or else (1) the call is blocked until the resource can be obtained from the pool, or (2) the request will return, unfulfilled. (1) or (2) happen based on the value of the blockAwaitingAcquisition parameter in the reserve or acquire APIs.
Public class ResourceManagerCollection
Public class ResourceMismatchException
Class ResourceMismatchException is fired when code tries to release or unreserve a resource with a ResourceRequest that doesn't own it.
Public class ResourcePoolInsufficientException
Class ResourcePoolInsufficientException is fired when there are insufficient resources available to a resource manager to ever satisfy the request.
Public class ResourceRequest
Public class ResourceTracker
This class is the baseline implementation of IResourceTracker. It watches a specified resource over a model run, and creates & collects ResourceEventRecords on the activities of that resource.
Public class ResourceTrackerAggregator
Class that consolidates a collection of IResourceTrackers
Public class SelfManagingResource
Summary description for Resource.
Public class SimpleAccessManager
A SimpleAccessManager is made a part of the resource acquisition protocol that is embodied in all resource managers. When a resource manager is aware of an access manager, it asks that access manager if any resource request is grantable before it even allows the resource request to score the available resources. Therefore, an access manager uses Access Regulators to prevent resource requests from being granted in certain cases.

A SimpleAccessManager manages a single AccessRegulator that it applies across all resources that are presented to it, or it manages a stack of AccessRegulators that are applied to specified resources.

NOTE: If an AccessManager has a default regulator as well as resource-specific ones, the resource-specific ones take precedence.

Public class SimpleResourceRequest
A SimpleResourceRequest requests a specified quantity of whatever is in a resource manager. It assumes the resources to be homogenenous (i.e. any offered resource is immediately accepted.)
Public class SingleKeyAccessRegulator
Grants access to the requestor if the subject is null or matches the requested subject, and the stored key matches the provided key via the .Equals(...) operator.
Public class TerminalResourceRequestAbortedWarning
A class that implements IModelWarning, and is intended to contain data on a resource request that was aborted due to deadlock or starvation, at the end of a model run. The creator of this class must add the instance into the Model's Warnings collection.

Interfaces


  Interface Description
Public interface IAccessManager
An object that manages multiple access regulators. They are managed in stacks, with one stack for each specific resource under management, and one stack for any requests for resources that do not have specific regulators assigned to them.
Public interface IAccessRegulator
An object that can be used by a ResourceManager to permit or deny individual resource aquisition reqests.
Public interface IHasCapacity
Implemented by a class (usually a resource) that has a quantity that can be considered capacity.
Public interface IHasControllableCapacity
Implemented by a class (usually a resource) that has a quantity that can be considered capacity. In the case of IHasControllableCapacity, though, the current capacity (Available) and maximum capacity (Capacity) can be overridden. and
Public interface IModelWithResources
Implemented by a model that manages resources.
Public interface IResource
An implementer of IResource is an object that can act as a resource.
Public interface IResourceManager
Interface IResourceManager is implemented by an object that manages the granting and recovery of resources. It executes a protocol for finding the best resource for a given resource request.
Public interface IResourceManagerCollection
Public interface IResourceRequest
IResourceRequest is an interface implemented by a class that is able to request a resource. This is typically an agent employed by the resource user itself. A resource request is submitted to a resource manager, whose job it is to mediate a process whereby the resource request selects, and is granted (or not) access to that resource.
Public interface IResourceTracker
Implemented by anything that gathers ResourceEventRecords on a specific resource or resources.
Public interface ResourceEventRecord..::..IEditor
Implemented by an object that can set the values of a ResourceEventRecord. Typically granted by the ResourceEventRecord itself, so that the RER can control who is able to modify it.

Delegates


  Delegate Description
Public delegate RequestPriorityChangeEvent
This is the signature of the event that is fired when a Resource request changes its priority.
Public delegate ResourceEvent
A delegate implemented by an event that is fired by a resource.
Public delegate ResourceEventRecordFilter
Implemented by anything that can filter ResourceEventRecords.
Public delegate ResourceManagerChangeListener
A delegate with which an event involving a SOMUnit is broadcast. Examples are ResourceManagerAdded and ResourceManagerRemoved.
Public delegate ResourceManagerEvent
A delegate implemented by an event that is fired, usually, by a resource manager.
Public delegate ResourceRequestAbortEvent
This is the signature of the event that is fired when a Resource request is aborted.
Public delegate ResourceRequestCallback
This is the signature of the callback that is invoked when a resource request, executed without a block and initially refused, is eventually deemed grantable, and as well, later, to notify the requester that its request has been granted.
Public delegate ResourceRequestSource
Implemented by a method that can generate or return a Resource Request.
Public delegate ResourceSelectionStrategy
This is a method that, given a list of objects implementing IResource, chooses the 'best' one.
Public delegate ResourceStatusEvent
A delegate implemented by an event that is fired by a resource, but related to a resource request.

Enumerations


  Enumeration Description
Public enumeration RequestStatus
Public enumeration ResourceAction
An enumeration of the types of transactions that can take place, involving a resource.
Public enumeration ResourceMismatchException..::..MismatchType