1 |
NAME |
2 |
Coro::Multicore - make coro threads on multiple cores with specially |
3 |
supported modules |
4 |
|
5 |
SYNOPSIS |
6 |
use Coro::Multicore; |
7 |
|
8 |
# or, if you want it disabled by default (e.g. to use it from a module) |
9 |
use Coro::Multicore (); |
10 |
|
11 |
DESCRIPTION |
12 |
While Coro threads (unlike ithreads) provide real threads similar to |
13 |
pthreads, python threads and so on, they do not run in parallel to each |
14 |
other even on machines with multiple CPUs or multiple CPU cores. |
15 |
|
16 |
This module lifts this restriction under two very specific but useful |
17 |
conditions: firstly, the coro thread executes in XS code and does not |
18 |
touch any perl data structures, and secondly, the XS code is specially |
19 |
prepared to allow this. |
20 |
|
21 |
This means that, when you call an XS function of a module prepared for |
22 |
it, this XS function can execute in parallel to any other Coro threads. |
23 |
|
24 |
The mechanism to support this is easily added to existing modules and is |
25 |
independent of Coro or Coro::Multicore, and therefore could be used, |
26 |
without changes, with other, similar, modules, or even the perl core, |
27 |
should it gain real thread support anytime soon. See |
28 |
<http://perlmulticore.schmorp.de/> for more info on how to prepare a |
29 |
module to allow parallel execution. Preparing an existing module is |
30 |
easy, doesn't add much overhead and no dependencies. |
31 |
|
32 |
This module is an AnyEvent user (and also, if not obvious, uses Coro). |
33 |
|
34 |
HOW TO USE IT |
35 |
It could hardly be simpler - if you use coro threads, and before you |
36 |
call a supported lengthy operation implemented in XS, use this module |
37 |
and other 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 *load* it before you can take advantage of it. |
43 |
|
44 |
EXPORTS |
45 |
This module does not (at the moment) export any symbols. It does, |
46 |
however, export "behaviour" - if you use the default import, then |
47 |
Coro::Multicore will be enabled for all threads and all callers in the |
48 |
whole program: |
49 |
|
50 |
use Coro::Multicore; |
51 |
|
52 |
In a module where you don't control what else might be loaded and run, |
53 |
you might want to be more conservative, and not import anything. This |
54 |
has the effect of not enabling the functionality by default, so you have |
55 |
to enable it per scope: |
56 |
|
57 |
use Coro::Multicore (); |
58 |
|
59 |
sub myfunc { |
60 |
Coro::Multicore::scoped_enable; |
61 |
|
62 |
# from here to the end of this function, and in any functions |
63 |
# called from this function, tasks will be executed asynchronously. |
64 |
} |
65 |
|
66 |
API FUNCTIONS |
67 |
$previous = Coro::Multicore::enable [$enable] |
68 |
This function enables (if $enable is true) or disables (if $enable |
69 |
is false) the multicore functionality globally. By default, it is |
70 |
enabled. |
71 |
|
72 |
This can be used to effectively disable this module's functionality |
73 |
by default, and enable it only for selected threads or scopes, by |
74 |
calling "Coro::Multicore::scope_enable". |
75 |
|
76 |
The function returns the previous value of the enable flag. |
77 |
|
78 |
Coro::Multicore::scoped_enable |
79 |
This function instructs Coro::Multicore to handle all requests |
80 |
executed in the current coro thread, from the call to the end of the |
81 |
current scope. |
82 |
|
83 |
Calls to "scoped_enable" and "scoped_disable" don't nest very well |
84 |
at the moment, so don't nest them. |
85 |
|
86 |
Coro::Multicore::scoped_disable |
87 |
The opposite of "Coro::Multicore::scope_disable": instructs |
88 |
Coro::Multicore to *not* handle the next multicore-enabled request. |
89 |
|
90 |
INTERACTION WITH OTHER SOFTWARE |
91 |
TODO |
92 |
|
93 |
BUGS |
94 |
(OS-) threads are never released |
95 |
At the moment, threads that were created once will never be freed. |
96 |
They will be reused for asynchronous requests, though, so a slong as |
97 |
you limit the maximum number of concurrent asynchronous tasks, this |
98 |
will also limit the maximum number of threads created. |
99 |
|
100 |
Future versions will likely lift this limitation. |
101 |
|
102 |
AnyEvent is initalised on module load |
103 |
AnyEvent is initialised on module load, as opposed to at a later |
104 |
time. |
105 |
|
106 |
Future versions will likely change this. |
107 |
|
108 |
AUTHOR |
109 |
Marc Lehmann <schmorp@schmorp.de> |
110 |
http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html |
111 |
|
112 |
Additional thanks to Zsbán Ambrus, who gave considerable desing input |
113 |
for this module and the perl multicore specification. |
114 |
|