POE::Component::IKC::Client - POE Inter-Kernel Communication client

    use POE;
    use POE::Component::IKC::Client;
    POE::Component::IKC::Client->spawn(
        ip=>$ip, 
        port=>$port,
        name=>"Client$$",
        on_connect=>\&create_sessions,
        subscribe=>[qw(poe:/*/timserver)],);
    ...
    $poe_kernel->run();

package POE::Component::IKC::Client;

############################################################
# $Id: Client.pm 494 2009-05-08 18:36:12Z fil $
# Based on refserver.perl
# Contributed by Artur Bergman <artur@vogon-solutions.com>
# Revised for 0.06 by Rocco Caputo <troc@netrus.net>
# Turned into a module by Philp Gwyn <fil@pied.nu>
#
# Copyright 1999-2009 Philip Gwyn.  All rights reserved.
# This program is free software; you can redistribute it and/or modify
# it under the same terms as Perl itself.
#
# Contributed portions of IKC may be copyright by their respective
# contributors.  

use strict;
use Socket;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
use POE qw(Wheel::ListenAccept Wheel::SocketFactory);
use POE::Component::IKC::Channel;
use Carp;

require Exporter;
@ISA = qw(Exporter);
@EXPORT = qw(create_ikc_client);
$VERSION = '0.2200';

sub DEBUG { 0 }


###############################################################################
#----------------------------------------------------
# This is just a convenient way to create servers.  To be useful in
# multi-server situations, it probably should accept a bind address
# and port.
sub create_ikc_client
{
    my(%parms)=@_;
    $parms{package}||=__PACKAGE__;
    $parms{on_connect}||=sub{};         # would be silly for this to be blank
                                        # 2001/04 not any more
    if($parms{unix}) {
    } else {
        $parms{ip}||='localhost';           
        $parms{port}||=903;                 # POE! (almost :)
    }
    $parms{name}||="Client$$";
    $parms{subscribe}||=[];
    my $defaults;
    if($parms{serializers}) {               # use ones provided
                                            # make sure it's an arrayref
        $parms{serializers}=[$parms{serializers}] 
                                    unless ref $parms{serializers};
    } 
    else {                                  # use default ones
        $defaults=1;                        # but don't gripe
        $parms{serializers}=[qw(Storable FreezeThaw
                                POE::Component::IKC::Freezer)];
    }

    # make sure the serializers are real 
    my @keep;
    foreach my $p (@{$parms{serializers}}) {
        unless(_package_exists($p)) {
            my $q=$p;
            $q=~s(::)(/)g;
            DEBUG and warn "Trying to load $p ($q)\n";
            eval {require "$q.pm"; import $p ();};
            warn $@ if not $defaults and $@;
        }
        next unless _package_exists($p);
        push @keep, $p;
        DEBUG and warn "Using $p as a serializer\n";
    }
    $parms{serializers}=\@keep;

    return POE::Session->create( 
            package_states => [ $parms{package} =>
                                [qw(_start _stop _child error shutdown connected)]],
            args => [\%parms]
        )->ID;
}

sub spawn
{
    my($package, %params)=@_;
    $params{package}=$package;
    return create_ikc_client(%params);
}

sub _package_exists
{
    my($package)=@_;
    my $symtable=$::{"main::"};
    foreach my $p (split /::/, $package) {
        return unless exists $symtable->{"$p\::"};
        $symtable=$symtable->{"$p\::"};
    }
    return 1;
}

#----------------------------------------------------
# Accept POE's standard _start event, and set up the listening socket
# factory.

sub _start {
    my($kernel, $heap, $parms) = @_[KERNEL, HEAP, ARG0];

    DEBUG and warn "Client starting.\n";
    my %wheel_p=(
        SuccessEvent   => 'connected',    # generating this event on connection
        FailureEvent   => 'error'         # generating this event on error
    );
                                        # create a socket factory
    if($parms->{unix}) {
        $wheel_p{SocketDomain}=AF_UNIX;
        $wheel_p{RemoteAddress}=$parms->{unix};
#        $heap->{remote_name}="unix:$parms->{unix}";
#        $heap->{remote_name}=~s/[^-:.\w]+/_/g;
        $heap->{unix}=$parms->{unix};
    } else {
        $wheel_p{RemotePort}=$parms->{port};
        $wheel_p{RemoteAddress}=$parms->{ip};

        $heap->{remote_name}="$parms->{ip}:$parms->{port}";
    }
    $heap->{wheel} = new POE::Wheel::SocketFactory(%wheel_p);
    $heap->{on_connect}=$parms->{on_connect};
    $heap->{on_error}=$parms->{on_error};
    $heap->{name}=$parms->{name};
    $heap->{alias} = "IKC Client $heap->{name}";
    $kernel->alias_set( $heap->{alias} );
    $heap->{subscribe}=$parms->{subscribe};
    $heap->{aliases}=$parms->{aliases};
    $heap->{serializers}=$parms->{serializers};

    # set up local names for kernel
    my @names=($heap->{name});
    if(exists $heap->{aliases}) {
        if(ref $heap->{aliases}) {
            push @names, @{$heap->{aliases}};
        } else {
            push @names, $heap->{aliases};
        }
    }
    $kernel->post(IKC=>'register_local', \@names);
}

#----------------------------------------------------
# Log server errors, but don't stop listening for connections.  If the
# error occurs while initializing the factory's listening socket, it
# will exit anyway.

sub error 
{
    my ($heap, $operation, $errnum, $errstr) = @_[HEAP, ARG0, ARG1, ARG2];
    DEBUG and warn "Client encountered $operation error $errnum: $errstr\n";
    my $w=delete $heap->{wheel};
    # WORK AROUND
    # $w->DESTROY;
    if($heap->{on_error}) {
        $heap->{on_error}->($operation, $errnum, $errstr);
    }
}

#----------------------------------------------------
# The socket factory invokes this state to take care of accepted
# connections.

sub connected
{
    my ($heap, $handle, $addr, $port) = @_[HEAP, ARG0, ARG1, ARG2];
    DEBUG and warn "Client connected\n"; 


                        # give the connection to a Channel
    $heap->{channel} = create_ikc_channel($handle, 
                        @{$heap}{qw(name on_connect subscribe
                                    remote_name unix aliases serializers)});
    delete @{$heap}{qw(name on_connect subscribe remote_name wheel aliases
                        serializers)};
    
}

sub shutdown
{
    my ($heap, $kernel) = @_[HEAP, KERNEL];
    DEBUG and 
        warn "$heap Client shutdown";
    if( $heap->{channel} ) {
        $kernel->call( delete $heap->{channel} => 'shutdown' );
    }
    if( $heap->{alias} ) {
        $kernel->alias_remove( delete $heap->{alias} );
    }
}

sub _stop
{
    DEBUG and warn "$_[HEAP] client _stop\n";
}

sub _child
{
    my( $heap, $reason, $child ) = @_[ HEAP, ARG0, ARG1 ];
    $child = $child->ID;
    DEBUG and warn "$heap $reason #$child";
    return unless defined $heap->{channel};
    if( $child eq $heap->{channel} and $reason eq 'lose' ) {
        delete $heap->{channel};
        $poe_kernel->yield( 'shutdown' );
    }
}

1;
__END__
# Below is the stub of documentation for your module. You better edit it!