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


Manual Reference Pages  -  POE::WHEEL::LISTENACCEPT (3)

.ds Aq ’

NAME

POE::Wheel::ListenAccept - accept connections from regular listening sockets

CONTENTS

SYNOPSIS

See SYNOPSIS in POE::Wheel::SocketFactory for a simpler version of this program.



  #!perl

  use warnings;
  use strict;

  use IO::Socket;
  use POE qw(Wheel::ListenAccept Wheel::ReadWrite);

  POE::Session->create(
    inline_states => {
      _start => sub {
        # Start the server.
        $_[HEAP]{server} = POE::Wheel::ListenAccept->new(
          Handle => IO::Socket::INET->new(
            LocalPort => 12345,
            Listen => 5,
          ),
          AcceptEvent => "on_client_accept",
          ErrorEvent => "on_server_error",
        );
      },
      on_client_accept => sub {
        # Begin interacting with the client.
        my $client_socket = $_[ARG0];
        my $io_wheel = POE::Wheel::ReadWrite->new(
          Handle => $client_socket,
          InputEvent => "on_client_input",
          ErrorEvent => "on_client_error",
        );
        $_[HEAP]{client}{ $io_wheel->ID() } = $io_wheel;
      },
      on_server_error => sub {
        # Shut down server.
        my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2];
        warn "Server $operation error $errnum: $errstr\n";
        delete $_[HEAP]{server};
      },
      on_client_input => sub {
        # Handle client input.
        my ($input, $wheel_id) = @_[ARG0, ARG1];
        $input =~ tr[a-zA-Z][n-za-mN-ZA-M]; # ASCII rot13
        $_[HEAP]{client}{$wheel_id}->put($input);
      },
      on_client_error => sub {
        # Handle client error, including disconnect.
        my $wheel_id = $_[ARG3];
        delete $_[HEAP]{client}{$wheel_id};
      },
    }
  );

  POE::Kernel->run();
  exit;



DESCRIPTION

POE::Wheel::ListenAccept implements non-blocking accept() calls for plain old listening server sockets. The application provides the socket, using some normal means such as socket(), IO::Socket::INET, or IO::Socket::UNIX. POE::Wheel::ListenAccept monitors the listening socket and emits events whenever a new client has been accepted.

Please see POE::Wheel::SocketFactory if you need non-blocking connect() or a more featureful listen/accept solution.

POE::Wheel::ListenAccept only accepts client connections. It does not read or write data, so it neither needs nor includes a put() method. POE::Wheel::ReadWrite generally handles the accepted client socket.

PUBLIC METHODS

    new

new() creates a new POE::Wheel::ListenAccept object for a given listening socket. The object will generate events relating to the socket for as long as it exists.

new() accepts two required named parameters:

Handle

The Handle constructor parameter must contain a listening socket handle. POE::Wheel::FollowTail will monitor this socket and accept() new connections as they arrive.

AcceptEvent

AcceptEvent is a required event name that POE::Wheel::ListenAccept will emit for each accepted client socket. PUBLIC EVENTS describes it in detail

ErrorEvent

ErrorEvent is an optional event name that will be emitted whenever a serious problem occurs. Please see PUBLIC EVENTS for more details.

    event

event() allows a session to change the events emitted by a wheel without destroying and re-creating the object. It accepts one or more of the events listed in PUBLIC EVENTS. Undefined event names disable those events.

Ignore connections:



  sub ignore_new_connections {
    $_[HEAP]{tailor}->event( AcceptEvent => "on_ignored_accept" );
  }

  sub handle_ignored_accept {
    # does nothing
  }



    ID

The ID() method returns the wheel’s unique ID. It’s useful for storing the wheel in a hash. All POE::Wheel events should be accompanied by a wheel ID, which allows the wheel to be referenced in their event handlers.



  sub setup_listener {
    my $wheel = POE::Wheel::ListenAccept->new(... etc  ...);
    $_[HEAP]{listeners}{$wheel->ID} = $wheel;
  }



PUBLIC EVENTS

POE::Wheel::ListenAccept emits a couple events.

    AcceptEvent

AcceptEvent names the event that will be emitted for each newly accepted client socket. It is accompanied by three parameters:

$_[ARG0] contains the newly accepted client socket handle. It’s up to the application to do something with this socket. Most use cases involve passing the socket to a POE::Wheel::ReadWrite constructor.

$_[ARG1] contains the accept() call’s return value, which is often the encoded remote end of the remote end of the socket.

$_[ARG2] contains the POE::Wheel::ListenAccept object’s unique ID. This is the same value as returned by the wheel’s ID() method.

A sample AcceptEvent handler:



  sub accept_state {
    my ($client_socket, $remote_addr, $wheel_id) = @_[ARG0..ARG2];

    # Make the remote address human readable.
    my ($port, $packed_ip) = sockaddr_in($remote_addr);
    my $dotted_quad = inet_ntoa($packed_ip);

    print(
      "Wheel $wheel_id accepted a connection from ",
      "$dotted_quad port $port.\n"
    );

    # Spawn off a session to interact with the socket.
    create_server_session($handle);
  }



    ErrorEvent

ErrorEvent names the event that will be generated whenever a new connection could not be successfully accepted. This event is accompanied by four parameters:

$_[ARG0] contains the name of the operation that failed. This usually is ’accept’, but be aware that it’s not necessarily a function name.

$_[ARG1] and $_[ARG2] hold the numeric and stringified values of $!, respectively. POE::Wheel::ListenAccept knows how to handle EAGAIN (and system-dependent equivalents), so this error will never be returned.

$_[ARG3] contains the wheel’s unique ID, which may be useful for shutting down one particular wheel out of a group of them.

A sample ErrorEvent event handler. This assumes the wheels are saved as in the ID example.



  sub error_state {
    my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
    warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
    delete $_[HEAP]{listeners}{$wheel_id};
  }



SEE ALSO

POE::Wheel describes the basic operations of all wheels in more depth. You need to know this.

POE::Wheel::ReadWrite for one possible way to handle clients once you have their sockets.

The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.

BUGS

None known.

AUTHORS & COPYRIGHTS

Please see POE for more information about authors and contributors.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 POE::WHEEL::LISTENACCEPT (3) 2015-06-03

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