TITLE

SUBTITLE

C<IO::Socket> contains read and write methods for sockets. It is usually used
through L<C<IO::Socket::INET>|/type/IO::Socket::INET>.


head

method recv(IO::Socket:D: Cool $elems = Inf, :$bin)


Receive a packet and return it, either as a L<C<Blob>|/type/Blob> if
C<:bin> was passed, or a L<C<Str>|/type/Str> if not.
Receives up to C<$elems> or C<65535> (whichever is smaller) bytes or characters.


If the socket has previously been read from in non-C<:bin> mode, it's not always
safe to read from it in C<:bin> mode again. Depending on the decoder it's
possible for the C<:bin> read to skip over bytes that the decoder has read
ahead messing up the order of bytes and chars. This effect can occur with the
UTF-8 decoder and if the previously decoded char could still receive combiners.


In Rakudo versions prior to 2024.07 mixing of binary and non-binary reads is
unsupported.


method read(IO::Socket:D: Int(Cool) $bytes)


Reads C<$bytes> bytes from the socket and returns them in a
L<C<Blob>|/type/Blob>.


The same caveat of mixed binary and non-binary reads described in
L<method recv|#method recv> applies.


Reads a single line of input from the socket, removing the trailing newline
characters (as set by L«C<.nl-in>|/routine/nl-in»). Returns L<C<Nil>|/type/Nil>, if no
more input is available.


method print(IO::Socket:D: Str(Cool) $string)


Writes the supplied string to the socket, thus sending it to other end of the
connection. The binary version is L<method write|#method write>.


Writes the supplied buffer to the socket, thus sending it to other end of the
connection. The string version is L<method print|#method print>.


method put(IO::Socket:D: Str(Cool) $string)


Writes the supplied string, with a C<\n> appended to it,
to the socket, thus sending it to other end of the connection.


This returns a value that the operating system would understand as a "socket descriptor" and
is suitable for passing to a native function that requires a socket descriptor as an
argument such as C<setsockopt>.


root

CompUnit::PrecompilationRepository


role CompUnit::PrecompilationRepository


CompUnit::Repository


role CompUnit::Repository


Input/output related routines


role IO


Scheme for automatically assigning tasks to threads


role Scheduler


Information related to the build system


role Systemic


Network socket


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

role IO::Socket


C<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:


code

=begin code
react {
    whenever IO::Socket::Async.listen('0.0.0.0', 8080) -> $conn {
        await $conn.print: qq:heredoc/END/;
            HTTP/1.1 200 OK
            Content-Type: text/html; charset=UTF-8
            Content-Encoding: UTF-8

            <html>
            <body>
                <h1>Incoming request:</h1>
            <pre>
            END
        whenever $conn.Supply.lines -> $line {
            $conn.say: $line;
            if $line ~~ "" {
                await $conn.print: "</pre></body></html>";
                $conn.close;
            }
            LAST { say "closed connection"; }
        }
    }
    CATCH {
        default {
            say .^name, ': ', .Str;
            say "handled in $?LINE";
        }
    }
}
=end code


And a client that connects to it, and prints out what the server answers:


=begin code
await IO::Socket::Async.connect('127.0.0.1', 3333).then( -> $promise {
    given $promise.result {
        .print("Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n");
        react {
            whenever .Supply() -> $v {
                $v.print;
                done;
            }
        }
        .close;
    }
});
=end code


C<IO::Socket::Async> can also send and receive
L<UDP|https://en.wikipedia.org/wiki/User_Datagram_Protocol> messages
An example server that outputs all the data it receives would be:


=begin code
my $socket = IO::Socket::Async.bind-udp('localhost', 3333);

react {
    whenever $socket.Supply -> $v {
        if $v.chars > 0 {
            say $v;
        }
    }
}
=end code


=begin code
my $socket = IO::Socket::Async.udp();
await $socket.print-to('localhost', 3333, "Hello, Raku!");
=end code


The L<C<CATCH> phaser|/language/phasers#CATCH> can be included to deal
specifically with problems that might occur in this kind of sockets, such as a
port being already taken:


