POE::Wheel::SocketFactory - non-blocking socket creation and management

  use Socket; # For the constants

  # Listening Unix domain socket.
  $wheel = POE::Wheel::SocketFactory->new(
    SocketDomain => AF_UNIX,               # Sets the socket() domain
    BindAddress  => $unix_socket_address,  # Sets the bind() address
    SuccessEvent => $event_success,        # Event to emit upon accept()
    FailureEvent => $event_failure,        # Event to emit upon error
    # Optional parameters (and default values):
    SocketType   => SOCK_STREAM,           # Sets the socket() type
  );

  # Connecting Unix domain socket.
  $wheel = POE::Wheel::SocketFactory->new(
    SocketDomain  => AF_UNIX,              # Sets the socket() domain
    RemoteAddress => $unix_server_address, # Sets the connect() address
    SuccessEvent  => $event_success,       # Event to emit on connection
    FailureEvent  => $event_failure,       # Event to emit on error
    # Optional parameters (and default values):
    SocketType    => SOCK_STREAM,          # Sets the socket() type
    # Optional parameters (that have no defaults):
    BindAddress   => $unix_client_address, # Sets the bind() address
  );

  # Listening Internet domain socket.
  $wheel = POE::Wheel::SocketFactory->new(
    BindAddress    => $inet_address,       # Sets the bind() address
    BindPort       => $inet_port,          # Sets the bind() port
    SuccessEvent   => $event_success,      # Event to emit upon accept()
    FailureEvent   => $event_failure,      # Event to emit upon error
    # Optional parameters (and default values):
    SocketDomain   => AF_INET,             # Sets the socket() domain
    SocketType     => SOCK_STREAM,         # Sets the socket() type
    SocketProtocol => 'tcp',               # Sets the socket() protocol
    ListenQueue    => SOMAXCONN,           # The listen() queue length
    Reuse          => 'on',                # Lets the port be reused
  );

  # Connecting Internet domain socket.
  $wheel = POE::Wheel::SocketFactory->new(
    RemoteAddress  => $inet_address,       # Sets the connect() address
    RemotePort     => $inet_port,          # Sets the connect() port
    SuccessEvent   => $event_success,      # Event to emit on connection
    FailureEvent   => $event_failure,      # Event to emit on error
    # Optional parameters (and default values):
    SocketDomain   => AF_INET,             # Sets the socket() domain
    SocketType     => SOCK_STREAM,         # Sets the socket() type
    SocketProtocol => 'tcp',               # Sets the socket() protocol
    Reuse          => 'yes',               # Lets the port be reused
  );

  $wheel->event( ... );

  $wheel->ID();

  $wheel->pause_accept();
  $wheel->resume_accept();

SocketFactory creates sockets. It can create connectionless sockets like UDP, or connected sockets like UNIX domain streams and TCP sockets.

The SocketFactory manages connecting and listening sockets on behalf of the session that created it. It will watch a connecting socket and fire a SuccessEvent or FailureEvent event when something happens. It will watch a listening socket and fire a SuccessEvent or FailureEvent for every connection.

new LOTS_OF_THINGS

new() creates a new socket. If necessary, it registers event handlers to manage the socket. new() has parameters for just about every aspect of socket creation; thankfully they all aren't needed at once. new() always returns a SocketFactory wheel reference, even if a socket couldn't be created. These parameters provide information for the SocketFactory's socket() call.

SocketDomain

SocketDomain supplies socket() with its DOMAIN parameter. Supported values are AF_UNIX, AF_INET, AF_INET6, PF_UNIX, PF_INET, and PF_INET6. If SocketDomain is omitted, it defaults to AF_INET. Note: AF_INET6 and PF_INET6 are supplied by the Socket6 module, which is available on the CPAN. You must have Socket6 loaded before SocketFactory can create IPv6 sockets.

SocketType

SocketType supplies socket() with its TYPE parameter. Supported values are SOCK_STREAM and SOCK_DGRAM, although datagram sockets haven't been tested at this time. If SocketType is omitted, it defaults to SOCK_STREAM.

SocketProtocol

SocketProtocol supplies socket() with its PROTOCOL parameter. Protocols may be specified by number or by a name that can be found in the system's protocol (or equivalent) database. SocketProtocol is ignored for UNIX domain sockets. It defaults to 'tcp' if it's omitted from an INET socket factory. These parameters provide information for the SocketFactory's bind() call.

BindAddress

BindAddress supplies the address where a socket will be bound to. It has different meanings and formats depending on the socket domain. BindAddress may contain either a string or a packed Internet address when it's specified for INET sockets. The string form of BindAddress should hold a dotted numeric address or resolvable host name. BindAddress is optional for INET sockets, and SocketFactory will use INADDR_ANY by default. When used to bind a UNIX domain socket, BindAddress should contain a path describing the socket's filename. This is required for server sockets and datagram client sockets. BindAddress has no default value for UNIX sockets.

