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.1;
our $MODEL;

our $AUTOLOAD;
our @ISA;

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

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

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