Coro/Coro/Signal.pm

=head1 NAME

Coro::Signal - thread signals (binary semaphores)

=head1 SYNOPSIS

 use Coro;

 $sig = new Coro::Signal;

 $sig->wait; # wait for signal

 # ... some other "thread"

 $sig->send;

=head1 DESCRIPTION

This module implements signals/binary semaphores/condition variables
(basically all the same thing). You can wait for a signal to occur or send
it, in which case it will wake up one waiter, or it can be broadcast,
waking up all waiters.

It is recommended not to mix C<send> and C<broadcast> calls on the same
C<Coro::Signal> - it should work as documented, but it can easily confuse
you :->

You don't have to load C<Coro::Signal> manually, it will be loaded 
automatically when you C<use Coro> and call the C<new> constructor. 

=over 4

=cut

package Coro::Signal;

use common::sense;

use Coro::Semaphore ();

our $VERSION = 6.02;

=item $sig = new Coro::Signal;

Create a new signal.

=item $sig->wait

Wait for the signal to occur (via either C<send> or C<broadcast>). Returns
immediately if the signal has been sent before.

=item $sem->wait ($callback)

If you pass a callback argument to C<wait>, it will not wait, but
immediately return. The callback will be called under the same conditions
as C<wait> without arguments would continue the thrad.

The callback might wake up any number of threads, but is I<NOT> allowed to
block (switch to other threads).

=item $sig->send

Send the signal, waking up I<one> waiting process or remember the signal
if no process is waiting.

=item $sig->broadcast

Send the signal, waking up I<all> waiting process. If no process is
waiting the signal is lost.

=item $sig->awaited

Return true when the signal is being awaited by some process.

=cut

#=item $status = $s->timed_wait ($timeout)
#
#Like C<wait>, but returns false if no signal happens within $timeout
#seconds, otherwise true.
#
#See C<wait> for some reliability concerns.
#
#=cut

#ub timed_wait {
#  require Coro::Timer;
#  my $timeout = Coro::Timer::timeout($_[1]);
#
#  unless (delete $_[0][0]) {
#     push @{$_[0][1]}, $Coro::current;
#     &Coro::schedule;
#
#     return 0 if $timeout;
#  }
#
#  1
#

1;

=back

=head1 AUTHOR

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

=cut

Revision:	1.105
Committed:	Wed Jul 13 02:36:03 2011 UTC (12 years, 11 months ago) by root
Branch:	MAIN
CVS Tags:	rel-6_02
Changes since 1.104:	+1 -1 lines
Log Message:	6.02
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.83	Coro::Signal - thread signals (binary semaphores)
4	root	1.1
5			=head1 SYNOPSIS
6
7	root	1.98	use Coro;
8	root	1.1
9			$sig = new Coro::Signal;
10
11			$sig->wait; # wait for signal
12
13			# ... some other "thread"
14
15			$sig->send;
16
17			=head1 DESCRIPTION
18
19	root	1.73	This module implements signals/binary semaphores/condition variables
20	root	1.11	(basically all the same thing). You can wait for a signal to occur or send
21			it, in which case it will wake up one waiter, or it can be broadcast,
22			waking up all waiters.
23
24	root	1.73	It is recommended not to mix C<send> and C<broadcast> calls on the same
25			C<Coro::Signal> - it should work as documented, but it can easily confuse
26			you :->
27
28	root	1.97	You don't have to load C<Coro::Signal> manually, it will be loaded
29			automatically when you C<use Coro> and call the C<new> constructor.
30
31	root	1.1	=over 4
32
33			=cut
34
35			package Coro::Signal;
36
37	root	1.90	use common::sense;
38	root	1.16
39	root	1.73	use Coro::Semaphore ();
40	root	1.1
41	root	1.105	our $VERSION = 6.02;
42	root	1.1
43	root	1.74	=item $sig = new Coro::Signal;
44	root	1.3
45			Create a new signal.
46
47	root	1.74	=item $sig->wait
48	root	1.3
49	root	1.73	Wait for the signal to occur (via either C<send> or C<broadcast>). Returns
50			immediately if the signal has been sent before.
51	root	1.3
52	root	1.83	=item $sem->wait ($callback)
53
54			If you pass a callback argument to C<wait>, it will not wait, but
55			immediately return. The callback will be called under the same conditions
56			as C<wait> without arguments would continue the thrad.
57
58			The callback might wake up any number of threads, but is I<NOT> allowed to
59			block (switch to other threads).
60
61	root	1.74	=item $sig->send
62
63			Send the signal, waking up I<one> waiting process or remember the signal
64			if no process is waiting.
65
66			=item $sig->broadcast
67	root	1.52
68	root	1.73	Send the signal, waking up I<all> waiting process. If no process is
69			waiting the signal is lost.
70	root	1.48
71	root	1.74	=item $sig->awaited
72	root	1.20
73	root	1.73	Return true when the signal is being awaited by some process.
74	root	1.48
75	root	1.3	=cut
76
77	root	1.73	#=item $status = $s->timed_wait ($timeout)
78			#
79			#Like C<wait>, but returns false if no signal happens within $timeout
80			#seconds, otherwise true.
81			#
82			#See C<wait> for some reliability concerns.
83			#
84			#=cut
85
86			#ub timed_wait {
87			# require Coro::Timer;
88			# my $timeout = Coro::Timer::timeout($_[1]);
89			#
90			# unless (delete $_[0][0]) {
91			# push @{$_[0][1]}, $Coro::current;
92			# &Coro::schedule;
93			#
94			# return 0 if $timeout;
95			# }
96			#
97			# 1
98			#
99
100	root	1.1	1;
101
102			=back
103
104			=head1 AUTHOR
105
106	root	1.38	Marc Lehmann <schmorp@schmorp.de>
107	root	1.36	http://home.schmorp.de/
108	root	1.1
109			=cut
110