Proposed interface

First, I propose to use the POE::IKC2 namespace for this, rather then POE::Component::IKC2.

Initial setup

    use POE::IKC2;
    POE::IKC2->spawn({
        Name=>[qw(list of aliases)],
        Listen=>['/path/to/unix/socket',
                 'localhost:1234',
                 {Host=>'someting.com',  Port=>1234},
                 1234        # a port
                ],
        Connect=>[                 # autodiscover kernel names
            '/path/to/mutter/bump',
            'somewhere.org',            # assumes port 903
            'appserv.localdomain:1234',
            {Host=>'name', Port=>1234} 
        ],
        Kernels=>{
            Name1=>{Host=>'HONKEROONIE.nu'},
            Zitzit=>'somewhere.org:4321'
        },
        AutoGank=>1,              # grab all remote interfaces
    });

Knowing a kernel's name before hand allows us to deffer connection until the a messages is actually posted to that kernel.

Deal with connections later

    POE::IKC2->connect({Host=>'name'});


    POE::IKC2->disconnect('Kernel-name');
    # all connection to this host
    POE::IKC2->disconnect({'somewhere.org'});    


    POE::IKC2->kernel_remove('name');      # kill that kernel
    POE::IKC2->kernel_add(name=>{how to reach it}); 
    POE::IKC2->kernel_modify(name=>{how to reach it});

or 

    $poe_kernel->post(IKC2 => connect => {Host=>'name'});
    $poe_kernel->post(IKC2 => disconnect => 'Kernel-name');
    $poe_kernel->post(IKC2 => kernel_remove => 'name');
    $poe_kernel->post(IKC2 => kernel_add => 
                  {name=>{how to reach it}});
    $poe_kernel->post(IKC2 => kernel_modify => 
                  {name=>{how to reach it}});

Kernel_add and Kernel_modify differ as follows:

Kernel_add disconnects from a remote kernel and reconnects using the new information if it differs. Kernel_modify keeps the current connection, but if it gets disconnected, reconnects with the new information.

Expose/Gank

    POE::IKC2->expose({
        session=>[qw(list of aliases we want remote kernels to                                  
                      call us)],
        name=>'unique name of this interface', 
        version=>1,
        events=>[qw(....)]
    });


    # or even
    my $iface=POE::IKC2::Interface->new(session=>[...],
                                        name=>'interface-name',
                                        version=>1,
                                        events=>[...]);
    POE::IKC2->expose($iface);

gank by name 

    POE::IKC2->gank({name=>'unique name'});

gank by interface contents 

    POE::IKC2->gank({session=>'name', events=>[qw(list)]});

Posting

    POE::IKC2->post({kernel=>'Kernel', session=>'Session', 
                     event=>'Event'}, @args);

If Kernel is "host:port", we could auto-vivify the connection. 

    $poe_kernel->post(RemoteSession => 'Event', @args);

This works most of the time; either RemoteSession has been ganked already or we can tell that RemoteSession belongs to remote kernel that we know about. This last means we are connected to that kernel, or it was specified with Kernels()

Postbacks

When we control caller code 

    my $event=POE::IKC2->postback('eventName');
    $poe_kernel->post(RemoteSession => 'event', Do=>'work', 
                      OnReady=>$event);

When we control destination code 

    $event=POE::IKC2->remoteback($event);

When we control neither 

    # args are hash or hashref
    POE::IKC2->marshall_postback('session', 'event', 
                      hash => [qw(....)]);
    # args are array or arrayref
    POE::IKC2->marshall_postback('session', 'event', 
                      array => [qw(....)]);
    # args are complicated
    POE::IKC2->marshall_postback('session', 'event', 
                      complex => sub());

Of course, getting 'session' right in the above code is dificult, seeing as there are many synonyms for remote sessions.