[ViewVC] Annotation of: cvs/Coro/README

NAME
    Coro - coroutine process abstraction

SYNOPSIS
     use Coro;

     async {
        # some asynchronous thread of execution
     };

     # alternatively create an async coroutine like this:

     sub some_func : Coro {
        # some more async code
     }

     cede;

DESCRIPTION
    This module collection manages coroutines. Coroutines are similar to
    threads but don't run in parallel.

    In this module, coroutines are defined as "callchain + lexical variables
    + @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own
    callchain, it's own set of lexicals and it's own set of perl's most
    important global variables.

    $main
        This coroutine represents the main program.

    $current (or as function: current)
        The current coroutine (the last coroutine switched to). The initial
        value is $main (of course).

        This variable is strictly *read-only*. It is provided for
        performance reasons. If performance is not essentiel you are
        encouraged to use the "Coro::current" function instead.

    $idle
        A callback that is called whenever the scheduler finds no ready
        coroutines to run. The default implementation prints "FATAL:
        deadlock detected" and exits, because the program has no other way
        to continue.

        This hook is overwritten by modules such as "Coro::Timer" and
        "Coro::Event" to wait on an external event that hopefully wake up a
        coroutine so the scheduler can run it.

        Please note that if your callback recursively invokes perl (e.g. for
        event handlers), then it must be prepared to be called recursively.

  STATIC METHODS
    Static methods are actually functions that operate on the current
    coroutine only.

    async { ... } [@args...]
        Create a new asynchronous coroutine and return it's coroutine object
        (usually unused). When the sub returns the new coroutine is
        automatically terminated.

        Calling "exit" in a coroutine will not work correctly, so do not do
        that.

        When the coroutine dies, the program will exit, just as in the main
        program.

           # create a new coroutine that just prints its arguments
           async {
              print "@_\n";
           } 1,2,3,4;

    schedule
        Calls the scheduler. Please note that the current coroutine will not
        be put into the ready queue, so calling this function usually means
        you will never be called again unless something else (e.g. an event
        handler) calls ready.

        The canonical way to wait on external events is this:

           {
              # remember current coroutine
              my $current = $Coro::current;

              # register a hypothetical event handler
              on_event_invoke sub {
                 # wake up sleeping coroutine
                 $current->ready;
                 undef $current;
              };

              # call schedule until event occured.
              # in case we are woken up for other reasons
              # (current still defined), loop.
              Coro::schedule while $current;
           }

    cede
        "Cede" to other coroutines. This function puts the current coroutine
        into the ready queue and calls "schedule", which has the effect of
        giving up the current "timeslice" to other coroutines of the same or
        higher priority.

    terminate [arg...]
        Terminates the current coroutine with the given status values (see
        cancel).

    # dynamic methods

  COROUTINE METHODS
    These are the methods you can call on coroutine objects.

    new Coro \&sub [, @args...]
        Create a new coroutine and return it. When the sub returns the
        coroutine automatically terminates as if "terminate" with the
        returned values were called. To make the coroutine run you must
        first put it into the ready queue by calling the ready method.

        Calling "exit" in a coroutine will not work correctly, so do not do
        that.

    $success = $coroutine->ready
        Put the given coroutine into the ready queue (according to it's
        priority) and return true. If the coroutine is already in the ready
        queue, do nothing and return false.

    $is_ready = $coroutine->is_ready
        Return wether the coroutine is currently the ready queue or not,

    $coroutine->cancel (arg...)
        Terminates the given coroutine and makes it return the given
        arguments as status (default: the empty list).

    $coroutine->join
        Wait until the coroutine terminates and return any values given to
        the "terminate" or "cancel" functions. "join" can be called multiple
        times from multiple coroutine.

    $oldprio = $coroutine->prio ($newprio)
        Sets (or gets, if the argument is missing) the priority of the
        coroutine. Higher priority coroutines get run before lower priority
        coroutines. Priorities are small signed integers (currently -4 ..
        +3), that you can refer to using PRIO_xxx constants (use the import
        tag :prio to get then):

           PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
               3    >     1     >      0      >    -1    >    -3     >    -4

           # set priority to HIGH
           current->prio(PRIO_HIGH);

        The idle coroutine ($Coro::idle) always has a lower priority than
        any existing coroutine.

        Changing the priority of the current coroutine will take effect
        immediately, but changing the priority of coroutines in the ready
        queue (but not running) will only take effect after the next
        schedule (of that coroutine). This is a bug that will be fixed in
        some future version.

    $newprio = $coroutine->nice ($change)
        Similar to "prio", but subtract the given value from the priority
        (i.e. higher values mean lower priority, just as in unix).

    $olddesc = $coroutine->desc ($newdesc)
        Sets (or gets in case the argument is missing) the description for
        this coroutine. This is just a free-form string you can associate
        with a coroutine.

  UTILITY FUNCTIONS
    unblock_sub { ... }
        This utility function takes a BLOCK or code reference and "unblocks"
        it, returning the new coderef. This means that the new coderef will
        return immediately without blocking, returning nothing, while the
        original code ref will be called (with parameters) from within its
        own coroutine.

        The reason this fucntion exists is that many event libraries (such
        as the venerable Event module) are not coroutine-safe (a weaker form
        of thread-safety). This means you must not block within event
        callbacks, otherwise you might suffer from crashes or worse.

        This function allows your callbacks to block by executing them in
        another coroutine where it is safe to block. One example where
        blocking is handy is when you use the Coro::AIO functions to save
        results to disk.

        In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
        when creating event callbacks that want to block.

