/ 
Resource-Silo-0.03
River stage zero No dependents
/ Resource::Silo::Container

NAME

Resource::Silo::Container - base resource container class for Resource::Silo.

DESCRIPTION

Resource::Silo isolates resources by storing them inside a container object.

The methods of such an object are generated on the fly and stored either in a special virtual package, or the calling module.

This class provides some common functionality that allows to access resources, as well as a doorway into a fine-grained control interface.

METHODS

new( resource => $override, ... )

Create a new container (also available as silo->new).

If arguments are given, they will be passed to the "override" method (see below).

CONTROL INTERFACE

Sometimes more fine-grained control over the container is needed than just fetching the resources.

Since the container class can contain arbitrary resource names and some user-defined methods to boot, instead of polluting its namespace, we provide a single method, ctl, that returns a temporary facade object that provide access to the following methods.

Most of them return the facade so that they can be chained. E.g.

# somewhere in your tests
silo->ctl->lock->override(
    config  => { ... },     # some fixed values
    dbh     => sub { ... }, # return SQLite instance
);

ctl

Returns the facade.

NOTE the facade object is weak reference to the parent object and thus must not be save anywhere, lest you be surprised. Use it and discard immediately.

override( %substitutes )

Provide a set of overrides for some of the resources.

This can be used e.g. in tests to mock certain external facilities.

%substitutes values are interpreted as follows:

  • sub { ... } - use this code instead of the resource's init;

  • undef - erase the override for given resource;

  • anything else is coerced into an initializer: $value => sub { return $value }.

Setting overrides has the side effect of clearing cache for the affected resources.

lock

Forbid initializing new resources.

The cached ones instantiated so far, the ones that have been overridden, and the ones with the derivative flag will still be returned.

unlock

Remove the lock set by lock.

preload()

Try loading all the resources that have preload flag set.

May be useful if e.g. a server-side application is starting and must check its database connection(s) before it starts handling any clients.

cleanup

Cleanup all resources. Once the cleanup is started, no more resources can be created, and trying to do so will result in exception. Typically only useful for destruction.

fresh( $resource_name [, $argument ] )

Instantiate resource and return it, ignoring cached value, if any. This may be useful if the resource's state is going to be modified in a manner incompatible with its other consumers within the same process.

E.g. performing a Big Evil SQL Transaction while other parts of the application are happily using DBIx::Class.

NOTE Use with caution. Resorting to this method frequently may be a sign of a broader architectural problem.

meta

Get resource metadata object (a Resource::Silo::Metadata).

COPYRIGHT AND LICENSE

Copyright (c) 2023, Konstantin Uvarin, <khedin@gmail.com>

This program is free software. You can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation, or the Artistic License.

See http://dev.perl.org/licenses/ for more information.