# $Id: Loop.pm,v 1.1 2005/04/10 21:07:12 joern Exp $

#-----------------------------------------------------------------------
# Copyright (C) 2002-2005 Jörn Reder <joern AT zyn.de>.
# All Rights Reserved. See file COPYRIGHT for details.
# 
# This module is part of Event::RPC, which is free software; you can
# redistribute it and/or modify it under the same terms as Perl itself.
#-----------------------------------------------------------------------

package Event::RPC::Loop;

sub new {
	my $class = shift;
	return bless {}, $class;
}

1;

__END__

=head1 NAME

Event::RPC::Loop - Mainloop Abstraction layer for Event::RPC

=head1 SYNOPSIS

  use Event::RPC::Server;
  use Event::RPC::Loop::Glib;
  
  my $server = Event::RPC::Server->new (
      ...
      loop => Event::RPC::Loop::Glib->new(),
      ...
  );

  $server->start;

=head1 DESCRIPTION

This modules defines the interface of Event::RPC's mainloop
abstraction layer. It's a virtual class all mainloop modules
should inherit from.

=head1 INTERFACE

The following methods need to be implemented:

=over 4

=item $loop->B<enter> ()

Enter resp. start a mainloop.

=item $loop->B<leave> ()

Leave the mainloop, which was started with the enter() method.

=item $watcher = $loop->B<add_io_watcher> ( %options )

Add an I/O watcher. Options are passed as a hash of
key/value pairs. The following options are known:

=over 4

=item B<fh>

The filehandle to be watched.

=item B<cb>

This callback is called, without any parameters, if
an event occured on the filehandle above.

=item B<desc>

A description of the watcher. Not necessarily implemented
by all modules, so it may be ignored.

=item B<poll>

Either 'r', if your program reads from the filehandle, or 'w'
if it writes to it.

=back

A watcher object is returned. What this exactly is depends
on the implementation, so you can't do anything useful with
it besides passing it back to del_io_watcher().

=item $loop->B<del_io_watcher> ( $watcher )

Deletes an I/O watcher which was added with $loop->add_io_watcher().

=item $timer = $loop->B<add_timer> ( %options )

This sets a timer, a subroutine called after a specific
timeout or on a regularly basis with a fixed time interval.

Options are passed as a hash of
key/value pairs. The following options are known:

=over 4

=item B<interval>

A time interval in seconds, may be fractional.

=item B<after>

Callback is called once after this amount of seconds,
may be fractional.

=item B<cb>

The callback.

=item B<desc>

A description of the timer. Not necessarily implemented
by all modules, so it may be ignored.

=back

A timer object is returned. What this exactly is depends
on the implementation, so you can't do anything useful with
it besides passing it back to del_io_timer().

=item $loop->B<del_timer> ( $timer )

Deletes a timer which was added with $loop->add_timer().

=back

=head1 DIRECT USAGE IN YOUR SERVER

You may use the methods of Event::RPC::Loop by yourself
if you like. This way your program keeps independent of
the actual mainloop module in use, if the simplified
interface of Event::RPC::Loop is sufficient for you.

In your server program you access the actual mainloop 
object this way:

  my $loop = Event::RPC::Server->instance->get_loop;

Naturally nothing speaks against making your program
to work only with a specific mainloop implementation,
if you need its features. In that case you may use
the corresponding API directly (e.g. of Event or Glib),
no need to access it through Event::RPC::Loop.

=head1 AUTHORS

  Jörn Reder <joern at zyn dot de>

=head1 COPYRIGHT AND LICENSE

Copyright 2002-2005 by Jörn Reder.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Library General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
USA.

=cut