Coro/Coro.pm

=head1 NAME

Coro - coroutine process abstraction

=head1 SYNOPSIS

 use Coro;

 async {
    # some asynchronous thread of execution
 };

 # alternatively create an async process like this:

 sub some_func : Coro {
    # some more async code
 }

 cede;

=head1 DESCRIPTION

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

This module is still experimental, see the BUGS section below.

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.

=cut

package Coro;

use Coro::State;

use base Exporter;

$VERSION = 0.45;

@EXPORT = qw(async cede schedule terminate current);
@EXPORT_OK = qw($current);

{
   my @async;
   my $init;

   # this way of handling attributes simply is NOT scalable ;()
   sub import {
      Coro->export_to_level(1, @_);
      my $old = *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"}{CODE};
      *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"} = sub {
         my ($package, $ref) = (shift, shift);
         my @attrs;
         for (@_) {
            if ($_ eq "Coro") {
               push @async, $ref;
               unless ($init++) {
                  eval q{
                     sub INIT {
                        &async(pop @async) while @async;
                     }
                  };
               }
            } else {
               push @attrs, $_;
            }
         }
         return $old ? $old->($package, $ref, @attrs) : @attrs;
      };
   }

}

=item $main

This coroutine represents the main program.

=cut

our $main = new Coro;

=item $current (or as function: current)

The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course).

=cut

# maybe some other module used Coro::Specific before...
if ($current) {
   $main->{specific} = $current->{specific};
}

our $current = $main;

sub current() { $current }

=item $idle

The coroutine to switch to when no other coroutine is running. The default
implementation prints "FATAL: deadlock detected" and exits.

=cut

# should be done using priorities :(
our $idle = new Coro sub {
   print STDERR "FATAL: deadlock detected\n";
   exit(51);
};

# this coroutine is necessary because a coroutine
# cannot destroy itself.
my @destroy;
my $manager = new Coro sub {
   while() {
      delete ((pop @destroy)->{_coro_state}) while @destroy;
      &schedule;
   }
};

# static methods. not really.

=head2 STATIC METHODS

Static methods are actually functions that operate on the current process only.

=over 4

=item async { ... } [@args...]

Create a new asynchronous process and return it's process object
(usually unused). When the sub returns the new process is automatically
terminated.

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

The coderef you submit MUST NOT be a closure that refers to variables
in an outer scope. This does NOT work. Pass arguments into it instead.

=cut

sub async(&@) {
   my $pid = new Coro @_;
   $manager->ready; # this ensures that the stack is cloned from the manager
   $pid->ready;
   $pid;
}

=item schedule

Calls the scheduler. Please note that the current process will not be put
into the ready queue, so calling this function usually means you will
never be called again.

=cut

=item cede

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

=cut

=item terminate

Terminates the current process.

Future versions of this function will allow result arguments.

=cut

sub terminate {
   $current->cancel;
   &schedule;
   die; # NORETURN
}

=back

# dynamic methods

=head2 PROCESS METHODS

These are the methods you can call on process objects.

=over 4

=item new Coro \&sub [, @args...]

Create a new process and return it. When the sub returns the process
automatically terminates. To start the process you must first put it into
the ready queue by calling the ready method.

The coderef you submit MUST NOT be a closure that refers to variables
in an outer scope. This does NOT work. Pass arguments into it instead.

=cut

sub _newcoro {
   terminate &{+shift};
}

sub new {
   my $class = shift;
   bless {
      _coro_state => (new Coro::State $_[0] && \&_newcoro, @_),
   }, $class;
}

=item $process->ready

Put the current process into the ready queue.

=cut

=item $process->cancel

Like C<terminate>, but terminates the specified process instead.

=cut

sub cancel {
   push @destroy, $_[0];
   $manager->ready;
}

=back

=cut

1;

=head1 BUGS/LIMITATIONS

 - could be faster, especially when the core would introduce special
   support for coroutines (like it does for threads).
 - there is still a memleak on coroutine termination that I could not
   identify. Could be as small as a single SV.
 - this module is not well-tested.
 - if variables or arguments "disappear" (become undef) or become
   corrupted please contact the author so he cen iron out the
   remaining bugs.
 - this module is not thread-safe. You must 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).

=head1 SEE ALSO

L<Coro::Channel>, L<Coro::Cont>, L<Coro::Specific>, L<Coro::Semaphore>,
L<Coro::Signal>, L<Coro::State>, L<Coro::Event>, L<Coro::RWLock>,
L<Coro::Handle>, L<Coro::Socket>.

=head1 AUTHOR

 Marc Lehmann <pcg@goof.com>
 http://www.goof.com/pcg/marc/

=cut

