quartermaster.core — com.workiva/quartermaster 0.1.1

*always-block-on-release* clj

acquiring clj macro

(acquiring bindings & body)

A guarded-let (utils.control) that releases symbols whose inits resolve to a ResourceHandle, but only if an exception is thrown in the bindings block.

all-handle-maps clj

(all-handle-maps)

Use to get a not-quite-consistent snapshot of the handle maps from every resource manager.

all-resource-managers clj

auto-reinitiater clj macro

(auto-reinitiater resource-description)

(auto-reinitiater user-id resource-description)

Can only be used within the context of defmanager. When a resource is constructed, it is sometimes desirable that the resource know how to reinitiate itself. This macro constructs a function of one argument (the resource itself), that will ask the resource-manager to reinitiate that resource without removing any acquired handles.

If the discrimination function employs the user-id, then you MUST pass in the user-id here. If and only if the determinating function ignores the user-id, you can freely use the single-arity version.

auto-releaser clj macro

(auto-releaser resource-description)

(auto-releaser user-id resource-description)

Can only be used within the context of a construction function passed to defmanager. When a resource is constructed, it is sometimes desirable that the resource know how to release itself from all handles. This macro constructs a function of one argument (the resource itself), with an optional second argument (block-on-release?) that will call release-all* on the resource-manager.

If the discrimination function employs the user-id, then you MUST pass in the user-id here. If and only if the determinating function ignores the user-id, you can freely use the single-arity version.

defmanager clj macro

(defmanager mgr-name & {:as options})

Creates a new resource manager defined by the supplied :discriminator, :constructor, and (optionally) :terminator.

Defines and registers three metrics associated with this manager: <namespace>.<manager-name>.construction-timer Times the actual construction of resources. For SharedResources, this includes calling initiate. <namespace>.<manager-name>.termination-timer Times the actual termination of resources. For SharedResources, this includes calling terminate. <namespace>.<manager-name>.extant-counter Tracks how many unique resources exist at any point in time.

ensure-initiated! clj macro

(ensure-initiated! resource message)

(ensure-initiated! resource message data)

Raises a :shared-resource/terminated error if the resource is terminated!

identify-resource-leaks clj macro

(identify-resource-leaks & body)

new-resource-id clj

(new-resource-id)

(new-resource-id tag)

Returns a unique identifier. Takes the form {:uuid UUID, :tag tag} with the :tag key optional.

overriding clj macro

(overriding manager->overrides & body)

Allows temporary redefinition of one or more resource-manager's parameters (:discriminator, :constructor, :terminator). Especially useful in tests.

(overriding [manager {& options} manager {& options} ...] & body)

resource-manager clj

(resource-manager rm-id discriminate constructor)

(resource-manager rm-id discriminate constructor terminator)

rm-id - used for logging and debugging discriminate - var containing function of <user-id, resource-description> -> unique identifier for resource constructor - var containing function of <unique-identifier, resource-description> -> new resource terminator - (optional) var containing function that the resource-manager will always call on the resource at termination.

Defines and registers three metrics associated with this manager: <namespace>.<manager-name>.construction-timer Times the actual construction of resources. For SharedResources, this includes calling initiate. <namespace>.<manager-name>.termination-timer Times the actual termination of resources. For SharedResources, this includes calling terminate. <namespace>.<manager-name>.extant-counter Tracks how many unique resources exist at any point in time.

defmanager is preferred outside of testing.

ResourceHandle clj protocol

reinitiate clj

(reinitiate handle)

(reinitiate handle target-resource-id)

If this resource handle is still valid, this attempts to force-terminate the resource and all its own resource, then reinitiate a new one, swapping the new resource for the old in the resource manager.

Any user-ids registered as having handlers on the old resource will still be registered as having handlers on the new resource, and the new resource will be accessible through all the old ResourceHandles.

If the resource implements SharedResource, then the target-resource-id is required; the reinitiation only takes effect if the target-resource-id matches the resource id of the resource in the manager. target-resource-id should be left off if the resource does not implement SharedResource.

Returns this ResourceHandle upon completion. If an exception is encountered this may raise a :quartermaster/reinitiate-error error.

release clj

(release handle)

(release handle block-on-release?)

Informs the manager that the user-id associated with this handle no longer wishes to maintain its handle on the resource, exactly as if the user called SharedResourceManager/release*. ResourceHandles are expected to hold only WeakReferences to the resource s.t. leaking a ResourceHandle does not prevent GC of the resource itself once the manager has dropped it.

Returns true upon completion. If :quartermaster/terminate-error is raised, this will attempt to log a warning.

release-all clj

(release-all handle target-resource-id)

(release-all handle target-resource-id block-on-release?)

Informs the manager that the user-id associated with this handle wishes to release all handles to this resource by all users, then to terminate the resource. ONLY TAKES EFFECT IF target-resource-id MATCHES THE RESOURCE KNOWN TO THE MANAGER. Use with caution.

If the resource does not implement SharedResource, nil may be passed as target-resource-id.

Returns true upon completion. If :quartermaster/terminate-error is raised, this will attempt to log a warning.

resource clj

(resource handle)

Returns the resource. Potentially repairs the resource. Use this or deref for cases that don't involve registered on-acquisition functions. This, and deref, should never be called inside a registerd on-acquisition function.

