class IO::Socket::Async
Asynchronous socket in TCP or UDP
IO::Socket::Async|/type/IO::Socket::Async
provides asynchronous sockets, for both the server and the client side.
Here is a simple example of a simple "hello world" HTTP server that listens on port 3333:
react
And a client that connects to it, and prints out what the server answers:
await IO::Socket::Async.connect('127.0.0.1', 3333).then( ->);
IO::Socket::Async can also send and receive UDP messages An example server that outputs all the data it receives would be:
my = IO::Socket::Async.bind-udp('localhost', 3333);react
And an associated client might be:
my = IO::Socket::Async.udp();await .print-to('localhost', 3333, "Hello, Perl 6!");
The CATCH
phaser can be included to deal specifically with problems that might occur in this kind of sockets, such as a port being already taken:
react# Will print this, if address 3000 is already in use:# X::AdHoc→ address already in use# handled in 23
Main difference with using other phasers such as CATCH
is that this kind of exception will be caught within the whenever
block and will put exiting the program, or not, under your control.
Methods
The IO::Socket::Async cannot be constructed directly, either connect
or listen
(for TCP connections) or udp
or bind-udp
(for UDP data) should be used to create a client or a server respectively.
method connect
method connect(Str , Int --> Promise)
Attempts to connect to the TCP server specified by $host
and $port
, returning a Promise that will either be kept with a connected IO::Socket::Async or broken if the connection cannot be made.
method listen
method listen(Str , Int --> Supply)
Creates a listening socket on the specified $host
and $port
, returning a Supply to which the accepted client IO::Socket::Asyncs will be emit
ted. This Supply should be tapped start listening for client connections. You can use $port = 0
if you want the operating system to find one for you.
To close the underlying listening socket, the Tap returned by tapping the listener should be close
d.
For example, when using tap
:
my = IO::Socket::Async.listen('127.0.0.1', 8080);my = .tap();# When you want to close the listener.close;
Or when using whenever
:
my = IO::Socket::Async.listen('127.0.0.1', 5000);my ;react# When you want to close the listener, you can still use:.close;
method udp
method udp(IO::Socket::Async: : --> IO::Socket::Async)
Returns an initialized IO::Socket::Async
client object that is configured to send UDP messages using print-to
or write-to
. The :broadcast
adverb will set the SO_BROADCAST
option which will allow the socket to send packets to a broadcast address.
method bind-udp
method bind-udp(IO::Socket::Async: Str() , Int() , : --> IO::Socket::Async)
This returns an initialized IO::Socket::Async
server object that is configured to receive UDP messages sent to the specified $host
and $port
and is equivalent to listen
for a TCP socket. The :broadcast
adverb can be specified to allow the receipt of messages sent to the broadcast address.
method print
method print(Str --> Promise)
Attempt to send $str
on the IO::Socket::Async that will have been obtained indirectly via connect
or listen
, returning a Promise that will be kept with the number of bytes sent or broken if there was an error sending.
method print-to
method print-to(IO::Socket::Async: Str() , Int() , Str() --> Promise)
This is the equivalent of print
for UDP sockets that have been created with the udp
method, it will try send a UDP message of $str
to the specified $host
and $port
returning a Promise that will be kept when the data is successfully sent or broken if it was unable to send the data. In order to send to a broadcast address the :broadcast
flag must have been specified when the socket was created.
method write
method write(Blob --> Promise)
This method will attempt to send the bytes in $b
on the IO::Socket::Async that will have been obtained indirectly via connect
or listen
, returning a Promise that will be kept with the number of bytes sent or broken if there was an error sending.
method write-to
method write-to(IO::Socket::Async: Str() , Int() , Blob --> Promise)
This is the equivalent of write
for UDP sockets that have been created with the udp
method. It will try send a UDP message comprised of the bytes in the Blob $b
to the specified $host
and $port
returning a Promise that will be kept when the data is successfully sent or broken if it was unable to send the data. In order to send to a broadcast address the :broadcast
flag must have been specified when the socket was created.
method Supply
method Supply(:, : = buf8.new --> Supply)
Returns a Supply which can be tapped to obtain the data read from the connected IO::Socket::Async as it arrives. By default the data will be emitted as characters, but if the :bin
adverb is provided a Buf of bytes will be emitted instead, optionally in this case you can provide your own Buf
with the :buf
named parameter.
A UDP socket in character mode will treat each packet as a complete message and decode it. In the event of a decoding error, the Supply
will quit
.
On the other hand, a TCP socket treats the incoming packets as part of a stream, and feeds the incoming bytes into a streaming decoder. It then emits whatever characters the decoder considers ready. Since strings work at grapheme level in Perl 6, this means that only known complete graphemes will be emitted. For example, if the UTF-8 encoding were being used and the last byte in the packet decoded to a
, this would not be emitted since the next packet may include a combining character that should form a single grapheme together with the a
. Control characters (such as \n
) always serve as grapheme boundaries, so any text-based protocols that use newlines or null bytes as terminators will not need special consideration. A TCP socket will also quit
upon a decoding error.
method close
method close()
Close the connected client IO::Socket::Async which will have been obtained from the listen
Supply or the connect
Promise.
In order to close the underlying listening socket created by listen
you can close
the Tap. See listen
for examples.
method socket-host
method socket-host(--> Str)
Returns the IP address of the local end of this socket.
method peer-host
method peer-host(--> Str)
Returns the IP address of the remote end of this socket.
method socket-port
method socket-port(--> Int)
Returns the port of the local end of this socket.
method peer-port
method peer-port(--> Int)
Returns the port of the remote end of this socket.
method native-descriptor
method native-descriptor(--> Int)
Returns the file descriptor of this socket.