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;
  }

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};
  }