=begin code
react {
    whenever IO::Socket::Async.listen('0.0.0.0', 3000) -> $conn {
        whenever $conn.Supply.lines -> $line {
            $conn.print: qq:heredoc/END/;
                HTTP/1.1 200 OK
                Content-Type: text/html; charset=UTF-8
                Content-Encoding: UTF-8

                <html>
                <body>
                    <h1>Hello World!</h1>
                    <p>{ $line }</p>
                </body>
                </html>
                END
            $conn.close;
        }
        QUIT {
            default {
                say .^name, '→ ', .Str;
                say "handled in line $?LINE";
            }
        }
    }

}
# Will print this, if address 3000 is already in use:
# X::AdHoc→ address already in use
# handled in 23
=end code


Main difference with using other phasers such as C<CATCH> is that this kind of
exception will be caught within the C<whenever> block and will put exiting the
program, or not, under your control.


The C<IO::Socket::Async> cannot be constructed directly, either
C<connect> or C<listen> (for TCP connections) or C<udp> or C<bind-udp>
(for UDP data) should be used to create a client or a server
respectively.


method connect(Str $host, Int $port --> Promise)


Attempts to connect to the TCP server specified by C<$host> and
C<$port>, returning a L<C<Promise>|/type/Promise> that will either be kept with a
connected C<IO::Socket::Async> or broken if the connection cannot be
made.


method connect-path(Str $path --> Promise)


Attempts to connect to a unix domain stream socket specified by C<$path>,
returning a L<C<Promise>|/type/Promise> that will either be kept with a
connected C<IO::Socket::Async> or broken if the connection cannot be
made.


method listen(Str $host, Int $port --> Supply)


Creates a listening socket on the specified C<$host> and C<$port>,
returning a L<C<Supply>|/type/Supply> to which the accepted client
C<IO::Socket::Async>s will be emitted. This
L<C<Supply>|/type/Supply> should be tapped start listening for client
connections.  You can set C<$port> to C<0> if you want the operating
system to find one for you.


The L<C<IO::Socket::Async::ListenSocket>|/type/IO::Socket::Async::ListenSocket>
returned by calling the L<tap|/type/Supply#method_tap> method on the supply
returned represents the underlying listening TCP socket, which can be closed
using its L<close|/type/Tap#method_close> method. If C<$port> was set to C<0>,
you can get the port the socket ended up with using its
L<socket-port|/type/IO::Socket::Async::ListenSocket#method_socket-port> method.


Creates a unix domain stream listening socket on the specified C<$path>,
returning a L<C<Supply>|/type/Supply> to which the accepted client
C<IO::Socket::Async>s will be emitted. This
L<C<Supply>|/type/Supply> should be tapped start listening for client
connections.


The L<C<IO::Socket::Async::ListenSocket>|/type/IO::Socket::Async::ListenSocket>
returned by calling the L<tap|/type/Supply#method_tap> method on the supply
returned represents the underlying listening TCP socket, which can be closed
using its L<close|/type/Tap#method_close> method.


method udp(IO::Socket::Async:U: :$broadcast --> IO::Socket::Async)


Returns an initialized C<IO::Socket::Async> client object that is
configured to send UDP messages using C<print-to> or C<write-to>.  The
C<:broadcast> adverb will set the C<SO_BROADCAST> option which will
allow the socket to send packets to a broadcast address.


method bind-udp(IO::Socket::Async:U: Str() $host, Int() $port, :$broadcast --> IO::Socket::Async)


This returns an initialized C<IO::Socket::Async> server object that is
configured to receive UDP messages sent to the specified C<$host> and
C<$port> and is equivalent to C<listen> for a TCP socket.  The
C<:broadcast> adverb can be specified to allow the receipt of messages
sent to the broadcast address.


method print(IO::Socket::Async:D: Str $str --> Promise)


Attempt to send C<$str> on the C<IO::Socket::Async> that will have been
obtained indirectly via C<connect> or C<listen>, returning a L<C<Promise>|/type/Promise>
that will be kept with the number of bytes sent or broken if there was
an error sending.


method print-to(IO::Socket::Async:D: Str() $host, Int() $port, Str() $str --> Promise)


This is the equivalent of C<print> for UDP sockets that have been
created with the C<udp> method, it will try send a UDP message of
C<$str> to the specified C<$host> and C<$port> returning a
L<C<Promise>|/type/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 C<:broadcast> flag must have been specified when
the socket was created.


method write(IO::Socket::Async:D: Blob $b --> Promise)


This method will attempt to send the bytes in C<$b> on the
C<IO::Socket::Async> that will have been obtained indirectly via
C<connect> or C<listen>, returning a L<C<Promise>|/type/Promise> that will be kept with
the number of bytes sent or broken if there was an error sending.


