GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
POE::Component::ControlPort(3) User Contributed Perl Documentation POE::Component::ControlPort(3)

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

    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();

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 "POE::Component::DebugShell" version 1.018 or above is installed, a set of POE debug commands will be loaded.

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.

    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.

  • 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 @ARGV and use Getopt::Long and friends to parse the arguments.

  • 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.

    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 "create()" method in the "POE::Component::ControlPort" namespace is used to create and launch the control port. There are several parameters available to "create()".

  • local_address

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

  • local_port

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

  • commands

    Optional (but boring if not provided). An array of command hashes. See "DEFINING COMMANDS" above.

  • hostname

    Optional. Mostly for display in the control port itself. Will probably be used for other things in the future.

  • appname

    Optional. The name of this application, defaulting to "basename($0)". This is used by TCPwrappers to determine if the connecting user is allowed to connect. This is also used as the master alias for the control port session.

  • poe_debug

    Optional. Defaults to 0. If true, attempts to load commands from POE::Component::DebugShell if said module is available and of the appropriate version.

The control port responds to a "shutdown" event to the appname given during control port creation. This event will cause the immediate shutdown of all connections and the termination of the listener.

The following perl modules are required for this module to work properly.
  • Authen::Libwrap
  • Carp
  • File::Basename
  • POE
  • Params::Validate
  • Sys::Hostname

Matt Cashner (sungo@pobox.com)

$Rev: 266 $

$Date: 2004-05-09 22:59:17 -0400 (Sun, 09 May 2004) $

Copyright (c) 2004, Matt Cashner

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

2004-05-10 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.