/ 
POE-1.282
River stage three • 402 direct dependents • 539 total dependents
/ POE::Wheel::ListenAccept

NAME

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

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