1Multicore(3)          User Contributed Perl Documentation         Multicore(3)
2
3
4

NAME

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

SYNOPSIS

10        # when you DO control the main event loop, e.g. in the main program
11
12        use Coro::Multicore; # enable by default
13
14        Coro::Multicore::scoped_disable;
15        AE::cv->recv; # or EV::run, AnyEvent::Loop::run, Event::loop, ...
16
17        # 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
20        use Coro::Multicore (); # disable by default
21
22        async {
23           Coro::Multicore::scoped_enable;
24
25           # blocking is safe in your own threads
26           ...
27        };
28

DESCRIPTION

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
34       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
39       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
46       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
54       This module is an AnyEvent user (and also, if not obvious, uses Coro).
55

HOW TO USE IT

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
60       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
65       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
70       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
78   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
84       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
88          # example 1, separate thread for event loop
89
90          use EV;
91          use Coro;
92          use Coro::Multicore;
93
94          async {
95             Coro::Multicore::scoped_disable;
96             EV::run;
97          };
98
99          # do something else
100
101          # example 2, run event loop as main program
102
103          use EV;
104          use Coro;
105          use Coro::Multicore;
106
107          Coro::Multicore::scoped_disable;
108
109          ... initialisation
110
111          EV::run;
112
113       The latter form is usually better and more idiomatic - the main thread
114       is the best place to run the event loop.
115
116       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
121          use AnyEvent::Loop;
122          use Coro::Multicore; # enable by default
123
124          async {
125             load_data;
126             do_other_init;
127             bind_socket;
128             ...
129          };
130
131          Coro::Multicore::scoped_disable;
132          AnyEvent::Loop::run;
133
134       This has the effect of running the event loop first, so the
135       initialisation code can block if it wants to.
136
137       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
141          use AnyEvent::Loop;
142          use Coro::Multicore (); # disable by default
143
144          load_data;
145          do_other_init;
146          bind_socket;
147          ...
148
149          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
153   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
158       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
164       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
172       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
178          use Coro;
179          use Coro::Multicore (); # note the () to disable by default
180
181          async {
182             Coro::Multicore::scoped_enable;
183
184             # do things asynchronously by calling perlmulticore-enabled functions
185          };
186
187   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
193          use Coro::Multicore;
194
195       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
200          use Coro::Multicore ();
201
202          sub myfunc {
203             Coro::Multicore::scoped_enable;
204
205             # from here to the end of this function, and in any functions
206             # called from this function, tasks will be executed asynchronously.
207          }
208

API FUNCTIONS

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
215           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
219           Note that this setting nonly affects the global default - it will
220           not reflect whether multicore functionality is enabled for the
221           current thread.
222
223           The function returns the previous value of the enable flag.
224
225       Coro::Multicore::scoped_enable
226           This function instructs Coro::Multicore to handle all requests
227           executed in the current coro thread, from the call to the end of
228           the current scope.
229
230           Calls to "scoped_enable" and "scoped_disable" don't nest very well
231           at the moment, so don't nest them.
232
233       Coro::Multicore::scoped_disable
234           The opposite of "Coro::Multicore::scope_disable": instructs
235           Coro::Multicore to not handle the next multicore-enabled request.
236

THREAD SAFETY OF SUPPORTING XS MODULES