Revision:	1.30
Committed:	Sat Aug 11 19:59:19 2001 UTC (22 years, 9 months ago) by root
Branch:	MAIN
Changes since 1.29:	+0 -20 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	Coro - coroutine process abstraction
4
5	=head1 SYNOPSIS
6
7	use Coro;
8
9	async {
10	# some asynchronous thread of execution
11	};
12
13	# alternatively create an async process like this:
14
15	sub some_func : Coro {
16	# some more async code
17	}
18
19	cede;
20
21	=head1 DESCRIPTION
22
23	This module collection manages coroutines. Coroutines are similar to
24	Threads but don't run in parallel.
25
26	This module is still experimental, see the BUGS section below.
27
28	In this module, coroutines are defined as "callchain + lexical variables
29	+ @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own
30	callchain, it's own set of lexicals and it's own set of perl's most
31	important global variables.
32
33	=cut
34
35	package Coro;
36
37	use Coro::State;
38
39	use base Exporter;
40
41	$VERSION = 0.45;
42
43	@EXPORT = qw(async cede schedule terminate current);
44	@EXPORT_OK = qw($current);
45
46	{
47	my @async;
48	my $init;
49
50	# this way of handling attributes simply is NOT scalable ;()
51	sub import {
52	Coro->export_to_level(1, @_);
53	my $old = *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"}{CODE};
54	*{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"} = sub {
55	my ($package, $ref) = (shift, shift);
56	my @attrs;
57	for (@_) {
58	if ($_ eq "Coro") {
59	push @async, $ref;
60	unless ($init++) {
61	eval q{
62	sub INIT {
63	&async(pop @async) while @async;
64	}
65	};
66	}
67	} else {
68	push @attrs, $_;
69	}
70	}
71	return $old ? $old->($package, $ref, @attrs) : @attrs;
72	};
73	}
74
75	}
76
77	=item $main
78
79	This coroutine represents the main program.
80
81	=cut
82
83	our $main = new Coro;
84
85	=item $current (or as function: current)
86
87	The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course).
88
89	=cut
90
91	# maybe some other module used Coro::Specific before...
92	if ($current) {
93	$main->{specific} = $current->{specific};
94	}
95
96	our $current = $main;
97
98	sub current() { $current }
99
100	=item $idle
101
102	The coroutine to switch to when no other coroutine is running. The default
103	implementation prints "FATAL: deadlock detected" and exits.
104
105	=cut
106
107	# should be done using priorities :(
108	our $idle = new Coro sub {
109	print STDERR "FATAL: deadlock detected\n";
110	exit(51);
111	};
112
113	# this coroutine is necessary because a coroutine
114	# cannot destroy itself.
115	my @destroy;
116	my $manager = new Coro sub {
117	while() {
118	delete ((pop @destroy)->{_coro_state}) while @destroy;
119	&schedule;
120	}
121	};
122
123	# static methods. not really.
124
125	=head2 STATIC METHODS
126
127	Static methods are actually functions that operate on the current process only.
128
129	=over 4
130
131	=item async { ... } [@args...]
132
133	Create a new asynchronous process and return it's process object
134	(usually unused). When the sub returns the new process is automatically
135	terminated.
136
137	# create a new coroutine that just prints its arguments
138	async {
139	print "@_\n";
140	} 1,2,3,4;
141
142	The coderef you submit MUST NOT be a closure that refers to variables
143	in an outer scope. This does NOT work. Pass arguments into it instead.
144
145	=cut
146
147	sub async(&@) {
148	my $pid = new Coro @_;
149	$manager->ready; # this ensures that the stack is cloned from the manager
150	$pid->ready;
151	$pid;
152	}
153
154	=item schedule
155
156	Calls the scheduler. Please note that the current process will not be put
157	into the ready queue, so calling this function usually means you will
158	never be called again.
159
160	=cut
161
162	=item cede
163
164	"Cede" to other processes. This function puts the current process into the
165	ready queue and calls C<schedule>, which has the effect of giving up the
166	current "timeslice" to other coroutines of the same or higher priority.
167
168	=cut
169
170	=item terminate
171
172	Terminates the current process.
173
174	Future versions of this function will allow result arguments.
175
176	=cut
177
178	sub terminate {
179	$current->cancel;
180	&schedule;
181	die; # NORETURN
182	}
183
184	=back
185
186	# dynamic methods
187
188	=head2 PROCESS METHODS
189
190	These are the methods you can call on process objects.
191
192	=over 4
193
194	=item new Coro \&sub [, @args...]
195
196	Create a new process and return it. When the sub returns the process
197	automatically terminates. To start the process you must first put it into
198	the ready queue by calling the ready method.
199
200	The coderef you submit MUST NOT be a closure that refers to variables
201	in an outer scope. This does NOT work. Pass arguments into it instead.
202
203	=cut
204
205	sub _newcoro {
206	terminate &{+shift};
207	}
208
209	sub new {
210	my $class = shift;
211	bless {
212	_coro_state => (new Coro::State $_[0] && \&_newcoro, @_),
213	}, $class;
214	}
215
216	=item $process->ready
217
218	Put the current process into the ready queue.
219
220	=cut
221
222	=item $process->cancel
223
224	Like C<terminate>, but terminates the specified process instead.
225
226	=cut
227
228	sub cancel {
229	push @destroy, $_[0];
230	$manager->ready;
231	}
232
233	=back
234
235	=cut
236
237	1;
238
239	=head1 BUGS/LIMITATIONS
240
241	- could be faster, especially when the core would introduce special
242	support for coroutines (like it does for threads).
243	- there is still a memleak on coroutine termination that I could not
244	identify. Could be as small as a single SV.
245	- this module is not well-tested.
246	- if variables or arguments "disappear" (become undef) or become
247	corrupted please contact the author so he cen iron out the
248	remaining bugs.
249	- this module is not thread-safe. You must only ever use this module from
250	the same thread (this requirement might be loosened in the future to
251	allow per-thread schedulers, but Coro::State does not yet allow this).
252
253	=head1 SEE ALSO
254
255	L<Coro::Channel>, L<Coro::Cont>, L<Coro::Specific>, L<Coro::Semaphore>,
256	L<Coro::Signal>, L<Coro::State>, L<Coro::Event>, L<Coro::RWLock>,
257	L<Coro::Handle>, L<Coro::Socket>.
258
259	=head1 AUTHOR
260
261	Marc Lehmann <pcg@goof.com>
262	http://www.goof.com/pcg/marc/
263
264	=cut
265