NAME

IO::Multiplex - Object interface to multiplex-style server implementations.

SYNOPSIS

use IO::Multiplex;

DESCRIPTION

IO::Multiplex is an object interface to classic multiplex server designs.

Alarmed by the time I was wasting re-implementing a fairly straightforward multiplexing server design, I decided it was time I abstracted the problem into an object for re-use. If the term 'multiplexing' preplexes you, read select(2), or read a good book on socket communications, I'm pretty sure most of them cover the subject.

This implementation is based on an event model. Users (programmers) control server behaviour by assigning handlers to certain server events (client connected, disconnected, input from client, server timeout).

CONSTRUCTOR

IO::Multiplex->new( %options );

Server construction arguments are supplied in a hash format.

IO::Multiplex->new(arg1 => 'val1', arg2 => 'val2' ...)

ARGUMENTS

Arguments define how the server will communicate with it's clients.

'loop_timeout'

Users may sometime find it useful to schedule a handler to be re-executed periodicly within the server's main event loop every defined number of seconds. Setting this argument will define the time interval between executions of the 'timeout' event.

'proto'

Optional. Setting this argument will define the server's communication layer with it's clients. Common values are 'unix' and 'tcp'. Other values ('udp' ?) are passed on to the IO::Socket::INET object.

If left undefined, IO::Multiplex will determine the server's transport layer by looking at some of the other arguments.

example: ('proto' => 'tcp', ...)

'localpath'

Passed on to the IO::Socket::UNIX object constructor, as the 'Local' options.

Warnings: we remove stale sockets by unlinking 'localpath' for you, any other file that happens to be there is removed with no warning.

Sockets are created with full world read-write permissions. This means any local user with execute permissions on the target directory can talk to the server.

Restrictions: Please realize you do need ordinary file write permissions to create a socket in a directory of choice.

'localaddr'

Optional. Passed on to the IO::Socket::INET object constructor, as the 'LocalAddr' option.

Setting this argument will define the server's local bind address, which is necessary in the case of multiple local network interfaces (routers, firewalls, proxies).

If left undefined, IO::Socket::INET will assume 'localhost'.

example: ('localaddr' => 'localhost', ...)

'localport'

Passed on to the IO::socket::INET object constructor. Setting this argument will define the server's local bind port.

Restrictions: If your running unix, binding to port numbers below 1024 is only allowed by root.

example: ('localport' => 6666, ...)

METHODS

set_handler($event, \&handler)

Set a handler for an event. See EVENTS further in this manual.

start()

Start main (infinite) event loop. Don't expect the program to return over execution after starting the start method.

Snippet:

$server->start() # NOT REACHED

disconnect($client_filehandle)

Disconnect a client_filehandle, envoking the $client_filehandle->close method and calling the 'client_disconnected' method. It is very important for users to understand that the server will never call this method on it's own.

When users decide a client should go, this is the only proper way to disconnect it (removing it from the server's internal 'select' object).

EVENTS

A brief reference discription of the server's events. With 'loop_timeout' being the exception, all events will be called with one argument:

($client_filehandle).

Event handlers should *never* block, or the server will (obviously, since we're under a single process model) deadlock for the duration of the execution misbehaving handler.

'loop_timeout' ()

Define a handler for 'loop_timeout'. A time-based event called in repeated intervals of every 'loop_timeout' seconds. Useful when a server needs to wake up in an inconditional interval and get something done.

Don't forget to assign supply a value for the 'loop_timeout' argument in the server's constructor method.

'client_input' ($client_filehandle)

The select object decided a client has something to say, and handler should read from $client_filehandle and handle input.

Note if input is null, client has most likely disconnected and $server->disconnect should be invoked.

'client_connected' ($client_filehandle)

Called when a new client connects, handler should handle the joyfull event, (print a banner, log connection).

RETURN VALUE: Return true if we keep the connection, false to drop it.

'client_disconnected' ($client_filehandle)

Called (by the IO::Multiplex::disconnect method) when a client disconnects.

AUTHOR

Liraz Siri <liraz_siri@usa.net>, Ariel, Israel.

COPYRIGHT

Copyright 1999 (c) Liraz Siri <liraz_siri@usa.net>, Ariel, Israel, All rights reserved.