NAME

       MongoDBx::Class::ConnectionPool - A simple connection pool for MongoDBx::Class

VERSION

       version 1.02

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

perl v5.14.2                                       2013-07-22               MongoDBx::Class::ConnectionPool(3pm)