.\" 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 "Mango 3pm"
.TH Mango 3pm "2013-12-13" "perl v5.18.1" "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"
Mango \- Pure\-Perl non\-blocking I/O MongoDB driver
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mango;
\&
\&  # Insert document
\&  my $mango = Mango\->new(\*(Aqmongodb://localhost:27017\*(Aq);
\&  my $oid   = $mango\->db(\*(Aqtest\*(Aq)\->collection(\*(Aqfoo\*(Aq)\->insert({bar => \*(Aqbaz\*(Aq});
\&
\&  # Find document
\&  my $doc = $mango\->db(\*(Aqtest\*(Aq)\->collection(\*(Aqfoo\*(Aq)\->find_one({bar => \*(Aqbaz\*(Aq});
\&  say $doc\->{bar};
\&
\&  # Update document
\&  $mango\->db(\*(Aqtest\*(Aq)\->collection(\*(Aqfoo\*(Aq)
\&    \->update({bar => \*(Aqbaz\*(Aq}, {bar => \*(Aqyada\*(Aq});
\&
\&  # Remove document
\&  $mango\->db(\*(Aqtest\*(Aq)\->collection(\*(Aqfoo\*(Aq)\->remove({bar => \*(Aqyada\*(Aq});
\&
\&  # Insert document with special BSON types
\&  use Mango::BSON \*(Aq:bson\*(Aq;
\&  my $oid = $mango\->db(\*(Aqtest\*(Aq)\->collection(\*(Aqfoo\*(Aq)
\&    \->insert({data => bson_bin("\ex00\ex01"), now => bson_time});
\&
\&  # Blocking parallel find (does not work inside a running event loop)
\&  my $delay = Mojo::IOLoop\->delay;
\&  for my $name (qw(sri marty)) {
\&    my $end = $delay\->begin(0);
\&    $mango\->db(\*(Aqtest\*(Aq)\->collection(\*(Aqusers\*(Aq)\->find({name => $name})\->all(sub {
\&      my ($cursor, $err, $docs) = @_;
\&      $end\->(@$docs);
\&    });
\&  }
\&  my @docs = $delay\->wait;
\&
\&  # Non\-blocking parallel find (does work inside a running event loop)
\&  my $delay = Mojo::IOLoop\->delay(sub {
\&    my ($delay, @docs) = @_;
\&    ...
\&  });
\&  for my $name (qw(sri marty)) {
\&    my $end = $delay\->begin(0);
\&    $mango\->db(\*(Aqtest\*(Aq)\->collection(\*(Aqusers\*(Aq)\->find({name => $name})\->all(sub {
\&      my ($cursor, $err, $docs) = @_;
\&      $end\->(@$docs);
\&    });
\&  }
\&  $delay\->wait unless Mojo::IOLoop\->is_running;
\&
\&  # Event loops such as AnyEvent are supported through EV
\&  use EV;
\&  use AnyEvent;
\&  my $cv = AE::cv;
\&  $mango\->db(\*(Aqtest\*(Aq)\->command(buildInfo => sub {
\&    my ($db, $err, $doc) = @_;
\&    $cv\->send($doc\->{version});
\&  });
\&  say $cv\->recv;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mango is a pure-Perl non-blocking I/O MongoDB driver, optimized for use
with the Mojolicious real-time web framework, and with multiple event loop
support. Since MongoDB is still changing rapidly, only the latest stable
version is supported.
.PP
To learn more about MongoDB you should take a look at the
official documentation <http://docs.mongodb.org>, the documentation included
in this distribution is no replacement for it.
.PP
Note that this whole distribution is \s-1EXPERIMENTAL\s0 and will change without
warning!
.PP
Most of the \s-1API\s0 is not changing much anymore, but you should wait for a stable
1.0 release before using any of the modules in this distribution in a
production environment. Unsafe operations are not supported, so far this is
considered a feature.
.PP
Many arguments passed to methods as well as values of attributes get
serialized to \s-1BSON\s0 with Mango::BSON, which provides many helper functions
you can use to generate data types that are not available natively in Perl.
All connections will be reset automatically if a new process has been forked,
this allows multiple processes to share the same Mango object safely.
.PP
For better scalability (epoll, kqueue) and to provide IPv6 as well as \s-1TLS\s0
support, the optional modules \s-1EV\s0 (4.0+), IO::Socket::IP (0.16+) and
IO::Socket::SSL (1.75+) will be used automatically by Mojo::IOLoop if
they are installed. Individual features can also be disabled with the
\&\s-1MOJO_NO_IPV6\s0 and \s-1MOJO_NO_TLS\s0 environment variables.
.SH "EVENTS"
.IX Header "EVENTS"
Mango inherits all events from Mojo::EventEmitter and can emit the
following new ones.
.SS "connection"
.IX Subsection "connection"
.Vb 4
\&  $mango\->on(connection => sub {
\&    my ($mango, $id) = @_;
\&    ...
\&  });
.Ve
.PP
Emitted when a new connection has been established.
.SS "error"
.IX Subsection "error"
.Vb 4
\&  $mango\->on(error => sub {
\&    my ($mango, $err) = @_;
\&    ...
\&  });
.Ve
.PP
Emitted if an error occurs that can't be associated with an operation.
.PP
.Vb 4
\&  $mango\->on(error => sub {
\&    my ($mango, $err) = @_;
\&    say "This looks bad: $err";
\&  });
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Mango implements the following attributes.
.SS "credentials"
.IX Subsection "credentials"
.Vb 2
\&  my $credentials = $mango\->credentials;
\&  $mango          = $mango\->credentials([[\*(Aqtest\*(Aq, \*(Aqsri\*(Aq, \*(Aqs3cret\*(Aq]]);
.Ve
.PP
Authentication credentials that will be used on every reconnect.
.SS "default_db"
.IX Subsection "default_db"
.Vb 2
\&  my $name = $mango\->default_db;
\&  $mango   = $mango\->default_db(\*(Aqtest\*(Aq);
.Ve
.PP
Default database, defaults to \f(CW\*(C`admin\*(C'\fR.
.SS "hosts"
.IX Subsection "hosts"
.Vb 2
\&  my $hosts = $mango\->hosts;
\&  $mango    = $mango\->hosts([[\*(Aqlocalhost\*(Aq, 3000], [\*(Aqlocalhost\*(Aq, 4000]]);
.Ve
.PP
Servers to connect to, defaults to \f(CW\*(C`localhost\*(C'\fR and port \f(CW27017\fR.
.SS "ioloop"
.IX Subsection "ioloop"
.Vb 2
\&  my $loop = $mango\->ioloop;
\&  $mango   = $mango\->ioloop(Mojo::IOLoop\->new);
.Ve
.PP
Event loop object to use for blocking I/O operations, defaults to a
Mojo::IOLoop object.
.SS "j"
.IX Subsection "j"
.Vb 2
\&  my $j  = $mango\->j;
\&  $mango = $mango\->j(1);
.Ve
.PP
Wait for all operations to have reached the journal, defaults to \f(CW0\fR.
.SS "max_connections"
.IX Subsection "max_connections"
.Vb 2
\&  my $max = $mango\->max_connections;
\&  $mango  = $mango\->max_connections(5);
.Ve
.PP
Maximum number of connections to use for non-blocking operations, defaults to
\&\f(CW5\fR.
.SS "protocol"
.IX Subsection "protocol"
.Vb 2
\&  my $protocol = $mango\->protocol;
\&  $mango       = $mango\->protocol(Mango::Protocol\->new);
.Ve
.PP
Protocol handler, defaults to a Mango::Protocol object.
.SS "w"
.IX Subsection "w"
.Vb 2
\&  my $w  = $mango\->w;
\&  $mango = $mango\->w(2);
.Ve
.PP
Wait for all operations to have reached at least this many servers, \f(CW1\fR
indicates just primary, \f(CW2\fR indicates primary and at least one secondary,
defaults to \f(CW1\fR.
.SS "wtimeout"
.IX Subsection "wtimeout"
.Vb 2
\&  my $timeout = $mango\->wtimeout;
\&  $mango      = $mango\->wtimeout(1);
.Ve
.PP
Timeout for write propagation in milliseconds, defaults to \f(CW1000\fR.
.SH "METHODS"
.IX Header "METHODS"
Mango inherits all methods from Mojo::Base and implements the following
new ones.
.SS "new"
.IX Subsection "new"
.Vb 2
\&  my $mango = Mango\->new;
\&  my $mango = Mango\->new(\*(Aqmongodb://sri:s3cret@localhost:3000/test?w=2\*(Aq);
.Ve
.PP
Construct a new Mango object and parse connection string with
\&\*(L"from_string\*(R" if necessary.
.SS "backlog"
.IX Subsection "backlog"
.Vb 1
\&  my $num = $mango\->backlog;
.Ve
.PP
Number of queued operations that have not yet been assigned to a connection.
.SS "db"
.IX Subsection "db"
.Vb 2
\&  my $db = $mango\->db;
\&  my $db = $mango\->db(\*(Aqtest\*(Aq);
.Ve
.PP
Get Mango::Database object for database, uses \*(L"default_db\*(R" if no name
is provided. Note that the reference \*(L"mango\*(R" in Mango::Database is weakened,
so the Mango object needs to be referenced elsewhere as well.
.SS "delete"
.IX Subsection "delete"
.Vb 1
\&  my $reply = $mango\->delete($namespace, $flags, $query);
.Ve
.PP
Perform low level \f(CW\*(C`delete\*(C'\fR operation followed by \f(CW\*(C`getLastError\*(C'\fR command. You
can also append a callback to perform operation non-blocking.
.PP
.Vb 5
\&  $mango\->delete(($namespace, $flags, $query) => sub {
\&    my ($mango, $err, $reply) = @_;
\&    ...
\&  });
\&  Mojo::IOLoop\->start unless Mojo::IOLoop\->is_running;
.Ve
.SS "from_string"
.IX Subsection "from_string"
.Vb 2
\&  $mango
\&    = $mango\->from_string(\*(Aqmongodb://sri:s3cret@localhost:3000/test?w=2\*(Aq);
.Ve
.PP
Parse configuration from connection string.
.SS "get_more"
.IX Subsection "get_more"
.Vb 1
\&  my $reply = $mango\->get_more($namespace, $return, $cursor);
.Ve
.PP
Perform low level \f(CW\*(C`get_more\*(C'\fR operation. You can also append a callback to
perform operation non-blocking.
.PP
.Vb 5
\&  $mango\->get_more(($namespace, $return, $cursor) => sub {
\&    my ($mango, $err, $reply) = @_;
\&    ...
\&  });
\&  Mojo::IOLoop\->start unless Mojo::IOLoop\->is_running;
.Ve
.SS "insert"
.IX Subsection "insert"
.Vb 1
\&  my $reply = $mango\->insert($namespace, $flags, @docs);
.Ve
.PP
Perform low level \f(CW\*(C`insert\*(C'\fR operation followed by \f(CW\*(C`getLastError\*(C'\fR command. You
can also append a callback to perform operation non-blocking.
.PP
.Vb 5
\&  $mango\->insert(($namespace, $flags, @docs) => sub {
\&    my ($mango, $err, $reply) = @_;
\&    ...
\&  });
\&  Mojo::IOLoop\->start unless Mojo::IOLoop\->is_running;
.Ve
.SS "kill_cursors"
.IX Subsection "kill_cursors"
.Vb 1
\&  $mango\->kill_cursors(@ids);
.Ve
.PP
Perform low level \f(CW\*(C`kill_cursors\*(C'\fR operation. You can also append a callback to
perform operation non-blocking.
.PP
.Vb 5
\&    $mango\->kill_cursors(@ids => sub {
\&      my ($mango, $err) = @_;
\&      ...
\&    });
\&    Mojo::IOLoop\->start unless Mojo::IOLoop\->is_running;
.Ve
.SS "query"
.IX Subsection "query"
.Vb 2
\&  my $reply
\&    = $mango\->query($namespace, $flags, $skip, $return, $query, $fields);
.Ve
.PP
Perform low level \f(CW\*(C`query\*(C'\fR operation. You can also append a callback to
perform operation non-blocking.
.PP
.Vb 5
\&  $mango\->query(($namespace, $flags, $skip, $return, $query, $fields) => sub {
\&    my ($mango, $err, $reply) = @_;
\&    ...
\&  });
\&  Mojo::IOLoop\->start unless Mojo::IOLoop\->is_running;
.Ve
.SS "update"
.IX Subsection "update"
.Vb 1
\&  my $reply = $mango\->update($namespace, $flags, $query, $update);
.Ve
.PP
Perform low level \f(CW\*(C`update\*(C'\fR operation followed by \f(CW\*(C`getLastError\*(C'\fR command. You
can also append a callback to perform operation non-blocking.
.PP
.Vb 5
\&  $mango\->update(($namespace, $flags, $query, $update) => sub {
\&    my ($mango, $err, $reply) = @_;
\&    ...
\&  });
\&  Mojo::IOLoop\->start unless Mojo::IOLoop\->is_running;
.Ve
.SH "DEBUGGING"
.IX Header "DEBUGGING"
You can set the \f(CW\*(C`MANGO_DEBUG\*(C'\fR environment variable to get some advanced
diagnostics information printed to \f(CW\*(C`STDERR\*(C'\fR.
.PP
.Vb 1
\&  MANGO_DEBUG=1
.Ve
.SH "SPONSORS"
.IX Header "SPONSORS"
Some of the work on this distribution has been sponsored by
Drip Depot <http://www.dripdepot.com>, thank you!
.SH "AUTHOR"
.IX Header "AUTHOR"
Sebastian Riedel, \f(CW\*(C`sri@cpan.org\*(C'\fR.
.SH "CREDITS"
.IX Header "CREDITS"
In alphabetical order:
.Sp
.RS 2
Andrey Khozov
.RE
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2013, Sebastian Riedel.
.PP
This program is free software, you can redistribute it and/or modify it under
the terms of the Artistic License version 2.0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious::Guides, <http://mojolicio.us>.