view release on metacpan or  search on metacpan

lib/POE/Component/Server/TCP.pm  view on Meta::CPAN

common error parameters: $_[ARG0] describes what was happening at the
time of failure.  $_[ARG1] and $_[ARG2] contain the numeric and string
versions of $!, respectively.

C<ClientError> is optional.  If omitted, POE::Component::Server::TCP
will provide a default callback that logs most errors to STDERR.

If C<ClientShutdownOnError> is set, the connection will be shut down
after C<ClientError> returns.  If C<ClientDisconnected> is specified,
it will be called as the client session is cleaned up.

C<ClientError> is triggered by POE::Wheel::ReadWrite's ErrorEvent, so
it follows that event's form.  Please see the ErrorEvent documentation
in POE::Wheel::ReadWrite for more details.

  ClientError => sub {
    my ($syscall_name, $error_num, $error_str) = @_[ARG0..ARG2];
    # Handle the client error here.
  }

=head4 ClientFilter

C<ClientFilter> specifies the POE::Filter object or class that will
parse input from each client and serialize output before it's sent to
each client.

C<ClientFilter> may be a SCALAR, in which case it should name the
POE::Filter class to use.  Each new connection will be given a freshly
instantiated filter of that class.  No constructor parameters will be
passed.

  ClientFilter => "POE::Filter::Stream",

Some filters require constructor parameters.  These may be specified
by an ARRAYREF.  The first element is the POE::Filter class name, and
subsequent elements are passed to the class' constructor.

  ClientFilter => [ "POE::Filter::Line", Literal => "\n" ],

C<ClientFilter> may also be given an archetypical POE::Filter OBJECT.
In this case, each new client session will receive a clone() of the
given object.

  ClientFilter => POE::Filter::Line->new(Literal => "\n"),

C<ClientFilter> is optional.  The component will use
"POE::Filter::Line" if it is omitted.  There is L</ClientInputFilter>
and L</ClientOutputFilter> if you want to specify a different filter
for both directions.

Filter modules are not automatically loaded.  Be sure that the program
loads the class before using it.

=head4 ClientFlushed

C<ClientFlushed> exposes POE::Wheel::ReadWrite's C<FlushedEvent> as a
callback.  It is called whenever the client's output buffer has been
fully flushed to the client socket.  At this point it's safe to shut
down the socket without losing data.

C<ClientFlushed> is useful for streaming servers, where a "flushed"
event signals the need to send more data.

  ClientFlushed => sub {
    my $data_source = $_[HEAP]{file_handle};
    my $read_count = sysread($data_source, my $buffer = "", 65536);
    if ($read_count) {
      $_[HEAP]{client}->put($buffer);
    }
    else {
      $_[KERNEL]->yield("shutdown");
    }
  },

POE::Component::Server::TCP's default C<Acceptor> ensures that data is
flushed before finishing a client shutdown.

=head4 ClientInput

C<ClientInput> defines a per-connection callback to handle client
input.  This callback receives its parameters directly from
POE::Wheel::ReadWrite's C<InputEvent>.  ARG0 contains the input
record, the format of which is defined by C<ClientFilter> or
C<ClientInputFilter>.  ARG1 has the wheel's unique ID, and so on.
Please see POE:Wheel::ReadWrite for an in-depth description of
C<InputEvent>.

C<ClientInput> and C<Acceptor> are mutually exclusive.  Enabling one
prohibits the other.

  ClientInput => sub {
    my $input = $_[ARG0];
    $_[HEAP]{wheel}->put("You said: $input");
  },

=head4 ClientInputFilter

C<ClientInputFilter> is used with C<ClientOutputFilter> to specify
different protocols for input and output.  Both must be used together.
Both follow the same usage as L</ClientFilter>.  Overrides the filter set
by L</ClientFilter>.

  ClientInputFilter  => [ "POE::Filter::Line", Literal => "\n" ],
  ClientOutputFilter => 'POE::Filter::Stream',

=head4 ClientOutputFilter

C<ClientOutputFilter> is used with C<ClientInputFilter> to specify
different protocols for input and output.  Both must be used together.
Both follow the same usage as L</ClientFilter>.  Overrides the filter set
by L</ClientFilter>.

  ClientInputFilter  => POE::Filter::Line->new(Literal => "\n"),
  ClientOutputFilter => 'POE::Filter::Stream',

=head4 ClientShutdownOnError

C<ClientShutdownOnError> tells the component whether client
connections should be shut down automatically if an error is detected.
It defaults to "true".  Setting it to false (0, undef, "") turns off
this feature.