AnyEvent/lib/AnyEvent.pm

=head1 NAME

AnyEvent - provide framework for multiple event loops

Event, Coro, Glib, Tk - various supported event loops

=head1 SYNOPSIS

use AnyEvent;

   my $w = AnyEvent->timer (fh => ..., poll => "[rw]+", cb => sub {
      my ($poll_got) = @_;
      ...
   });
   my $w = AnyEvent->io (after => $seconds, cb => sub {
      ...
   });

   # watchers get canceled whenever $w is destroyed
   # only one watcher per $fh and $poll type is allowed
   # (i.e. on a socket you cna have one r + one w or one rw
   # watcher, not any more.
   # timers can only be used once

   my $w = AnyEvent->condvar; # kind of main loop replacement
   # can only be used once
   $w->wait; # enters main loop till $condvar gets ->send
   $w->broadcast; # wake up waiting and future wait's

=head1 DESCRIPTION

L<AnyEvent> provides an identical interface to multiple event loops. This
allows module authors to utilizy an event loop without forcing module
users to use the same event loop (as only a single event loop can coexist
peacefully at any one time).

The interface itself is vaguely similar but not identical to the Event
module.

On the first call of any method, the module tries to detect the currently
loaded event loop by probing wether any of the following modules is
loaded: L<Coro::Event>, L<Event>, L<Glib>, L<Tk>. The first one found is
used. If none is found, the module tries to load these modules in the
order given. The first one that could be successfully loaded will be
used. If still none could be found, it will issue an error.

=over 4

=cut

package AnyEvent;

no warnings;
use strict 'vars';
use Carp;

our $VERSION = 0.2;
our $MODEL;

our $AUTOLOAD;
our @ISA;

my @models = (
      [Coro  => Coro::Event::],
      [Event => Event::],
      [Glib  => Glib::],
      [Tk    => Tk::],
);

our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY);

sub AUTOLOAD {
   $AUTOLOAD =~ s/.*://;

   $method{$AUTOLOAD}
      or croak "$AUTOLOAD: not a valid method for AnyEvent objects";

   unless ($MODEL) {
      # check for already loaded models
      for (@models) {
         my ($model, $package) = @$_;
         if (scalar keys %{ *{"$package\::"} }) {
            eval "require AnyEvent::Impl::$model";
            last if $MODEL;
         }
      }

      unless ($MODEL) {
         # try to load a model

         for (@models) {
            my ($model, $package) = @$_;
            eval "require AnyEvent::Impl::$model";
            last if $MODEL;
         }

         $MODEL
           or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";
      }
   }

   @ISA = $MODEL;

   my $class = shift;
   $class->$AUTOLOAD (@_);
}

=back

=head1 EXAMPLE

The following program uses an io watcher to read data from stdin, a timer
to display a message once per second, and a condvar to exit the program
when the user enters quit:

   use AnyEvent;

   my $cv = AnyEvent->condvar;

   my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
      warn "io event <$_[0]>\n";   # will always output <r>
      chomp (my $input = <STDIN>); # read a line
      warn "read: $input\n";       # output what has been read
      $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i
   });

   my $time_watcher; # can only be used once

   sub new_timer {
      $timer = AnyEvent->timer (after => 1, cb => sub {
         warn "timeout\n"; # print 'timeout' about every second
         &new_timer; # and restart the time
      });
   }

   new_timer; # create first timer

   $cv->wait; # wait until user enters /^q/i

=head1 SEE ALSO

L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>,
L<AnyEvent::Impl::Coro>,
L<AnyEvent::Impl::Event>,
L<AnyEvent::Impl::Glib>,
L<AnyEvent::Impl::Tk>.

=head1

=cut

1

