Creates a new keepalive connection manager. A program may contain
several connection managers. Each will operate independently of the
others. None will know about the limits set in the others, so its
possible to overrun your file descriptors for a process if youre not
new() takes up to five parameters. All of them are optional.
To limit the number of simultaneous connections to a particular host (defined by a combination of scheme, address and port):
To limit the overall number of connections that may be open at once, use
Programs are required to give connections back to the manager when they are done. See the free() method for how that works. The connection manager will keep connections alive for a period of time before recycling them. The maximum keep-alive time may be set with
Programs may not want to wait a long time for a connection to be established. They can set the request timeout to alter how long the component holds a request before generating an error.
Specify a bind_address to bind all client sockets to a particular local address. The value of bind_address will be passed directly to POE::Wheel::SocketFactory. See that modules documentation for implementation details.
Allocate a new connection. Allocate() will return a request ID
immediately. The allocated connection, however, will be posted back
to the requesting session. This happens even if the connection was
found in the components keep-alive cache. Its a bit slower, but the
use cases are cleaner that way.
Allocate() requires five parameters and has an optional sixth.
Specify the scheme that will be used to communicate on the connection (typically http or https). The scheme is required, but youre free to make something up here. Its used internally to differentiate different types of socket (e.g., ssl vs. cleartext) on the same address and port.
Request a connection to a particular address and port. The address and port must be numeric. Both the address and port are required.
Specify an name of the event to post when an asynchronous response is ready. This is of course required.
Set the connection timeout, in seconds. The connection manager will post back an error message if it cant establish a connection within the requested time. This parameter is optional. It will default to the master timeout provided to the connection managers constructor.
Specify additional contextual data. The context defines the connections purpose. It is used to maintain continuity between a call to allocate() and an asynchronous response. A context is extremely handy, but its optional.
The response event (got_a_connection in this example) contains several fields, passed as a list of key/value pairs. The list may be assigned to a hash for convenience:
Four of the fields exist to echo back your data:
On success, another field tells you whether the connection contains all new materials. That is, whether the connection has been recycled from the components cache or created anew.
The from_cache status may be immediate if the connection was immediately available from the cache. It will be deferred if the connection was reused, but another user had to release it first. Finally, from_cache will be false if the connection had to be created to satisfy allocate().
Free() notifies the connection manager when connections are free to be
reused. Freed connections are entered into the keep-alive pool and
may be returned by subsequent allocate() calls.
For now free() is called with a socket, not a connection object. This is usually not a problem since POE::Component::Connection::Keepalive objects call free() for you when they are destroyed.
Not calling free() will cause a program to leak connections. This is also not generally a problem, since free() is called automatically whenever connection objects are destroyed.
|deallocate||Cancel a connection that has not yet been established. Requires one parameter, the request ID returned by allocate().|
The keep-alive pool requires connections to be active internally.
This may keep a program active even when all connections are idle.
The shutdown() method forces the connection manager to clear its
keep-alive pool, allowing a program to terminate gracefully.
This distribution is copyright 2004-2009 by Rocco Caputo. All rights are reserved. This distribution is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
Rocco Caputo <email@example.com>
Rob Bloodgood helped out a lot. Thank you.
Joel Bernstein solved some nasty race conditions. Portugal Telecom <http://www.sapo.pt/> was kind enough to support his contributions.
|perl v5.20.3||POE::COMPONENT::CLIENT::KEEPALIVE (3)||2012-05-15|