1Multicore(3) User Contributed Perl Documentation Multicore(3)
2
6 Coro::Multicore - make coro threads on multiple cores with specially
7 supported modules
8
10 # when you DO control the main event loop, e.g. in the main program
11 use Coro::Multicore; # enable by default
13 Coro::Multicore::scoped_disable;
15 AE::cv->recv; # or EV::run, AnyEvent::Loop::run, Event::loop, ...
16 # when you DO NOT control the event loop, e.g. in a module on CPAN
18 # do nothing (see HOW TO USE IT) or something like this:
19 use Coro::Multicore (); # disable by default
21 async {
23 Coro::Multicore::scoped_enable;
24 # blocking is safe in your own threads
26 ...
27 };
28
30 While Coro threads (unlike ithreads) provide real threads similar to
31 pthreads, python threads and so on, they do not run in parallel to each
32 other even on machines with multiple CPUs or multiple CPU cores.
33 This module lifts this restriction under two very specific but useful
35 conditions: firstly, the coro thread executes in XS code and does not
36 touch any perl data structures, and secondly, the XS code is specially
37 prepared to allow this.
38 This means that, when you call an XS function of a module prepared for
40 it, this XS function can execute in parallel to any other Coro threads.
41 This is useful for both CPU bound tasks (such as cryptography) as well
42 as I/O bound tasks (such as loading an image from disk). It can also be
43 used to do stuff in parallel via APIs that were not meant for this,
44 such as database accesses via DBI.
45 The mechanism to support this is easily added to existing modules and
47 is independent of Coro or Coro::Multicore, and therefore could be used,
48 without changes, with other, similar, modules, or even the perl core,
49 should it gain real thread support anytime soon. See
50 <http://perlmulticore.schmorp.de/> for more info on how to prepare a
51 module to allow parallel execution. Preparing an existing module is
52 easy, doesn't add much overhead and no dependencies.
53 This module is an AnyEvent user (and also, if not obvious, uses Coro).
55
57 Quick explanation: decide whether you control the main program/the
58 event loop and choose one of the two styles from the SYNOPSIS.
59 Longer explanation: There are two major modes this module can used in -
61 supported operations run asynchronously either by default, or only when
62 requested. The reason you might not want to enable this module for all
63 operations by default is compatibility with existing code:
64 Since this module integrates into an event loop and you must not
66 normally block and wait for something in an event loop callbacks. Now
67 imagine somebody patches your favourite module (e.g. Digest::MD5) to
68 take advantage of of the Perl Multicore API.
69 Then code that runs in an event loop callback and executes
71 Digest::MD5::md5 would work fine without "Coro::Multicore" - it would
72 simply calculate the MD5 digest and block execution of anything else.
73 But with "Coro::Multicore" enabled, the same operation would try to run
74 other threads. And when those wait for events, there is no event loop
75 anymore, as the event loop thread is busy doing the MD5 calculation,
76 leading to a deadlock.
77 USE IT IN THE MAIN PROGRAM
79 One way to avoid this is to not run perlmulticore enabled functions in
80 any callbacks. A simpler way to ensure it works is to disable
81 "Coro::Multicore" thread switching in event loop callbacks, and enable
82 it everywhere else.
83 Therefore, if you control the event loop, as is usually the case when
85 you write program and not a module, then you can enable
86 "Coro::Multicore" by default, and disable it in your event loop thread:
87 # example 1, separate thread for event loop
89 use EV;
91 use Coro;
92 use Coro::Multicore;
93 async {
95 Coro::Multicore::scoped_disable;
96 EV::run;
97 };
98 # do something else
100 # example 2, run event loop as main program
102 use EV;
104 use Coro;
105 use Coro::Multicore;
106 Coro::Multicore::scoped_disable;
108 ... initialisation
110 EV::run;
112 The latter form is usually better and more idiomatic - the main thread
114 is the best place to run the event loop.
115 Often you want to do some initialisation before running the event loop.
117 The most efficient way to do that is to put your intialisation code
118 (and main program) into its own thread and run the event loop in your
119 main program:
120 use AnyEvent::Loop;
122 use Coro::Multicore; # enable by default
123 async {
125 load_data;
126 do_other_init;
127 bind_socket;
128 ...
129 };
130 Coro::Multicore::scoped_disable;
132 AnyEvent::Loop::run;
133 This has the effect of running the event loop first, so the
135 initialisation code can block if it wants to.
136 If this is too cumbersome but you still want to make sure you can call
138 blocking functions before entering the event loop, you can keep
139 "Coro::Multicore" disabled till you cna run the event loop:
140 use AnyEvent::Loop;
142 use Coro::Multicore (); # disable by default
143 load_data;
145 do_other_init;
146 bind_socket;
147 ...
148 Coro::Multicore::scoped_disable; # disable for event loop
150 Coro::Multicore::enable 1; # enable for the rest of the program
151 AnyEvent::Loop::run;
152 USE IT IN A MODULE
154 When you do not control the event loop, for example, because you want
155 to use this from a module you published on CPAN, then the previous
156 method doesn't work.
157 However, this is not normally a problem in practise - most modules only
159 do work at request of the caller. In that case, you might not care
160 whether it does block other threads or not, as this would be the
161 callers responsibility (or decision), and by extension, a decision for
162 the main program.
163 So unless you use XS and want your XS functions to run asynchronously,
165 you don't have to worry about "Coro::Multicore" at all - if you happen
166 to call XS functions that are multicore-enabled and your caller has
167 configured things correctly, they will automatically run
168 asynchronously. Or in other words: nothing needs to be done at all,
169 which also means that this method works fine for existing pure-perl
170 modules, without having to change them at all.
171 Only if your module runs it's own Coro threads could it be an issue -
173 maybe your module implements some kind of job pool and relies on
174 certain operations to run asynchronously. Then you can still use
175 "Coro::Multicore" by not enabling it be default and only enabling it in
176 your own threads:
177 use Coro;
179 use Coro::Multicore (); # note the () to disable by default
180 async {
182 Coro::Multicore::scoped_enable;
183 # do things asynchronously by calling perlmulticore-enabled functions
185 };
186 EXPORTS
188 This module does not (at the moment) export any symbols. It does,
189 however, export "behaviour" - if you use the default import, then
190 Coro::Multicore will be enabled for all threads and all callers in the
191 whole program:
192 use Coro::Multicore;
194 In a module where you don't control what else might be loaded and run,
196 you might want to be more conservative, and not import anything. This
197 has the effect of not enabling the functionality by default, so you
198 have to enable it per scope:
199 use Coro::Multicore ();
201 sub myfunc {
203 Coro::Multicore::scoped_enable;
204 # from here to the end of this function, and in any functions
206 # called from this function, tasks will be executed asynchronously.
207 }
208
210 $previous = Coro::Multicore::enable [$enable]
211 This function enables (if $enable is true) or disables (if $enable
212 is false) the multicore functionality globally. By default, it is
213 enabled.
214 This can be used to effectively disable this module's functionality
216 by default, and enable it only for selected threads or scopes, by
217 calling "Coro::Multicore::scoped_enable".
218 The function returns the previous value of the enable flag.
220 Coro::Multicore::scoped_enable
222 This function instructs Coro::Multicore to handle all requests
223 executed in the current coro thread, from the call to the end of
224 the current scope.
225 Calls to "scoped_enable" and "scoped_disable" don't nest very well
227 at the moment, so don't nest them.
228 Coro::Multicore::scoped_disable
230 The opposite of "Coro::Multicore::scope_disable": instructs
231 Coro::Multicore to not handle the next multicore-enabled request.
232
234 Just because an XS module supports perlmulticore might not immediately
235 make it reentrant. For example, while you can (try to) call "execute"
236 on the same database handle for the patched "DBD::mysql" (see the
237 registry <http://perlmulticore.schmorp.de/registry>), this will almost
238 certainly not work, despite "DBD::mysql" and "libmysqlclient" being
239 thread safe and reentrant - just not on the same database handle.
240 Many modules have limitations such as these - some can only be called
242 concurrently from a single thread as they use global variables, some
243 can only be called concurrently on different handles (e.g. database
244 connections for DBD modules, or digest objects for Digest modules), and
245 some can be called at any time (such as the "md5" function in
246 "Digest::MD5").
247 Generally, you only have to be careful with the very few modules that
249 use global variables or rely on C libraries that aren't thread-safe,
250 which should be documented clearly in the module documentation.
251 Most modules are either perfectly reentrant, or at least reentrant as
253 long as you give every thread it's own handle object.
254
256 Coro allows you to cancel threads even when they execute within an XS
257 function ("cancel" vs. "cancel" methods). Similarly, Coro allows you to
258 send exceptions (e.g. via the "throw" method) to threads executing
259 inside an XS function.
260 While doing this is questionable and dangerous with normal Coro threads
262 already, they are both supported in this module, although with
263 potentially unwanted effects. The following describes the current
264 implementation and is subject to change. It is described primarily so
265 you can understand what went wrong, if things go wrong.
266 EXCEPTIONS
268 When a thread that has currently released the perl interpreter
269 (e.g. because it is executing a perlmulticore enabled XS function)
270 receives an exception, it will at first continue normally.
271 After acquiring the perl interpreter again, it will throw the
273 exception it previously received. More specifically, when a thread
274 calls "perlinterp_acquire ()" and has received an exception, then
275 "perlinterp_acquire ()" will not return but instead "die".
276 Most code that has been updated for perlmulticore support will not
278 expect this, and might leave internal state corrupted to some
279 extent.
280 CANCELLATION
282 Unsafe cancellation on a thread that has released the perl
283 interpreter frees its resources, but let's the XS code continue at
284 first. This should not lead to corruption on the perl level, as the
285 code isn't allowed to touch perl data structures until it
286 reacquires the interpreter.
287 The call to "perlinterp_acquire ()" will then block indefinitely,
289 leaking the (OS level) thread.
290 Safe cancellation will simply fail in this case, so is still "safe"
292 to call.
293
295 This module is very similar to other environments where perl
296 interpreters are moved between threads, such as mod_perl2, and the same
297 caveats apply.
298 I want to spell out the most important ones:
300 pthreads usage
302 Any creation of pthreads make it impossible to fork portably from a
303 perl program, as forking from within a threaded program will leave
304 the program in a state similar to a signal handler. While it might
305 work on some platforms (as an extension), this might also result in
306 silent data corruption. It also seems to work most of the time, so
307 it's hard to test for this.
308 I recommend using something like AnyEvent::Fork, which can create
310 subprocesses safely (via Proc::FastSpawn).
311 Similar issues exist for signal handlers, although this module
313 works hard to keep safe perl signals safe.
314 module support
316 This module moves the same perl interpreter between different
317 threads. Some modules might get confused by that (although this can
318 usually be considered a bug). This is a rare case though.
319 event loop reliance
321 To be able to wake up programs waiting for results, this module
322 relies on an active event loop (via AnyEvent). This is used to
323 notify the perl interpreter when the asynchronous task is done.
324 Since event loops typically fail to work properly after a fork,
326 this means that some operations that were formerly working will now
327 hang after fork.
328 A workaround is to call "Coro::Multicore::enable 0" after a fork to
330 disable the module.
331 Future versions of this module might do this automatically.
333
335 (OS-) threads are never released
336 At the moment, threads that were created once will never be freed.
337 They will be reused for asynchronous requests, though, so as long
338 as you limit the maximum number of concurrent asynchronous tasks,
339 this will also limit the maximum number of threads created.
340 The idle threads are not necessarily using a lot of resources: on
342 GNU/Linux + glibc, each thread takes about 8KiB of userspace memory
343 + whatever the kernel needs (probably less than 8KiB).
344 Future versions will likely lift this limitation.
346 AnyEvent is initalised at module load time
348 AnyEvent is initialised on module load, as opposed to at a later
349 time.
350 Future versions will likely change this.
352
354 Marc Lehmann <schmorp@schmorp.de>
355 http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html
356 Additional thanks to Zsbán Ambrus, who gave considerable desing input
358 for this module and the perl multicore specification.
359perl v5.28.0 2018-08-15 Multicore(3)