cvsroot/Coro-Multicore/Multicore.pm

=head1 NAME

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

=head1 SYNOPSIS

 # when you DO control the main event loop, e.g. in the main program

 use Coro::Multicore; # enable by default

 Coro::Multicore::scoped_disable;
 EV::loop; # or AnyEvent::Loop::run, Event::loop, AE::cv->recv, ...

 # when you DO NOT control the event loop, e.g. in a module on CPAN

 use Coro::Multicore (); # disable by default

 async {
    Coro::Multicore::scoped_enable;

    # blocking is safe in your own threads
    ...
 };

=head1 DESCRIPTION

EXPERIMENTAL WARNING: This module is in its early stages of
development. It's fine to try out, but it didn't receive the normal amount
of testing and real-world usage that my other modules have gone through.

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://perlmulticore.schmorp.de/> for more info on how to prepare a
module to allow parallel execution. Preparing an existing module is easy,
doesn't add much overhead and no dependencies.

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.

=head2 EXPORTS

This module does not (at the moment) export any symbols. It does, however,
export "behaviour" - if you use the default import, then Coro::Multicore
will be enabled for all threads and all callers in the whole program:

   use Coro::Multicore;

In a module where you don't control what else might be loaded and run, you
might want to be more conservative, and not import anything. This has the
effect of not enabling the functionality by default, so you have to enable
it per scope:

   use Coro::Multicore ();

   sub myfunc {
      Coro::Multicore::scoped_enable;

      # from here to the end of this function, and in any functions
      # called from this function, tasks will be executed asynchronously.
   }

=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.

=back

=cut

package Coro::Multicore;

use Coro ();
use AnyEvent ();

