Coro-Multicore/Multicore.pm

=head1 NAME

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

=head1 SYNOPSIS

 use Coro::Multicore;

 # or, if you want it disabled by default (e.g. to use it from a module)
 use Coro::Multicore ();

=head1 DESCRIPTION

While L<Coro> threads (unlike ithreads) provide real threads similar to
pthreads, python threads and so on, they do not run in parallel to each
other even on machines with multiple CPUs or multiple CPU cores.

This module lifts this restriction under two very specific but useful
conditions: firstly, the coro thread executes in XS code and does not
touch any perl data structures, and secondly, the XS code is specially
prepared to allow this.

This means that, when you call an XS function of a module prepared for it,
this XS function can execute in parallel to any other Coro threads.

The mechanism to support this is easily added to existing modules
and is independent of L<Coro> or L<Coro::Multicore>, and therefore
could be used, without changes, with other, similar, modules, or even
the perl core, should it gain real thread support anytime soon. See
L<http://perlmulticore.schmorp.de/> for more info on how to prepare a
module to allow parallel execution. Preparing an existing module is easy,
doesn't add much overhead and no dependencies.

This module is an L<AnyEvent> user (and also, if not obvious, uses
L<Coro>).

=head1 HOW TO USE IT

It could hardly be simpler - if you use coro threads, and before you call
a supported lengthy operation implemented in XS, use this module and other
coro threads can run in parallel:

   use Coro::Multicore;

This module has no important API functions to learn or remember. All you
need to do is I<load> it before you can take advantage of it.

=head2 EXPORTS

This module does not (at the moment) export any symbols. It does, however,
export "behaviour" - if you use the default import, then Coro::Multicore
will be enabled for all threads and all callers in the whole program:

   use Coro::Multicore;

In a module where you don't control what else might be loaded and run, you
might want to be more conservative, and not import anything. This has the
effect of not enabling the functionality by default, so you have to enable
it per scope:

   use Coro::Multicore ();

   sub myfunc {
      Coro::Multicore::scoped_enable;

      # from here to the end of this function, and in any functions
      # called from this function, tasks will be executed asynchronously.
   }

=head1 API FUNCTIONS

=over 4

=item $previous = Coro::Multicore::enable [$enable]

This function enables (if C<$enable> is true) or disables (if C<$enable>
is false) the multicore functionality globally. By default, it is enabled.

This can be used to effectively disable this module's functionality by
default, and enable it only for selected threads or scopes, by calling
C<Coro::Multicore::scope_enable>.

The function returns the previous value of the enable flag.

=item Coro::Multicore::scoped_enable

This function instructs Coro::Multicore to handle all requests executed
in the current coro thread, from the call to the end of the current scope.

Calls to C<scoped_enable> and C<scoped_disable> don't nest very well at
the moment, so don't nest them.

=item Coro::Multicore::scoped_disable

The opposite of C<Coro::Multicore::scope_disable>: instructs Coro::Multicore to
I<not> handle the next multicore-enabled request.

=back

=cut

package Coro::Multicore;

use Coro ();
use AnyEvent ();

BEGIN {
   our $VERSION = 0.02;

   use XSLoader;
   XSLoader::load __PACKAGE__, $VERSION;
}


sub import {
   if (@_ > 1) {
      require Carp;
      Carp::croak ("Coro::Multicore does not export any symbols");
   }

   enable 1;
}

our $WATCHER = AE::io fd, 0, \&poll;

=head1 INTERACTION WITH OTHER SOFTWARE

TODO

=head1 BUGS

=over 4

=item (OS-) threads are never released

At the moment, threads that were created once will never be freed. They
will be reused for asynchronous requests, though, so a slong as you limit
the maximum number of concurrent asynchronous tasks, this will also limit
the maximum number of threads created.

Future versions will likely lift this limitation.

=item AnyEvent is initalised on module load

AnyEvent is initialised on module load, as opposed to at a later time.

Future versions will likely change this.

=back

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html

Additional thanks to Zsbán Ambrus, who gave considerable desing input for
this module and the perl multicore specification.

=cut

1

Revision:	1.6
Committed:	Mon Jun 29 13:33:48 2015 UTC (8 years, 11 months ago) by root
Branch:	MAIN
Changes since 1.5:	+16 -2 lines
Log Message:	* empty log message *
#	User	Rev	Content
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	root	1.5	# or, if you want it disabled by default (e.g. to use it from a module)
10			use Coro::Multicore ();
11
12	root	1.1	=head1 DESCRIPTION
13
14	root	1.2	While L<Coro> threads (unlike ithreads) provide real threads similar to
15	root	1.3	pthreads, python threads and so on, they do not run in parallel to each
16	root	1.2	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	root	1.3	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	root	1.5	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	root	1.3
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	root	1.5	=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	root	1.6	# called from this function, tasks will be executed asynchronously.
68	root	1.5	}
69
70	root	1.4	=head1 API FUNCTIONS
71	root	1.3
72	root	1.4	=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	root	1.2
85	root	1.4	=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	root	1.1
98	root	1.3	=back
99
100	root	1.1	=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	root	1.5
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	root	1.1	our $WATCHER = AE::io fd, 0, \&poll;
125
126	root	1.5	=head1 INTERACTION WITH OTHER SOFTWARE
127
128			TODO
129
130			=head1 BUGS
131
132	root	1.6	=over 4
133
134			=item (OS-) threads are never released
135
136	root	1.5	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	root	1.6	=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	root	1.1	=head1 AUTHOR
152
153			Marc Lehmann <schmorp@schmorp.de>
154			http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html
155
156	root	1.6	Additional thanks to Zsbán Ambrus, who gave considerable desing input for
157			this module and the perl multicore specification.
158
159	root	1.1	=cut
160
161			1
162