|
POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction |
POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction
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( ... );
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.
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 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 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 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 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 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 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 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 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.
Please see POE::Wheel.
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.
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.
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";
}
POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept; POE::Wheel::ReadWrite; POE::Wheel::SocketFactory
Many (if not all) of the croak/carp/warn/die statements should fire back $state_failure instead.
Please see the POE manpage.
|
POE::Wheel::SocketFactory - POE Socket Creation Logic Abstraction |