NAME

POE::Component::ResourcePool - Asynchronous generic resource management for POE based apps.

SYNOPSIS

my $resource = POE::Component::ResourcePool::Resource::Blah->new( ... );

my $pool = POE::Component::ResourcePool->new(
	resources => {
		moose => $resource,
		elk   => ...,
		cow   => ...,
	},
);

# ... in some session somewhere:

$pool->request(
	params => {
		moose => ..., # arbitrary params for Blah type resources
		elk   => ...,
	},
	event => "got_it", # dispatched when both moose and elk can be allocated at the same time
);

DESCRIPTION

This resource pool object provides very flexible resource management for POE based apps.

A pool consists of any number of named, abstract resources to be shared amongst several tasks.

Requests for resources can contain arbitrary parameters and are fulfilled with arbitrary values.

The pool will manage resources, sharing them between requests as they become available.

Using a simple interface one can easily write arbitrary resource abstractions, which are potentially affected by outside mechanisms (for example the token bucket resource allows time based throttling).

QUEUE ALGORITHM

The request queue works by maintaining a set of ready and blocked resources for each request.

Whenever all the resources for a given request are ready the pool will attempt to allocate the request.

If any resource failed to allocate the parameter specified for it in the request, it is marked as blocked for that request.

If all resources succeeded the allocations are finalized, the request callback is invoked and the request is removed from the queue.

Whenever a resource signals that it's been updated (for example if its allocation has been freed, or if some other POE event changed it) it will be marked as ready for allocation in the queue again.

REFERENCE MANAGEMENT

Based on the values of refcount_allocated (defaults to false) and refcount_pending (defaults to true) the resource pool will increment the reference count of sessions that have created requests and decrement it when the resource is fulfilled.

This is because typically a session is not doing anything, and as such has no resources/events associated with it while it waits for a resource.

Once the resource is allocated the session will probably have at least one more event (depending on the callback), and will continue working until it's done, at which point the kernel will garbage collect it.

This default behavior allows you to simply keep your requests on the heap so that when the session closes automatically fulfilled requests will be freed.

Setting refcount_allocated will cause the session to remain alive until the resource is dismissed (whether manually or due to DESTROY). Note that if refcount_allocated is true and the resource is kept on the heap a circular reference is caused and the session will leak unless the resource is explicitly dismissed.

Setting refcount_pending to a false value may cause sessions to disappear prematurely. The resource pool will not check that the session still exists when issuing the callback so this may cause problems.

METHODS

new %args

spawn %args

Construct a new resource pool.

See "ATTRIBUTES" for parameters.

spawn is provided as an alias due to POE::Component convensions.

request %args

request $req

Queues a new request, optionally creating a request object based on the request_class attribute.

See POE::Component::ResourcePool::Request.

create_request %args

Used by request to create a request object with some default arguments in addition to the supplied ones.

Delegates to construct_request.

construct_request @args

Calls new on the class returned by request_class with the provided arguments.

queue $request

Inserts the request into the queue.

dismiss $request

Deallocates the request if it has been fulfilled, or cancels it otherwise.

shutdown

Remove the alias for the pool, causing its session to close.

resource_updated $resource, [ @requests ]

Called by resources to signal that a resource has been updated.

@requests can be specified in order to only recheck certain requests (instead of all the requests associated with the resource).

pending_requests

Returns a list of the currently pending requests.

If a resource is specified as the first argument then only returns the requests for that resource.

allocated_requests

Returns a list of the currently allocated requests.

If a resource is specified as the first argument then only returns the requests for that resource.

all_requests

Returns all the requests active in the pool (pending and allocated).

If a resource is specified as the first argument then only returns the requests for that resource.

ATTRIBUTES

resources

The hash of resources to manage.

Resources may be shared by several pools.

Modifying this hash is not supported yet but might be in the future using a method API.

alias

Comes from MooseX::POE::Aliased.

Note that the alias is not currently useful for anything, since the only events the resource pool currently responds to are internal.

request_class

The class to use when constructing new request objects.

weak_queue

Normally strong references are made to requests in the queue, to prevent their destruction.

When requests leave the queue all references to them maintained by the pool are weak, so that if the request gets garbage collected its allocations may be returned to the resources.

If this parameter is set then unfulfilled requests will also be weak, so that requests which are no longer referenced elsewhere are canceled.

refcount_pending

Whether or not to maintain POE reference counts for sessions that have pending requests.

Defaults to true.

See "REFERENCE MANAGEMENT".

refcount_allocated

Whether or not to maintain POE reference counts for sessions that have allocated requests.

Defaults to false.

See "REFERENCE MANAGEMENT".

TODO

Prioritization

Resource contention is a problem, so a pluggable scheduler should be available, with the default one being a FIFO (the current order is based on Set::Object's internal hasing).

The module should ship with a priority based FIFO queue that supports priority inheritence as well, in order to provide decent prioritization facilities out of the box.

Nestability

Allow pools to also behave as resources in other pools.

This should be fairly easy.

Allow weak lifetime without an alias

Try to find a way for POE to keep the pool alive as long as other sessions may use it, just like when it's got an alias, but without needing to set one.

This is very annoying for resources that need their own sessions, as it rarely akes sense for them to also have aliases.

VERSION CONTROL

This module is maintained using Darcs. You can get the latest version from http://nothingmuch.woobling.org/code, and use darcs send to commit changes.

AUTHOR

Yuval Kogman <nothingmuch@woobling.org>

COPYRIGHT

Copyright (c) 2008 Yuval Kogman. All rights reserved
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.