Sloop::Base

DESCRIPTION

This is the top of the fundamental sloop class hierarchy, which includes Sloop::Server and Sloop::Client. It represents some basic properties of an I/O socket, but does not include any I/O functionality; that is provided by subclasses, usually via multiple inheritance from one of the Sloop::Socket classes. Sloop::Base implements a "dummy" method system whereby if a subclass does not override one of the dummy methods, calling it is a fatal error (since perl does not otherwise implement abstract methods). This same system is used further down the heirarchy as well.

SYNOPSIS

 use Sloop::Base;
 my $base = Sloop::Base->new(
        debug => (optional) a Sloop::Constant ":Debug" constants
        fd => (optional) integer file descriptor
        id => (optional) string used in logging
        logger => (REQUIRED) a Sloop::Logger object
 );

debug: Zero, or one or more of the 'Debug Constants' from Sloop::Constants added (or OR'd) together. The default is 0.
fd: The file descriptor for the socket represented. The default is -1.
id: A string identifier used in logging. The default is 'noid'.
logger: An object matching the specifications of Sloop::Logger.

ATTRIBUTES

All the fields from the constructor are subsequently accessible by the same name, with the same meaning.

An additional field which is used internally by sloop and is significant when subclassing is $base->{SHUT}. This is checked via the API with $base->okay() and should not be modified directly, so there is no need to make use of it outside of a subclassing context. It represents some of the coupling between the Sloop::Server class and objects derived from `Sloop::Connection` and `Sloop::Socket` (see comments about $connection->cancel in the docs for Sloop::Connection). Since this coupling is integral to how the Server object handles Connections, SHUT must always be accounted for properly.

METHODS

`$base->err_log($message)`

$message is a message to log. A trailing newline is unnecessary.

Prepended to the message on a separate line is:

 !$base->{id}! class::subroutine

Referring to the caller.

`$base->debug_log($message)`

$message is a message to log. A trailing newline is unnecessary.

Prepended to the message on a separate line is:

 {$base->{id}} class::subroutine

Referring to the caller -- unless, as per perldoc caller(), "there is no caller", i.e., this is a line in the main scipt outside any subroutine, in which case nothing is prepended.

`$base->req_log($message)`

$message is a message to log using Sloop::Logger::LOG_REQUEST. A trailing newline is unnecessary.

Prepended to the message is "[$base->{id}] ".

`$base->shut`

Abstract dummy; this should close the connection.

`$base->goodbye($msg, $notHere)`

$msg is a text message.

$notHere is optional. If defined, the calling subroutine will not be named.

Can be used to indicate fatal errors, as it calls croak(). The name of the calling subroutine is included in the output by default; this can be suppressed with '$notHere'.

If called as an OO method, a copy of the message, sans croak additions, is logged via $self->err_log.

`$base->okay`

As implemented here, will return a true value for core derived types such as Sloop::Client and Sloop::Other until they are shut() (which should happen when rendered, or found to be, defunct by the server). Otherwise returns undef.