[ViewVC] Annotation of: cvs/Coro-Multicore/README

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

SYNOPSIS
     use Coro::Multicore;

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

DESCRIPTION
    While 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 Coro or 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
    <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 AnyEvent user (and also, if not obvious, uses Coro).

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 *load* it before you can take advantage of it.

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

API FUNCTIONS
    $previous = Coro::Multicore::enable [$enable]
        This function enables (if $enable is true) or disables (if $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 "Coro::Multicore::scope_enable".

        The function returns the previous value of the enable flag.

    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 "scoped_enable" and "scoped_disable" don't nest very well
        at the moment, so don't nest them.

    Coro::Multicore::scoped_disable
        The opposite of "Coro::Multicore::scope_disable": instructs
        Coro::Multicore to *not* handle the next multicore-enabled request.

INTERACTION WITH OTHER SOFTWARE
    TODO

BUGS
    (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.

    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.

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.

Revision:	1.2
Committed:	Tue Jun 30 01:01:34 2015 UTC (8 years, 10 months ago) by root
Branch:	MAIN
Changes since 1.1:	+114 -0 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.2	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