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"
               or die;

            last if $MODEL;
         }
      }

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

         for (@models) {
            my ($model, $package) = @$_;
            eval "require AnyEvent::Impl::$model"
               or die;

            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.3
Committed:	Thu Dec 1 21:19:58 2005 UTC (18 years, 7 months ago) by root
Branch:	MAIN
Changes since 1.2:	+6 -1 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			eval "require AnyEvent::Impl::$model"
84			or die;
85
86			last if $MODEL;
87			}
88	root	1.1	}
89
90	root	1.2	unless ($MODEL) {
91			# try to load a model
92
93			for (@models) {
94			my ($model, $package) = @$_;
95			eval "require AnyEvent::Impl::$model"
96			or die;
97
98			last if $MODEL;
99			}
100
101			$MODEL
102			or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";
103	root	1.1	}
104			}
105
106	root	1.2	@ISA = $MODEL;
107
108			my $class = shift;
109			$class->$AUTOLOAD (@_);
110	root	1.1	}
111
112	root	1.2	=back
113
114			=head1 EXAMPLE
115
116			The following program uses an io watcher to read data from stdin, a timer
117			to display a message once per second, and a condvar to exit the program
118			when the user enters quit:
119
120			use AnyEvent;
121
122			my $cv = AnyEvent->condvar;
123
124			my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
125			warn "io event <$_[0]>\n"; # will always output <r>
126			chomp (my $input = <STDIN>); # read a line
127			warn "read: $input\n"; # output what has been read
128			$cv->broadcast if $input =~ /^q/i; # quit program if /^q/i
129			});
130
131			my $time_watcher; # can only be used once
132
133			sub new_timer {
134			$timer = AnyEvent->timer (after => 1, cb => sub {
135			warn "timeout\n"; # print 'timeout' about every second
136			&new_timer; # and restart the time
137			});
138			}
139
140			new_timer; # create first timer
141
142			$cv->wait; # wait until user enters /^q/i
143
144			=head1 SEE ALSO
145
146			L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>,
147			L<AnyEvent::Impl::Coro>,
148			L<AnyEvent::Impl::Event>,
149			L<AnyEvent::Impl::Glib>,
150			L<AnyEvent::Impl::Tk>.
151
152			=head1
153
154			=cut
155
156			1
157	root	1.1