BEGIN {
   our $VERSION = 0.02;

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


sub import {
   if (@_ > 1) {
      require Carp;
      Carp::croak ("Coro::Multicore does not export any symbols");
   }

   enable 1;
}

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

=head1 INTERACTION WITH OTHER SOFTWARE

This module is very similar to other environments where perl interpreters
are moved between threads, such as mod_perl2, and the same caveats apply.

I want to spell out the most important ones:

=over 4

=item pthreads usage

Any creation of pthreads make it impossible to fork portably from a
perl program, as forking from within a threaded program will leave the
program in a state similar to a signal handler. While it might work on
some platforms (as an extension), this might also result in silent data
corruption. It also seems to work most of the time, so it's hard to test
for this.

I recommend using something like L<AnyEvent::Fork>, which can create
subprocesses safely (via L<Proc::FastSpawn>).

Similar issues exist for signal handlers, although this module works hard
to keep safe perl signals safe.

=item module support

This module moves the same perl interpreter between different
threads. Some modules might get confused by that (although this can
usually be considered a bug). This is a rare case though.

=item event loop reliance

To be able to wake up programs waiting for results, this module relies on
an active event loop (via L<AnyEvent>). This is used to notify the perl
interpreter when the asynchronous task is done.

Since event loops typically fail to work properly after a fork, this means
that some operations that were formerly working will now hang after fork.

A workaround is to call C<Coro::Multicore::enable 0> after a fork to
disable the module.

Future versions of this module might do this automatically.

=back

=head1 BUGS

=over 4

=item (OS-) threads are never released

At the moment, threads that were created once will never be freed. They
will be reused for asynchronous requests, though, so as long as you limit
the maximum number of concurrent asynchronous tasks, this will also limit
the maximum number of threads created.

The idle threads are not necessarily using a lot of resources: on
GNU/Linux + glibc, each thread takes about 8KiB of userspace memory +
whatever the kernel needs (probably less than 8KiB).

Future versions will likely lift this limitation.

=item AnyEvent is initalised at module load time

AnyEvent is initialised on module load, as opposed to at a later time.

Future versions will likely change this.

=back

=head1 AUTHOR

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

Additional thanks to Zsbán Ambrus, who gave considerable desing input for
this module and the perl multicore specification.

=cut

1

Revision:	1.9
Committed:	Mon Jul 27 12:05:09 2015 UTC (11 years, 2 months ago) by root
Branch:	MAIN
Changes since 1.8:	+16 -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	root	1.9	# when you DO control the main event loop, e.g. in the main program
8	root	1.1
9	root	1.9	use Coro::Multicore; # enable by default
10
11			Coro::Multicore::scoped_disable;
12			EV::loop; # or AnyEvent::Loop::run, Event::loop, AE::cv->recv, ...
13
14			# when you DO NOT control the event loop, e.g. in a module on CPAN
15
16			use Coro::Multicore (); # disable by default
17
18			async {
19			Coro::Multicore::scoped_enable;
20
21			# blocking is safe in your own threads
22			...
23			};
24	root	1.5
25	root	1.1	=head1 DESCRIPTION
26
27	root	1.7	EXPERIMENTAL WARNING: This module is in its early stages of
28			development. It's fine to try out, but it didn't receive the normal amount
29			of testing and real-world usage that my other modules have gone through.
30
31	root	1.2	While L<Coro> threads (unlike ithreads) provide real threads similar to
32	root	1.3	pthreads, python threads and so on, they do not run in parallel to each
33	root	1.2	other even on machines with multiple CPUs or multiple CPU cores.
34
35			This module lifts this restriction under two very specific but useful
36			conditions: firstly, the coro thread executes in XS code and does not
37			touch any perl data structures, and secondly, the XS code is specially
38			prepared to allow this.
39
40			This means that, when you call an XS function of a module prepared for it,
41			this XS function can execute in parallel to any other Coro threads.
42
43	root	1.3	The mechanism to support this is easily added to existing modules
44			and is independent of L<Coro> or L<Coro::Multicore>, and therefore
45			could be used, without changes, with other, similar, modules, or even
46			the perl core, should it gain real thread support anytime soon. See
47	root	1.5	L<http://perlmulticore.schmorp.de/> for more info on how to prepare a
48			module to allow parallel execution. Preparing an existing module is easy,
49			doesn't add much overhead and no dependencies.
50	root	1.3
51			This module is an L<AnyEvent> user (and also, if not obvious, uses
52			L<Coro>).
53
54			=head1 HOW TO USE IT
55
56			It could hardly be simpler - if you use coro threads, and before you call
57			a supported lengthy operation implemented in XS, use this module and other
58			coro threads can run in parallel:
59
60			use Coro::Multicore;
61
62			This module has no important API functions to learn or remember. All you
63			need to do is I<load> it before you can take advantage of it.
64
65	root	1.5	=head2 EXPORTS
66
67			This module does not (at the moment) export any symbols. It does, however,
68			export "behaviour" - if you use the default import, then Coro::Multicore
69			will be enabled for all threads and all callers in the whole program:
70
71			use Coro::Multicore;
72
73			In a module where you don't control what else might be loaded and run, you
74			might want to be more conservative, and not import anything. This has the
75			effect of not enabling the functionality by default, so you have to enable
76			it per scope:
77
78			use Coro::Multicore ();
79
80			sub myfunc {
81			Coro::Multicore::scoped_enable;
82
83			# from here to the end of this function, and in any functions
84	root	1.6	# called from this function, tasks will be executed asynchronously.
85	root	1.5	}
86
87	root	1.4	=head1 API FUNCTIONS
88	root	1.3
89	root	1.4	=over 4
90
91			=item $previous = Coro::Multicore::enable [$enable]
92
93			This function enables (if C<$enable> is true) or disables (if C<$enable>
94			is false) the multicore functionality globally. By default, it is enabled.
95
96			This can be used to effectively disable this module's functionality by
97			default, and enable it only for selected threads or scopes, by calling
98			C<Coro::Multicore::scope_enable>.
99
100			The function returns the previous value of the enable flag.
101	root	1.2
102	root	1.4	=item Coro::Multicore::scoped_enable
103
104			This function instructs Coro::Multicore to handle all requests executed
105			in the current coro thread, from the call to the end of the current scope.
106
107			Calls to C<scoped_enable> and C<scoped_disable> don't nest very well at
108			the moment, so don't nest them.
109
110			=item Coro::Multicore::scoped_disable
111
112			The opposite of C<Coro::Multicore::scope_disable>: instructs Coro::Multicore to
113			I<not> handle the next multicore-enabled request.
114	root	1.1
115	root	1.3	=back
116
117	root	1.1	=cut
118
119			package Coro::Multicore;
120
121			use Coro ();
122			use AnyEvent ();
123
124			BEGIN {
125			our $VERSION = 0.02;
126
127			use XSLoader;
128			XSLoader::load __PACKAGE__, $VERSION;
129			}
130
131	root	1.5
132			sub import {
133			if (@_ > 1) {
134			require Carp;
135			Carp::croak ("Coro::Multicore does not export any symbols");
136			}
137
138			enable 1;
139			}
140
141	root	1.1	our $WATCHER = AE::io fd, 0, \&poll;
142
143	root	1.5	=head1 INTERACTION WITH OTHER SOFTWARE
144
145	root	1.7	This module is very similar to other environments where perl interpreters
146			are moved between threads, such as mod_perl2, and the same caveats apply.
147
148			I want to spell out the most important ones:
149
150			=over 4
151
152			=item pthreads usage
153
154			Any creation of pthreads make it impossible to fork portably from a
155			perl program, as forking from within a threaded program will leave the
156			program in a state similar to a signal handler. While it might work on
157			some platforms (as an extension), this might also result in silent data
158			corruption. It also seems to work most of the time, so it's hard to test
159			for this.
160
161			I recommend using something like L<AnyEvent::Fork>, which can create
162			subprocesses safely (via L<Proc::FastSpawn>).
163
164			Similar issues exist for signal handlers, although this module works hard
165			to keep safe perl signals safe.
166
167			=item module support
168
169			This module moves the same perl interpreter between different
170			threads. Some modules might get confused by that (although this can
171			usually be considered a bug). This is a rare case though.
172
173			=item event loop reliance
174
175			To be able to wake up programs waiting for results, this module relies on
176			an active event loop (via L<AnyEvent>). This is used to notify the perl
177			interpreter when the asynchronous task is done.
178
179			Since event loops typically fail to work properly after a fork, this means
180			that some operations that were formerly working will now hang after fork.
181
182			A workaround is to call C<Coro::Multicore::enable 0> after a fork to
183			disable the module.
184
185			Future versions of this module might do this automatically.
186
187			=back
188	root	1.5
189			=head1 BUGS
190
191	root	1.6	=over 4
192
193			=item (OS-) threads are never released
194
195	root	1.5	At the moment, threads that were created once will never be freed. They
196	root	1.8	will be reused for asynchronous requests, though, so as long as you limit
197	root	1.5	the maximum number of concurrent asynchronous tasks, this will also limit
198			the maximum number of threads created.
199
200	root	1.8	The idle threads are not necessarily using a lot of resources: on
201			GNU/Linux + glibc, each thread takes about 8KiB of userspace memory +
202			whatever the kernel needs (probably less than 8KiB).
203
204	root	1.5	Future versions will likely lift this limitation.
205
206	root	1.7	=item AnyEvent is initalised at module load time
207	root	1.6
208			AnyEvent is initialised on module load, as opposed to at a later time.
209
210			Future versions will likely change this.
211
212			=back
213
214	root	1.1	=head1 AUTHOR
215
216			Marc Lehmann <schmorp@schmorp.de>
217			http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html
218
219	root	1.6	Additional thanks to Zsbán Ambrus, who gave considerable desing input for
220			this module and the perl multicore specification.
221
222	root	1.1	=cut
223
224			1
225