view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

DBIx::Connector::Pool - A pool of DBIx::Connector or its subclasses for asynchronous environment

# SYNOPSIS

    use Coro;
    use AnyEvent;
    use Coro::AnyEvent;
    use DBIx::Connector::Pool;
    
    my $pool = DBIx::Connector::Pool->new(
      initial    => 1,
      keep_alive => 1,
      max_size   => 5,
      tid_func   => sub {"$Coro::current" =~ /(0x[0-9a-f]+)/i; hex $1},
      wait_func => sub        {Coro::AnyEvent::sleep 0.05},
      attrs     => {RootClass => 'DBIx::PgCoroAnyEvent'}
    );
    
    async {
      my $connector = $pool->get_connector;
      $connector->run(
        sub {
          my $sth = $_->prepare(q{select isbn, title, rating from books});
          $sth->execute;
          my ($isbn, $title, $rating) = $sth->fetchrow_array;
          # ... 
        }
      );
    };

# Description

[DBI](https://metacpan.org/pod/DBI) is great and [DBIx::Connector](https://metacpan.org/pod/DBIx::Connector) is a nice interface with good features 
to it. But when it comes to work in some asynchronous environment like
[AnyEvent](https://metacpan.org/pod/AnyEvent) you have to use something another with callbacks if you don't want
to block your event loop completely waiting for data from DB. This module 
(together with [DBIx::PgCoroAnyEvent](https://metacpan.org/pod/DBIx::PgCoroAnyEvent) for PostgreSQL or some another alike) 
was developed to overcome this inconvenience. You can write your "normal" DBI
code without blocking your event loop. 

This module requires some threading model and I know about only one really 
working [Coro](https://metacpan.org/pod/Coro). 

# Methods

- **new**

        my $pool = DBIx::Connector::Pool->new(
          initial    => 1,
          keep_alive => 1,
          max_size   => 5,
          tid_func   => sub {"$Coro::current" =~ /(0x[0-9a-f]+)/i; hex $1},
          wait_func => sub        {Coro::AnyEvent::sleep 0.05},
          attrs     => {RootClass => 'DBIx::PgCoroAnyEvent'}
        );

    Creates new pool. Possible parameters:

    - **initial**

        Initial number of connected connectors. This means also minimum of of
        connected connectors. It throws error if this minimum can not be met.

    - **keep\_alive**

        How long connector can live after it becomes unused. Initial connectors will
        live forever. `-1` means no limit. `0` means collect it immediate. Positive 
        number means seconds.

    - **max\_size**

        Maximum pool capacity. `-1` means unlimited.

    - **user**
    - **password**
    - **dsn**
    - **attrs**

        Data for `DBIx::Connector->new` function. This is the same as for 
        `DBI->connect`. Usually you want to add some unblocking DBI subclass
        as `RootClass` attribute. Like `RootClass => 'DBIx::PgCoroAnyEvent'`
        for PostgreSQL.  

    - **tid\_func**

        Thread identification function. Must return number. Good choice for [Coro](https://metacpan.org/pod/Coro) is

            sub {"$Coro::current" =~ /(0x[0-9a-f]+)/i; hex $1}

    - **wait\_func**

        This function put **get\_connector** into sleep to wait for a free connector 
        in pool.

    - **connector\_base**