1POE::Wheel::SocketFactoUrsye(r3)Contributed Perl DocumenPtOaEt:i:oWnheel::SocketFactory(3)
2
6 POE::Wheel::SocketFactory - non-blocking socket creation and management
7
9 use Socket; # For the constants
10 # Listening Unix domain socket.
12 $wheel = POE::Wheel::SocketFactory->new(
13 SocketDomain => AF_UNIX, # Sets the socket() domain
14 BindAddress => $unix_socket_address, # Sets the bind() address
15 SuccessEvent => $event_success, # Event to emit upon accept()
16 FailureEvent => $event_failure, # Event to emit upon error
17 # Optional parameters (and default values):
18 SocketType => SOCK_STREAM, # Sets the socket() type
19 );
20 # Connecting Unix domain socket.
22 $wheel = POE::Wheel::SocketFactory->new(
23 SocketDomain => AF_UNIX, # Sets the socket() domain
24 RemoteAddress => $unix_server_address, # Sets the connect() address
25 SuccessEvent => $event_success, # Event to emit on connection
26 FailureEvent => $event_failure, # Event to emit on error
27 # Optional parameters (and default values):
28 SocketType => SOCK_STREAM, # Sets the socket() type
29 # Optional parameters (that have no defaults):
30 BindAddress => $unix_client_address, # Sets the bind() address
31 );
32 # Listening Internet domain socket.
34 $wheel = POE::Wheel::SocketFactory->new(
35 BindAddress => $inet_address, # Sets the bind() address
36 BindPort => $inet_port, # Sets the bind() port
37 SuccessEvent => $event_success, # Event to emit upon accept()
38 FailureEvent => $event_failure, # Event to emit upon error
39 # Optional parameters (and default values):
40 SocketDomain => AF_INET, # Sets the socket() domain
41 SocketType => SOCK_STREAM, # Sets the socket() type
42 SocketProtocol => 'tcp', # Sets the socket() protocol
43 ListenQueue => SOMAXCONN, # The listen() queue length
44 Reuse => 'on', # Lets the port be reused
45 );
46 # Connecting Internet domain socket.
48 $wheel = POE::Wheel::SocketFactory->new(
49 RemoteAddress => $inet_address, # Sets the connect() address
50 RemotePort => $inet_port, # Sets the connect() port
51 SuccessEvent => $event_success, # Event to emit on connection
52 FailureEvent => $event_failure, # Event to emit on error
53 # Optional parameters (and default values):
54 SocketDomain => AF_INET, # Sets the socket() domain
55 SocketType => SOCK_STREAM, # Sets the socket() type
56 SocketProtocol => 'tcp', # Sets the socket() protocol
57 Reuse => 'yes', # Lets the port be reused
58 );
59 $wheel->event( ... );
61 $wheel->ID();
63 $wheel->pause_accept();
65 $wheel->resume_accept();
66
68 SocketFactory creates sockets. It can create connectionless sockets
69 like UDP, or connected sockets like UNIX domain streams and TCP sock‐
70 ets.
71 The SocketFactory manages connecting and listening sockets on behalf of
73 the session that created it. It will watch a connecting socket and
74 fire a SuccessEvent or FailureEvent event when something happens. It
75 will watch a listening socket and fire a SuccessEvent or FailureEvent
76 for every connection.
77
79 new LOTS_OF_THINGS
80 new() creates a new socket. If necessary, it registers event han‐
81 dlers to manage the socket. new() has parameters for just about
82 every aspect of socket creation; thankfully they all aren't needed at
83 once.
84 new() always returns a SocketFactory wheel reference, even if a
86 socket couldn't be created.
87 These parameters provide information for the SocketFactory's socket()
89 call.
90 SocketDomain
92 SocketDomain supplies socket() with its DOMAIN parameter. Sup‐
93 ported values are AF_UNIX, AF_INET, AF_INET6, PF_UNIX, PF_INET, and
94 PF_INET6. If SocketDomain is omitted, it defaults to AF_INET.
95 Note: AF_INET6 and PF_INET6 are supplied by the Socket6 module,
97 which is available on the CPAN. You must have Socket6 loaded
98 before SocketFactory can create IPv6 sockets.
99 SocketType
101 SocketType supplies socket() with its TYPE parameter. Supported
102 values are SOCK_STREAM and SOCK_DGRAM, although datagram sockets
103 haven't been tested at this time. If SocketType is omitted, it
104 defaults to SOCK_STREAM.
105 SocketProtocol
107 SocketProtocol supplies socket() with its PROTOCOL parameter. Pro‐
108 tocols may be specified by number or by a name that can be found in
109 the system's protocol (or equivalent) database. SocketProtocol is
110 ignored for UNIX domain sockets. It defaults to 'tcp' if it's
111 omitted from an INET socket factory.
112 These parameters provide information for the SocketFactory's bind()
114 call.
115 BindAddress
117 BindAddress supplies the address where a socket will be bound to.
118 It has different meanings and formats depending on the socket
119 domain.
120 BindAddress may contain either a string or a packed Internet
122 address when it's specified for INET sockets. The string form of
123 BindAddress should hold a dotted numeric address or resolvable host
124 name. BindAddress is optional for INET sockets, and SocketFactory
125 will use INADDR_ANY by default.
126 When used to bind a UNIX domain socket, BindAddress should contain
128 a path describing the socket's filename. This is required for
129 server sockets and datagram client sockets. BindAddress has no
130 default value for UNIX sockets.
131 BindPort
133 BindPort is only meaningful for INET domain sockets. It contains a
134 port on the BindAddress interface where the socket will be bound.
135 It defaults to 0 if omitted.
136 BindPort may be a port number or a name that can be looked up in
138 the system's services (or equivalent) database.
139 These parameters are used for outbound sockets.
141 RemoteAddress
143 RemoteAddress specifies the remote address to which a socket should
144 connect. If present, the SocketFactory will create a connecting
145 socket. Otherwise, it will make a listening socket, should the
146 protocol warrant it.
147 Like with the bind address, RemoteAddress may be a string contain‐
149 ing a dotted quad or a resolvable host name. It may also be a
150 packed Internet address, or a UNIX socket path. It will be packed,
151 with or without an accompanying RemotePort, as necessary for the
152 socket domain.
153 RemotePort
155 RemotePort is the port to which the socket should connect. It is
156 required for connecting Internet sockets and ignored in all other
157 cases.
158 The remote port may be a number or a name in the /etc/services (or
160 equivalent) database.
161 This parameter is used for listening sockets.
163 ListenQueue
165 ListenQueue specifies the length of the socket's listen() queue.
166 It defaults to SOMAXCONN if omitted. SocketFactory will ensure
167 that it doesn't exceed SOMAXCONN.
168 event EVENT_TYPE => EVENT_NAME, ...
170 event() is covered in the POE::Wheel manpage.
171 getsockname
173 getsockname() behaves like the built-in function of the same name.
174 Because the SocketFactory's underlying socket is hidden away, it's
175 hard to do this directly.
176 It's useful for finding which address and/or port the SocketFactory
178 has bound to when it's been instructed to use BindAddress =>
179 INADDR_ANY or BindPort => 0.
180 ID
182 The ID method returns a SocketFactory wheel's unique ID. This ID
183 will be included in every event the wheel generates, and it can be
184 used to match events with the wheels which generated them.
185 pause_accept
187 resume_accept
188 Listening SocketFactory instances will accept connections for as long
189 as they exist. This may not be desirable in pre-forking servers
190 where the main process must not handle connections.
191 pause_accept() temporarily stops a SocketFactory from accepting new
193 connections. It continues to listen, however. resume_accept() ends
194 a temporary pause, allowing a SocketFactory to accept new connec‐
195 tions.
196 In a pre-forking server, the main process would pause_accept() imme‐
198 diately after the SocketFactory was created. As forked child pro‐
199 cesses start, they call resume_accept() to begin accepting connec‐
200 tions.
201
203 SuccessEvent
204 SuccessEvent defines the event that will be emitted when a socket has
205 been established successfully. The SuccessEvent event is fired when
206 outbound sockets have connected or whenever listening sockets accept
207 new connections.
208 SuccessEvent must be the name of a state within the current session.
210 In all cases, "ARG0" holds the new socket handle. "ARG3" holds the
212 wheel's unique ID. The parameters between them differ according to
213 the socket's domain and whether it's listening or connecting.
214 For INET sockets, "ARG1" and "ARG2" hold the socket's remote address
216 and port, respectively. The address is packed; use inet_ntoa() (See
217 Socket) if a human-readable version is necessary.
218 For UNIX client sockets, "ARG1" holds the server address. It may be
220 undefined on systems that have trouble retrieving a UNIX socket's
221 remote address. "ARG2" is always undefined for UNIX client sockets.
222 According to _Perl Cookbook_, the remote address returned by accept()
224 on UNIX sockets is undefined, so "ARG1" and "ARG2" are also undefined
225 in this case.
226 A sample SuccessEvent handler:
228 sub server_accept {
230 my $accepted_handle = $_[ARG0];
231 my $peer_host = inet_ntoa($_[ARG1]);
233 print( "Wheel $_[ARG3] accepted a connection from ",
234 "$peer_host port $peer_port\n"
235 );
236 # Do something with the new connection.
238 &spawn_connection_session( $accepted_handle );
239 }
240 FailureEvent
242 FailureEvent defines the event that will be emitted when a socket
243 error occurs. EAGAIN does not count as an error since the SocketFac‐
244 tory knows what to do with it.
245 FailureEvent must be the name of a state within the current session.
247 The FailureEvent event comes with the standard error event parame‐
249 ters.
250 "ARG0" contains the name of the operation that failed. "ARG1" and
252 "ARG2" hold numeric and string values for $!, respectively. "ARG3"
253 contains the wheel's unique ID, which may be matched back to the
254 wheel itself via the $wheel->ID call.
255 A sample ErrorEvent handler:
257 sub error_state {
259 my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
260 warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
261 delete $heap->{wheels}->{$wheel_id}; # shut down that wheel
262 }
263
265 POE::Wheel, Socket6.
266 The SEE ALSO section in POE contains a table of contents covering the
268 entire POE distribution.
269
271 Many (if not all) of the croak/carp/warn/die statements should fire
272 back FailureEvent instead.
273 SocketFactory is only tested with UNIX streams and INET sockets using
275 the UDP and TCP protocols. Others may or may not work, but the latest
276 design is data driven and should be easy to extend. Patches are wel‐
277 come, as are test cases for new families and protocols. Even if test
278 cases fail, they'll make nice reference code to test additions to the
279 SocketFactory class.
280
282 Please see POE for more information about authors and contributors.
283perl v5.8.8 2006-09-01 POE::Wheel::SocketFactory(3)