1IO::Async::Socket(3)  User Contributed Perl Documentation IO::Async::Socket(3)
2
3
4

NAME

6       "IO::Async::Socket" - event callbacks and send buffering for a socket
7       filehandle
8

SYNOPSIS

10          use IO::Async::Socket;
11
12          use IO::Async::Loop;
13          my $loop = IO::Async::Loop->new;
14
15          my $socket = IO::Async::Socket->new(
16             on_recv => sub {
17                my ( $self, $dgram, $addr ) = @_;
18
19                print "Received reply: $dgram\n",
20                $loop->stop;
21             },
22             on_recv_error => sub {
23                my ( $self, $errno ) = @_;
24                die "Cannot recv - $errno\n";
25             },
26          );
27          $loop->add( $socket );
28
29          $socket->connect(
30             host     => "some.host.here",
31             service  => "echo",
32             socktype => 'dgram',
33          )->get;
34
35          $socket->send( "A TEST DATAGRAM" );
36
37          $loop->run;
38

DESCRIPTION

40       This subclass of IO::Async::Handle contains a socket filehandle. It
41       provides a queue of outgoing data. It invokes the "on_recv" handler
42       when new data is received from the filehandle. Data may be sent to the
43       filehandle by calling the "send" method.
44
45       It is primarily intended for "SOCK_DGRAM" or "SOCK_RAW" sockets (such
46       as UDP or packet-capture); for "SOCK_STREAM" sockets (such as TCP) an
47       instance of IO::Async::Stream is more appropriate.
48

EVENTS

50       The following events are invoked, either using subclass methods or CODE
51       references in parameters:
52
53   on_recv $data, $addr
54       Invoke on receipt of a packet, datagram, or stream segment.
55
56       The "on_recv" handler is invoked once for each packet, datagram, or
57       stream segment that is received. It is passed the data itself, and the
58       sender's address.
59
60   on_recv_error $errno
61       Optional. Invoked when the "recv" method on the receiving handle fails.
62
63   on_send_error $errno
64       Optional. Invoked when the "send" method on the sending handle fails.
65
66       The "on_recv_error" and "on_send_error" handlers are passed the value
67       of $! at the time the error occurred. (The $! variable itself, by its
68       nature, may have changed from the original error by the time this
69       handler runs so it should always use the value passed in).
70
71       If an error occurs when the corresponding error callback is not
72       supplied, and there is not a subclass method for it, then the "close"
73       method is called instead.
74
75   on_outgoing_empty
76       Optional. Invoked when the sending data buffer becomes empty.
77

PARAMETERS

79       The following named parameters may be passed to "new" or "configure":
80
81   read_handle => IO
82       The IO handle to receive from. Must implement "fileno" and "recv"
83       methods.
84
85   write_handle => IO
86       The IO handle to send to. Must implement "fileno" and "send" methods.
87
88   handle => IO
89       Shortcut to specifying the same IO handle for both of the above.
90
91   on_recv => CODE
92   on_recv_error => CODE
93   on_outgoing_empty => CODE
94   on_send_error => CODE
95   autoflush => BOOL
96       Optional. If true, the "send" method will atempt to send data to the
97       operating system immediately, without waiting for the loop to indicate
98       the filehandle is write-ready.
99
100   recv_len => INT
101       Optional. Sets the buffer size for "recv" calls. Defaults to 64 KiB.
102
103   recv_all => BOOL
104       Optional. If true, repeatedly call "recv" when the receiving handle
105       first becomes read-ready. By default this is turned off, meaning at
106       most one fixed-size buffer is received. If there is still more data in
107       the kernel's buffer, the handle will stil be readable, and will be
108       received from again.
109
110       This behaviour allows multiple streams and sockets to be multiplexed
111       simultaneously, meaning that a large bulk transfer on one cannot starve
112       other filehandles of processing time. Turning this option on may
113       improve bulk data transfer rate, at the risk of delaying or stalling
114       processing on other filehandles.
115
116   send_all => INT
117       Optional. Analogous to the "recv_all" option, but for sending. When
118       "autoflush" is enabled, this option only affects deferred sending if
119       the initial attempt failed.
120
121       The condition requiring an "on_recv" handler is checked at the time the
122       object is added to a Loop; it is allowed to create a
123       "IO::Async::Socket" object with a read handle but without a "on_recv"
124       handler, provided that one is later given using "configure" before the
125       stream is added to its containing Loop, either directly or by being a
126       child of another Notifier already in a Loop, or added to one.
127

METHODS

129   send
130          $socket->send( $data, $flags, $addr )
131
132       This method adds a segment of data to be sent, or sends it immediately,
133       according to the "autoflush" parameter. $flags and $addr are optional.
134
135       If the "autoflush" option is set, this method will try immediately to
136       send the data to the underlying filehandle, optionally using the given
137       flags and destination address. If this completes successfully then it
138       will have been sent by the time this method returns. If it fails to
139       send, then the data is queued as if "autoflush" were not set, and will
140       be flushed as normal.
141

EXAMPLES

143   Send-first on a UDP Socket
144       "UDP" is carried by the "SOCK_DGRAM" socket type, for which the string
145       'dgram' is a convenient shortcut:
146
147          $socket->connect(
148             host     => $hostname,
149             service  => $service,
150             socktype => 'dgram',
151             ...
152          )
153
154   Receive-first on a UDP Socket
155       A typical server pattern with "UDP" involves binding a well-known port
156       number instead of connecting to one, and waiting on incoming packets.
157
158          $socket->bind(
159             service  => 12345,
160             socktype => 'dgram',
161          )->get;
162

SEE ALSO

164       •   IO::Handle - Supply object methods for I/O handles
165

AUTHOR

167       Paul Evans <leonerd@leonerd.org.uk>
168
169
170
171perl v5.34.0                      2021-08-08              IO::Async::Socket(3)
Impressum