/ 
IO-Mux-0.11
River stage zero No dependents
/ IO::Mux::Handler

NAME

IO::Mux::Handler - handle a connection

INHERITANCE

IO::Mux::Handler is extended by
  IO::Mux::Handler::Read
  IO::Mux::Handler::Service
  IO::Mux::Handler::Write

SYNOPSIS

# only extensions can be instantiated

METHODS

Constructors

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

Nice name, most useful in error messages.

IO::Mux::Handler->open(MODE, WHAT, OPTIONS)

Most handlers provide an easy way to instantiate them via the IO::Mux::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)
IO::Mux::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 IO-Mux distribution version 0.11, built on January 26, 2011. Website: http://perl.overmeer.net/ All modules in this suite: "Any::Daemon", "IO::Mux", and "IO::Mux::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