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