NAME

DBIx::Threaded::Server - Server container class to provide thread-safe proxy for DBI objects

SYNOPSIS

        #
        #       NOTE: DBIx::Threaded::Server derived objects are
        #       not intended for direct use by an application.
        #       See DBIx::Threaded for the proxy client i/f
        #
        my $cmdq = Thread::Queue::Duplex->new();
        my $proxy = DBIx::Threaded::Server->new($cmdq);
        
        my $rc = $proxy->start('freeze', @connect_params);
        
        my $id = $cmdq->enqueue('do', @params);
        my $rc = $cmdq->wait($id);

DESCRIPTION

DBIx::Threaded::Server provides a container class to create and access a DBI connection within its own thread, in order to permit it to be used by multiple threads. As of version 1.48, DBI does not permit DBI-generated objects (namely, connection and statement handles) to be used outside of the thread in which they are created.

A pleasant side effect of DBIx::Threaded's architecture is that it permits thread-safe use of DBD's which are not currently thread-safe or thread-friendly.

NOTE: DBIx::Threaded::Server is not intended to be used directly by applications. See DBIx::Threaded for the DBI subclass which provides the client side stubs intended for application use.

DBIx::Threaded provides a Thread::Queue::Duplex object to DBIx::Threaded::Server objects when a connection is created (or when a pooled Server instance is created), in order to provide a lightweight communications channel between the client stubs and the server container objects, using either threads::shared variables, or Storable freeze/thaw to pass parameters and results between the client and server.

DBIx::Threaded is inspired by, but does not directly use, the Pots::* set of modules to implement threadsafe objects.

Also note that, due to the way in which Perl threads are spawned (i.e., cloning the entire interpretter context of the spawning thread), a create_pool() class level method is provided to permit creation of minimal context threads during application initialization, in order to conserve memory resources.

DBI method calls are initiated over the queue using threads::shared copies of the parameter list elements; however, alternate encodings are possible by implementing the Thread::Queue::Queueable interface on any objects in the parameter list to, e.g., use Storable freeze/thaw.

DBIx::Threaded::Server implements the following methods:

new

Constructor, creates a thread.

start

Starts the thread with connection parameters; the thread will immediately accept the connection parameters and attempt to connect.

stop

Stops the currently running thread.

run

Runs the thread routine as an infinite loop, dequeueing requests as they arrive on the queue, processing them by calling the appropriate DBI functions, and then collecting the results and posting the response to the queue via Thread::Queue::Duplex::respond().

AUTHOR, COPYRIGHT, & LICENSE

Dean Arnold, Presicient Corp. darnold@presicient.com

Copyright(C) 2005, Presicient Corp., USA

Permission is granted to use this software under the same terms as Perl itself. Refer to the Perl Artistic License for details.