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

DESCRIPTION

This is the generic base class for all kinds of connections, both the readers and the writers. It is used to administer which file descriptors are in use in the mux.

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->muxInit( $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->muxRemove()

Remove the handler from the multiplexer.

$obj->muxTimeout()

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->muxExceptFlagged($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->muxReadFlagged($fileno)

Called when the read flag is set for this handler.

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

Writing

$obj->muxWriteFlagged($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 muxOutputbufferEmpty(), 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 1.00, built on November 11, 2015. 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-2015 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

cpanm IOMux

perl -MCPAN -e shell
install IOMux