BUGS/LIMITATIONS
     - you must make very sure that no coro is still active on global
       destruction. very bad things might happen otherwise (usually segfaults).

     - this module is not thread-safe. You should only ever use this module
       from the same thread (this requirement might be losened in the future
       to allow per-thread schedulers, but Coro::State does not yet allow
       this).

SEE ALSO
    Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.

    Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
    Coro::SemaphoreSet, Coro::RWLock.

    Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket,
    Coro::Select.

    Embedding: <Coro:MakeMaker>

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.4
Committed:	Sun Dec 3 21:59:53 2006 UTC (17 years, 5 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_0, rel-3_01
Changes since 1.3:	+101 -36 lines
Log Message:	3.0
#	User	Rev	Content
1	root	1.1	NAME
2			Coro - coroutine process abstraction
3
4			SYNOPSIS
5			use Coro;
6
7			async {
8			# some asynchronous thread of execution
9			};
10
11	root	1.4	# alternatively create an async coroutine like this:
12	root	1.1
13			sub some_func : Coro {
14			# some more async code
15			}
16
17			cede;
18
19			DESCRIPTION
20			This module collection manages coroutines. Coroutines are similar to
21			threads but don't run in parallel.
22
23			In this module, coroutines are defined as "callchain + lexical variables
24			+ @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own
25			callchain, it's own set of lexicals and it's own set of perl's most
26			important global variables.
27
28			$main
29			This coroutine represents the main program.
30
31			$current (or as function: current)
32			The current coroutine (the last coroutine switched to). The initial
33			value is $main (of course).
34
35	root	1.4	This variable is strictly read-only. It is provided for
36			performance reasons. If performance is not essentiel you are
37			encouraged to use the "Coro::current" function instead.
38
39	root	1.1	$idle
40	root	1.4	A callback that is called whenever the scheduler finds no ready
41			coroutines to run. The default implementation prints "FATAL:
42			deadlock detected" and exits, because the program has no other way
43			to continue.
44
45			This hook is overwritten by modules such as "Coro::Timer" and
46			"Coro::Event" to wait on an external event that hopefully wake up a
47			coroutine so the scheduler can run it.
48
49			Please note that if your callback recursively invokes perl (e.g. for
50			event handlers), then it must be prepared to be called recursively.
51	root	1.1
52			STATIC METHODS
53			Static methods are actually functions that operate on the current
54	root	1.4	coroutine only.
55	root	1.1
56			async { ... } [@args...]
57	root	1.4	Create a new asynchronous coroutine and return it's coroutine object
58			(usually unused). When the sub returns the new coroutine is
59	root	1.1	automatically terminated.
60
61	root	1.4	Calling "exit" in a coroutine will not work correctly, so do not do
62			that.
63
64	root	1.3	When the coroutine dies, the program will exit, just as in the main
65			program.
66
67	root	1.1	# create a new coroutine that just prints its arguments
68			async {
69			print "@_\n";
70			} 1,2,3,4;
71
72			schedule
73	root	1.4	Calls the scheduler. Please note that the current coroutine will not
74	root	1.1	be put into the ready queue, so calling this function usually means
75	root	1.4	you will never be called again unless something else (e.g. an event
76			handler) calls ready.
77
78			The canonical way to wait on external events is this:
79
80			{
81			# remember current coroutine
82			my $current = $Coro::current;
83
84			# register a hypothetical event handler
85			on_event_invoke sub {
86			# wake up sleeping coroutine
87			$current->ready;
88			undef $current;
89			};
90
91			# call schedule until event occured.
92			# in case we are woken up for other reasons
93			# (current still defined), loop.
94			Coro::schedule while $current;
95			}
96	root	1.1
97			cede
98	root	1.4	"Cede" to other coroutines. This function puts the current coroutine
99	root	1.1	into the ready queue and calls "schedule", which has the effect of
100			giving up the current "timeslice" to other coroutines of the same or
101			higher priority.
102
103			terminate [arg...]
104	root	1.4	Terminates the current coroutine with the given status values (see
105	root	1.1	cancel).
106
107			# dynamic methods
108
109	root	1.4	COROUTINE METHODS
110			These are the methods you can call on coroutine objects.
111	root	1.1
112			new Coro \&sub [, @args...]
113	root	1.4	Create a new coroutine and return it. When the sub returns the
114			coroutine automatically terminates as if "terminate" with the
115			returned values were called. To make the coroutine run you must
116			first put it into the ready queue by calling the ready method.
117
118			Calling "exit" in a coroutine will not work correctly, so do not do
119			that.
120
121			$success = $coroutine->ready
122			Put the given coroutine into the ready queue (according to it's
123			priority) and return true. If the coroutine is already in the ready
124			queue, do nothing and return false.
125
126			$is_ready = $coroutine->is_ready
127			Return wether the coroutine is currently the ready queue or not,
128
129			$coroutine->cancel (arg...)
130			Terminates the given coroutine and makes it return the given
131			arguments as status (default: the empty list).
132	root	1.1
133	root	1.4	$coroutine->join
134	root	1.1	Wait until the coroutine terminates and return any values given to
135			the "terminate" or "cancel" functions. "join" can be called multiple
136	root	1.4	times from multiple coroutine.
137	root	1.1
138	root	1.4	$oldprio = $coroutine->prio ($newprio)
139	root	1.1	Sets (or gets, if the argument is missing) the priority of the
140	root	1.4	coroutine. Higher priority coroutines get run before lower priority
141			coroutines. Priorities are small signed integers (currently -4 ..
142	root	1.1	+3), that you can refer to using PRIO_xxx constants (use the import
143			tag :prio to get then):
144
145			PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
146			3 > 1 > 0 > -1 > -3 > -4
147
148			# set priority to HIGH
149			current->prio(PRIO_HIGH);
150
151			The idle coroutine ($Coro::idle) always has a lower priority than
152			any existing coroutine.
153
154	root	1.4	Changing the priority of the current coroutine will take effect
155			immediately, but changing the priority of coroutines in the ready
156	root	1.1	queue (but not running) will only take effect after the next
157	root	1.4	schedule (of that coroutine). This is a bug that will be fixed in
158			some future version.
159	root	1.1
160	root	1.4	$newprio = $coroutine->nice ($change)
161	root	1.1	Similar to "prio", but subtract the given value from the priority
162			(i.e. higher values mean lower priority, just as in unix).
163
164	root	1.4	$olddesc = $coroutine->desc ($newdesc)
165	root	1.1	Sets (or gets in case the argument is missing) the description for
166	root	1.4	this coroutine. This is just a free-form string you can associate
167			with a coroutine.
168
169			UTILITY FUNCTIONS
170			unblock_sub { ... }
171			This utility function takes a BLOCK or code reference and "unblocks"
172			it, returning the new coderef. This means that the new coderef will
173			return immediately without blocking, returning nothing, while the
174			original code ref will be called (with parameters) from within its
175			own coroutine.
176
177			The reason this fucntion exists is that many event libraries (such
178			as the venerable Event module) are not coroutine-safe (a weaker form
179			of thread-safety). This means you must not block within event
180			callbacks, otherwise you might suffer from crashes or worse.
181
182			This function allows your callbacks to block by executing them in
183			another coroutine where it is safe to block. One example where
184			blocking is handy is when you use the Coro::AIO functions to save
185			results to disk.
186
187			In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
188			when creating event callbacks that want to block.
189	root	1.1
190			BUGS/LIMITATIONS
191			- you must make very sure that no coro is still active on global
192			destruction. very bad things might happen otherwise (usually segfaults).
193
194			- this module is not thread-safe. You should only ever use this module
195			from the same thread (this requirement might be losened in the future
196			to allow per-thread schedulers, but Coro::State does not yet allow
197			this).
198
199			SEE ALSO
200	root	1.2	Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.
201
202			Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
203			Coro::SemaphoreSet, Coro::RWLock.
204
205			Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket,
206			Coro::Select.
207
208			Embedding: <Coro:MakeMaker>
209	root	1.1
210			AUTHOR
211			Marc Lehmann <schmorp@schmorp.de>
212			http://home.schmorp.de/
213