[ViewVC] Annotation of: cvs/Coro/README

NAME
    Coro - coroutine process abstraction

SYNOPSIS
     use Coro;

     async {
        # some asynchronous thread of execution
        print "2\n";
        cede; # yield back to main
        print "4\n";
     };
     print "1\n";
     cede; # yield to coroutine
     print "3\n";
     cede; # and again

     # use locking
     my $lock = new Coro::Semaphore;
     my $locked;

     $lock->down;
     $locked = 1;
     $lock->up;

DESCRIPTION
    This module collection manages coroutines. Coroutines are similar to
    threads but don't run in parallel at the same time even on SMP machines.
    The specific flavor of coroutine used in this module also guarantees you
    that it will not switch between coroutines unless necessary, at
    easily-identified points in your program, so locking and parallel access
    are rarely an issue, making coroutine programming much safer than
    threads programming.

    (Perl, however, does not natively support real threads but instead does
    a very slow and memory-intensive emulation of processes using threads.
    This is a performance win on Windows machines, and a loss everywhere
    else).

    In this module, coroutines are defined as "callchain + lexical variables
    + @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
    callchain, its own set of lexicals and its own set of perls most
    important global variables (see Coro::State for more configuration).

    $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 essential 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
        itself.

  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.

        See the "Coro::State::new" constructor for info about the coroutine
        environment in which coroutines run.

        Calling "exit" in a coroutine will do the same as calling exit
        outside the coroutine. Likewise, when the coroutine dies, the
        program will exit, just as it would in the main program.

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

    async_pool { ... } [@args...]
        Similar to "async", but uses a coroutine pool, so you should not
        call terminate or join (although you are allowed to), and you get a
        coroutine that might have executed other code already (which can be
        good or bad :).

        Also, the block is executed in an "eval" context and a warning will
        be issued in case of an exception instead of terminating the
        program, as "async" does. As the coroutine is being reused, stuff
        like "on_destroy" will not work in the expected way, unless you call
        terminate or cancel, which somehow defeats the purpose of pooling.

        The priority will be reset to 0 after each job, tracing will be
        disabled, the description will be reset and the default output
        filehandle gets restored, so you can change alkl these. Otherwise
        the coroutine will be re-used "as-is": most notably if you change
        other per-coroutine global stuff such as $/ you need to revert that
        change, which is most simply done by using local as in " local $/ ".

        The pool size is limited to 8 idle coroutines (this can be adjusted
        by changing $Coro::POOL_SIZE), and there can be as many non-idle
        coros as required.

        If you are concerned about pooled coroutines growing a lot because a
        single "async_pool" used a lot of stackspace you can e.g.
        "async_pool { terminate }" once per second or so to slowly replenish
        the pool. In addition to that, when the stacks used by a handler
        grows larger than 16kb (adjustable with $Coro::POOL_RSS) it will
        also exit.

    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 occurred.
              # 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.

    Coro::cede_notself
        Works like cede, but is not exported by default and will cede to any
        coroutine, regardless of priority, once.

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

    killall
        Kills/terminates/cancels all coroutines except the currently running
        one. This is useful after a fork, either in the child or the parent,
        as usually only one of them should inherit the running coroutines.

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

        See "async" and "Coro::State::new" for additional info about the
        coroutine environment.

    $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). Never returns if the
        coroutine is the current coroutine.

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

    $coroutine->on_destroy (\&cb)
        Registers a callback that is called when this coroutine gets
        destroyed, but before it is joined. The callback gets passed the
        terminate arguments, if any.

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

        This method simply sets the "$coroutine->{desc}" member to the given
        string. You can modify this member directly if you wish.

    $coroutine->throw ([$scalar])
        If $throw is specified and defined, it will be thrown as an
        exception inside the coroutine at the next convinient point in time
        (usually after it gains control at the next schedule/transfer/cede).
        Otherwise clears the exception object.

        The exception object will be thrown "as is" with the specified
        scalar in $@, i.e. if it is a string, no line number or newline will
        be appended (unlike with "die").

        This can be used as a softer means than "cancel" to ask a coroutine
        to end itself, although there is no guarentee that the exception
        will lead to termination, and if the exception isn't caught it might
        well end the whole program.

  GLOBAL FUNCTIONS
    Coro::nready
        Returns the number of coroutines that are currently in the ready
        state, i.e. that can be switched to. The value 0 means that the only
        runnable coroutine is the currently running one, so "cede" would
        have no effect, and "schedule" would cause a deadlock unless there
        is an idle handler that wakes up some coroutines.

    my $guard = Coro::guard { ... }
        This creates and returns a guard object. Nothing happens until the
        object gets destroyed, in which case the codeblock given as argument
        will be executed. This is useful to free locks or other resources in
        case of a runtime error or when the coroutine gets canceled, as in
        both cases the guard block will be executed. The guard object
        supports only one method, "->cancel", which will keep the codeblock
        from being executed.

        Example: set some flag and clear it again when the coroutine gets
        canceled or the function returns:

           sub do_something {
              my $guard = Coro::guard { $busy = 0 };
              $busy = 1;

              # do something that requires $busy to be true
           }

    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 function 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 loosened in the future
       to allow per-thread schedulers, but Coro::State does not yet allow
       this).