Revision:	1.4
Committed:	Thu Dec 1 22:04:50 2005 UTC (18 years, 7 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_2
Changes since 1.3:	+2 -6 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.2	AnyEvent - provide framework for multiple event loops
4
5			Event, Coro, Glib, Tk - various supported event loops
6	root	1.1
7			=head1 SYNOPSIS
8
9	root	1.2	use AnyEvent;
10
11			my $w = AnyEvent->timer (fh => ..., poll => "[rw]+", cb => sub {
12			my ($poll_got) = @_;
13			...
14			});
15			my $w = AnyEvent->io (after => $seconds, cb => sub {
16			...
17			});
18
19			# watchers get canceled whenever $w is destroyed
20			# only one watcher per $fh and $poll type is allowed
21			# (i.e. on a socket you cna have one r + one w or one rw
22			# watcher, not any more.
23			# timers can only be used once
24
25			my $w = AnyEvent->condvar; # kind of main loop replacement
26			# can only be used once
27			$w->wait; # enters main loop till $condvar gets ->send
28			$w->broadcast; # wake up waiting and future wait's
29
30	root	1.1	=head1 DESCRIPTION
31
32	root	1.2	L<AnyEvent> provides an identical interface to multiple event loops. This
33			allows module authors to utilizy an event loop without forcing module
34			users to use the same event loop (as only a single event loop can coexist
35			peacefully at any one time).
36
37			The interface itself is vaguely similar but not identical to the Event
38			module.
39
40			On the first call of any method, the module tries to detect the currently
41			loaded event loop by probing wether any of the following modules is
42			loaded: L<Coro::Event>, L<Event>, L<Glib>, L<Tk>. The first one found is
43			used. If none is found, the module tries to load these modules in the
44			order given. The first one that could be successfully loaded will be
45			used. If still none could be found, it will issue an error.
46
47	root	1.1	=over 4
48
49			=cut
50
51			package AnyEvent;
52
53	root	1.2	no warnings;
54			use strict 'vars';
55	root	1.1	use Carp;
56
57	root	1.3	our $VERSION = 0.2;
58	root	1.2	our $MODEL;
59	root	1.1
60	root	1.2	our $AUTOLOAD;
61			our @ISA;
62	root	1.1
63			my @models = (
64			[Coro => Coro::Event::],
65			[Event => Event::],
66			[Glib => Glib::],
67			[Tk => Tk::],
68			);
69
70	root	1.3	our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY);
71
72	root	1.1	sub AUTOLOAD {
73			$AUTOLOAD =~ s/.*://;
74
75	root	1.3	$method{$AUTOLOAD}
76			or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
77
78	root	1.2	unless ($MODEL) {
79			# check for already loaded models
80			for (@models) {
81			my ($model, $package) = @$_;
82			if (scalar keys %{ *{"$package\::"} }) {
83	root	1.4	eval "require AnyEvent::Impl::$model";
84	root	1.2	last if $MODEL;
85			}
86	root	1.1	}
87
88	root	1.2	unless ($MODEL) {
89			# try to load a model
90
91			for (@models) {
92			my ($model, $package) = @$_;
93	root	1.4	eval "require AnyEvent::Impl::$model";
94	root	1.2	last if $MODEL;
95			}
96
97			$MODEL
98			or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";
99	root	1.1	}
100			}
101
102	root	1.2	@ISA = $MODEL;
103
104			my $class = shift;
105			$class->$AUTOLOAD (@_);
106	root	1.1	}
107
108	root	1.2	=back
109
110			=head1 EXAMPLE
111
112			The following program uses an io watcher to read data from stdin, a timer
113			to display a message once per second, and a condvar to exit the program
114			when the user enters quit:
115
116			use AnyEvent;
117
118			my $cv = AnyEvent->condvar;
119
120			my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
121			warn "io event <$_[0]>\n"; # will always output <r>
122			chomp (my $input = <STDIN>); # read a line
123			warn "read: $input\n"; # output what has been read
124			$cv->broadcast if $input =~ /^q/i; # quit program if /^q/i
125			});
126
127			my $time_watcher; # can only be used once
128
129			sub new_timer {
130			$timer = AnyEvent->timer (after => 1, cb => sub {
131			warn "timeout\n"; # print 'timeout' about every second
132			&new_timer; # and restart the time
133			});
134			}
135
136			new_timer; # create first timer
137
138			$cv->wait; # wait until user enters /^q/i
139
140			=head1 SEE ALSO
141
142			L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>,
143			L<AnyEvent::Impl::Coro>,
144			L<AnyEvent::Impl::Event>,
145			L<AnyEvent::Impl::Glib>,
146			L<AnyEvent::Impl::Tk>.
147
148			=head1
149
150			=cut
151
152			1
153	root	1.1