• NAME
• SUPPORTED PLATFORMS
• SYNOPSIS
• DESCRIPTION
• PUBLIC METHODS
• EVENTS AND PARAMETERS
• SEE ALSO
• BUGS
• AUTHORS & COPYRIGHTS

NAME

POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction

SUPPORTED PLATFORMS

• Linux
• Solaris
• Windows

SYNOPSIS

  use Socket; # For the constants

  # Listening Unix domain socket.
  $wheel = new POE::Wheel::SocketFactory(
    SocketDomain => AF_UNIX,               # Sets the socket() domain
    BindAddress  => $unix_socket_address,  # Sets the bind() address
    SuccessState => $success_state,        # State to call upon accept()
    FailureState => $state_failure,        # State to call upon error
    # Optional parameters (and default values):
    SocketType   => SOCK_STREAM,           # Sets the socket() type
  );

  # Connecting Unix domain socket.
  $wheel = new POE::Wheel::SocketFactory(
    SocketDomain  => AF_UNIX,              # Sets the socket() domain
    RemoteAddress => $unix_server_address, # Sets the connect() address
    SuccessState  => $success_state,       # State to call on connection
    FailureState  => $state_failure,       # State to call 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 = new POE::Wheel::SocketFactory(
    BindAddress    => $inet_address,       # Sets the bind() address
    BindPort       => $inet_port,          # Sets the bind() port
    SuccessState   => $success_state,      # State to call upon accept()
    FailureState   => $state_failure,      # State to call 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          => 'no',                # Lets the port be reused
  );

  # Connecting Internet domain socket.
  $wheel = new POE::Wheel::SocketFactory(
    RemoteAddress  => $inet_address,       # Sets the connect() address
    RemotePort     => $inet_port,          # Sets the connect() port
    SuccessState   => $success_state,      # State to call on connection
    FailureState   => $state_failure,      # State to call 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          => 'no',                # Lets the port be reused
  );

  $wheel->event( ... );

DESCRIPTION

This wheel creates sockets, generating events when something happens to them. Success events come with connected, ready to use sockets. Failure events are accompanied by error codes, similar to other wheels'.

SocketFactory currently supports Unix domain sockets, and TCP sockets within the Internet domain. Other protocols are forthcoming, eventually; let the author or mailing list know if they're needed sooner.

PUBLIC METHODS

• POE::Wheel::SocketFactory::new()

  The new() method does most of the work. It has parameters for just about every aspect of socket creation: socket(), setsockopt(), bind(), listen(), connect() and accept(). Thankfully they all aren't used at the same time.

  The parameters:

  • SocketDomain

    SocketDomain is the DOMAIN parameter for the socket() call. Currently supported values are AF_UNIX, AF_INET, PF_UNIX and PF_INET. It defaults to AF_INET if omitted.

  • SocketType

    SocketType is the TYPE parameter for the socket() call. Currently supported values are SOCK_STREAM and SOCK_DGRAM (although datagram sockets aren't tested at this time). It defaults to SOCK_STREAM if omitted.

  • SocketProtocol

    SocketProtocol is the PROTOCOL parameter for the socket() call. Protocols may be specified by name or number (see /etc/protocols, or the equivalent file). The only supported protocol at this time is 'tcp'. SocketProtocol is ignored for Unix domain sockets. It defaults to 'tcp' if omitted from an Internet socket constructor.

  • BindAddress

    BindAddress is the local interface address that the socket will be bound to.

    For Internet domain sockets: The bind address may be a string containing a dotted quad, a host name, or a packed Internet address (without the port). It defaults to INADDR_ANY if it's not specified, which will try to bind the socket to every interface. If any interface has a socket already bound to the BindPort, then bind() (and the SocketFactory) will fail.

    For Unix domain sockets: The bind address is a path where the socket will be created. It is required for server sockets and datagram client sockets. If a file exists at the bind address, then bind() (and the SocketFactory) will fail.

  • BindPort

    BindPort is the port of the local interface(s) that the socket will try to bind to. It is ignored for Unix sockets and recommended for Internet sockets. It defaults to 0 if omitted, which will bind the socket to an unspecified available port.

    The bind port may be a number, or a name in the /etc/services (or equivalent) database.

  • ListenQueue

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

    It should go without saying that ListenQueue is only appropriate for listening sockets.

  • RemoteAddress

    RemoteAddress is the remote address to which the socket should connect. If present, the SocketFactory will create a connecting socket; otherwise, the SocketFactory will make a listening socket.

    The remote address may be a string containing a dotted quad, a host name, 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.

• POE::Wheel::SocketFactory::event(...)

  Please see POE::Wheel.

• POE::Wheel::SocketFactory::getsockname()

  Returns the value of getsockname() as called with the SocketFactory's socket.

  This is useful for finding out what the SocketFactory's internal socket has bound to when it's been instructed to use BindAddress => INADDR_ANY and/or BindPort => INADDR_ANY.

EVENTS AND PARAMETERS

• SuccessState

  The SuccessState parameter defines a state name or coderef to call upon a successful connect or accept. The operation it succeeds on depends on the type of socket created.

  For connecting sockets, the success state/coderef is called when the socket has connected. For listening sockets, the success state/coderef is called for each successfully accepted client connection.

  ARG0 contains the connected or accepted socket.

  For INET sockets, ARG1 and ARG2 hold the socket's remote address and port, respectively.

  For Unix client sockets, ARG1 contains the server address and ARG2 is undefined.

  According to _Perl Cookbook_, the remote address for accepted Unix domain sockets is undefined. So ARG0 and ARG1 are, too.

• FailureState

  The FailureState parameter defines a state name or coderef to call when a socket error occurs. The SocketFactory knows what to do with EAGAIN, so that's not considered an error.

  The ARG0 parameter contains the name of the function that failed. ARG1 and ARG2 contain the numeric and string versions of $! at the time of the error, respectively.

  A sample ErrorState state:

    sub error_state {
      my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2];
      warn "$operation error $errnum: $errstr\n";
    }

SEE ALSO

POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept; POE::Wheel::ReadWrite; POE::Wheel::SocketFactory

BUGS

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

AUTHORS & COPYRIGHTS

Please see the POE manpage.