cvsroot/Coro-Multicore/Multicore.pm

=head1 NAME

Coro::Multicore - make coro threads on multiple cores with specially supported modules

=head1 SYNOPSIS

 use Coro::Multicore;

=head1 DESCRIPTION

While L<Coro> threads (unlike ithreads) provide real threads similar to
pthreads, python threads and so on, they do not run in parallel to each
other even on machines with multiple CPUs or multiple CPU cores.

This module lifts this restriction under two very specific but useful
conditions: firstly, the coro thread executes in XS code and does not
touch any perl data structures, and secondly, the XS code is specially
prepared to allow this.

This means that, when you call an XS function of a module prepared for it,
this XS function can execute in parallel to any other Coro threads.

The mechanism to support this is easily added to existing modules
and is independent of L<Coro> or L<Coro::Multicore>, and therefore
could be used, without changes, with other, similar, modules, or even
the perl core, should it gain real thread support anytime soon. See
L<http://pod.tst.eu/http://cvs.schmorp.de/Coro-Multicore/perlmulticore.h>
for more info on how to prepare a module to allow parallel execution.

This module is an L<AnyEvent> user (and also, if not obvious, uses
L<Coro>).

=head1 HOW TO USE IT

It could hardly be simpler - if you use coro threads, and before you call
a supported lengthy operation implemented in XS, use this module and other
coro threads can run in parallel:

   use Coro::Multicore;

This module has no important API functions to learn or remember. All you
need to do is I<load> it before you can take advantage of it.

=head1 API FUNCTIONS

=over 4

=item $previous = Coro::Multicore::enable [$enable]

This function enables (if C<$enable> is true) or disables (if C<$enable>
is false) the multicore functionality globally. By default, it is enabled.

This can be used to effectively disable this module's functionality by
default, and enable it only for selected threads or scopes, by calling
C<Coro::Multicore::scope_enable>.

The function returns the previous value of the enable flag.

=item Coro::Multicore::scoped_enable

This function instructs Coro::Multicore to handle all requests executed
in the current coro thread, from the call to the end of the current scope.

Calls to C<scoped_enable> and C<scoped_disable> don't nest very well at
the moment, so don't nest them.

=item Coro::Multicore::scoped_disable

The opposite of C<Coro::Multicore::scope_disable>: instructs Coro::Multicore to
I<not> handle the next multicore-enabled request.

=item $previous = Coro::Multicore::max_idle_threads [$count]

To run on multiple cores, this module creates I<threads>. Since thread
creation is costly, it will keep some of them around for future uses. This
function returns the current maximum number of threads that are being kept
around (default: C<8>), and can be used to set a new limit, in case you
have bigger requirements.

Future implementations will also provide a timeout mechanism, for even
better behaviour.

=back

=cut

package Coro::Multicore;

use Coro ();
use AnyEvent ();

BEGIN {
   our $VERSION = 0.02;

   use XSLoader;
   XSLoader::load __PACKAGE__, $VERSION;
}

our $WATCHER = AE::io fd, 0, \&poll;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html

=cut

1

Revision:	1.4
Committed:	Sun Jun 28 17:39:42 2015 UTC (11 years, 3 months ago) by root
Branch:	MAIN
Changes since 1.3:	+25 -3 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Coro::Multicore - make coro threads on multiple cores with specially supported modules
4
5			=head1 SYNOPSIS
6
7			use Coro::Multicore;
8
9			=head1 DESCRIPTION
10
11	root	1.2	While L<Coro> threads (unlike ithreads) provide real threads similar to
12	root	1.3	pthreads, python threads and so on, they do not run in parallel to each
13	root	1.2	other even on machines with multiple CPUs or multiple CPU cores.
14
15			This module lifts this restriction under two very specific but useful
16			conditions: firstly, the coro thread executes in XS code and does not
17			touch any perl data structures, and secondly, the XS code is specially
18			prepared to allow this.
19
20			This means that, when you call an XS function of a module prepared for it,
21			this XS function can execute in parallel to any other Coro threads.
22
23	root	1.3	The mechanism to support this is easily added to existing modules
24			and is independent of L<Coro> or L<Coro::Multicore>, and therefore
25			could be used, without changes, with other, similar, modules, or even
26			the perl core, should it gain real thread support anytime soon. See
27			L<http://pod.tst.eu/http://cvs.schmorp.de/Coro-Multicore/perlmulticore.h>
28			for more info on how to prepare a module to allow parallel execution.
29
30			This module is an L<AnyEvent> user (and also, if not obvious, uses
31			L<Coro>).
32
33			=head1 HOW TO USE IT
34
35			It could hardly be simpler - if you use coro threads, and before you call
36			a supported lengthy operation implemented in XS, use this module and other
37			coro threads can run in parallel:
38
39			use Coro::Multicore;
40
41			This module has no important API functions to learn or remember. All you
42			need to do is I<load> it before you can take advantage of it.
43
44	root	1.4	=head1 API FUNCTIONS
45	root	1.3
46	root	1.4	=over 4
47
48			=item $previous = Coro::Multicore::enable [$enable]
49
50			This function enables (if C<$enable> is true) or disables (if C<$enable>
51			is false) the multicore functionality globally. By default, it is enabled.
52
53			This can be used to effectively disable this module's functionality by
54			default, and enable it only for selected threads or scopes, by calling
55			C<Coro::Multicore::scope_enable>.
56
57			The function returns the previous value of the enable flag.
58	root	1.2
59	root	1.4	=item Coro::Multicore::scoped_enable
60
61			This function instructs Coro::Multicore to handle all requests executed
62			in the current coro thread, from the call to the end of the current scope.
63
64			Calls to C<scoped_enable> and C<scoped_disable> don't nest very well at
65			the moment, so don't nest them.
66
67			=item Coro::Multicore::scoped_disable
68
69			The opposite of C<Coro::Multicore::scope_disable>: instructs Coro::Multicore to
70			I<not> handle the next multicore-enabled request.
71	root	1.1
72	root	1.3	=item $previous = Coro::Multicore::max_idle_threads [$count]
73
74			To run on multiple cores, this module creates I<threads>. Since thread
75			creation is costly, it will keep some of them around for future uses. This
76			function returns the current maximum number of threads that are being kept
77			around (default: C<8>), and can be used to set a new limit, in case you
78			have bigger requirements.
79
80			Future implementations will also provide a timeout mechanism, for even
81			better behaviour.
82
83			=back
84
85	root	1.1	=cut
86
87			package Coro::Multicore;
88
89			use Coro ();
90			use AnyEvent ();
91
92			BEGIN {
93			our $VERSION = 0.02;
94
95			use XSLoader;
96			XSLoader::load __PACKAGE__, $VERSION;
97			}
98
99			our $WATCHER = AE::io fd, 0, \&poll;
100
101			=head1 AUTHOR
102
103			Marc Lehmann <schmorp@schmorp.de>
104			http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html
105
106			=cut
107
108			1
109