Sloop::Connection

DESCRIPTION

Sloop::Base derived class representing a connection to the server; all socket descriptors except for the server listen socket are encapsulated by something descended from Sloop::Connection. It adds input/output routines to Sloop::Base although the low level details are in the Sloop::Socket classes (in other words, Sloop::Connection is still abstract, no pure Sloop::Connection objects are instantiated).

SYNOPSIS

 my $connection = Sloop::Connection->new (
     debug => (optional) see Sloop::Base
     fault_max => (optional) integer
     fd => (optional) see Sloop::Base
     id => (optional) see Sloop::Base
     logger => (REQUIRED) see Sloop::Base
     max_recv => (optional) integer
     max_send => (optional) integer
     onCancelHandlers => (optional) Array of subroutine references
     timeout => (REQUIRED) integer
 );

Fields not documented in Sloop::Base are described below.

fault_max

If $connection->{errcount} exceeds this value, the connection will be terminated with cancel(). 'Errcount' is a count of low level read()/write() and other errors that are consecutive (i.e., it is cleared when such an I/O call succeeds). The default is 3. This almost never comes into play; don't increase it.

max_recv

Maximum number of bytes to try reading at once, the default is 262144. This doesn't limit the total size of a request, just how much of it is read in at once. This is to help prevent fast connections involving a lot of data from choking off everything else. You probably should not set this lower than the size of the system socket receive buffer, see 'man 7 socket'.

max_send

Maximum number of bytes to try sending at once, the default is 1048576. This doesn't limit the total size of a response, see max_recv above.

onCancelHandlers

If set, these will be called in order on the first call to $connection-cancel>, with the $connection object passed in (but do not use it to send data, it will be defunct).

This attribute may be set (including undef) any time post construction as well.

timeout

Duration in seconds after which an idle $connection will be closed. "Idle" here means there is no pending request or response. This value is set by the Sloop::Server object, see 'timeout' in the SYNOPSIS there. Connections with a timeout of 0 never time out.

ATTRIBUTES

In addition to the attributes listed for Sloop::Base, the following fields from the constructor are accessible by the same name, with the same meaning:

fault_max
max_recv
max_send
timeout

The following attibutes may be accessed/set only after the constructor call:

$connection->{buffer_data}

This is a subroutine reference that can used if you want to send a reply that is longer than the actual data passed to Sloop::Client::reply() -- in which case, you should be sure to pass a 'length' argument to that method that matches the total amount that will be sent, because it is still all part of the same HTTP response even if the data in the body is delivered in chunks. If you cannot provide an exact length of the total data, don't do this.

Sloop::Static::directory() uses this to avoid loading large files into memory all at once. The subroutine will be called when the previous data has been sent, and should return a reference to a scalar containing additional data. As long as this field is defined, it will continue to be called for the same reply, so when the data is complete, the subroutine should leave $connection->{buffer_data} undefined. It receives one argument, the Sloop::Connection derived object to which it is attached.

$connection->{readerr}

Stores an error code from the last failed sysread().

$connection->{readErrStr}

String representation of the last sysread() error.

METHODS

`$connection->cancel`

Calls $connection->shut(), which must be implemented by subclasses (in the sloop core this is actually done polymorphically via the Sloop::Socket implementations; see also comments about $base->{SHUT} in Sloop::Base).

Derived classes which override this and do not call it should possibly deal with $connection->{onCancelHandlers}.