resource* clj

(resource* handle)

Returns the resource. Makes no attempt to check health or make repairs. Use this inside registered on-acquisition functions.

SharedResource clj protocol

force-terminate clj

(force-terminate _)

Used by resource managers when reinitiating a resource. The shared resource that has already been terminated will do nothing. Otherwise, it is expected to force-terminate all its own resources before terminating itself. Idempotent.

initiate clj

(initiate _)

If not initiated, puts this resource into a usable state by generating a unique resource-id and acquiring any resources it requires (threads, channels, SharedResources, etc.). Returns an updated version of this resource. Calling initiate on a ResourceReference behaves as though calling initiate on the resource itself. Idempotent. May raise an error with type :quartermaster/initiate-error.

initiated? clj

(initiated? _)

Has this resource been initiated?

resource-id clj

(resource-id _)

Returns this resource's unique resource-id if initiated; nil if terminated.

status* clj

(status* _)

Returns a (possibly empty) map of resource-specific status information.

terminate clj

(terminate _)

Used to tell this resource to release all resources it required and to clean itself up, putting itself into an unusable state. Attempting to use a terminated resource may result in a :quartermaster/resource-terminated error being raised. Idempotent.

SharedResourceManager clj protocol

acquire clj

(acquire rm user-id description)

(acquire rm user-id description on-acquisition)

Attempts to acquire the resource uniquely determined by description. Returns a ResourceReference on success. May raise various :quartermaster/* errors correponding to the management/lifecycle stage in which exceptions were encountered.

The mapping from description to unique resource is determined by means of the equivalence class indicated by a discriminator passed to the resource manager's constructor.

If an appropriate resource does not exist already, it will be created by passing description to the construction function passed to the resource manager's constructor. If the constructed resource implements SharedResource, it will be initiated before being cached by the manager.

Either way, this method will ensure that user-id is registered as having a handle on the resource. The resource will be evicted from the cache when the last user-id has released the resource. If it is a SharedResource, it will be terminated as well.

Calling acquire a second time with the same arguments should merely ensure that the resource, if SharedResource, is initiated, then return a new handle object without any additional side effects.

Some users require that certain side-effects be executed the first time the resource is created and any time it is dynamically swapped out by the resource manager for any reason. If this is the case, an optional on-acquisition argument may be passed. It is expected to be a function of one argument, a ResourceReference, which executes the side effects. The returned ResourceReference will ensure that this function is called appropriately.

handle-map clj

(handle-map rm)

Returns a snapshot {equivalence-class --> #{& user-ids}} for the resource-manager.

reacquire clj

(reacquire rm user-id description)

Attempts to fetch a resource already acquired. Useful if that resource instance was terminated for any reason. If user-id doesn't already have a handle on it, then this throws an exception. Mainly used by ResourceReference.

DOES NOT RETURN A ResourceReference. Returns the resource itself.

reinitiate* clj

(reinitiate* rm user-id description)

(reinitiate* rm user-id description resource-id)

(reinitiate* rm user-id description resource-id on-acquisition)

If there is a resource determined by description being managed by this manager, this method will attempt to destroy the old resource and replace it with a new one, BUT ONLY IF THAT RESOURCE'S ID IS resource-id.

All user-ids registered as having handlers on the old resource will still be registered as having handlers on the replacement resource. Any ResourceReference that pointed to the old resource will now point to the new resource.

The old resource is destroyed by means of force-terminate. It is expected that the old resource will transitively call force-terminate on all its own resources.

Forcibly terminated resources are expected to raise a :shared-resource/terminated error, so that users may know to retry or to attempt to reinitiate resources.

DOES NOT RETURN A ResourceReference. Returns the resource itself. Mainly intended for use by ResourceHandle/reinitiate.

release* clj

(release* rm user-id description)

(release* rm user-id description block-on-release?)

Informs the manager that user-id no longer wishes to maintain its handle on the resource determined by description.

If user-id has the last handle on the resource, all references to the resource are dropped by the resource manager.

If a dropped resource implements SharedResource, it is terminated when it is dropped. By default, this occurs asynchronously; if block-on-release? is true, release will not return until the resource has been terminated. If the only other references to the resource are ResourceReferences, the resource may be garbage-collected.

Returns true. May raise a :quartermaster/terminate-error error. Mainly intended for internal use by ResourceHandle/release.

release-all* clj

(release-all* rm user-id description target-resource-id)

(release-all* rm user-id description target-resource-id block-on-release?)

If there is a resource determined by description being managed by this manager, this method will attempt atomically to release all handles to this resource and then terminate the resource -- BUT ONLY IF THAT RESOURCE'S ID IS resource-id. Use with caution. If the manager's discriminator function depends at all on user-id, then user-id must be correspond to that used at the resource's acquisition. In all other cases, its value is irrelevant.

Returns true. May raise a :quartermaster/terminate-error error. Mainly intended for use by ResourceReference/release-all.

status clj

(status resource)

Returns the resource's status map, with the following keys merged in: #{:quartermaster/initiated?}

terminated? clj

(terminated? resource)

Is it in a terminated state?

testing-for-resource-leaks clj macro

(testing-for-resource-leaks & body)

For use in clojure.test tests. Tests that any resources acquired in the body are also released in the body. Binds always-block-on-release to true during the execution of body.