238       Just because an XS module supports perlmulticore might not immediately
239       make it reentrant. For example, while you can (try to) call "execute"
240       on the same database handle for the patched "DBD::mysql" (see the
241       registry <http://perlmulticore.schmorp.de/registry>), this will almost
242       certainly not work, despite "DBD::mysql" and "libmysqlclient" being
243       thread safe and reentrant - just not on the same database handle.
244
245       Many modules have limitations such as these - some can only be called
246       concurrently from a single thread as they use global variables, some
247       can only be called concurrently on different handles (e.g. database
248       connections for DBD modules, or digest objects for Digest modules), and
249       some can be called at any time (such as the "md5" function in
250       "Digest::MD5").
251
252       Generally, you only have to be careful with the very few modules that
253       use global variables or rely on C libraries that aren't thread-safe,
254       which should be documented clearly in the module documentation.
255
256       Most modules are either perfectly reentrant, or at least reentrant as
257       long as you give every thread it's own handle object.
258

EXCEPTIONS AND THREAD CANCELLATION

260       Coro allows you to cancel threads even when they execute within an XS
261       function ("cancel" vs. "cancel" methods). Similarly, Coro allows you to
262       send exceptions (e.g. via the "throw" method) to threads executing
263       inside an XS function.
264
265       While doing this is questionable and dangerous with normal Coro threads
266       already, they are both supported in this module, although with
267       potentially unwanted effects. The following describes the current
268       implementation and is subject to change. It is described primarily so
269       you can understand what went wrong, if things go wrong.
270
271       EXCEPTIONS
272           When a thread that has currently released the perl interpreter
273           (e.g.  because it is executing a perlmulticore enabled XS function)
274           receives an exception, it will at first continue normally.
275
276           After acquiring the perl interpreter again, it will throw the
277           exception it previously received. More specifically, when a thread
278           calls "perlinterp_acquire ()" and has received an exception, then
279           "perlinterp_acquire ()" will not return but instead "die".
280
281           Most code that has been updated for perlmulticore support will not
282           expect this, and might leave internal state corrupted to some
283           extent.
284
285       CANCELLATION
286           Unsafe cancellation on a thread that has released the perl
287           interpreter frees its resources, but let's the XS code continue at
288           first. This should not lead to corruption on the perl level, as the
289           code isn't allowed to touch perl data structures until it
290           reacquires the interpreter.
291
292           The call to "perlinterp_acquire ()" will then block indefinitely,
293           leaking the (OS level) thread.
294
295           Safe cancellation will simply fail in this case, so is still "safe"
296           to call.
297

INTERACTION WITH OTHER SOFTWARE

299       This module is very similar to other environments where perl
300       interpreters are moved between threads, such as mod_perl2, and the same
301       caveats apply.
302
303       I want to spell out the most important ones:
304
305       pthreads usage
306           Any creation of pthreads make it impossible to fork portably from a
307           perl program, as forking from within a threaded program will leave
308           the program in a state similar to a signal handler. While it might
309           work on some platforms (as an extension), this might also result in
310           silent data corruption. It also seems to work most of the time, so
311           it's hard to test for this.
312
313           I recommend using something like AnyEvent::Fork, which can create
314           subprocesses safely (via Proc::FastSpawn).
315
316           Similar issues exist for signal handlers, although this module
317           works hard to keep safe perl signals safe.
318
319       module support
320           This module moves the same perl interpreter between different
321           threads. Some modules might get confused by that (although this can
322           usually be considered a bug). This is a rare case though.
323
324       event loop reliance
325           To be able to wake up programs waiting for results, this module
326           relies on an active event loop (via AnyEvent). This is used to
327           notify the perl interpreter when the asynchronous task is done.
328
329           Since event loops typically fail to work properly after a fork,
330           this means that some operations that were formerly working will now
331           hang after fork.
332
333           A workaround is to call "Coro::Multicore::enable 0" after a fork to
334           disable the module.
335
336           Future versions of this module might do this automatically.
337

BUGS & LIMITATIONS

339       (OS-) threads are never released
340           At the moment, threads that were created once will never be freed.
341           They will be reused for asynchronous requests, though, so as long
342           as you limit the maximum number of concurrent asynchronous tasks,
343           this will also limit the maximum number of threads created.
344
345           The idle threads are not necessarily using a lot of resources: on
346           GNU/Linux + glibc, each thread takes about 8KiB of userspace memory
347           + whatever the kernel needs (probably less than 8KiB).
348
349           Future versions will likely lift this limitation.
350
351       The enable_times feature of Coro is messed up
352           The enable_times feature uses the per-thread timer to measure per-
353           thread execution time, but since Coro::Multicore runs threads on
354           different pthreads it will get the wrong times. Real times are not
355           affected.
356
357       Fork support
358           Due to the nature of threads, you are not allowed to use this
359           module in a forked child normally, with one exception: If you don't
360           create any threads in the parent, then it is safe to start using it
361           in a forked child.
362

AUTHOR

364        Marc Lehmann <schmorp@schmorp.de>
365        http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html
366
367       Additional thanks to Zsbán Ambrus, who gave considerable desing input
368       for this module and the perl multicore specification.
369
370
371
372perl v5.36.0                      2022-07-22                      Multicore(3)
Impressum