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 |
|
|
use Coro::Multicore; |
8 |
|
|
|
9 |
|
|
=head1 DESCRIPTION |
10 |
|
|
|
11 |
root |
1.2 |
While L<Coro> threads (unlike ithreads) provide real threads similar to |
12 |
root |
1.3 |
pthreads, python threads and so on, they do not run in parallel to each |
13 |
root |
1.2 |
other even on machines with multiple CPUs or multiple CPU cores. |
14 |
|
|
|
15 |
|
|
This module lifts this restriction under two very specific but useful |
16 |
|
|
conditions: firstly, the coro thread executes in XS code and does not |
17 |
|
|
touch any perl data structures, and secondly, the XS code is specially |
18 |
|
|
prepared to allow this. |
19 |
|
|
|
20 |
|
|
This means that, when you call an XS function of a module prepared for it, |
21 |
|
|
this XS function can execute in parallel to any other Coro threads. |
22 |
|
|
|
23 |
root |
1.3 |
The mechanism to support this is easily added to existing modules |
24 |
|
|
and is independent of L<Coro> or L<Coro::Multicore>, and therefore |
25 |
|
|
could be used, without changes, with other, similar, modules, or even |
26 |
|
|
the perl core, should it gain real thread support anytime soon. See |
27 |
|
|
L<http://pod.tst.eu/http://cvs.schmorp.de/Coro-Multicore/perlmulticore.h> |
28 |
|
|
for more info on how to prepare a module to allow parallel execution. |
29 |
|
|
|
30 |
|
|
This module is an L<AnyEvent> user (and also, if not obvious, uses |
31 |
|
|
L<Coro>). |
32 |
|
|
|
33 |
|
|
=head1 HOW TO USE IT |
34 |
|
|
|
35 |
|
|
It could hardly be simpler - if you use coro threads, and before you call |
36 |
|
|
a supported lengthy operation implemented in XS, use this module and other |
37 |
|
|
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 I<load> it before you can take advantage of it. |
43 |
|
|
|
44 |
root |
1.4 |
=head1 API FUNCTIONS |
45 |
root |
1.3 |
|
46 |
root |
1.4 |
=over 4 |
47 |
|
|
|
48 |
|
|
=item $previous = Coro::Multicore::enable [$enable] |
49 |
|
|
|
50 |
|
|
This function enables (if C<$enable> is true) or disables (if C<$enable> |
51 |
|
|
is false) the multicore functionality globally. By default, it is enabled. |
52 |
|
|
|
53 |
|
|
This can be used to effectively disable this module's functionality by |
54 |
|
|
default, and enable it only for selected threads or scopes, by calling |
55 |
|
|
C<Coro::Multicore::scope_enable>. |
56 |
|
|
|
57 |
|
|
The function returns the previous value of the enable flag. |
58 |
root |
1.2 |
|
59 |
root |
1.4 |
=item Coro::Multicore::scoped_enable |
60 |
|
|
|
61 |
|
|
This function instructs Coro::Multicore to handle all requests executed |
62 |
|
|
in the current coro thread, from the call to the end of the current scope. |
63 |
|
|
|
64 |
|
|
Calls to C<scoped_enable> and C<scoped_disable> don't nest very well at |
65 |
|
|
the moment, so don't nest them. |
66 |
|
|
|
67 |
|
|
=item Coro::Multicore::scoped_disable |
68 |
|
|
|
69 |
|
|
The opposite of C<Coro::Multicore::scope_disable>: instructs Coro::Multicore to |
70 |
|
|
I<not> handle the next multicore-enabled request. |
71 |
root |
1.1 |
|
72 |
root |
1.3 |
=item $previous = Coro::Multicore::max_idle_threads [$count] |
73 |
|
|
|
74 |
|
|
To run on multiple cores, this module creates I<threads>. Since thread |
75 |
|
|
creation is costly, it will keep some of them around for future uses. This |
76 |
|
|
function returns the current maximum number of threads that are being kept |
77 |
|
|
around (default: C<8>), and can be used to set a new limit, in case you |
78 |
|
|
have bigger requirements. |
79 |
|
|
|
80 |
|
|
Future implementations will also provide a timeout mechanism, for even |
81 |
|
|
better behaviour. |
82 |
|
|
|
83 |
|
|
=back |
84 |
|
|
|
85 |
root |
1.1 |
=cut |
86 |
|
|
|
87 |
|
|
package Coro::Multicore; |
88 |
|
|
|
89 |
|
|
use Coro (); |
90 |
|
|
use AnyEvent (); |
91 |
|
|
|
92 |
|
|
BEGIN { |
93 |
|
|
our $VERSION = 0.02; |
94 |
|
|
|
95 |
|
|
use XSLoader; |
96 |
|
|
XSLoader::load __PACKAGE__, $VERSION; |
97 |
|
|
} |
98 |
|
|
|
99 |
|
|
our $WATCHER = AE::io fd, 0, \&poll; |
100 |
|
|
|
101 |
|
|
=head1 AUTHOR |
102 |
|
|
|
103 |
|
|
Marc Lehmann <schmorp@schmorp.de> |
104 |
|
|
http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html |
105 |
|
|
|
106 |
|
|
=cut |
107 |
|
|
|
108 |
|
|
1 |
109 |
|
|
|