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

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

  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 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, otherwise the
        coroutine will be re-used "as-is".

        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.

        Returns true if at least one coroutine switch has happened.

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

        Returns true if at least one coroutine switch has happened.

    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.

        See "async" for additional discussion.

    $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 multiple
        times from multiple coroutine.

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

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