Mark Overmeer > IOMux > IOMux::Handler

Download:
IOMux-0.12.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.12   Source  

NAME ^

IOMux::Handler - handle a connection

INHERITANCE ^

 IOMux::Handler is extended by
   IOMux::Handler::Read
   IOMux::Handler::Service
   IOMux::Handler::Write

SYNOPSIS ^

 # only extensions can be instantiated

METHODS ^

Constructors

IOMux::Handler->new(OPTIONS)
 -Option--Default
  fh      <required>
  name    <stringified handle>
fh => FILEHANDLE
name => STRING

Nice name, most useful in error messages.

IOMux::Handler->open(MODE, WHAT, OPTIONS)

Most handlers provide an easy way to instantiate them via the IOMux::Open module.

Accessors

$obj->fh

Returns the filehandle.

$obj->fileno

The sequence number of the filehandle, UNIX style. See man 3 fileno

$obj->mux
$obj->name
$obj->usesSSL

User interface

Connection

$obj->close([CALLBACK])

Close the handler. When the CALLBACK is provided, it will be called after the filehandle has been closed and the object disconnected from the multiplexer.

$obj->timeout([TIMEOUT])

Set (or get) the timer. The TIMEOUT value is a certain number of seconds in the future, after which the mux_timeout callback is called. When TIMEOUT is not defined or zero, the timer is cancelled. Timers are not reset automatically.

When the timeout value is very large (larger then time when the program started), it is considered absolute, not relative. This is very useful when you wish a timeout to appear on some exact moment.

When the timeout is very small (but larger than 0), then still at least one select loop will be used for this timeout is handled.

example:

  $conn->timeout(23.6);   # over 23 seconds
  print $conn->timeout;   # moment in epoc
  $conn->timeout(0);      # cancel

  use Time::HiRes 'time';
  BEGIN {$begin = time}
  $conn->timeout($begin+2.5);

Multiplexer

Connection

The user interface provides a higher level interaction then the raw interface. These methods may be extended by users, but there are usually simpler methods to achieve that.

$obj->mux_init(MUX, [HANDLER])

Called after the multiplexer has added this handler to its administration.

In rare cases, it may happen that an other HANDLER needs to be called when this filehandle get tickled, especially for tricks with bundles.

$obj->mux_remove

Remove the handler from the multiplexer.

$obj->mux_timeout

Called when a timer expires on the FILEHANDLE.

Use timeout() to set (or clear) a timeout. When new data is sent or received on the FILEHANDLE, that will not expire the timeout.

Reading

$obj->mux_except_flagged(FILENO)

Called (in the rare case) that an exception event if flagged. This means that the socket needs urgent inspection.

According to the Linux manual page for select(), these exceptions only happen when out-of-band (OOB) data arrives over udp or tcp.

$obj->mux_read_flagged(FILENO)

Called when the read flag is set for this handler.

When you extend this module, you probably want to override mux_connection() or mux_input(), not this "raw" method.

Writing

$obj->mux_write_flagged(FILENO)

Called when the write flag is set for this handler; this indicates that the output buffer is empty hence more data can be sent.

When you extend this module, you probably want to override mux_outputbuffer_empty(), not this "raw" method.

Service

Helpers

$obj->extractSocket(HASH)
IOMux::Handler->extractSocket(HASH)

Extract IO::Socket::INET (or ::SSL) parameters from the HASH and construct a socket from it. The used options are all starting with a capital and removed from the HASH. Additionally, some controlling options are used.

 -Option --Default
  socket   <created>
  use_ssl  <false>
socket => IO::Socket object

You may pre-initialize an IO::Socket.

use_ssl => BOOLEAN

When true, a IO::Socket::SSL object will be created, otherwise a IO::Socket::INET object.

$obj->fdset(STATE, READ, WRITE, ERROR)

Change the flags for the READ, WRITE and/or ERROR acceptance by the mux to STATE.

$obj->show

Returns a textblock with some info about the filehandle, for debugging purposes.

example:

  print $conn->show;

SEE ALSO ^

This module is part of IOMux distribution version 0.12, built on January 27, 2011. Website: http://perl.overmeer.net/ All modules in this suite: "Any::Daemon", "IOMux", and "IOMux::HTTP".

Please post questions or ideas to perl@overmeer.net

LICENSE ^

Copyrights 2011 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html

syntax highlighting: