NAME

Labrador::Dispatcher::Connections

SYNOPSIS

	Labrador::Dispatcher::Connections::run(2680, $event_handler);
	warn "Server has been shutdown\n";
	exit;

DESCRIPTION

This class performs the non-blocking network IO with each subcrawler. It passes on command events to the event handler object, whose job it is to pass the command on to the appropriate command handler. Other events are handled by the events handler, such as unexpected disconection of a client.

This class is a singleton - ie it cannot be instantiated as an object. The non-blocking network code is heavily based on Recipe 17.17 in the Perl Cookbook, with some alterations where I disagree with its handling of partial sends and EWOULDBLOCK. Further reference should be made to Richard W. Stevens book on Unix Network Progamming.

EVENTS

This class calls several methods of $event_handler to represent events occurring. The event handling methods are expected to exist in the provided $event_handler.. They are listed below:

NB: Event handling code is not permitted to write to $client at any time.

event_connect($client): Fired when a network connection is accepted. $client contains the socket.
event_disconnect($client): Fired when a network connection is dropped unexpectedly. This module assumes it is it's own responsibilty to disconnect clients when they ask. Clients disconnecting of their own accord is an error condition. $client contains the socket.
event_command($invocation): Fired when an entire command sequence is received on a network connection. $invocation is a reference to a hash. This hash contains details of the invocation - view the code of _handle for more infomation.

FUNCTIONS

run($port, $event_handler): Starts up all the network gubbins. Does not return unless a shutdown is signalled by calling shutdown().
shutdown(): Close all sockets, causes a return from run()
disconnect_client($client): $client will be disconnected a the end of the current iteration of the mail while(1) loop. By delaying the disconnection until the end of the iteration, this means the final message reply to the client can be written.
ip($client): Returns the IP address of $client
idle_alarm($every, $name, $coderef): Run this $coderef every $every seconds, called $name.
get_stats(): Returns an array of network level stats
log_to_file($filename): Enables connection logging to $filename.
log_off(): Disabled connection logging.

PRIVATE METHODS

NB: Should not be called by client code, but documented here for completeness.

_disconnect($client): Handle the disconnection of $client. Called by disconnect_client() (indirectly), and also when an error occurs when reading or writing to a socket, and the connection should be dropped. Handles removal of all lowlevel mapping - ie per-client buffers.
_handle($client): Deals with all pending requests from $client, by taking exactly one command from the start of the client's ready buffer, processing the request (by calling forward to the Event handler), and the supplying the returned data to the client by appending it to the client's outbuffer.
_nonblock($socket): Puts the given $socket into non-blocking mode.
_log($state, $client, $data)

REVISION

	$Revision: 1.18 $