/ 
MongoDBx-Class-1.01
River stage zero No dependents
/ MongoDBx::Class::ConnectionPool

NAME

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

VERSION

version 1.01

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 dependant 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:

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.