POE::Wheel::ListenAccept(3pm)

1POE::Wheel::ListenAccepUts(e3r)Contributed Perl DocumentPaOtEi:o:nWheel::ListenAccept(3)
2
3
4

NAME

6       POE::Wheel::ListenAccept - accept connections from regular listening
7       sockets
8

SYNOPSIS

10         $wheel = POE::Wheel::ListenAccept->new(
11           Handle      => $socket_handle,      # Listening socket
12           AcceptEvent => $accept_event_name,  # Event to emit on successful accept
13           ErrorEvent  => $error_event_name,   # Event to emit on some kind of error
14         );
15
16         $wheel->event( AcceptEvent => $new_event_name ); # Add/change event
17         $wheel->event( ErrorEvent  => undef );           # Remove event
18

DESCRIPTION

20       ListenAccept listens on an already established socket and accepts
21       remote connections from it as they arrive.  Sockets it listens on can
22       come from anything that makes filehandles.  This includes socket()
23       calls and IO::Socket::* instances.
24
25       The ListenAccept wheel generates events for successful and failed con‐
26       nections.  EAGAIN is handled internally, so sessions needn't worry
27       about it.
28
29       This wheel neither needs nor includes a put() method.
30

CONSTRUCTOR

32       new new() creates a new wheel, returning the wheels reference.
33

PUBLIC METHODS

35       event EVENT_TYPE => EVENT_NAME, ...
36         event() is covered in the POE::Wheel manpage.
37
38         ListenAccept's event types are "AcceptEvent" and "ErrorEvent".
39
40       ID
41         The ID method returns a ListenAccept wheel's unique ID.  This ID will
42         be included in every event the wheel generates, and it can be used to
43         match events with the wheels which generated them.
44

EVENT TYPES AND THEIR PARAMETERS

46       These are the event types this wheel emits and the parameters which are
47       included with each.
48
49       AcceptEvent
50         An AcceptEvent is generated whenever a new connection has been suc‐
51         cessfully accepted.  AcceptEvent is accompanied by three parameters:
52         "ARG0" contains the accepted socket handle.  "ARG1" contains the
53         accept() call's return value, which often is the address of the other
54         end of the socket.  "ARG2" contains the wheel's unique ID.
55
56         A sample AcceptEvent handler:
57
58           sub accept_state {
59             my ($accepted_handle, $remote_address, $wheel_id) = @_[ARG0..ARG2];
60
61             # The remote address is always good here.
62             my ($port, $packed_ip) = sockaddr_in($remote_address);
63             my $dotted_quad = inet_ntoa($packed_ip);
64
65             print( "Wheel $wheel_id accepted a connection from ",
66                    "$dotted_quad port $port.\n"
67                  );
68
69             # Spawn off a session to interact with the socket.
70             &create_server_session($handle);
71           }
72
73       ErrorEvent
74         The ErrorEvent event is generated whenever a new connection could not
75         be successfully accepted.  Its event is accompanied by four parame‐
76         ters.
77
78         "ARG0" contains the name of the operation that failed.  This usually
79         is 'accept'.  Note: This is not necessarily a function name.
80
81         "ARG1" and "ARG2" hold numeric and string values for $!, respec‐
82         tively.  Note: ListenAccept knows how to handle EAGAIN, so it will
83         never return that error.
84
85         "ARG3" contains the wheel's unique ID.
86
87         A sample ErrorEvent event handler:
88
89           sub error_state {
90             my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
91             warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
92           }
93

BUGS

101       Oh, probably some.
102

AUTHORS & COPYRIGHTS

104       Please see POE for more information about authors and contributors.
105
106
107
108perl v5.8.8                       2006-09-01       POE::Wheel::ListenAccept(3)