The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Resource-Silo-0.13
River stage zero No dependents
2 ++
/ 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).

ctl

As the container class may contain arbitrary resource names and user-defined methods to boot, we intend to declare as few public methods as possible.

Instead, we create a facade object that has access to container's internals and can perform fine-grained management operations. See "CONTROL INTERFACE" below.

Example:

    # Somewhere in a test file
    use Test::More;
    use My::App qw(silo);

    silo->ctl->override( dbh => $fake_database_connection );
    silo->ctl->lock; # forbid instantiating new resources

Returns a facade object.

NOTE Such object contains a weak reference to the parent object and thus must not be saved anywhere, lest you be surprised. Use it and discard immediately.

CONTROL INTERFACE

The below methods are all accessible via $container->ctl->$method_name.

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 derived 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.

In addition, self-check will be called and all declared require'd modules will be loaded, even if they are not required by preloaded resources.

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.

list_cached

Return list of services that are currently present in the cache as strings of form $service_name or $service_name/$argument if argument is present.

Useful for debugging.

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.