BindPort

BindPort is only meaningful for INET domain sockets. It contains a port on the BindAddress interface where the socket will be bound. It defaults to 0 if omitted. BindPort may be a port number or a name that can be looked up in the system's services (or equivalent) database. These parameters are used for outbound sockets.

RemoteAddress

RemoteAddress specifies the remote address to which a socket should connect. If present, the SocketFactory will create a connecting socket. Otherwise, it will make a listening socket, should the protocol warrant it. Like with the bind address, RemoteAddress may be a string containing a dotted quad or a resolvable host name. It may also be a packed Internet address, or a UNIX socket path. It will be packed, with or without an accompanying RemotePort, as necessary for the socket domain.

RemotePort

RemotePort is the port to which the socket should connect. It is required for connecting Internet sockets and ignored in all other cases. The remote port may be a number or a name in the /etc/services (or equivalent) database. This parameter is used for listening sockets.

ListenQueue

ListenQueue specifies the length of the socket's listen() queue. It defaults to SOMAXCONN if omitted. SocketFactory will ensure that it doesn't exceed SOMAXCONN.

event EVENT_TYPE => EVENT_NAME, ...

event() is covered in the POE::Wheel manpage.

getsockname

getsockname() behaves like the built-in function of the same name. Because the SocketFactory's underlying socket is hidden away, it's hard to do this directly. It's useful for finding which address and/or port the SocketFactory has bound to when it's been instructed to use BindAddress => INADDR_ANY or BindPort => 0.

ID

The ID method returns a SocketFactory wheel's unique ID. This ID will be included in every event the wheel generates, and it can be used to match events with the wheels which generated them.

pause_accept

resume_accept

Listening SocketFactory instances will accept connections for as long as they exist. This may not be desirable in pre-forking servers where the main process must not handle connections. pause_accept() temporarily stops a SocketFactory from accepting new connections. It continues to listen, however. resume_accept() ends a temporary pause, allowing a SocketFactory to accept new connections. In a pre-forking server, the main process would pause_accept() immediately after the SocketFactory was created. As forked child processes start, they call resume_accept() to begin accepting connections.

SuccessEvent

SuccessEvent defines the event that will be emitted when a socket has been established successfully. The SuccessEvent event is fired when outbound sockets have connected or whenever listening sockets accept new connections. SuccessEvent must be the name of a state within the current session. In all cases, CWARG0 holds the new socket handle. CWARG3 holds the wheel's unique ID. The parameters between them differ according to the socket's domain and whether it's listening or connecting. For INET sockets, CWARG1 and CWARG2 hold the socket's remote address and port, respectively. The address is packed; use inet_ntoa() (See Socket) if a human-readable version is necessary. For UNIX client sockets, CWARG1 holds the server address. It may be undefined on systems that have trouble retrieving a UNIX socket's remote address. CWARG2 is always undefined for UNIX client sockets. According to _Perl Cookbook_, the remote address returned by accept() on UNIX sockets is undefined, so CWARG1 and CWARG2 are also undefined in this case. A sample SuccessEvent handler:

  sub server_accept {
    my $accepted_handle = $_[ARG0];

    my $peer_host = inet_ntoa($_[ARG1]);
    print( "Wheel $_[ARG3] accepted a connection from ",
           "$peer_host port $peer_port\n"
         );

    # Do something with the new connection.
    &spawn_connection_session( $accepted_handle );
  }

FailureEvent

FailureEvent defines the event that will be emitted when a socket error occurs. EAGAIN does not count as an error since the SocketFactory knows what to do with it. FailureEvent must be the name of a state within the current session. The FailureEvent event comes with the standard error event parameters. CWARG0 contains the name of the operation that failed. CWARG1 and CWARG2 hold numeric and string values for CW$!, respectively. CWARG3 contains the wheel's unique ID, which may be matched back to the wheel itself via the CW$wheel->ID call. A sample ErrorEvent handler:

  sub error_state {
    my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
    warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
    delete $heap->{wheels}->{$wheel_id}; # shut down that wheel
  }

POE::Wheel, Socket6.

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

Many (if not all) of the croak/carp/warn/die statements should fire back FailureEvent instead.

SocketFactory is only tested with UNIX streams and INET sockets using the UDP and TCP protocols. Others may or may not work, but the latest design is data driven and should be easy to extend. Patches are welcome, as are test cases for new families and protocols. Even if test cases fail, they'll make nice reference code to test additions to the SocketFactory class.

Please see POE for more information about authors and contributors.