|
|
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 | |
