[ViewVC] Annotation of: cvs/Coro-Mysql/README

NAME
    Coro::Mysql - let other threads run while doing mysql requests

SYNOPSIS
     use Coro::Mysql;

     my $DBH = Coro::Mysql::unblock DBI->connect (...);

DESCRIPTION
    (Note that in this manual, "thread" refers to real threads as
    implemented by the Coro module, not to the built-in windows process
    emulation which unfortunately is also called "threads")

    This module "patches" DBD::mysql database handles so that they do not
    block the whole process, but only the thread that they are used in.

    This can be used to make parallel sql requests using Coro, or to do
    other stuff while mysql is rumbling in the background.

  CAVEAT
    Note that this module must be linked against exactly the same
    libmysqlclient library as DBD::mysql, otherwise it will not work.

    Also, while this module makes database handles non-blocking, you still
    cannot run multiple requests in parallel on the same database handle. If
    you want to run multiple queries in parallel, you have to create
    multiple database connections, one for each thread that runs queries.

    If you make sure that you never run two or more requests in parallel,
    you cna freely share the database handles between threads, of course.

    Also, this module uses a number of "unclean" techniques (patching an
    internal libmysql structure for one thing) and was hacked within a few
    hours on a long flight to Malaysia.

    It does, however, check whether it indeed got the structure layout
    correct, so you should expect perl exceptions or early crashes as
    opposed to data corruption when something goes wrong.

  SPEED
    This module is implemented in XS, and as long as mysqld replies quickly
    enough, it adds no overhead to the standard libmysql communication
    routines (which are very badly written).

    For very fast queries ("select 0"), this module can add noticable
    overhead (around 15%) as it tries to switch to other coroutines when
    mysqld doesn't deliver the data instantly.

    For most types of queries, there will be no overhead, especially on
    multicore systems where your perl process can do other things while
    mysqld does its stuff.

    $DBH = Coro::Mysql::unblock $DBH
        This function takes a DBI database handles and "patches" it so it
        becomes compatible to Coro threads.

        After that, it returns the patched handle - you should always use
        the newly returned database handle.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.2
Committed:	Sat May 30 06:58:22 2009 UTC (15 years ago) by root
Branch:	MAIN
CVS Tags:	rel-0_1
Changes since 1.1:	+63 -0 lines
Log Message:	0.1
#	User	Rev	Content
1	root	1.2	NAME
2			Coro::Mysql - let other threads run while doing mysql requests
3
4			SYNOPSIS
5			use Coro::Mysql;
6
7			my $DBH = Coro::Mysql::unblock DBI->connect (...);
8
9			DESCRIPTION
10			(Note that in this manual, "thread" refers to real threads as
11			implemented by the Coro module, not to the built-in windows process
12			emulation which unfortunately is also called "threads")
13
14			This module "patches" DBD::mysql database handles so that they do not
15			block the whole process, but only the thread that they are used in.
16
17			This can be used to make parallel sql requests using Coro, or to do
18			other stuff while mysql is rumbling in the background.
19
20			CAVEAT
21			Note that this module must be linked against exactly the same
22			libmysqlclient library as DBD::mysql, otherwise it will not work.
23
24			Also, while this module makes database handles non-blocking, you still
25			cannot run multiple requests in parallel on the same database handle. If
26			you want to run multiple queries in parallel, you have to create
27			multiple database connections, one for each thread that runs queries.
28
29			If you make sure that you never run two or more requests in parallel,
30			you cna freely share the database handles between threads, of course.
31
32			Also, this module uses a number of "unclean" techniques (patching an
33			internal libmysql structure for one thing) and was hacked within a few
34			hours on a long flight to Malaysia.
35
36			It does, however, check whether it indeed got the structure layout
37			correct, so you should expect perl exceptions or early crashes as
38			opposed to data corruption when something goes wrong.
39
40			SPEED
41			This module is implemented in XS, and as long as mysqld replies quickly
42			enough, it adds no overhead to the standard libmysql communication
43			routines (which are very badly written).
44
45			For very fast queries ("select 0"), this module can add noticable
46			overhead (around 15%) as it tries to switch to other coroutines when
47			mysqld doesn't deliver the data instantly.
48
49			For most types of queries, there will be no overhead, especially on
50			multicore systems where your perl process can do other things while
51			mysqld does its stuff.
52
53			$DBH = Coro::Mysql::unblock $DBH
54			This function takes a DBI database handles and "patches" it so it
55			becomes compatible to Coro threads.
56
57			After that, it returns the patched handle - you should always use
58			the newly returned database handle.
59
60			AUTHOR
61			Marc Lehmann <schmorp@schmorp.de>
62			http://home.schmorp.de/
63