.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MongoDBx::Class::ConnectionPool 3pm" .TH MongoDBx::Class::ConnectionPool 3pm "2014-05-13" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" MongoDBx::Class::ConnectionPool \- A simple connection pool for MongoDBx::Class .SH "VERSION" .IX Header "VERSION" version 1.030002 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& # create a MongoDBx::Class object normally: \& use MongoDBx::Class; \& my $dbx = MongoDBx::Class\->new(namespace => \*(AqMyApp::Model::DB\*(Aq); \& \& # instead of connection, create a rotated pool \& my $pool = $dbx\->pool(max_conns => 200, type => \*(Aqrotated\*(Aq); # max_conns defaults to 100 \& \& # or, if you need to pass attributes to MongoDB::Connection\->new(): \& my $pool = $dbx\->pool(max_conns => 200, type => \*(Aqrotated\*(Aq, 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 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1WARNING:\s0 connection pooling via MongoDBx::Class is experimental. It is a quick, simple implementation that may or may not work as expected. .PP 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: .IP "\(bu" 4 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. .IP "\(bu" 4 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. .PP 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)? .PP At any rate, every end-user will receive a connection, shared or not. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "max_conns" .IX Subsection "max_conns" An integer defining the maximum number of connections a pool can hold. Defaults to 100. .SS "pool" .IX Subsection "pool" An array-reference of MongoDBx::Class::Connection objects, this is the actual pool. Mostly used and populated internally. .SS "num_used" .IX Subsection "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. .SS "params" .IX Subsection "params" A hash-ref of parameters to pass to \f(CW\*(C`MongoDB::Connection\->new()\*(C'\fR when creating a new connection. See \*(L"\s-1ATTRIBUTES\*(R"\s0 in MongoDB::Connection for more information. .SH "REQUIRED METHODS" .IX Header "REQUIRED METHODS" This Moose role requires consuming classes to implement the following methods: .IP "\(bu" 4 \&\fIget_conn()\fR .Sp 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. .IP "\(bu" 4 return_conn( \f(CW$conn\fR ) .Sp Returns a connection (receievd via \f(CW\*(C`get_conn()\*(C'\fR) to the pool, meant to be called by the end-user after being done with the connection. Only relevant when \f(CW\*(C`get_conn()\*(C'\fR actually takes the connection out of the pool (so it is not shared), like with backup pools. Otherwise this method may do nothing. .SH "PROVIDED METHODS" .IX Header "PROVIDED METHODS" Meant to be used by consuming classes: .SS "\fI_get_new_conn()\fP" .IX Subsection "_get_new_conn()" Creates a new MongoDBx::Class::Connection object, increments the \f(CW\*(C`num_used\*(C'\fR attribute, and returns the new connection. Should be used by \f(CW\*(C`get_conn()\*(C'\fR. .ie n .SS "_inc_used( [ $int ] )" .el .SS "_inc_used( [ \f(CW$int\fP ] )" .IX Subsection "_inc_used( [ $int ] )" Increases the \f(CW\*(C`num_used\*(C'\fR attribute by \f(CW$int\fR (which can be negative), or by 1 if \f(CW$int\fR is not supplied. .ie n .SS "_add_to_pool( $conn )" .el .SS "_add_to_pool( \f(CW$conn\fP )" .IX Subsection "_add_to_pool( $conn )" Adds a connection object to the end of the pool (the \f(CW\*(C`pool\*(C'\fR attribute). .SH "AUTHOR" .IX Header "AUTHOR" Ido Perlmuter, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-mongodbx\-class at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc MongoDBx::Class::ConnectionPool .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "SEE ALSO" .IX Header "SEE ALSO" MongoDBx::Class, MongoDB::Connection. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2010\-2014 Ido Perlmuter. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See http://dev.perl.org/licenses/ for more information.