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.