NAME¶
MongoDBx::Class::ConnectionPool - A simple connection pool for MongoDBx::Class
VERSION¶
version 1.030002
SYNOPSIS¶
# create a MongoDBx::Class object normally:
use MongoDBx::Class;
my $dbx = MongoDBx::Class->new(namespace => 'MyApp::Model::DB');
# instead of connection, create a rotated pool
my $pool = $dbx->pool(max_conns => 200, type => 'rotated'); # max_conns defaults to 100
# or, if you need to pass attributes to MongoDB::Connection->new():
my $pool = $dbx->pool(max_conns => 200, type => 'rotated', params => {
host => $host,
username => $username,
password => $password,
...
});
# get a connection from the pool on a per-request basis
my $conn = $pool->get_conn;
# ... do stuff with $conn and return it when done ...
$pool->return_conn($conn); # only relevant on backup pools but a good practice anyway
DESCRIPTION¶
WARNING: connection pooling via MongoDBx::Class is experimental. It is a quick,
simple implementation that may or may not work as expected.
MongoDBx::Class::ConnectionPool is a very simple interface for creating MongoDB
connection pools. The basic idea is: create a pool with a maximum number of
connections as a setting. Give connections from the pool on a per-request
basis. The pool is empty at first, and connections are created for each
request, until the maximum is reached. The behaviour of the pool when this
maximum is reached is dependent on the implementation. There are currently two
implementations:
- •
- Rotated pools (MongoDBx::Class::ConnectionPool::Rotated) - these pools
hold at most the number of maximum connections defined. An index is held,
initially starting at zero. When a request for a connection is made, the
connection located at the current index is returned (if exists, otherwise
a new one is created), and the index is incremented. When the index
reaches the end of the pool, it returns to the beginning (i.e. zero), and
the next request will receive the first connection in the pool, and so on.
This means that every connection in the pool can be shared by an unlimited
number of requesters.
- •
- Backup pools (MongoDBx::Class::ConnectionPool::Backup) - these pools
expect the receiver of a connection to return it when they're done using
it. If no connections are available when a request is made (i.e. all
connections are being used), a backup connection is returned (there can be
only one backup connection). This means that every connection in the pool
can be used by one requester, except for the backup connection which can
be shared.
The rotated pool makes more sense for pools with a relatively low number of
connections, while the backup pool is more fit for a larger number of
connections. The selection should be based, among other factors, on your
application's metrics: how many end-users (e.g. website visitors) use your
application concurrently? does your application experience larger loads and
usage numbers at certain points of the day/week? does it make more sense for
you to balance work between a predefined number of connections (rotated pool)
or do you prefer each end-user to get their own connection (backup pool)?
At any rate, every end-user will receive a connection, shared or not.
ATTRIBUTES¶
max_conns¶
An integer defining the maximum number of connections a pool can hold. Defaults
to 100.
pool¶
An array-reference of MongoDBx::Class::Connection objects, this is the actual
pool. Mostly used and populated internally.
num_used¶
For backup pools, this will be an integer indicating the number of connections
from the pool currently being used. For rotated pools, this will be the index
of the connection to be given to the next end-user.
params¶
A hash-ref of parameters to pass to "MongoDB::Connection->new()"
when creating a new connection. See "ATTRIBUTES" in
MongoDB::Connection for more information.
REQUIRED METHODS¶
This Moose role requires consuming classes to implement the following methods:
- •
- get_conn()
Returns a connection from the pool to a requester, possibly creating a new
one in the process if no connections are available and the maximum has not
been reached yet.
- •
- return_conn( $conn )
Returns a connection (receievd via "get_conn()") to the pool,
meant to be called by the end-user after being done with the connection.
Only relevant when "get_conn()" actually takes the connection
out of the pool (so it is not shared), like with backup pools. Otherwise
this method may do nothing.
PROVIDED METHODS¶
Meant to be used by consuming classes:
_get_new_conn()¶
Creates a new MongoDBx::Class::Connection object, increments the
"num_used" attribute, and returns the new connection. Should be used
by "get_conn()".
_inc_used( [ $int ] )¶
Increases the "num_used" attribute by $int (which can be negative), or
by 1 if $int is not supplied.
_add_to_pool( $conn )¶
Adds a connection object to the end of the pool (the "pool"
attribute).
AUTHOR¶
Ido Perlmuter, "<ido at ido50.net>"
BUGS¶
Please report any bugs or feature requests to "bug-mongodbx-class at
rt.cpan.org", or through the web interface at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MongoDBx-Class>. I will
be notified, and then you'll automatically be notified of progress on your bug
as I make changes.
SUPPORT¶
You can find documentation for this module with the perldoc command.
perldoc MongoDBx::Class::ConnectionPool
You can also look for information at:
- •
- RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MongoDBx::Class>
- •
- AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/MongoDBx::Class>
- •
- CPAN Ratings
<http://cpanratings.perl.org/d/MongoDBx::Class>
- •
- Search CPAN
<http://search.cpan.org/dist/MongoDBx::Class/>
SEE ALSO¶
MongoDBx::Class, MongoDB::Connection.
LICENSE AND COPYRIGHT¶
Copyright 2010-2014 Ido Perlmuter.
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.