[ViewVC] Contents 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 use din this module also guarentees 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 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.

  GLOBAL FUNCTIONS
    Coro::nready
        Returns the number of coroutines that are currently in the ready
        state, i.e. that can be swicthed 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.

    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.5
Committed:	Mon Dec 4 22:06:02 2006 UTC (17 years, 5 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_1, rel-3_2, rel-3_11
Changes since 1.4:	+21 -4 lines
Log Message:	* empty log message *
#	Content
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	# alternatively create an async coroutine like this:
12
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 at the same time even on SMP machines.
22	The specific flavor of coroutine use din this module also guarentees you
23	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
33	In this module, coroutines are defined as "callchain + lexical variables
34	+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
35	callchain, its own set of lexicals and its own set of perls most
36	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	This variable is strictly read-only. It is provided for
46	performance reasons. If performance is not essentiel you are
47	encouraged to use the "Coro::current" function instead.
48
49	$idle
50	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
62	STATIC METHODS
63	Static methods are actually functions that operate on the current
64	coroutine only.
65
66	async { ... } [@args...]
67	Create a new asynchronous coroutine and return it's coroutine object
68	(usually unused). When the sub returns the new coroutine is
69	automatically terminated.
70
71	Calling "exit" in a coroutine will not work correctly, so do not do
72	that.
73
74	When the coroutine dies, the program will exit, just as in the main
75	program.
76
77	# create a new coroutine that just prints its arguments
78	async {
79	print "@_\n";
80	} 1,2,3,4;
81
82	schedule
83	Calls the scheduler. Please note that the current coroutine will not
84	be put into the ready queue, so calling this function usually means
85	you will never be called again unless something else (e.g. an event
86	handler) calls ready.
87
88	The canonical way to wait on external events is this:
89
90	{
91	# remember current coroutine
92	my $current = $Coro::current;
93
94	# register a hypothetical event handler
95	on_event_invoke sub {
96	# wake up sleeping coroutine
97	$current->ready;
98	undef $current;
99	};
100
101	# call schedule until event occured.
102	# in case we are woken up for other reasons
103	# (current still defined), loop.
104	Coro::schedule while $current;
105	}
106
107	cede
108	"Cede" to other coroutines. This function puts the current coroutine
109	into the ready queue and calls "schedule", which has the effect of
110	giving up the current "timeslice" to other coroutines of the same or
111	higher priority.
112
113	terminate [arg...]
114	Terminates the current coroutine with the given status values (see
115	cancel).
116
117	# dynamic methods
118
119	COROUTINE METHODS
120	These are the methods you can call on coroutine objects.
121
122	new Coro \&sub [, @args...]
123	Create a new coroutine and return it. When the sub returns the
124	coroutine automatically terminates as if "terminate" with the
125	returned values were called. To make the coroutine run you must
126	first put it into the ready queue by calling the ready method.
127
128	Calling "exit" in a coroutine will not work correctly, so do not do
129	that.
130
131	$success = $coroutine->ready
132	Put the given coroutine into the ready queue (according to it's
133	priority) and return true. If the coroutine is already in the ready
134	queue, do nothing and return false.
135
136	$is_ready = $coroutine->is_ready
137	Return wether the coroutine is currently the ready queue or not,
138
139	$coroutine->cancel (arg...)
140	Terminates the given coroutine and makes it return the given
141	arguments as status (default: the empty list).
142
143	$coroutine->join
144	Wait until the coroutine terminates and return any values given to
145	the "terminate" or "cancel" functions. "join" can be called multiple
146	times from multiple coroutine.
147
148	$oldprio = $coroutine->prio ($newprio)
149	Sets (or gets, if the argument is missing) the priority of the
150	coroutine. Higher priority coroutines get run before lower priority
151	coroutines. Priorities are small signed integers (currently -4 ..
152	+3), that you can refer to using PRIO_xxx constants (use the import
153	tag :prio to get then):
154
155	PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
156	3 > 1 > 0 > -1 > -3 > -4
157
158	# set priority to HIGH
159	current->prio(PRIO_HIGH);
160
161	The idle coroutine ($Coro::idle) always has a lower priority than
162	any existing coroutine.
163
164	Changing the priority of the current coroutine will take effect
165	immediately, but changing the priority of coroutines in the ready
166	queue (but not running) will only take effect after the next
167	schedule (of that coroutine). This is a bug that will be fixed in
168	some future version.
169
170	$newprio = $coroutine->nice ($change)
171	Similar to "prio", but subtract the given value from the priority
172	(i.e. higher values mean lower priority, just as in unix).
173
174	$olddesc = $coroutine->desc ($newdesc)
175	Sets (or gets in case the argument is missing) the description for
176	this coroutine. This is just a free-form string you can associate
177	with a coroutine.
178
179	GLOBAL FUNCTIONS
180	Coro::nready
181	Returns the number of coroutines that are currently in the ready
182	state, i.e. that can be swicthed to. The value 0 means that the only
183	runnable coroutine is the currently running one, so "cede" would
184	have no effect, and "schedule" would cause a deadlock unless there
185	is an idle handler that wakes up some coroutines.
186
187	unblock_sub { ... }
188	This utility function takes a BLOCK or code reference and "unblocks"
189	it, returning the new coderef. This means that the new coderef will
190	return immediately without blocking, returning nothing, while the
191	original code ref will be called (with parameters) from within its
192	own coroutine.
193
194	The reason this fucntion exists is that many event libraries (such
195	as the venerable Event module) are not coroutine-safe (a weaker form
196	of thread-safety). This means you must not block within event
197	callbacks, otherwise you might suffer from crashes or worse.
198
199	This function allows your callbacks to block by executing them in
200	another coroutine where it is safe to block. One example where
201	blocking is handy is when you use the Coro::AIO functions to save
202	results to disk.
203
204	In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
205	when creating event callbacks that want to block.
206
207	BUGS/LIMITATIONS
208	- you must make very sure that no coro is still active on global
209	destruction. very bad things might happen otherwise (usually segfaults).
210
211	- this module is not thread-safe. You should only ever use this module
212	from the same thread (this requirement might be losened in the future
213	to allow per-thread schedulers, but Coro::State does not yet allow
214	this).
215
216	SEE ALSO
217	Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.
218
219	Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
220	Coro::SemaphoreSet, Coro::RWLock.
221
222	Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket,
223	Coro::Select.
224
225	Embedding: <Coro:MakeMaker>
226
227	AUTHOR
228	Marc Lehmann <schmorp@schmorp.de>
229	http://home.schmorp.de/
230