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