view release on metacpan or  search on metacpan

lib/POE/Component/ControlPort.pm  view on Meta::CPAN

# $Id: ControlPort.pm 266 2004-05-10 02:59:17Z sungo $
package POE::Component::ControlPort;

=pod

=head1 NAME

POE::Component::ControlPort - network control port for POE applications

=head1 SYNOPSIS

    use POE;
    use Getopt::Long;
    
    use POE::Component::ControlPort;
    use POE::Component::ControlPort::Command;

    my @commands = (
       {
           help_text    => 'My command',
           usage        => 'my_command [ arg1, arg2 ]',
           topic        => 'custom',
           name         => 'my_command',
           command      => sub {
              my %input = @_;
              
              local @ARGV = @{ $input{args} };
              GetOptions( ... ); 
           },
       } 
    );


    POE::Component::ControlPort->create(
        local_address   => '127.0.0.1',
        local_port      => '31337',
    
    # optional...
        hostname        => 'pie.pants.org',
        appname         => 'my perl app',

        commands        => \@commands,

        poe_debug       => 1,
    );

    # other poe sessions or whatever ...

    POE::Kernel->run();
    

=head1 DESCRIPTION

When building network applications, it is often helpful to have a
network accessible control and diagnostic interface. This module
provides such an interface for POE applications. By default, it provides
a fairly limited set of commands but is easily extended to provide
whatever command set you require. In addition, if
C<POE::Component::DebugShell> version 1.018 or above is installed, a set
of POE debug commands will be loaded.

=head1 GETTING STARTED

The utility of a network accessible controlport is limited only by the commands
you allow access to. A controlport with only a status command isn't very useful.
Defining commands is easy.

=head2 DEFINING COMMANDS

    my @commands = (
       {
           help_text    => 'My command',
           usage        => 'my_command [ arg1, arg2 ]',
           topic        => 'custom',
           name         => 'my_command',
           command      => sub {
              my %input = @_;
              
              local @ARGV = @{ $input{args} };
              GetOptions( ... ); 
           },
       } 
    );


A command is defined by a hash of metadata and a subroutine reference. The
metadata helps to group commands into functional units as well as display help
and usage information for the confused user.  The meat of a command, obviously,
is the subroutine reference which makes up the 'command' part of the metadata.

The subroutine reference is executed every time a user issues the command name
that is assigned for it.  Any text returned from the subroutine will be printed
out to the user in the control port. The subroutine's arguments are a hash of 
data about the command invocation.

=over 4

=item * args

This hash element is a list of arguments the user passed in to the command. It
is suggested that you assign this list to C< @ARGV > and use L<Getopt::Long> and
friends to parse the arguments.

=item * oob

This hash element contains a hash of out of band data about the transaction. It
is populated with hostname, appname, client_addr, and client_port.

=back

=head2 LAUNCHING THE PORT 

    POE::Component::ControlPort->create(
        local_address => '127.0.0.1',
        local_port => '31337',
    
    # optional...
        hostname => 'pie.pants.org',
        appname => 'my perl app',

        commands => \@commands,

        poe_debug => 1,
    )

The C<create()> method in the C<POE::Component::ControlPort> namespace is used
to create and launch the control port.  There are several parameters available
to C<create()>.

=over 4

=item * local_address

Mandatory. The address on which the control port should listen.

=item * local_port

Mandatory. The port on which the control port should listen.