phpman > perldoc > POE::Wheel::ListenAccept(3pm)

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