105 lines
23 KiB
HTML
105 lines
23 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Networking and Streams · The Julia Language</title><script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-28835595-6', 'auto');
|
|
ga('send', 'pageview');
|
|
</script><link href="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css" rel="stylesheet" type="text/css"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link href="../assets/documenter.css" rel="stylesheet" type="text/css"/><link href="../assets/julia-manual.css" rel="stylesheet" type="text/css"/></head><body><nav class="toc"><a href="../index.html"><img class="logo" src="../assets/logo.png" alt="The Julia Language logo"/></a><h1>The Julia Language</h1><select id="version-selector" onChange="window.location.href=this.value" style="visibility: hidden"></select><form class="search" id="search-form" action="../search.html"><input id="search-query" name="q" type="text" placeholder="Search docs"/></form><ul><li><a class="toctext" href="../index.html">Home</a></li><li><span class="toctext">Manual</span><ul><li><a class="toctext" href="introduction.html">Introduction</a></li><li><a class="toctext" href="getting-started.html">Getting Started</a></li><li><a class="toctext" href="variables.html">Variables</a></li><li><a class="toctext" href="integers-and-floating-point-numbers.html">Integers and Floating-Point Numbers</a></li><li><a class="toctext" href="mathematical-operations.html">Mathematical Operations and Elementary Functions</a></li><li><a class="toctext" href="complex-and-rational-numbers.html">Complex and Rational Numbers</a></li><li><a class="toctext" href="strings.html">Strings</a></li><li><a class="toctext" href="functions.html">Functions</a></li><li><a class="toctext" href="control-flow.html">Control Flow</a></li><li><a class="toctext" href="variables-and-scoping.html">Scope of Variables</a></li><li><a class="toctext" href="types.html">Types</a></li><li><a class="toctext" href="methods.html">Methods</a></li><li><a class="toctext" href="constructors.html">Constructors</a></li><li><a class="toctext" href="conversion-and-promotion.html">Conversion and Promotion</a></li><li><a class="toctext" href="interfaces.html">Interfaces</a></li><li><a class="toctext" href="modules.html">Modules</a></li><li><a class="toctext" href="documentation.html">Documentation</a></li><li><a class="toctext" href="metaprogramming.html">Metaprogramming</a></li><li><a class="toctext" href="arrays.html">Multi-dimensional Arrays</a></li><li><a class="toctext" href="linear-algebra.html">Linear algebra</a></li><li class="current"><a class="toctext" href="networking-and-streams.html">Networking and Streams</a><ul class="internal"><li><a class="toctext" href="#Basic-Stream-I/O-1">Basic Stream I/O</a></li><li><a class="toctext" href="#Text-I/O-1">Text I/O</a></li><li><a class="toctext" href="#IO-Output-Contextual-Properties-1">IO Output Contextual Properties</a></li><li><a class="toctext" href="#Working-with-Files-1">Working with Files</a></li><li><a class="toctext" href="#A-simple-TCP-example-1">A simple TCP example</a></li><li><a class="toctext" href="#Resolving-IP-Addresses-1">Resolving IP Addresses</a></li></ul></li><li><a class="toctext" href="parallel-computing.html">Parallel Computing</a></li><li><a class="toctext" href="dates.html">Date and DateTime</a></li><li><a class="toctext" href="interacting-with-julia.html">Interacting With Julia</a></li><li><a class="toctext" href="running-external-programs.html">Running External Programs</a></li><li><a class="toctext" href="calling-c-and-fortran-code.html">Calling C and Fortran Code</a></li><li><a class="toctext" href="handling-operating-system-variation.html">Handling Operating System Variation</a></li><li><a class="toctext" href="environment-variables.html">Environment Variables</a></li><li><a class="toctext" href="embedding.html">Embedding Julia</a></li><li><a class="toctext" href="packages.html">Packages</a></li><li><a class="toctext" href="profile.html">Profiling</a></li><li><a class="toctext" href="stacktraces.html">Stack Traces</a></li><li><a class="toctext" href="performance-tips.html">Performance Tips</a></li><li><a class="toctext" href="workflow-tips.html">Workflow Tips</a></li><li><a class="toctext" href="style-guide.html">Style Guide</a></li><li><a class="toctext" href="faq.html">Frequently Asked Questions</a></li><li><a class="toctext" href="noteworthy-differences.html">Noteworthy Differences from other Languages</a></li><li><a class="toctext" href="unicode-input.html">Unicode Input</a></li></ul></li><li><span class="toctext">Standard Library</span><ul><li><a class="toctext" href="../stdlib/base.html">Essentials</a></li><li><a class="toctext" href="../stdlib/collections.html">Collections and Data Structures</a></li><li><a class="toctext" href="../stdlib/math.html">Mathematics</a></li><li><a class="toctext" href="../stdlib/numbers.html">Numbers</a></li><li><a class="toctext" href="../stdlib/strings.html">Strings</a></li><li><a class="toctext" href="../stdlib/arrays.html">Arrays</a></li><li><a class="toctext" href="../stdlib/parallel.html">Tasks and Parallel Computing</a></li><li><a class="toctext" href="../stdlib/linalg.html">Linear Algebra</a></li><li><a class="toctext" href="../stdlib/constants.html">Constants</a></li><li><a class="toctext" href="../stdlib/file.html">Filesystem</a></li><li><a class="toctext" href="../stdlib/io-network.html">I/O and Network</a></li><li><a class="toctext" href="../stdlib/punctuation.html">Punctuation</a></li><li><a class="toctext" href="../stdlib/sort.html">Sorting and Related Functions</a></li><li><a class="toctext" href="../stdlib/pkg.html">Package Manager Functions</a></li><li><a class="toctext" href="../stdlib/dates.html">Dates and Time</a></li><li><a class="toctext" href="../stdlib/iterators.html">Iteration utilities</a></li><li><a class="toctext" href="../stdlib/test.html">Unit Testing</a></li><li><a class="toctext" href="../stdlib/c.html">C Interface</a></li><li><a class="toctext" href="../stdlib/libc.html">C Standard Library</a></li><li><a class="toctext" href="../stdlib/libdl.html">Dynamic Linker</a></li><li><a class="toctext" href="../stdlib/profile.html">Profiling</a></li><li><a class="toctext" href="../stdlib/stacktraces.html">StackTraces</a></li><li><a class="toctext" href="../stdlib/simd-types.html">SIMD Support</a></li></ul></li><li><span class="toctext">Developer Documentation</span><ul><li><a class="toctext" href="../devdocs/reflection.html">Reflection and introspection</a></li><li><span class="toctext">Documentation of Julia's Internals</span><ul><li><a class="toctext" href="../devdocs/init.html">Initialization of the Julia runtime</a></li><li><a class="toctext" href="../devdocs/ast.html">Julia ASTs</a></li><li><a class="toctext" href="../devdocs/types.html">More about types</a></li><li><a class="toctext" href="../devdocs/object.html">Memory layout of Julia Objects</a></li><li><a class="toctext" href="../devdocs/eval.html">Eval of Julia code</a></li><li><a class="toctext" href="../devdocs/callconv.html">Calling Conventions</a></li><li><a class="toctext" href="../devdocs/compiler.html">High-level Overview of the Native-Code Generation Process</a></li><li><a class="toctext" href="../devdocs/functions.html">Julia Functions</a></li><li><a class="toctext" href="../devdocs/cartesian.html">Base.Cartesian</a></li><li><a class="toctext" href="../devdocs/meta.html">Talking to the compiler (the <code>:meta</code> mechanism)</a></li><li><a class="toctext" href="../devdocs/subarrays.html">SubArrays</a></li><li><a class="toctext" href="../devdocs/sysimg.html">System Image Building</a></li><li><a class="toctext" href="../devdocs/llvm.html">Working with LLVM</a></li><li><a class="toctext" href="../devdocs/stdio.html">printf() and stdio in the Julia runtime</a></li><li><a class="toctext" href="../devdocs/boundscheck.html">Bounds checking</a></li><li><a class="toctext" href="../devdocs/locks.html">Proper maintenance and care of multi-threading locks</a></li><li><a class="toctext" href="../devdocs/offset-arrays.html">Arrays with custom indices</a></li><li><a class="toctext" href="../devdocs/libgit2.html">Base.LibGit2</a></li><li><a class="toctext" href="../devdocs/require.html">Module loading</a></li></ul></li><li><span class="toctext">Developing/debugging Julia's C code</span><ul><li><a class="toctext" href="../devdocs/backtraces.html">Reporting and analyzing crashes (segfaults)</a></li><li><a class="toctext" href="../devdocs/debuggingtips.html">gdb debugging tips</a></li><li><a class="toctext" href="../devdocs/valgrind.html">Using Valgrind with Julia</a></li><li><a class="toctext" href="../devdocs/sanitizers.html">Sanitizer support</a></li></ul></li></ul></li></ul></nav><article id="docs"><header><nav><ul><li>Manual</li><li><a href="networking-and-streams.html">Networking and Streams</a></li></ul><a class="edit-page" href="https://github.com/JuliaLang/julia/blob/master/doc/src/manual/networking-and-streams.md"><span class="fa"></span> Edit on GitHub</a></nav><hr/><div id="topbar"><span>Networking and Streams</span><a class="fa fa-bars" href="#"></a></div></header><h1><a class="nav-anchor" id="Networking-and-Streams-1" href="#Networking-and-Streams-1">Networking and Streams</a></h1><p>Julia provides a rich interface to deal with streaming I/O objects such as terminals, pipes and TCP sockets. This interface, though asynchronous at the system level, is presented in a synchronous manner to the programmer and it is usually unnecessary to think about the underlying asynchronous operation. This is achieved by making heavy use of Julia cooperative threading (<a href="control-flow.html#man-tasks-1">coroutine</a>) functionality.</p><h2><a class="nav-anchor" id="Basic-Stream-I/O-1" href="#Basic-Stream-I/O-1">Basic Stream I/O</a></h2><p>All Julia streams expose at least a <a href="../stdlib/io-network.html#Base.read"><code>read()</code></a> and a <a href="../stdlib/io-network.html#Base.write"><code>write()</code></a> method, taking the stream as their first argument, e.g.:</p><pre><code class="language-julia-repl">julia> write(STDOUT,"Hello World"); # suppress return value 11 with ;
|
|
Hello World
|
|
julia> read(STDIN,Char)
|
|
|
|
'\n': ASCII/Unicode U+000a (category Cc: Other, control)</code></pre><p>Note that <a href="../stdlib/io-network.html#Base.write"><code>write()</code></a> returns 11, the number of bytes (in <code>"Hello World"</code>) written to <a href="../stdlib/io-network.html#Base.STDOUT"><code>STDOUT</code></a>, but this return value is suppressed with the <code>;</code>.</p><p>Here Enter was pressed again so that Julia would read the newline. Now, as you can see from this example, <a href="../stdlib/io-network.html#Base.write"><code>write()</code></a> takes the data to write as its second argument, while <a href="../stdlib/io-network.html#Base.read"><code>read()</code></a> takes the type of the data to be read as the second argument.</p><p>For example, to read a simple byte array, we could do:</p><pre><code class="language-julia-repl">julia> x = zeros(UInt8, 4)
|
|
4-element Array{UInt8,1}:
|
|
0x00
|
|
0x00
|
|
0x00
|
|
0x00
|
|
|
|
julia> read!(STDIN, x)
|
|
abcd
|
|
4-element Array{UInt8,1}:
|
|
0x61
|
|
0x62
|
|
0x63
|
|
0x64</code></pre><p>However, since this is slightly cumbersome, there are several convenience methods provided. For example, we could have written the above as:</p><pre><code class="language-julia-repl">julia> read(STDIN,4)
|
|
abcd
|
|
4-element Array{UInt8,1}:
|
|
0x61
|
|
0x62
|
|
0x63
|
|
0x64</code></pre><p>or if we had wanted to read the entire line instead:</p><pre><code class="language-julia-repl">julia> readline(STDIN)
|
|
abcd
|
|
"abcd"</code></pre><p>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.</p><p>To read every line from <a href="../stdlib/io-network.html#Base.STDIN"><code>STDIN</code></a> you can use <a href="../stdlib/io-network.html#Base.eachline"><code>eachline()</code></a>:</p><pre><code class="language-julia">for line in eachline(STDIN)
|
|
print("Found $line")
|
|
end</code></pre><p>or <a href="../stdlib/io-network.html#Base.read"><code>read()</code></a> if you wanted to read by character instead:</p><pre><code class="language-julia">while !eof(STDIN)
|
|
x = read(STDIN, Char)
|
|
println("Found: $x")
|
|
end</code></pre><h2><a class="nav-anchor" id="Text-I/O-1" href="#Text-I/O-1">Text I/O</a></h2><p>Note that the <a href="../stdlib/io-network.html#Base.write"><code>write()</code></a> 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:</p><pre><code class="language-julia-repl">julia> write(STDOUT,0x61); # suppress return value 1 with ;
|
|
a</code></pre><p>Note that <code>a</code> is written to <a href="../stdlib/io-network.html#Base.STDOUT"><code>STDOUT</code></a> by the <a href="../stdlib/io-network.html#Base.write"><code>write()</code></a> function and that the returned value is <code>1</code> (since <code>0x61</code> is one byte).</p><p>For text I/O, use the <a href="../stdlib/io-network.html#Base.print"><code>print()</code></a> or <a href="../stdlib/io-network.html#Base.show-Tuple{Any}"><code>show()</code></a> methods, depending on your needs (see the standard library reference for a detailed discussion of the difference between the two):</p><pre><code class="language-julia-repl">julia> print(STDOUT, 0x61)
|
|
97</code></pre><h2><a class="nav-anchor" id="IO-Output-Contextual-Properties-1" href="#IO-Output-Contextual-Properties-1">IO Output Contextual Properties</a></h2><p>Sometimes IO output can benefit from the ability to pass contextual information into show methods. The <a href="../stdlib/io-network.html#Base.IOContext"><code>IOContext</code></a> object provides this framework for associating arbitrary metadata with an IO object. For example, <a href="../stdlib/io-network.html#Base.showcompact"><code>showcompact</code></a> adds a hinting parameter to the IO object that the invoked show method should print a shorter output (if applicable).</p><h2><a class="nav-anchor" id="Working-with-Files-1" href="#Working-with-Files-1">Working with Files</a></h2><p>Like many other environments, Julia has an <a href="../stdlib/io-network.html#Base.open"><code>open()</code></a> function, which takes a filename and returns an <code>IOStream</code> object that you can use to read and write things from the file. For example if we have a file, <code>hello.txt</code>, whose contents are <code>Hello, World!</code>:</p><pre><code class="language-julia-repl">julia> f = open("hello.txt")
|
|
IOStream(<file hello.txt>)
|
|
|
|
julia> readlines(f)
|
|
1-element Array{String,1}:
|
|
"Hello, World!"</code></pre><p>If you want to write to a file, you can open it with the write (<code>"w"</code>) flag:</p><pre><code class="language-julia-repl">julia> f = open("hello.txt","w")
|
|
IOStream(<file hello.txt>)
|
|
|
|
julia> write(f,"Hello again.")
|
|
12</code></pre><p>If you examine the contents of <code>hello.txt</code> at this point, you will notice that it is empty; nothing has actually been written to disk yet. This is because the <code>IOStream</code> must be closed before the write is actually flushed to disk:</p><pre><code class="language-julia-repl">julia> close(f)</code></pre><p>Examining <code>hello.txt</code> again will show its contents have been changed.</p><p>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 <a href="../stdlib/io-network.html#Base.open"><code>open()</code></a> 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:</p><pre><code class="language-julia">function read_and_capitalize(f::IOStream)
|
|
return uppercase(readstring(f))
|
|
end</code></pre><p>You can call:</p><pre><code class="language-julia-repl">julia> open(read_and_capitalize, "hello.txt")
|
|
"HELLO AGAIN."</code></pre><p>to open <code>hello.txt</code>, call <code>read_and_capitalize on it</code>, close <code>hello.txt</code> and return the capitalized contents.</p><p>To avoid even having to define a named function, you can use the <code>do</code> syntax, which creates an anonymous function on the fly:</p><pre><code class="language-julia-repl">julia> open("hello.txt") do f
|
|
uppercase(readstring(f))
|
|
end
|
|
"HELLO AGAIN."</code></pre><h2><a class="nav-anchor" id="A-simple-TCP-example-1" href="#A-simple-TCP-example-1">A simple TCP example</a></h2><p>Let's jump right in with a simple example involving TCP sockets. Let's first create a simple server:</p><pre><code class="language-julia-repl">julia> @async begin
|
|
server = listen(2000)
|
|
while true
|
|
sock = accept(server)
|
|
println("Hello World\n")
|
|
end
|
|
end
|
|
Task (runnable) @0x00007fd31dc11ae0</code></pre><p>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 <a href="../stdlib/io-network.html#Base.listen-Tuple{Any}"><code>listen()</code></a> 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:</p><pre><code class="language-julia-repl">julia> listen(2000) # Listens on localhost:2000 (IPv4)
|
|
TCPServer(active)
|
|
|
|
julia> listen(ip"127.0.0.1",2000) # Equivalent to the first
|
|
TCPServer(active)
|
|
|
|
julia> listen(ip"::1",2000) # Listens on localhost:2000 (IPv6)
|
|
TCPServer(active)
|
|
|
|
julia> listen(IPv4(0),2001) # Listens on port 2001 on all IPv4 interfaces
|
|
TCPServer(active)
|
|
|
|
julia> listen(IPv6(0),2001) # Listens on port 2001 on all IPv6 interfaces
|
|
TCPServer(active)
|
|
|
|
julia> listen("testsocket") # Listens on a UNIX domain socket/named pipe
|
|
PipeServer(active)</code></pre><p>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. The difference is subtle and has to do with the <a href="../stdlib/io-network.html#Base.accept"><code>accept()</code></a> and <a href="../stdlib/io-network.html#Base.connect-Tuple{TCPSocket,Integer}"><code>connect()</code></a> methods. The <a href="../stdlib/io-network.html#Base.accept"><code>accept()</code></a> method retrieves a connection to the client that is connecting on the server we just created, while the <a href="../stdlib/io-network.html#Base.connect-Tuple{TCPSocket,Integer}"><code>connect()</code></a> function connects to a server using the specified method. The <a href="../stdlib/io-network.html#Base.connect-Tuple{TCPSocket,Integer}"><code>connect()</code></a> function takes the same arguments as <a href="../stdlib/io-network.html#Base.listen-Tuple{Any}"><code>listen()</code></a>, so, assuming the environment (i.e. host, cwd, etc.) is the same you should be able to pass the same arguments to <a href="../stdlib/io-network.html#Base.connect-Tuple{TCPSocket,Integer}"><code>connect()</code></a> as you did to listen to establish the connection. So let's try that out (after having created the server above):</p><pre><code class="language-julia-repl">julia> connect(2000)
|
|
TCPSocket(open, 0 bytes waiting)
|
|
|
|
julia> Hello World</code></pre><p>As expected we saw "Hello World" printed. So, let's actually analyze what happened behind the scenes. When we called <a href="../stdlib/io-network.html#Base.connect-Tuple{TCPSocket,Integer}"><code>connect()</code></a>, 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.</p><p>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 callbacks or even making sure that the server gets to run. When we called <a href="../stdlib/io-network.html#Base.connect-Tuple{TCPSocket,Integer}"><code>connect()</code></a> 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:</p><pre><code class="language-julia-repl">julia> @async begin
|
|
server = listen(2001)
|
|
while true
|
|
sock = accept(server)
|
|
@async while isopen(sock)
|
|
write(sock,readline(sock))
|
|
end
|
|
end
|
|
end
|
|
Task (runnable) @0x00007fd31dc12e60
|
|
|
|
julia> clientside = connect(2001)
|
|
TCPSocket(RawFD(28) open, 0 bytes waiting)
|
|
|
|
julia> @async while true
|
|
write(STDOUT,readline(clientside))
|
|
end
|
|
Task (runnable) @0x00007fd31dc11870
|
|
|
|
julia> println(clientside,"Hello World from the Echo Server")
|
|
Hello World from the Echo Server</code></pre><p>As with other streams, use <a href="../stdlib/io-network.html#Base.close"><code>close()</code></a> to disconnect the socket:</p><pre><code class="language-julia-repl">julia> close(clientside)</code></pre><h2><a class="nav-anchor" id="Resolving-IP-Addresses-1" href="#Resolving-IP-Addresses-1">Resolving IP Addresses</a></h2><p>One of the <a href="../stdlib/io-network.html#Base.connect-Tuple{TCPSocket,Integer}"><code>connect()</code></a> methods that does not follow the <a href="../stdlib/io-network.html#Base.listen-Tuple{Any}"><code>listen()</code></a> methods is <code>connect(host::String,port)</code>, which will attempt to connect to the host given by the <code>host</code> parameter on the port given by the port parameter. It allows you to do things like:</p><pre><code class="language-julia-repl">julia> connect("google.com",80)
|
|
TCPSocket(RawFD(30) open, 0 bytes waiting)</code></pre><p>At the base of this functionality is <a href="../stdlib/io-network.html#Base.getaddrinfo"><code>getaddrinfo()</code></a>, which will do the appropriate address resolution:</p><pre><code class="language-julia-repl">julia> getaddrinfo("google.com")
|
|
ip"74.125.226.225"</code></pre><footer><hr/><a class="previous" href="linear-algebra.html"><span class="direction">Previous</span><span class="title">Linear algebra</span></a><a class="next" href="parallel-computing.html"><span class="direction">Next</span><span class="title">Parallel Computing</span></a></footer></article></body></html>
|