method write-to(IO::Socket::Async:D: Str() $host, Int() $port, Blob $b --> Promise)


This is the equivalent of C<write> for UDP sockets that have been
created with the C<udp> method. It will try send a UDP message comprised
of the bytes in the L<C<Blob>|/type/Blob>  C<$b> to the specified C<$host>
and C<$port> returning a L<C<Promise>|/type/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 C<:broadcast> flag
must have been specified when the socket was created.


Member variable


class Attribute


Removal of a task from a Scheduler before normal completion


class Cancellation


Thread-safe queue for sending values from producers to consumers


class Channel


CompUnit


class CompUnit


CompUnit::Repository::FileSystem


class CompUnit::Repository::FileSystem


CompUnit::Repository::Installation


class CompUnit::Repository::Installation


Distribution related information


class Distro


Formal grammar made up of named regexes


class Grammar


Iterate over contents of files specified on command line


class IO::ArgFiles


Use multiple IO handles as if they were one


class IO::CatHandle


Opened file or stream


class IO::Handle


Asynchronous notification for file and directory changes





class IO::Notification


Changes in a file, produced by watch-file


class IO::Notification::Change


File or directory path


class IO::Path


IO::Path pre-loaded with IO::Spec::Cygwin


class IO::Path::Cygwin


IO::Path parts encapsulation


class IO::Path::Parts


IO::Path pre-loaded with IO::Spec::QNX


class IO::Path::QNX


IO::Path pre-loaded with IO::Spec::Unix


class IO::Path::Unix


IO::Path pre-loaded with IO::Spec::Win32


class IO::Path::Win32


Buffered inter-process string or binary stream


class IO::Pipe


A tap for listening TCP sockets


class IO::Socket::Async::ListenSocket


TCP Socket


class IO::Socket::INET


Platform specific operations on file and directory paths


class IO::Spec


Platform specific operations on file and directory paths for Cygwin


class IO::Spec::Cygwin


Platform specific operations on file and directory paths QNX


class IO::Spec::QNX


Platform specific operations on file and directory paths for POSIX


class IO::Spec::Unix


Platform specific operations on file and directory paths for Windows


class IO::Spec::Win32


Path to special I/O device


class IO::Special


Kernel related information


class Kernel


A low-level, re-entrant, mutual exclusion lock


class Lock


Condition variables used in locks


class Lock::ConditionVariable


Result of a successful regex match


class Match


Block in a Pod document


class Pod::Block


Verbatim code block in a Pod document


class Pod::Block::Code


Comment in a Pod document


class Pod::Block::Comment


Declarator block in a Pod document


class Pod::Block::Declarator


Named block in a Pod document


class Pod::Block::Named


Paragraph in a Pod document


class Pod::Block::Para


Table in a Pod document


class Pod::Block::Table


Pod definition list


class Pod::Defn


Pod formatting code


class Pod::FormattingCode


Heading in a Pod document


class Pod::Heading


Item in a Pod enumeration list


class Pod::Item


Running process (filehandle-based interface)


class Proc


Running process (asynchronous interface)


class Proc::Async


Status/result of an asynchronous computation


class Promise


String pattern


class Regex


Control access to shared resources by multiple threads


class Semaphore


Live Supply factory


class Supplier


Cached live Supply factory


class Supplier::Preserving


Asynchronous data stream with multiple subscribers


class Supply


Subscription to a Supply


class Tap


Concurrent execution of code (low-level)


class Thread


Scheduler that distributes work among a pool of threads


class ThreadPoolScheduler


Unicode related information


class Unicode


Raku Virtual Machine related information


class VM


Asynchronous socket in TCP or UDP


class IO::Socket::Async


An C<IO::Pipe> object closely corresponds to a UNIX pipe. It has one end where
it consumes string or binary data, and another where it reproduces the same
data. It is buffered, so that a write without a read doesn't immediately
block.


Pipes can be easily constructed with L<sub run and Proc::Async.new|/type/Proc::Async>.


Closes the pipe and returns L<C<Proc>|/type/Proc> object from which the pipe originates.


Returns an L<C<IO::Path>|/type/IO::Path> type object.


Returns the L<C<Proc>|/type/Proc> object from which the pipe originates.


The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


role IO::Socket

Methods

method recv

method read

routine get

method print

method write

method put

method close

method native-descriptor

See Also