automaton-simulation-de.rc.impl.resource — org.clojars.hephaistox/automaton-simulation-de 2.0.1-la

A resource is a limited quantity of items that are used by entities as they proceed through the system. A resource has a capacity that governs the total quantity of items that may be available. All the items in the resource are homogeneous, meaning that they are indistinguishable. If an entity attempts to seize a resource that does not have any units available it must wait in a queue. It is often representing real world items that availability is limited (e.g. machine, wrench, ...).

A resource knows its instantenous capacity, its policies,and the element waiting for its availablility in the queue. The properties of a resource are:

• capacity (default 1) total number of available resources, note that this number may evolve over time.
• currently-consuming (default []) list of events currently consuming this resource, is useful to track them and enabling preemption and failures. The event contains the information on the waiting entity.
• preemption-policy (default ::sim-de-rc/no-preemption) is the policy to apply when a resource is consumed and none is available.
• queue (default []) list of blocked entities.
• renewable? (default true) when true, the disposing is not giving back the values.
• unblocking-policy (default ::simde-rc/FIFO) refers to an entity from the automaton-simulation-de.rc.policies registry, that registry will allow to pick one element in a queue.

defaulting-values clj/s

(defaulting-values {:automaton-simulation-de.rc/keys
                      [capacity currently-consuming preemption-policy queue
                       renewable? unblocking-policy]
                    :as resource
                    :or {capacity 1
                         currently-consuming {}
                         preemption-policy
                           :automaton-simulation-de.rc/no-preemption
                         queue []
                         renewable? true
                         unblocking-policy :automaton-simulation-de.rc/FIFO}}
                   unblocking-policy-registry
                   preemption-policy-registry)

Returns a resource with default values added.

dispose clj/s

(dispose resource consumption-uuid)

Returns a pair of:

• unblockings list of blockings that should be try to seize again the resource
• resource updated with consumption consumption-uuid removed.

nb-available-resources clj/s

(nb-available-resources
  {:automaton-simulation-de.rc/keys [capacity] :or {capacity 1} :as resource})

Returns the number of available resources based on the defined capacity, and the currently-consuming resources (i.e. sum of their ).

nb-consumed-resources clj/s

(nb-consumed-resources {:keys [:automaton-simulation-de.rc/currently-consuming]
                        :as _resource})

Returns the number of consumed resources.

seize clj/s

(seize resource consumed-quantity postponed-event)

Returns a pair:

• the consumption-uuid if it has happened, nil if the execution is postponed awaiting for a resource disposal
• the state reflecting the resource consumption

The seizing-event is added in the currently-seizing so:

• the number of available resources can be calculated, based on the used quantity
• in case the seizing event should be cancelled (failures or preemption), the events are found in that list.

update-capacity clj/s

(update-capacity {:automaton-simulation-de.rc/keys [cache capacity]
                  :or {capacity 1}
                  :as resource}
                 new-capacity)

Returns a pair of:

• unblocked-events list of events that should be try to seize again the
• resource updated with the resource capacity

If the new capacity is lower than the number of element consumed (i.e. in currently-consuming), then the preemption-policy choose one event to stop:

• ::no-premption is the only implemented, it doesn't do anything and let the currently executing event finish.