view release on metacpan or  search on metacpan

lib/MongoDB/Async.pm  view on Meta::CPAN

#  You may obtain a copy of the License at
#
#  http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#

use v5.10.0;
use strict;
use warnings;

package MongoDB::Async;
{
  $MongoDB::Async::VERSION = '0.702.3';
}
# ABSTRACT: A Mongo Driver for Perl

use XSLoader;
use MongoDB::Async::Connection;
use MongoDB::Async::MongoClient;
use MongoDB::Async::Database;
use MongoDB::Async::Collection;

use MongoDB::Async::DBRef;
# use MongoDB::Async::OID;

use EV;
use Coro;
use Coro::EV;


XSLoader::load(__PACKAGE__, $MongoDB::Async::VERSION, int rand(2 ** 24));

1;

__END__

=pod

=head1 NAME

MongoDB::Async - Asynchronous Mongo Driver for Perl

=head1 ABOUT ASYNC DRIVER

Changes relative to L<MongoDB>:

L<MongoDB::Async::Pool> - pool of persistent connects

Added ->data method to L<MongoDB::Async::Cursor>. Same as ->all, but returns array ref. 

dt_type now $MongoDB::Async::BSON::dt_type global variable, not connection object property 

inflate_dbrefs now $MongoDB::Async::Cursor::inflate_dbrefs global variable


This module is 20-100% (in single-(coro)threaded test , mulithreaded will be even faster) faster than original L<MongoDB>. See benchmark L<http://pastebin.com/vFWENzW7> or run benchmark_compare.pl from archive. It might be 1-5% slower than original o...

This driver NOT ithreads safe

SASL and SSL unsupported (ssl may work in blocking mode, not tested it). 

PLEASE DON'T USE documentation of this module and refere to doc of original MongoDB module with corresponding version. Because I'm porting here only features and too lazy to copy-paste docs.

Don't work with this module inside Coro::unblock_sub, it leaks memory. Use separate coro thread to work with database, and if you need callback interface you need to write it yourself.

Please report bugs/suggestions to I<nyaknyan@gmail.com> or cpan's RT.


TODO:

Make async connection - currently it may block for some time while trying to connect to node which is down.

Implement SSL support using normal SSL module object. 

May (or may not, not tested it) segfault if intesively trying reconnect to servers under heavy load. Fix it.

Minimize Moose usage, because perl isn't C++ or Java and all this getter/setter shit if just slow. 

=head1 VERSION

version 0.702.3

=head1 SYNOPSIS

    use MongoDB::Async;

    my $client     = MongoDB::Async::MongoClient->new(host => 'localhost', port => 27017);
    my $database   = $client->get_database( 'foo' );
    my $collection = $database->get_collection( 'bar' );
    my $id         = $collection->insert({ some => 'data' });
    my $data       = $collection->find_one({ _id => $id });

=head1 DESCRIPTION

MongoDB is a database access module.

MongoDB (the database) store all strings as UTF-8.  Non-UTF-8 strings will be
forcibly converted to UTF-8.  To convert something from another encoding to
UTF-8, you can use L<Encode>:

    use Encode;

    my $name = decode('cp932', "\x90\xbc\x96\xec\x81\x40\x91\xbe\x98\x59");
    my $id = $coll->insert( { name => $name, } );

    my $object = $coll->find_one( { name => $name } );

Thanks to taronishino for this example.

=head2 Notation and Conventions

The following conventions are used in this document:

    $client Database client object
    $db     Database
    $coll   Collection
    undef   C<null> values are represented by undefined values in Perl
    \@arr   Reference to an array passed to methods
    \%attr  Reference to a hash of attribute values passed to methods

Note that Perl will automatically close and clean up database connections if
all references to them are deleted.

=head2 Outline Usage