Mark Overmeer > IOMux-0.12 > IOMux::Handler



Annotate this POD

View/Report Bugs
Module Version: 0.12   Source   Latest Release: IOMux-0.13


IOMux::Handler - handle a connection


 IOMux::Handler is extended by


 # only extensions can be instantiated



  fh      <required>
  name    <stringified handle>
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.



Returns the filehandle.


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


User interface



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.


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.


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

  use Time::HiRes 'time';
  BEGIN {$begin = time}



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.


Remove the handler from the multiplexer.


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.



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.


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.



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.




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.


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


  print $conn->show;


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

Please post questions or ideas to


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

syntax highlighting: