NAME

POE::Class::Client::UNIX - Base class to create POE based UNIX clients

SYNOPSIS

#!/usr/bin/perl

use strict;

# A strange echo client for UNIX sockets
package My::EchoClient::Conn;

use POE qw(
    Wheel::ReadWrite
    Wheel::ReadLine
    Class::Conn::UNIXStream
);

@My::EchoClient::Conn::ISA = qw(POE::Class::Conn::UNIXStream);

sub handler_start {
    my ($self, $kernel) = @_[OBJECT, KERNEL];
    $self->SUPER::handler_start(@_[1 .. $#_]);

    $self->{rl} = POE::Wheel::ReadLine->new(InputEvent => 'input');
    $self->{rl}->get('> ');
    $SIG{__WARN__} = sub { $self->{rl}->put("@_") };
}

sub disconnect {
    my ($self) = @_;
    $self->SUPER::disconnect;
    delete $self->{rl};
}

sub create_states {
    my ($self) = @_;
    $self->SUPER::create_states;
    $poe_kernel->state(input => $self, 'handler_input');
}

sub handler_input {
    my ($self, $kernel, $input, $exception) = @_[OBJECT, KERNEL, ARG0, ARG1];
    return if $self->get_shutdown;
    if ($input eq 'close' or $input eq 'quit') {
        $self->yield('shutdown');
        return;
    }
    if (defined $input) {
        $self->{rl}->addhistory($input);
        $kernel->yield(put => $input);
        $self->{rl}->get('> ');
    }
    else {
        $self->{rl}->put($exception);
    }
}

sub handler_input {
    my ($self, $input) = @_[OBJECT, ARG0];
    return if $self->get_shutdown;
    $self->{rl}->put("< $input");
    $self->{rl}->get('> ');
}

package main;

use POE qw(Class::Client::UNIX);

my $path = shift;
die "Usage: $0 path\n" unless defined $path;

my $client = POE::Class::Client::UNIX->new(
    path       => $path,
    conn_class => 'My::EchoClient::Conn',
);

$client->start;

$poe_kernel->run;

DESCRIPTION

POE::Class::Client::UNIX is a base class for creating POE based UNIX clients. This class uses POE::Class as a base for Object/Session glue. Each connection spawns a new sonnection session. See POE::Class::Conn for details on the connection class.

HANDLERS

_start => handler_start

Error checking on path(). Calles the method connect() which performs the actual connection.

connection => handler_connection

Fired from POE::Wheel::SocketFactory when a connection is established. Creates a new connection object of get_conn_class() type and calles the method start() on it. Sets connected() to one.

error => handler_error

This event happens when POE::Wheel::SocketFactory encounters an error. It warn()s the error and call()s shutdown.

timeout => handler_timeout

Client::UNIX set's an alarm in connect() to call this handler. When the connection happens the alarm is reset. This event signifies the connection has timed out. The method disconnect() is called here.

shutdown => handler_shutdown

You shuold yield this event when you want the connection shutdown. It posts the shutdown event to it's children and then calles the method disconnect().

ACCESSORS

All accessors have three methods ala POE::Class::Attribs. set_ATTRIB, get_ATTRIB and ATTRIB. Set and get are obvious. ATTRIB is simply a set/get method. See POE::Class::Attribs for more details.

alarm_id

Used interally to store the current alarm ID for timeout.

timeout

Sets the timeout in seconds before a connection is established.

connected

Whether Client::UNIX has established a connection or not.

path

Path to the socket Client::UNIX is connecting to.

wheel

Stores the POE::Wheel::SocketFactory object.

conn_class

Sets the connection class to use when a connection comes in. The new() contructor method is called on this class with the following arguments:

socket         => socket that just connected
path           => path to the socket file as set by C<path()>

The start() method is then called on the returned object. This class defaults to POE::Class::Conn::UNIXStream, which is NOT what you want. You should set it to your subclass of that class or POE::Class::Conn::UNIXStream will just croak with an error about virtual methods not defined in the subclass.

METHODS

new

Constructor, sets up internal data.

DESTROY

Destructor, frees internal data.

connect

Creates a new POE::Wheel::SocketFactory object with parameters specified by accessors and begines an alarm for this connect by calling the method timeout_alarm(1).

disconnect

Removes the connection alarm by calling timeout_alarm(0). Sets the flag connected() to zero. Sets the POE::Wheel::SocketFactory object to undef set_wheel(undef).

create_states

Creates the states talked about in "HANDLERS" section that are not set by the base class POE::Class.

timeout_alarm

Called to add or remove the connection alarm. First argument it s boolean. If true the alarm is removed and re-added with timeout() else the alarm is just removed.

TODO

Write better documentation.

AUTHOR

Scott Beck <sbeck@gossamer-threads.com>

SEE ALSO

POE POE::Class POE::Class::Conn POE::Class::Conn::Stream POE::Class::Conn::UNIXStream