SEE ALSO
    Lower level Configuration, Coroutine Environment: Coro::State.

    Debugging: Coro::Debug.

    Support/Utility: Coro::Specific, Coro::Util.

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

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

    Compatibility: Coro::LWP, Coro::Storable, Coro::Select.

    Embedding: <Coro:MakeMaker>.

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

Revision:	1.12
Committed:	Thu Oct 11 00:38:37 2007 UTC (16 years, 7 months ago) by root
Branch:	MAIN
CVS Tags:	rel-4_22, rel-4_21, rel-4_3, rel-4_13, rel-4_11, rel-4_1, rel-4_2, rel-4_31
Changes since 1.11:	+28 -19 lines
Log Message:	* empty log message *
#	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	root	1.12	print "2\n";
10			cede; # yield back to main
11			print "4\n";
12	root	1.1	};
13	root	1.12	print "1\n";
14			cede; # yield to coroutine
15			print "3\n";
16			cede; # and again
17
18			# use locking
19			my $lock = new Coro::Semaphore;
20			my $locked;
21
22			$lock->down;
23			$locked = 1;
24			$lock->up;
25	root	1.1
26			DESCRIPTION
27			This module collection manages coroutines. Coroutines are similar to
28	root	1.5	threads but don't run in parallel at the same time even on SMP machines.
29	root	1.8	The specific flavor of coroutine used in this module also guarantees you
30	root	1.5	that it will not switch between coroutines unless necessary, at
31			easily-identified points in your program, so locking and parallel access
32			are rarely an issue, making coroutine programming much safer than
33			threads programming.
34
35			(Perl, however, does not natively support real threads but instead does
36			a very slow and memory-intensive emulation of processes using threads.
37			This is a performance win on Windows machines, and a loss everywhere
38			else).
39	root	1.1
40			In this module, coroutines are defined as "callchain + lexical variables
41	root	1.5	+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
42			callchain, its own set of lexicals and its own set of perls most
43	root	1.12	important global variables (see Coro::State for more configuration).
44	root	1.1
45			$main
46			This coroutine represents the main program.
47
48			$current (or as function: current)
49			The current coroutine (the last coroutine switched to). The initial
50			value is $main (of course).
51
52	root	1.4	This variable is strictly read-only. It is provided for
53	root	1.8	performance reasons. If performance is not essential you are
54	root	1.4	encouraged to use the "Coro::current" function instead.
55
56	root	1.1	$idle
57	root	1.4	A callback that is called whenever the scheduler finds no ready
58			coroutines to run. The default implementation prints "FATAL:
59			deadlock detected" and exits, because the program has no other way
60			to continue.
61
62			This hook is overwritten by modules such as "Coro::Timer" and
63			"Coro::Event" to wait on an external event that hopefully wake up a
64			coroutine so the scheduler can run it.
65
66			Please note that if your callback recursively invokes perl (e.g. for
67	root	1.12	event handlers), then it must be prepared to be called recursively
68			itself.
69	root	1.1
70			STATIC METHODS
71			Static methods are actually functions that operate on the current
72	root	1.4	coroutine only.
73	root	1.1
74			async { ... } [@args...]
75	root	1.4	Create a new asynchronous coroutine and return it's coroutine object
76			(usually unused). When the sub returns the new coroutine is
77	root	1.1	automatically terminated.
78
79	root	1.10	See the "Coro::State::new" constructor for info about the coroutine
80	root	1.12	environment in which coroutines run.
81	root	1.10
82	root	1.7	Calling "exit" in a coroutine will do the same as calling exit
83			outside the coroutine. Likewise, when the coroutine dies, the
84			program will exit, just as it would in the main program.
85	root	1.3
86	root	1.1	# create a new coroutine that just prints its arguments
87			async {
88			print "@_\n";
89			} 1,2,3,4;
90
91	root	1.6	async_pool { ... } [@args...]
92			Similar to "async", but uses a coroutine pool, so you should not
93			call terminate or join (although you are allowed to), and you get a
94			coroutine that might have executed other code already (which can be
95			good or bad :).
96
97			Also, the block is executed in an "eval" context and a warning will
98			be issued in case of an exception instead of terminating the
99			program, as "async" does. As the coroutine is being reused, stuff
100			like "on_destroy" will not work in the expected way, unless you call
101			terminate or cancel, which somehow defeats the purpose of pooling.
102
103	root	1.10	The priority will be reset to 0 after each job, tracing will be
104			disabled, the description will be reset and the default output
105			filehandle gets restored, so you can change alkl these. Otherwise
106			the coroutine will be re-used "as-is": most notably if you change
107			other per-coroutine global stuff such as $/ you need to revert that
108			change, which is most simply done by using local as in " local $/ ".
109	root	1.6
110			The pool size is limited to 8 idle coroutines (this can be adjusted
111			by changing $Coro::POOL_SIZE), and there can be as many non-idle
112			coros as required.
113
114			If you are concerned about pooled coroutines growing a lot because a
115			single "async_pool" used a lot of stackspace you can e.g.
116			"async_pool { terminate }" once per second or so to slowly replenish
117	root	1.9	the pool. In addition to that, when the stacks used by a handler
118			grows larger than 16kb (adjustable with $Coro::POOL_RSS) it will
119			also exit.
120	root	1.6
121	root	1.1	schedule
122	root	1.4	Calls the scheduler. Please note that the current coroutine will not
123	root	1.1	be put into the ready queue, so calling this function usually means
124	root	1.4	you will never be called again unless something else (e.g. an event
125			handler) calls ready.
126
127			The canonical way to wait on external events is this:
128
129			{
130			# remember current coroutine
131			my $current = $Coro::current;
132
133			# register a hypothetical event handler
134			on_event_invoke sub {
135			# wake up sleeping coroutine
136			$current->ready;
137			undef $current;
138			};
139
140	root	1.8	# call schedule until event occurred.
141	root	1.4	# in case we are woken up for other reasons
142			# (current still defined), loop.
143			Coro::schedule while $current;
144			}
145	root	1.1
146			cede
147	root	1.4	"Cede" to other coroutines. This function puts the current coroutine
148	root	1.1	into the ready queue and calls "schedule", which has the effect of
149			giving up the current "timeslice" to other coroutines of the same or
150			higher priority.
151
152	root	1.6	Coro::cede_notself
153			Works like cede, but is not exported by default and will cede to any
154			coroutine, regardless of priority, once.
155
156	root	1.1	terminate [arg...]
157	root	1.4	Terminates the current coroutine with the given status values (see
158	root	1.1	cancel).
159
160	root	1.10	killall
161			Kills/terminates/cancels all coroutines except the currently running
162			one. This is useful after a fork, either in the child or the parent,
163			as usually only one of them should inherit the running coroutines.
164
165	root	1.1	# dynamic methods
166
167	root	1.4	COROUTINE METHODS
168			These are the methods you can call on coroutine objects.
169	root	1.1
170			new Coro \&sub [, @args...]
171	root	1.4	Create a new coroutine and return it. When the sub returns the
172			coroutine automatically terminates as if "terminate" with the
173			returned values were called. To make the coroutine run you must
174			first put it into the ready queue by calling the ready method.
175
176	root	1.10	See "async" and "Coro::State::new" for additional info about the
177			coroutine environment.
178	root	1.4
179			$success = $coroutine->ready
180			Put the given coroutine into the ready queue (according to it's
181			priority) and return true. If the coroutine is already in the ready
182			queue, do nothing and return false.
183
184			$is_ready = $coroutine->is_ready
185			Return wether the coroutine is currently the ready queue or not,
186
187			$coroutine->cancel (arg...)
188			Terminates the given coroutine and makes it return the given
189	root	1.6	arguments as status (default: the empty list). Never returns if the
190			coroutine is the current coroutine.
191	root	1.1
192	root	1.4	$coroutine->join
193	root	1.1	Wait until the coroutine terminates and return any values given to
194	root	1.10	the "terminate" or "cancel" functions. "join" can be called
195			concurrently from multiple coroutines.
196	root	1.1
197	root	1.6	$coroutine->on_destroy (\&cb)
198			Registers a callback that is called when this coroutine gets
199			destroyed, but before it is joined. The callback gets passed the
200			terminate arguments, if any.
201
202	root	1.4	$oldprio = $coroutine->prio ($newprio)
203	root	1.1	Sets (or gets, if the argument is missing) the priority of the
204	root	1.4	coroutine. Higher priority coroutines get run before lower priority
205			coroutines. Priorities are small signed integers (currently -4 ..
206	root	1.1	+3), that you can refer to using PRIO_xxx constants (use the import
207			tag :prio to get then):
208
209			PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
210			3 > 1 > 0 > -1 > -3 > -4
211
212			# set priority to HIGH
213			current->prio(PRIO_HIGH);
214
215			The idle coroutine ($Coro::idle) always has a lower priority than
216			any existing coroutine.
217
218	root	1.4	Changing the priority of the current coroutine will take effect
219			immediately, but changing the priority of coroutines in the ready
220	root	1.1	queue (but not running) will only take effect after the next
221	root	1.4	schedule (of that coroutine). This is a bug that will be fixed in
222			some future version.
223	root	1.1
224	root	1.4	$newprio = $coroutine->nice ($change)
225	root	1.1	Similar to "prio", but subtract the given value from the priority
226			(i.e. higher values mean lower priority, just as in unix).
227
228	root	1.4	$olddesc = $coroutine->desc ($newdesc)
229	root	1.1	Sets (or gets in case the argument is missing) the description for
230	root	1.4	this coroutine. This is just a free-form string you can associate
231			with a coroutine.
232
233	root	1.10	This method simply sets the "$coroutine->{desc}" member to the given
234			string. You can modify this member directly if you wish.
235
236	root	1.11	$coroutine->throw ([$scalar])
237			If $throw is specified and defined, it will be thrown as an
238			exception inside the coroutine at the next convinient point in time
239			(usually after it gains control at the next schedule/transfer/cede).
240			Otherwise clears the exception object.
241
242			The exception object will be thrown "as is" with the specified
243			scalar in $@, i.e. if it is a string, no line number or newline will
244			be appended (unlike with "die").
245
246			This can be used as a softer means than "cancel" to ask a coroutine
247			to end itself, although there is no guarentee that the exception
248			will lead to termination, and if the exception isn't caught it might
249			well end the whole program.
250
251	root	1.5	GLOBAL FUNCTIONS
252			Coro::nready
253			Returns the number of coroutines that are currently in the ready
254	root	1.8	state, i.e. that can be switched to. The value 0 means that the only
255	root	1.5	runnable coroutine is the currently running one, so "cede" would
256			have no effect, and "schedule" would cause a deadlock unless there
257			is an idle handler that wakes up some coroutines.
258
259	root	1.6	my $guard = Coro::guard { ... }
260			This creates and returns a guard object. Nothing happens until the
261	root	1.7	object gets destroyed, in which case the codeblock given as argument
262	root	1.6	will be executed. This is useful to free locks or other resources in
263			case of a runtime error or when the coroutine gets canceled, as in
264			both cases the guard block will be executed. The guard object
265			supports only one method, "->cancel", which will keep the codeblock
266			from being executed.
267
268			Example: set some flag and clear it again when the coroutine gets
269			canceled or the function returns:
270
271			sub do_something {
272			my $guard = Coro::guard { $busy = 0 };
273			$busy = 1;
274
275			# do something that requires $busy to be true
276			}
277
278	root	1.4	unblock_sub { ... }
279			This utility function takes a BLOCK or code reference and "unblocks"
280			it, returning the new coderef. This means that the new coderef will
281			return immediately without blocking, returning nothing, while the
282			original code ref will be called (with parameters) from within its
283			own coroutine.
284
285	root	1.8	The reason this function exists is that many event libraries (such
286	root	1.4	as the venerable Event module) are not coroutine-safe (a weaker form
287			of thread-safety). This means you must not block within event
288			callbacks, otherwise you might suffer from crashes or worse.
289
290			This function allows your callbacks to block by executing them in
291			another coroutine where it is safe to block. One example where
292			blocking is handy is when you use the Coro::AIO functions to save
293			results to disk.
294
295			In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
296			when creating event callbacks that want to block.
297	root	1.1
298			BUGS/LIMITATIONS
299			- you must make very sure that no coro is still active on global
300			destruction. very bad things might happen otherwise (usually segfaults).
301
302			- this module is not thread-safe. You should only ever use this module
303	root	1.8	from the same thread (this requirement might be loosened in the future
304	root	1.1	to allow per-thread schedulers, but Coro::State does not yet allow
305			this).
306
307			SEE ALSO
308	root	1.12	Lower level Configuration, Coroutine Environment: Coro::State.
309
310			Debugging: Coro::Debug.
311
312			Support/Utility: Coro::Specific, Coro::Util.
313	root	1.2
314			Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
315			Coro::SemaphoreSet, Coro::RWLock.
316
317	root	1.12	Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket.
318
319			Compatibility: Coro::LWP, Coro::Storable, Coro::Select.
320	root	1.2
321	root	1.12	Embedding: <Coro:MakeMaker>.
322	root	1.1
323			AUTHOR
324			Marc Lehmann <schmorp@schmorp.de>
325			http://home.schmorp.de/
326