Coro/Coro.pm

=head1 NAME

Coro - create and manage coroutines

=head1 SYNOPSIS

 use Coro;

 $new = new Coro sub {
    print "in coroutine, switching back\n";
    $Coro::main->resume;
    print "in coroutine again, switching back\n";
    $Coro::main->resume;
 };

 print "in main, switching to coroutine\n";
 $new->resume;
 print "back in main, switch to coroutine again\n";
 $new->resume;
 print "back in main\n";

=head1 DESCRIPTION

This module implements coroutines. Coroutines, similar to continuations,
allow you to run more than one "thread of execution" in parallel. Unlike
threads this, only voluntary switching is used so locking problems are
greatly reduced.

Although this is the "main" module of the Coro family it provides only
low-level functionality. See L<Coro::Process> and related modules for a
more useful process abstraction including scheduling.

=over 4

=cut

package Coro;

BEGIN {
   $VERSION = 0.01;

   require XSLoader;
   XSLoader::load Coro, $VERSION;
}

=item $main

This coroutine represents the main program.

=item $current

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

=cut

$main = $current = _newprocess { 
   # never being called
};

=item $error, $error_msg, $error_coro

This coroutine will be called on fatal errors. C<$error_msg> and
C<$error_coro> return the error message and the error-causing coroutine,
respectively.

=cut

$error_msg =
$error_coro = undef;

$error = _newprocess {
   print STDERR "FATAL: $error_msg\nprogram aborted\n";
   exit 250;
};

=item $coro = new $coderef [, @args]

Create a new coroutine and return it. The first C<resume> call to this
coroutine will start execution at the given coderef. If it returns it
should return a coroutine to switch to. If, after returning, the coroutine
is C<resume>d again it starts execution again at the givne coderef.

=cut

sub new {
   my $class = $_[0];
   my $proc = $_[1];
   bless _newprocess {
      do {
         eval { &$proc->resume };
         if ($@) {
            ($error_msg, $error_coro) = ($@, $current);
            $error->resume;
         }
      } while ();
   }, $class;
}

=item $coro->resume

Resume execution at the given coroutine.

=cut

my $prev;

sub resume {
   $prev = $current; $current = $_[0];
   _transfer($prev, $current);
}

1;

=back

=head1 BUGS

This module has not yet been extensively tested.

=head1 SEE ALSO

L<Coro::Process>, L<Coro::Signal>.

=head1 AUTHOR

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

=cut

Revision:	1.3
Committed:	Tue Jul 3 04:02:31 2001 UTC (22 years, 10 months ago) by root
Branch:	MAIN
Changes since 1.2:	+1 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.3	Coro - create and manage coroutines
4	root	1.1
5			=head1 SYNOPSIS
6
7			use Coro;
8
9	root	1.2	$new = new Coro sub {
10			print "in coroutine, switching back\n";
11			$Coro::main->resume;
12			print "in coroutine again, switching back\n";
13			$Coro::main->resume;
14			};
15
16			print "in main, switching to coroutine\n";
17			$new->resume;
18			print "back in main, switch to coroutine again\n";
19			$new->resume;
20			print "back in main\n";
21
22	root	1.1	=head1 DESCRIPTION
23
24	root	1.2	This module implements coroutines. Coroutines, similar to continuations,
25			allow you to run more than one "thread of execution" in parallel. Unlike
26			threads this, only voluntary switching is used so locking problems are
27			greatly reduced.
28
29			Although this is the "main" module of the Coro family it provides only
30			low-level functionality. See L<Coro::Process> and related modules for a
31			more useful process abstraction including scheduling.
32
33	root	1.1	=over 4
34
35			=cut
36
37			package Coro;
38
39			BEGIN {
40			$VERSION = 0.01;
41
42			require XSLoader;
43			XSLoader::load Coro, $VERSION;
44			}
45
46			=item $main
47
48			This coroutine represents the main program.
49
50			=item $current
51
52			The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course).
53
54			=cut
55
56			$main = $current = _newprocess {
57			# never being called
58			};
59
60			=item $error, $error_msg, $error_coro
61
62			This coroutine will be called on fatal errors. C<$error_msg> and
63			C<$error_coro> return the error message and the error-causing coroutine,
64			respectively.
65
66			=cut
67
68			$error_msg =
69			$error_coro = undef;
70
71			$error = _newprocess {
72	root	1.2	print STDERR "FATAL: $error_msg\nprogram aborted\n";
73	root	1.1	exit 250;
74			};
75
76			=item $coro = new $coderef [, @args]
77
78			Create a new coroutine and return it. The first C<resume> call to this
79			coroutine will start execution at the given coderef. If it returns it
80			should return a coroutine to switch to. If, after returning, the coroutine
81			is C<resume>d again it starts execution again at the givne coderef.
82
83			=cut
84
85			sub new {
86			my $class = $_[0];
87			my $proc = $_[1];
88			bless _newprocess {
89			do {
90			eval { &$proc->resume };
91			if ($@) {
92			($error_msg, $error_coro) = ($@, $current);
93			$error->resume;
94			}
95			} while ();
96			}, $class;
97			}
98
99			=item $coro->resume
100
101			Resume execution at the given coroutine.
102
103			=cut
104
105			my $prev;
106
107			sub resume {
108			$prev = $current; $current = $_[0];
109			_transfer($prev, $current);
110			}
111
112			1;
113
114			=back
115
116			=head1 BUGS
117
118			This module has not yet been extensively tested.
119	root	1.2
120			=head1 SEE ALSO
121
122			L<Coro::Process>, L<Coro::Signal>.
123	root	1.1
124			=head1 AUTHOR
125
126			Marc Lehmann <pcg@goof.com>
127			http://www.goof.com/pcg/marc/
128
129			=cut
130