POE::W...Accept(3pm)

📦
version 1.3700 · 7 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

🌸 POE::Wheel::ListenAccept 🌸

okay bestie, gather round, because we're talking about POE::Wheel::ListenAccept — that's the Perl module, manual page POE::W...Accept(3pm), from the User Contributed Perl Documentation collection. It does one thing and it does it adorably: it accepts connections from regular listening sockets. That's the whole NAME energy. No cap. 💅

✨ SYNOPSIS ✨

first of all, the page says: peep "SYNOPSIS" in POE::Wheel::SocketFactory if you want a simpler version of this exact program. This one here is the full send:

#!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;

look at that rot13 server just living its best life 🌀 iconic behavior.

💖 DESCRIPTION 💖

so POE::Wheel::ListenAccept implements non-blocking accept() calls for plain old listening server sockets. that's it, that's the job. 🫶

you (yes, you) provide the socket, using some normal means like socket(), IO::Socket::INET, or IO::Socket::UNIX. then POE::Wheel::ListenAccept monitors the listening socket and emits events whenever a new client has been accepted. it's giving vigilant little bouncer at the door 🚪✨

bestie, please see POE::Wheel::SocketFactory if you need non-blocking connect() or a more featureful listen/accept solution. this one is the lowkey version.

also important: POE::Wheel::ListenAccept only accepts client connections. it does not read or write data, so it neither needs nor includes a put() method. don't go looking for one, she's not there 🙈. POE::Wheel::ReadWrite generally handles the accepted client socket — that's the division of labor, slay.

👑 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. it's committed, it's loyal, main character energy fr fr.

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() lets a session 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. (so you can just. turn them off. ghost them 💀)

ignoring connections, as a treat:

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

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

🌈 PUBLIC EVENTS 🌈

POE::Wheel::ListenAccept emits a couple events. just a couple. small but mighty.

🦋 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. no pressure tho 🫶
  • $_[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. good. we love that for us.
  • $_[ARG3] contains the wheel's unique ID, which may be useful for shutting down one particular wheel out of a group of them. targeted shutdown, periodt 💅

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. like, genuinely, bestie, go read it. 📚
  • 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. ✨ flawless. not me checking three times. she's clean, your honor.

🎀 AUTHORS & COPYRIGHTS 🎀

please see POE for more information about authors and contributors. 🫶

and that's the whole page, babes! this one shipped with perl v5.34.0, dated 2022-03-25 — go forth, accept your sockets, and slay 💖✨🎀🦋

📦 where this page comes from