Networking and Streams

    All Julia streams expose at least a and a write method, taking the stream as their first argument, e.g.:

    Note that returns 11, the number of bytes (in ) written to stdout, but this return value is suppressed with the ;.

    Here Enter was pressed again so that Julia would read the newline. Now, as you can see from this example, takes the data to write as its second argument, while read takes the type of the data to be read as the second argument.

    For example, to read a simple byte array, we could do:

    1. julia> x = zeros(UInt8, 4)
    2. 4-element Array{UInt8,1}:
    3.  0x00
    4.  0x00
    5.  0x00
    6.  0x00
    8. julia> read!(stdin, x)
    9. abcd
    10. 4-element Array{UInt8,1}:
    11.  0x61
    12.  0x62
    13.  0x63
    14.  0x64

    However, since this is slightly cumbersome, there are several convenience methods provided. For example, we could have written the above as:

    1. julia> read(stdin, 4)
    2. abcd
    3. 4-element Array{UInt8,1}:
    4.  0x61
    5.  0x62
    6.  0x63
    7.  0x64

    or if we had wanted to read the entire line instead:

    1. julia> readline(stdin)
    2. abcd
    3. "abcd"

    Note that depending on your terminal settings, your TTY may be line buffered and might thus require an additional enter before the data is sent to Julia.

    To read every line from you can use eachline:

    1. for line in eachline(stdin)
    2.     print("Found $line")
    3. end

    or if you wanted to read by character instead:

    1. while !eof(stdin)
    2.     x = read(stdin, Char)
    3.     println("Found: $x")
    4. end

    Note that the write method mentioned above operates on binary streams. In particular, values do not get converted to any canonical text representation but are written out as is:

    1. julia> write(stdout, 0x61);  # suppress return value 1 with ;
    2. a

    For text I/O, use the or show methods, depending on your needs (see the documentation for these two methods for a detailed discussion of the difference between them):

    See for more information on how to implement display methods for custom types.

    Sometimes IO output can benefit from the ability to pass contextual information into show methods. The IOContext object provides this framework for associating arbitrary metadata with an IO object. For example, :compact => true adds a hinting parameter to the IO object that the invoked show method should print a shorter output (if applicable). See the documentation for a list of common properties.

    Like many other environments, Julia has an open function, which takes a filename and returns an object that you can use to read and write things from the file. For example, if we have a file, hello.txt, whose contents are Hello, World!:

    1. IOStream(<file hello.txt>)
    3. julia> readlines(f)
    4. 1-element Array{String,1}:

    If you want to write to a file, you can open it with the write ("w") flag:

    1. julia> f = open("hello.txt","w")
    2. IOStream(<file hello.txt>)
    4. julia> write(f,"Hello again.")
    5. 12

    If you examine the contents of hello.txt at this point, you will notice that it is empty; nothing has actually been written to disk yet. This is because the IOStream must be closed before the write is actually flushed to disk:

    1. julia> close(f)

    Examining hello.txt again will show its contents have been changed.

    Opening a file, doing something to its contents, and closing it again is a very common pattern. To make this easier, there exists another invocation of open which takes a function as its first argument and filename as its second, opens the file, calls the function with the file as an argument, and then closes it again. For example, given a function:

    1. function read_and_capitalize(f::IOStream)
    2.     return uppercase(read(f, String))
    3. end

    You can call:

    1. julia> open(read_and_capitalize, "hello.txt")
    2. "HELLO AGAIN."

    to open hello.txt, call read_and_capitalize on it, close hello.txt and return the capitalized contents.

    1. julia> open("hello.txt") do f
    2.            uppercase(read(f, String))
    3.        end
    4. "HELLO AGAIN."

    Let’s jump right in with a simple example involving TCP sockets. This functionality is in a standard library package called Sockets. Let’s first create a simple server:

    To those familiar with the Unix socket API, the method names will feel familiar, though their usage is somewhat simpler than the raw Unix socket API. The first call to will create a server waiting for incoming connections on the specified port (2000) in this case. The same function may also be used to create various other kinds of servers:

    1. julia> listen(2000) # Listens on localhost:2000 (IPv4)
    2. Sockets.TCPServer(active)
    4. julia> listen(ip"127.0.0.1",2000) # Equivalent to the first
    5. Sockets.TCPServer(active)
    7. julia> listen(ip"::1",2000) # Listens on localhost:2000 (IPv6)
    8. Sockets.TCPServer(active)
    10. julia> listen(IPv4(0),2001) # Listens on port 2001 on all IPv4 interfaces
    11. Sockets.TCPServer(active)
    13. julia> listen(IPv6(0),2001) # Listens on port 2001 on all IPv6 interfaces
    14. Sockets.TCPServer(active)
    16. julia> listen("testsocket") # Listens on a UNIX domain socket
    17. Sockets.PipeServer(active)
    19. julia> listen("\\\\.\\pipe\\testsocket") # Listens on a Windows named pipe
    20. Sockets.PipeServer(active)

    Note that the return type of the last invocation is different. This is because this server does not listen on TCP, but rather on a named pipe (Windows) or UNIX domain socket. Also note that Windows named pipe format has to be a specific pattern such that the name prefix (\\.\pipe\) uniquely identifies the file type. The difference between TCP and named pipes or UNIX domain sockets is subtle and has to do with the and connect methods. The method retrieves a connection to the client that is connecting on the server we just created, while the connect function connects to a server using the specified method. The function takes the same arguments as listen, so, assuming the environment (i.e. host, cwd, etc.) is the same you should be able to pass the same arguments to as you did to listen to establish the connection. So let’s try that out (after having created the server above):

    1. TCPSocket(open, 0 bytes waiting)
    3. julia> Hello World

    As expected we saw “Hello World” printed. So, let’s actually analyze what happened behind the scenes. When we called connect, we connect to the server we had just created. Meanwhile, the accept function returns a server-side connection to the newly created socket and prints “Hello World” to indicate that the connection was successful.

    A great strength of Julia is that since the API is exposed synchronously even though the I/O is actually happening asynchronously, we didn’t have to worry about callbacks or even making sure that the server gets to run. When we called the current task waited for the connection to be established and only continued executing after that was done. In this pause, the server task resumed execution (because a connection request was now available), accepted the connection, printed the message and waited for the next client. Reading and writing works in the same way. To see this, consider the following simple echo server:

    1. julia> @async begin
    2.            server = listen(2001)
    3.            while true
    4.                sock = accept(server)
    5.                @async while isopen(sock)
    6.                    write(sock, readline(sock, keep=true))
    7.                end
    8.            end
    9.        end
    10. Task (runnable) @0x00007fd31dc12e60
    12. julia> clientside = connect(2001)
    13. TCPSocket(RawFD(28) open, 0 bytes waiting)
    15. julia> @async while isopen(clientside)
    16.            write(stdout, readline(clientside, keep=true))
    17.        end
    18. Task (runnable) @0x00007fd31dc11870
    20. julia> println(clientside,"Hello World from the Echo Server")
    21. Hello World from the Echo Server

    As with other streams, use close to disconnect the socket:

    1. julia> close(clientside)

    Resolving IP Addresses

    One of the methods that does not follow the listen methods is connect(host::String,port), which will attempt to connect to the host given by the host parameter on the port given by the port parameter. It allows you to do things like:

    1. julia> connect("google.com", 80)
    2. TCPSocket(RawFD(30) open, 0 bytes waiting)

    At the base of this functionality is , which will do the appropriate address resolution:

    1. julia> getaddrinfo("google.com")
    2. ip"74.125.226.225"

    All I/O operations exposed by Base.read and can be performed asynchronously through the use of coroutines. You can create a new coroutine to read from or write to a stream using the macro:

    It’s common to run into situations where you want to perform multiple asynchronous operations concurrently and wait until they’ve all completed. You can use the @sync macro to cause your program to block until all of the coroutines it wraps around have exited:

    1. julia> using Sockets
    3. julia> @sync for hostname in ("google.com", "github.com", "julialang.org")
    4.            @async begin
    5.                conn = connect(hostname, 80)
    6.                write(conn, "GET / HTTP/1.1\r\nHost:$(hostname)\r\n\r\n")
    7.                readline(conn, keep=true)
    8.                println("Finished connection to $(hostname)")
    9.            end
    10.        end
    11. Finished connection to google.com
    12. Finished connection to github.com