[Swift-commit] r8053 - www/Swift-T
wozniak at ci.uchicago.edu
wozniak at ci.uchicago.edu
Fri Jul 18 16:56:10 CDT 2014
Author: wozniak
Date: 2014-07-18 17:13:49 -0500 (Fri, 18 Jul 2014)
New Revision: 8053
Modified:
www/Swift-T/swift.html
Log:
Document Julia
Modified: www/Swift-T/swift.html
===================================================================
--- www/Swift-T/swift.html 2014-07-18 22:02:59 UTC (rev 8052)
+++ www/Swift-T/swift.html 2014-07-18 22:13:49 UTC (rev 8053)
@@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
-<meta name="generator" content="AsciiDoc 8.6.7" />
+<meta name="generator" content="AsciiDoc 8.6.9" />
<title>Swift/T Guide</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
@@ -87,10 +87,16 @@
ul > li { color: #aaa; }
ul > li > * { color: black; }
-pre {
+.monospaced, code, pre {
+ font-family: "Courier New", Courier, monospace;
+ font-size: inherit;
+ color: navy;
padding: 0;
margin: 0;
}
+pre {
+ white-space: pre-wrap;
+}
#author {
color: #527bbd;
@@ -219,7 +225,7 @@
}
div.imageblock div.content { padding-left: 0; }
-span.image img { border-style: none; }
+span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }
dl {
@@ -415,12 +421,6 @@
*
* */
-tt {
- font-family: "Courier New", Courier, monospace;
- font-size: inherit;
- color: navy;
-}
-
div.tableblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
@@ -454,12 +454,6 @@
*
* */
-.monospaced {
- font-family: "Courier New", Courier, monospace;
- font-size: inherit;
- color: navy;
-}
-
table.tableblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
@@ -540,6 +534,8 @@
body.manpage div#toc { display: none; }
}
+
+
/* SWIFT/T GUIDE CUSTOMIZATIONS */
a:visited {
@@ -748,7 +744,7 @@
<body class="article" style="max-width:750px">
<div id="header">
<h1>Swift/T Guide</h1>
-<span id="author">v0.5.0, April 2014</span><br />
+<span id="author">v0.6.0, July 2014</span><br />
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
@@ -798,7 +794,7 @@
<p>
Many operating systems provide packages with MPI implementations
that are usable, but often outdated.
- E.g. the <tt>mpich2</tt> package on Debian/Ubuntu.
+ E.g. the <code>mpich2</code> package on Debian/Ubuntu.
</p>
</li>
<li>
@@ -813,8 +809,8 @@
</p>
<div class="paragraph"><p>Swift/T attempts to use MPI 3.0 functionality by default. If you
are using an MPI implementation that does not support the MPI 3.0 standard,
-you must set <tt>MPI_VERSION=2</tt> (if using the <tt>exm-setup.zsh</tt> build process),
-or provide the <tt>--enable-mpi-2</tt> configure option (if using
+you must set <code>MPI_VERSION=2</code> (if using the <code>exm-setup.zsh</code> build process),
+or provide the <code>--enable-mpi-2</code> configure option (if using
the manual build process).</p></div>
</li>
</ul></div>
@@ -829,7 +825,7 @@
Tcl is available through the package manager on many systems.
You may need to install an additional Tcl development package
in addition to the standard tcl package,
- e.g. <tt>tcl8.6</tt> plus <tt>tcl8.6-dev</tt> on Debian/Ubuntu systems.
+ e.g. <code>tcl8.6</code> plus <code>tcl8.6-dev</code> on Debian/Ubuntu systems.
</p>
</li>
<li>
@@ -846,7 +842,7 @@
<div class="ulist"><ul>
<li>
<p>
-You can check if SWIG is installed by running <tt>swig -version</tt>
+You can check if SWIG is installed by running <code>swig -version</code>
</p>
</li>
<li>
@@ -875,7 +871,7 @@
</p>
<div class="listingblock">
<div class="content">
-<pre><tt>wget http://www.mcs.anl.gov/exm/local/downloads/exm-0.5.0.tar.gz</tt></pre>
+<pre><code>wget http://www.mcs.anl.gov/exm/local/downloads/exm-0.5.0.tar.gz</code></pre>
</div></div>
<div class="paragraph"><p>Cf. <a href="http://www.mcs.anl.gov/exm/local/downloads/downloads.html">Swift/T Downloads</a>
for other packages</p></div>
@@ -886,15 +882,15 @@
</p>
<div class="listingblock">
<div class="content">
-<pre><tt>tar xfz exm-trunk.tar.gz
-cd exm-trunk</tt></pre>
+<pre><code>tar xfz exm-trunk.tar.gz
+cd exm-trunk</code></pre>
</div></div>
</li>
<li>
<p>
-Edit the settings file: <tt>exm-settings.sh</tt>
+Edit the settings file: <code>exm-settings.sh</code>
</p>
-<div class="paragraph"><p>At a minimum, you must set the install directory with <tt>EXM_PREFIX</tt>.
+<div class="paragraph"><p>At a minimum, you must set the install directory with <code>EXM_PREFIX</code>.
On a standard system, no further configuration may be needed.
In many cases, however, you will need to modify additional
configuration settings so that all prerequisites can
@@ -907,7 +903,7 @@
<td class="icon">
<div class="title">Tip</div>
</td>
-<td class="content">Save your <tt>exm-settings.sh</tt> when you download a new package</td>
+<td class="content">Save your <code>exm-settings.sh</code> when you download a new package</td>
</tr></table>
</div>
</li>
@@ -917,16 +913,16 @@
</p>
<div class="listingblock">
<div class="content">
-<pre><tt>./exm-setup.zsh</tt></pre>
+<pre><code>./exm-setup.zsh</code></pre>
</div></div>
-<div class="paragraph"><p>If <tt>exm-setup.zsh</tt> does not succeed on your system, see Section
+<div class="paragraph"><p>If <code>exm-setup.zsh</code> does not succeed on your system, see Section
<a href="#Build_configuration">Build configuration</a> below.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Tip</div>
</td>
-<td class="content">if you want more control than <tt>exm-setup.zsh</tt> provides, you can
+<td class="content">if you want more control than <code>exm-setup.zsh</code> provides, you can
build Swift/T with the
<a href="#Manual_build_configuration">manual configure/make workflow</a>.</td>
</tr></table>
@@ -938,8 +934,8 @@
</p>
<div class="listingblock">
<div class="content">
-<pre><tt>PATH=${PATH}:/path/to/exm-install/turbine/bin
-PATH=${PATH}:/path/to/exm-install/stc/bin</tt></pre>
+<pre><code>PATH=${PATH}:/path/to/exm-install/turbine/bin
+PATH=${PATH}:/path/to/exm-install/stc/bin</code></pre>
</div></div>
</li>
</ol></div>
@@ -949,26 +945,26 @@
<div class="sect1">
<h2 id="_usage">3. Usage</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Swift code is conventionally written in <tt>*.swift</tt> files. Turbine
-code is stored in Tcl files <tt>*.tcl</tt>. After writing the Swift program
-<tt>program.swift</tt>, run:</p></div>
+<div class="paragraph"><p>Swift code is conventionally written in <code>*.swift</code> files. Turbine
+code is stored in Tcl files <code>*.tcl</code>. After writing the Swift program
+<code>program.swift</code>, run:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>stc program.swift</tt></pre>
+<pre><code>stc program.swift</code></pre>
</div></div>
-<div class="paragraph"><p>This will compile the program to <tt>program.tcl</tt>. A second, optional
+<div class="paragraph"><p>This will compile the program to <code>program.tcl</code>. A second, optional
argument may be given as an alternate output file name.</p></div>
<div class="paragraph"><p>Then, to run the program, use Turbine:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>turbine -n 4 program.tcl</tt></pre>
+<pre><code>turbine -n 4 program.tcl</code></pre>
</div></div>
<div class="paragraph"><p>See the <a href="#Turbine">Turbine section</a> for more information about
running the program.</p></div>
<div class="paragraph" id="stc_arguments"><p>STC accepts the following arguments:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>-A <em>name</em>=<em>value</em></tt>
+<code>-A <em>name</em>=<em>value</em></code>
</dt>
<dd>
<p>
@@ -979,7 +975,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-D <em>macro</em>=<em>value</em></tt>
+<code>-D <em>macro</em>=<em>value</em></code>
</dt>
<dd>
<p>
@@ -987,7 +983,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-E</tt>
+<code>-E</code>
</dt>
<dd>
<p>
@@ -996,7 +992,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-I</tt>
+<code>-I</code>
</dt>
<dd>
<p>
@@ -1004,7 +1000,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-O</tt>
+<code>-O</code>
</dt>
<dd>
<p>
@@ -1012,15 +1008,15 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-j</tt>
+<code>-j</code>
</dt>
<dd>
<p>
-Set the location of the <tt>java</tt> executable.
+Set the location of the <code>java</code> executable.
</p>
</dd>
<dt class="hdlist1">
-<tt>-p</tt>
+<code>-p</code>
</dt>
<dd>
<p>
@@ -1028,7 +1024,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-u</tt>
+<code>-u</code>
</dt>
<dd>
<p>
@@ -1036,7 +1032,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-v</tt>
+<code>-v</code>
</dt>
<dd>
<p>
@@ -1044,7 +1040,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-V</tt>
+<code>-V</code>
</dt>
<dd>
<p>
@@ -1052,16 +1048,16 @@
</p>
</dd>
</dl></div>
-<div class="paragraph"><p>STC runs as a Java program. You may use <tt>-j</tt> to set the Java VM
-executable. This Java VM must be compatible with the <tt>javac</tt> used to
+<div class="paragraph"><p>STC runs as a Java program. You may use <code>-j</code> to set the Java VM
+executable. This Java VM must be compatible with the <code>javac</code> used to
compile STC.</p></div>
<div class="paragraph"><p>By default, STC runs the user script through the C preprocessor
-(<tt>cpp</tt>), enabling arbitrary macro processing, etc. The <tt>-D</tt>, <tt>-E</tt>,
-<tt>-I</tt>, and <tt>-p</tt> options are relevant to this feature.</p></div>
+(<code>cpp</code>), enabling arbitrary macro processing, etc. The <code>-D</code>, <code>-E</code>,
+<code>-I</code>, and <code>-p</code> options are relevant to this feature.</p></div>
<div class="paragraph"><p>Additional arguments for advanced users/developers:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>-C</tt>
+<code>-C</code>
</dt>
<dd>
<p>
@@ -1069,7 +1065,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-l</tt>
+<code>-l</code>
</dt>
<dd>
<p>
@@ -1077,7 +1073,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-L</tt>
+<code>-L</code>
</dt>
<dd>
<p>
@@ -1085,7 +1081,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-T</tt>
+<code>-T</code>
</dt>
<dd>
<p>
@@ -1093,7 +1089,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-t</tt>
+<code>-t</code>
</dt>
<dd>
<p>
@@ -1107,24 +1103,24 @@
<h2 id="_program_structure">4. Program structure</h2>
<div class="sectionbody">
<div class="paragraph"><p>Swift programs are composed of <em>composite</em> functions. These
-share syntax with C-like languages. The program starts in <tt>main()</tt>.
+share syntax with C-like languages. The program starts in <code>main()</code>.
The following is a complete Swift program:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>main
-{}</tt></pre>
+<pre><code>main
+{}</code></pre>
</div></div>
-<div class="paragraph"><p>STC input is preprocessed by <tt>cpp</tt>, the C preprocessor.</p></div>
+<div class="paragraph"><p>STC input is preprocessed by <code>cpp</code>, the C preprocessor.</p></div>
<div class="paragraph"><p>Hello world is written as:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>import io;
+<pre><code>import io;
main
{
printf("Hello world");
-}</tt></pre>
+}</code></pre>
</div></div>
-<div class="paragraph"><p>The newline is supplied by <tt>printf()</tt>.</p></div>
+<div class="paragraph"><p>The newline is supplied by <code>printf()</code>.</p></div>
<div class="paragraph"><p>Swift programs eventually call <em>leaf</em> functions, which are the primary
way to do work. From the perspective of the Swift script, they are
atomic operations that wait for input variables and set output
@@ -1138,17 +1134,17 @@
<div class="paragraph"><p>Swift supports C/C++-style comments:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>// This is a comment
+<pre><code>// This is a comment
/* This is a
comment */
/** Also a
-comment */</tt></pre>
+comment */</code></pre>
</div></div>
<div class="paragraph"><p>Additionally, if the preprocessor is disabled, single-line comments
starting with # are supported:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt># This will work if source file is not preprocessed</tt></pre>
+<pre><code># This will work if source file is not preprocessed</code></pre>
</div></div>
</div>
</div>
@@ -1160,8 +1156,8 @@
function and variable definitions from that module into your program.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>import io;
-import mypackage.mymodule;</tt></pre>
+<pre><code>import io;
+import mypackage.mymodule;</code></pre>
</div></div>
<div class="paragraph"><p>The mechanisms for locating source files is as follows:</p></div>
<div class="ulist"><ul>
@@ -1179,31 +1175,31 @@
</li>
<li>
<p>
-Additional directories can be added with the <tt>-I</tt> option to STC.
+Additional directories can be added with the <code>-I</code> option to STC.
</p>
</li>
<li>
<p>
-Swift source files must have a <tt>.swift</tt> suffix. E.g. <tt>import io;</tt>
- looks for a file called <tt>io.swift</tt>.
+Swift source files must have a <code>.swift</code> suffix. E.g. <code>import io;</code>
+ looks for a file called <code>io.swift</code>.
</p>
</li>
<li>
<p>
-In the case of a multi-part import name, E.g. <tt>import mypackage.mymodule</tt>,
- then, it looks for <tt>mymodule.swift</tt> in subdirectory <tt>mypackage</tt>.
+In the case of a multi-part import name, E.g. <code>import mypackage.mymodule</code>,
+ then, it looks for <code>mymodule.swift</code> in subdirectory <code>mypackage</code>.
</p>
</li>
</ul></div>
-<div class="paragraph"><p>The alternative <tt>#include</tt> statement textually includes an entire
+<div class="paragraph"><p>The alternative <code>#include</code> statement textually includes an entire
file using the C preprocessor at the point of the statement.
-Note that <tt>#include</tt> will only work if the preprocessor is enabled
-on the current file. In contrast to <tt>import</tt>, <tt>#include</tt> will run the
-C preprocessor on any included modules. <tt>import</tt> is recommended over
-<tt>#include</tt> unless the imported module requires preprocessing.</p></div>
+Note that <code>#include</code> will only work if the preprocessor is enabled
+on the current file. In contrast to <code>import</code>, <code>#include</code> will run the
+C preprocessor on any included modules. <code>import</code> is recommended over
+<code>#include</code> unless the imported module requires preprocessing.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>#include <mypackage/mymodule.swift></tt></pre>
+<pre><code>#include <mypackage/mymodule.swift></code></pre>
</div></div>
</div>
</div>
@@ -1213,19 +1209,19 @@
<div class="paragraph"><p>Swift expressions are evaluated in <em>dataflow</em> order:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>int z1,z2;
+<pre><code>int z1,z2;
int y;
int x = f(y);
y = g(2);
z1 = h(x,y,1);
z2 = h(x,y,2);
-int output = r(z1,z2);</tt></pre>
+int output = r(z1,z2);</code></pre>
</div></div>
<div class="paragraph"><p>This allows code to execute as concurrently as possible, limited
-only by data availability. In this example, <tt>g()</tt> runs first, because it
-is dependent only on a literal. When <tt>y</tt> is set, <tt>f()</tt> runs, setting
-<tt>x</tt>. Then, two invocations of <tt>h()</tt> execute. Finally, <tt>z1</tt> and <tt>z2</tt>
-are set, allowing <tt>r()</tt> to run.</p></div>
+only by data availability. In this example, <code>g()</code> runs first, because it
+is dependent only on a literal. When <code>y</code> is set, <code>f()</code> runs, setting
+<code>x</code>. Then, two invocations of <code>h()</code> execute. Finally, <code>z1</code> and <code>z2</code>
+are set, allowing <code>r()</code> to run.</p></div>
<div class="paragraph"><p>Variables may be assigned only once. Multiple assignment is often
detected at compile time, and will always be detected at run time,
resulting in a run time error. If variable is not assigned,
@@ -1240,25 +1236,25 @@
<h2 id="_composite_functions">8. Composite functions</h2>
<div class="sectionbody">
<div class="paragraph"><p>Swift code is written in composite functions. The composite function
-<tt>main</tt> is required.</p></div>
+<code>main</code> is required.</p></div>
<div class="paragraph"><p>Composite functions have the form:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>[(<output list>)] function_name [(<input list>)]
+<pre><code>[(<output list>)] function_name [(<input list>)]
{
statement;
statement;
...
-}</tt></pre>
+}</code></pre>
</div></div>
-<div class="paragraph"><p>An empty input or output list may be omitted or written as <tt>()</tt>.</p></div>
+<div class="paragraph"><p>An empty input or output list may be omitted or written as <code>()</code>.</p></div>
<div class="paragraph"><p>The output list may have more than one entry. Thus, assignments
may be written as:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>x1, x2 = f(i1, i2);
+<pre><code>x1, x2 = f(i1, i2);
// or equivalently:
-(x1, x2) = f(i1, i2);</tt></pre>
+(x1, x2) = f(i1, i2);</code></pre>
</div></div>
</div>
</div>
@@ -1275,7 +1271,7 @@
<div class="paragraph"><p>Swift has the conventional types:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>string</tt>
+<code>string</code>
</dt>
<dd>
<p>
@@ -1283,7 +1279,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>int</tt>
+<code>int</code>
</dt>
<dd>
<p>
@@ -1291,7 +1287,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>float</tt>
+<code>float</code>
</dt>
<dd>
<p>
@@ -1299,7 +1295,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>boolean</tt>
+<code>boolean</code>
</dt>
<dd>
<p>
@@ -1307,7 +1303,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>file</tt>
+<code>file</code>
</dt>
<dd>
<p>
@@ -1315,7 +1311,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>blob</tt>
+<code>blob</code>
</dt>
<dd>
<p>
@@ -1327,83 +1323,83 @@
<div class="ulist"><ul>
<li>
<p>
-<tt>int</tt> literals are written as decimal numbers, e.g. <tt>-1234</tt>
+<code>int</code> literals are written as decimal numbers, e.g. <code>-1234</code>
</p>
</li>
<li>
<p>
-<tt>float</tt> literals are written as decimal numbers with a decimal point,
- e.g <tt>5493.352</tt> or <tt>1.0</tt>.
+<code>float</code> literals are written as decimal numbers with a decimal point,
+ e.g <code>5493.352</code> or <code>1.0</code>.
Scientific notation may be used,
- as in <tt>2.3e-2</tt> which is equivalent to <tt>0.023</tt>.
- The literals <tt>NaN</tt> and <tt>inf</tt> may be used. In some contexts <tt>int</tt>
- literals are promoted automatically to <tt>float</tt>.
+ as in <code>2.3e-2</code> which is equivalent to <code>0.023</code>.
+ The literals <code>NaN</code> and <code>inf</code> may be used. In some contexts <code>int</code>
+ literals are promoted automatically to <code>float</code>.
</p>
</li>
<li>
<p>
-<tt>boolean</tt> literals <tt>true</tt> and <tt>false</tt> may be used.
+<code>boolean</code> literals <code>true</code> and <code>false</code> may be used.
</p>
</li>
<li>
<p>
-<tt>string</tt> literals are enclosed in double quotes, with a range of escape
+<code>string</code> literals are enclosed in double quotes, with a range of escape
sequences supported:
</p>
<div class="ulist"><ul>
<li>
<p>
-<tt>\\</tt> for a single backslash
+<code>\\</code> for a single backslash
</p>
</li>
<li>
<p>
-<tt>\"</tt> for a quote
+<code>\"</code> for a quote
</p>
</li>
<li>
<p>
-<tt>\n</tt> for newline
+<code>\n</code> for newline
</p>
</li>
<li>
<p>
-<tt>\t</tt> for tab
+<code>\t</code> for tab
</p>
</li>
<li>
<p>
-<tt>\a</tt> (alarm)
+<code>\a</code> (alarm)
</p>
</li>
<li>
<p>
-<tt>\b</tt> (backspace)
+<code>\b</code> (backspace)
</p>
</li>
<li>
<p>
-<tt>\f</tt> (form feed)
+<code>\f</code> (form feed)
</p>
</li>
<li>
<p>
-<tt>\r</tt> (carriage return)
+<code>\r</code> (carriage return)
</p>
</li>
<li>
<p>
-<tt>\v</tt> (vertical tab)
+<code>\v</code> (vertical tab)
</p>
</li>
<li>
<p>
-octal escape codes, e.g. <tt>\001</tt>
+octal escape codes, e.g. <code>\001</code>
</p>
</li>
<li>
<p>
-hexadecimal escape codes, e.g. <tt>\xf2</tt>
+hexadecimal escape codes, e.g. <code>\xf2</code>
</p>
</li>
<li>
@@ -1424,11 +1420,11 @@
</p>
<div class="listingblock">
<div class="content">
-<pre><tt>string s =
+<pre><code>string s =
"""
line data 1
line data 2
-""";</tt></pre>
+""";</code></pre>
</div></div>
</li>
<li>
@@ -1441,7 +1437,7 @@
<strong>Note:</strong> Multi-line strings are somewhat incompatible with the C preprocessor:
if you try to compile a Swift program using multi-line strings with
the preprocessor enabled, you will likely see warnings or strange
- behavior. To disable the C preprocessor, use the <tt>-p</tt> option
+ behavior. To disable the C preprocessor, use the <code>-p</code> option
to STC.
</p>
</li>
@@ -1455,28 +1451,28 @@
as any other variable. The main difference is that a file can be
<strong>mapped</strong> to path in a filesystem. Assigning to a mapped file variable
results in a file being created in the file system at the specified path.
-File paths can be arbitrary Swift expressions of type <tt>string</tt>. Absolute
+File paths can be arbitrary Swift expressions of type <code>string</code>. Absolute
paths or relative paths are specified, with relative paths interpreted
relative to the path in which turbine was run.
File variables can also be initialized with data from a pre-existing
-file using the <tt>input_file</tt> function. File paths are relative to the
+file using the <code>input_file</code> function. File paths are relative to the
working directory for Turbine.</p></div>
-<div class="paragraph"><p>For example, if <tt>/home/user/in.txt</tt> is a file with some data in it,
-the following Swift program will copy the file to <tt>/home/user/out.txt</tt>.</p></div>
+<div class="paragraph"><p>For example, if <code>/home/user/in.txt</code> is a file with some data in it,
+the following Swift program will copy the file to <code>/home/user/out.txt</code>.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>main
+<pre><code>main
{
file x = input_file("/home/user/in.txt");
file y <"/home/user/out.txt">; // Declare a mapped file
y = x; // Do the copy
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>A range of functions to work with files are provided in the
-<tt>files</tt> library module.</p></div>
+<code>files</code> library module.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>// Initialize an array of files from a range of files on disk with glob
+<pre><code>// Initialize an array of files from a range of files on disk with glob
file f[] = glob("directory/*.txt");
// Read the contents of a file with read
@@ -1488,13 +1484,13 @@
file tmp = write("first line\nsecond line");
// Find the name of a file with filename
-trace("Temporary filename is: " + filename(tmp));</tt></pre>
+trace("Temporary filename is: " + filename(tmp));</code></pre>
</div></div>
<div class="paragraph"><p>Temporary files are created as necessary if unmapped files are
-written to. For example, the file <tt>tmp</tt> in the above code snippet.
-This feature is implemented by calling GNU <tt>mktemp</tt> with suffix
-<tt>.turbine</tt>; thus, the directory is set with environment variable
-<tt>TMPDIR</tt> which defaults to <tt>/tmp</tt>.</p></div>
+written to. For example, the file <code>tmp</code> in the above code snippet.
+This feature is implemented by calling GNU <code>mktemp</code> with suffix
+<code>.turbine</code>; thus, the directory is set with environment variable
+<code>TMPDIR</code> which defaults to <code>/tmp</code>.</p></div>
<div class="paragraph"><p>Currently Swift/T assumes that the file system is shared among
all nodes.</p></div>
<div class="admonitionblock">
@@ -1506,14 +1502,14 @@
<div class="paragraph"><p>The syntax</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>file f<"f.txt"> = g();</tt></pre>
+<pre><code>file f<"f.txt"> = g();</code></pre>
</div></div>
<div class="paragraph"><p>is allowed but</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>file f<"f.txt">=g();</tt></pre>
+<pre><code>file f<"f.txt">=g();</code></pre>
</div></div>
-<div class="paragraph"><p>results in a parse error: the <tt>>=</tt> sequence is tokenized as
+<div class="paragraph"><p>results in a parse error: the <code>>=</code> sequence is tokenized as
<em>greater-than-or-equal-to</em>.</p></div>
</td>
</tr></table>
@@ -1532,35 +1528,35 @@
<div class="paragraph"><p>Arrays can be declared with empty square brackets:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>int A[];</tt></pre>
+<pre><code>int A[];</code></pre>
</div></div>
<div class="paragraph"><p>Arrays with empty square brackets have integer indices. It is
also possible to declare integers with other index types, such as
strings:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>string dict[string];</tt></pre>
+<pre><code>string dict[string];</code></pre>
</div></div>
<div class="paragraph"><p>They are dynamically sized, expanding each time an item is inserted at
a new index. Arrays are indexed using square brackets.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>int A[string];
+<pre><code>int A[string];
int B[];
B = function_returning_array();
A["zero"] = B[0];
-A["one"] = B[1];</tt></pre>
+A["one"] = B[1];</code></pre>
</div></div>
<div class="paragraph"><p>Each array index can only be assigned to once.</p></div>
<div class="paragraph"><p>A given array variable must be assigned either <em>in toto</em> (as a whole)
-or <em>in partes</em> (piece by piece). In this example, <tt>B</tt> is assigned in toto
-and <tt>A</tt> is assigned in partes. Code that attempts to do both is in error.</p></div>
+or <em>in partes</em> (piece by piece). In this example, <code>B</code> is assigned in toto
+and <code>A</code> is assigned in partes. Code that attempts to do both is in error.</p></div>
<div class="paragraph"><p>Arrays may be used as inputs or outputs of functions.</p></div>
<div class="paragraph"><p>Arrays are part of Swift dataflow semantics. An array is closed
when all possible insertions to it are complete.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>(int B[]) f(int j)
+<pre><code>(int B[]) f(int j)
{
int A[];
A = subroutine_function(1);
@@ -1570,23 +1566,23 @@
// OK: assigning to output variable
B = subroutine_function(2);
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>Array literals may be expressed using the range operator:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>int start = 0;
+<pre><code>int start = 0;
int stop = 10;
int step = 2;
// Array of length 10:
int A[] = [start:stop];
// Array of length 5, containing only even numbers:
-int B[] = [start:stop:step];</tt></pre>
+int B[] = [start:stop:step];</code></pre>
</div></div>
<div class="paragraph"><p>Array literals may also be expressed with list syntax:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>int C[] = [4,5,6];</tt></pre>
+<pre><code>int C[] = [4,5,6];</code></pre>
</div></div>
</div>
<div class="sect2">
@@ -1595,43 +1591,43 @@
assigned as follows:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>// An array of arrays of files with string keys
+<pre><code>// An array of arrays of files with string keys
file A[string][string];
A["foo"]["bar"] = input_file("test.txt");
-A["foo"]["qux"] = input_file("test2.txt");</tt></pre>
+A["foo"]["qux"] = input_file("test2.txt");</code></pre>
</div></div>
<div class="paragraph"><p><strong>Note:</strong> there is currently a limitation in assignment of nested arrays
that a given array can only be assigned at a single "index level". If
-<tt>A</tt> is a 2D array, for example, then you cannot mix assignments specifying
-one index (e.g. <tt>A[i] = …</tt>) with assignments specifying three indices
-(e.g. <tt>A[i][j] = …</tt>).</p></div>
+<code>A</code> is a 2D array, for example, then you cannot mix assignments specifying
+one index (e.g. <code>A[i] = …</code>) with assignments specifying three indices
+(e.g. <code>A[i][j] = …</code>).</p></div>
</div>
<div class="sect2">
<h3 id="_structs">9.6. Structs</h3>
-<div class="paragraph"><p>In Swift, structs are defined with the <tt>type</tt> keyword. They define
+<div class="paragraph"><p>In Swift, structs are defined with the <code>type</code> keyword. They define
a new type.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>type person
+<pre><code>type person
{
string name;
int age;
int events[];
-}</tt></pre>
+}</code></pre>
</div></div>
-<div class="paragraph"><p>Structs are accessed with the <tt>.</tt> syntax:</p></div>
+<div class="paragraph"><p>Structs are accessed with the <code>.</code> syntax:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>person p;
+<pre><code>person p;
p.name = "Abe";
-p.age = 90;</tt></pre>
+p.age = 90;</code></pre>
</div></div>
<div class="paragraph"><p>It is possible to have arrays of structs, with some restriction on
how they can be assigned. Each struct in the array must be assigned
<em>in toto</em> (as a whole). For example, the following code is valid:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>person people[], p1, p2;
+<pre><code>person people[], p1, p2;
p1.name = "Thelma";
p1.age = 31;
@@ -1640,35 +1636,35 @@
p2.age = 29;
people[0] = p1;
-people[1] = p2;</tt></pre>
+people[1] = p2;</code></pre>
</div></div>
<div class="paragraph"><p>However, attempting to assign the structs in the following way is
currently unsupported:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>people[2].name = "Abe"; // Not supported!
-people[2].age = 90; // Not supported!</tt></pre>
+<pre><code>people[2].name = "Abe"; // Not supported!
+people[2].age = 90; // Not supported!</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_defining_new_types">9.7. Defining new types</h3>
<div class="paragraph"><p>Swift has two ways to define new types based on existing types.</p></div>
-<div class="paragraph"><p>The first is <tt>typedef</tt>, which creates a new name for the type.
+<div class="paragraph"><p>The first is <code>typedef</code>, which creates a new name for the type.
The new type and the existing type will be completely interchangeable,
since they are simply different names for the same underlying type.
The new type name simply serves to improve readability or documentation.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>typedef newint int;
+<pre><code>typedef newint int;
main {
// We can freely convert between int and newint
newint x = 1;
int y = x;
newint z = y;
-}</tt></pre>
+}</code></pre>
</div></div>
-<div class="paragraph"><p>The second is with <tt>type</tt>, which creates a new type that is a
+<div class="paragraph"><p>The second is with <code>type</code>, which creates a new type that is a
specialization of an existing type. That is, it is a distinct
type that is not interchangeable. A specialized type can be
converted into the original type, but the reverse transformation is
@@ -1679,7 +1675,7 @@
of encountering compiler bugs or limitations.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>typedef sorted_file file;
+<pre><code>typedef sorted_file file;
app (sorted_file out) sort (file i) {
"/usr/bin/sort" "-o" out i
}
@@ -1699,27 +1695,27 @@
// This would cause a type error
// sorted_file not_sorted = unsorted;
-}</tt></pre>
+}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_global_constants">9.8. Global Constants</h3>
<div class="paragraph"><p>Swift supports a basic feature for defining globally visible constants. You
-can use the <tt>global const</tt> statement at the top level of the program. The
+can use the <code>global const</code> statement at the top level of the program. The
syntax only supports literals of scalar types: e.g. integer literals, floating
point literals and string literals.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>global const string hello = "Hello World";
+<pre><code>global const string hello = "Hello World";
global const float pi_approx = 3.142;
global const int ONE = 1;
main () {
trace(hello, pi_approx, ONE);
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p><strong>Note:</strong> global constants provide no performance benefit compared with
-variables initialized to constant values at optimization levels <tt>O1</tt>
+variables initialized to constant values at optimization levels <code>O1</code>
or greater.</p></div>
<div class="paragraph"><p><strong>Note:</strong> better support is planned in future for more flexible support for
global variables and code.</p></div>
@@ -1738,7 +1734,7 @@
<div class="paragraph"><p>If statements have the form:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>if (<condition>)
+<pre><code>if (<condition>)
{
statement;
...
@@ -1747,7 +1743,7 @@
{
statement;
...
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>As required by dataflow processing, neither branch of the conditional can
execute until the value of the condition expression is available.</p></div>
@@ -1756,7 +1752,7 @@
<h4 id="_switch_statement">10.1.2. Switch statement</h4>
<div class="listingblock">
<div class="content">
-<pre><tt>int a = 20;
+<pre><code>int a = 20;
switch (a)
{
case 1:
@@ -1770,46 +1766,46 @@
default:
b = 2102 + 2420;
}
-printf("b: %i\n", b);</tt></pre>
+printf("b: %i\n", b);</code></pre>
</div></div>
<div class="paragraph"><p><strong>Note:</strong> there is no fall-through between cases in switch statements.</p></div>
</div>
</div>
<div class="sect2">
<h3 id="_iteration">10.2. Iteration</h3>
-<div class="paragraph"><p>Iteration is performed with the <tt>foreach</tt> and <tt>for</tt> statements.</p></div>
+<div class="paragraph"><p>Iteration is performed with the <code>foreach</code> and <code>for</code> statements.</p></div>
<div class="sect3">
<h4 id="_foreach_loop">10.2.1. Foreach loop</h4>
-<div class="paragraph"><p>The <tt>foreach</tt> loop allows for parallel iteration over an array:</p></div>
+<div class="paragraph"><p>The <code>foreach</code> loop allows for parallel iteration over an array:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>string A[];
+<pre><code>string A[];
foreach value, index in A
{
printf("A[%i] = %s\n", index, value);
-}</tt></pre>
+}</code></pre>
</div></div>
-<div class="paragraph"><p>The <tt>index</tt> and <tt>value</tt> variables are automatically declared. The
-<tt>index</tt> variable may be omitted from the syntax.</p></div>
+<div class="paragraph"><p>The <code>index</code> and <code>value</code> variables are automatically declared. The
+<code>index</code> variable may be omitted from the syntax.</p></div>
<div class="paragraph"><p>A special case of the foreach loop occurs when combined with the
array range operator. This is the idiomatic way to iterate over
a range of integer values in Swift. The STC compiler has special
handling for this case that avoids constructing an array.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>foreach i in [start:stop:step] {
+<pre><code>foreach i in [start:stop:step] {
...
-}</tt></pre>
+}</code></pre>
</div></div>
</div>
<div class="sect3">
<h4 id="_for_loop">10.2.2. For loop</h4>
-<div class="paragraph"><p>The <tt>for</tt> loop allows for sequential iteration. This example
+<div class="paragraph"><p>The <code>for</code> loop allows for sequential iteration. This example
implements a counter based on the return values of a function that
accepts integers:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>int N = 100;
+<pre><code>int N = 100;
int count = 0;
for (int i = 0; i < N; i = i+1, count = count+c)
{
@@ -1822,16 +1818,16 @@
{
c = 0;
}
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>The general form is:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>for ( <initializer> ; <condition> ; <updates> )
+<pre><code>for ( <initializer> ; <condition> ; <updates> )
{
statement;
...
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>The initializer is executed first, once. The initializer is a
comma-separated list of statements. The body statements are then
@@ -1841,7 +1837,7 @@
while the right-hand-side is the variable in the <em>previous</em> loop
iteration. Then, the condition is checked for loop exit. If the loop
continues, the body is executed again, etc.</p></div>
-<div class="paragraph"><p><strong>Performance Tip:</strong> use the <tt>foreach</tt> loop instead of <tt>for</tt> if your
+<div class="paragraph"><p><strong>Performance Tip:</strong> use the <code>foreach</code> loop instead of <code>for</code> if your
loop iterations are independent and can be executed in parallel.</p></div>
</div>
</div>
@@ -1851,55 +1847,55 @@
data dependencies. In some cases it is useful to add explicit data
dependencies, for example if you want to print a message to indicate
that variable was assigned. It is possible for the programmer to
-express additional execution ordering using two constructs: the <tt>wait</tt>
-statement and the <tt>=></tt> chaining operator.</p></div>
+express additional execution ordering using two constructs: the <code>wait</code>
+statement and the <code>=></code> chaining operator.</p></div>
<div class="paragraph"><p>In a wait statement, a block of code is executed after
one or more variables are closed.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>x = f();
+<pre><code>x = f();
y = g();
wait (x) {
trace("x is closed!");
}
wait(x, y) {
trace("x and y are closed!");
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>The chaining operator chains statements together so that a
statement only executes after the previous statement’s output
value is closed. This is
-a more concise way to express dependencies than the <tt>wait</tt> statement.</p></div>
+a more concise way to express dependencies than the <code>wait</code> statement.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>sleep(1) =>
+<pre><code>sleep(1) =>
x = f() =>
int y = g() =>
- trace("DONE!");</tt></pre>
+ trace("DONE!");</code></pre>
</div></div>
<div class="paragraph"><p>Chaining is based on the <strong>output values</strong>
-of a statement. In the simple case of a function call <tt>f() => …</tt>,
+of a statement. In the simple case of a function call <code>f() => …</code>,
the output values are the output values of the function. In the
-case of and assignment <tt>x = f() => …</tt> or a declaration,
-<tt>int y = g() => …</tt>, then the next statement is dependent on
+case of and assignment <code>x = f() => …</code> or a declaration,
+<code>int y = g() => …</code>, then the next statement is dependent on
the assigned values, or the declared values. Some functions such
-as <tt>sleep</tt> have <tt>void</tt> output values so that they can be used
+as <code>sleep</code> have <code>void</code> output values so that they can be used
in this fashion.</p></div>
</div>
<div class="sect2">
<h3 id="_scoping_blocks">10.4. Scoping blocks</h3>
<div class="paragraph"><p>Arbitrary scoping blocks may be used. In this example, two different
-variables, both represented by <tt>b</tt>, are assigned different values.</p></div>
+variables, both represented by <code>b</code>, are assigned different values.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>{
+<pre><code>{
int b;
b = 1;
}
{
int b;
b = 2;
-}</tt></pre>
+}</code></pre>
</div></div>
</div>
</div>
@@ -1908,19 +1904,19 @@
<h2 id="_operators">11. Operators</h2>
<div class="sectionbody">
<div class="paragraph"><p>The following binary arithmetic operators on numbers are defined:</p></div>
-<div class="paragraph"><p><tt>+</tt> (plus), <tt>-</tt> (minus), <tt>*</tt> (times), <tt>/</tt> (divide),
-<tt>%/</tt> (integer divide), <tt>%%</tt> (modulus), <tt>**</tt> (power)</p></div>
-<div class="paragraph"><p><tt>&&</tt> (boolean and), <tt>||</tt> (boolean or),
-<tt>==</tt> (equals), <tt>!=</tt> (not equals), <tt>></tt> (greater than), <tt><</tt> (less than),
-<tt>>=</tt> (greater than or equal to), <tt><=</tt> (less than or equal to)</p></div>
-<div class="paragraph"><p><tt>xor()</tt> is a builtin function.</p></div>
+<div class="paragraph"><p><code>+</code> (plus), <code>-</code> (minus), <code>*</code> (times), <code>/</code> (divide),
+<code>%/</code> (integer divide), <code>%%</code> (modulus), <code>**</code> (power)</p></div>
+<div class="paragraph"><p><code>&&</code> (boolean and), <code>||</code> (boolean or),
+<code>==</code> (equals), <code>!=</code> (not equals), <code>></code> (greater than), <code><</code> (less than),
+<code>>=</code> (greater than or equal to), <code><=</code> (less than or equal to)</p></div>
+<div class="paragraph"><p><code>xor()</code> is a builtin function.</p></div>
<div class="paragraph"><p>Swift boolean operators are not short-circuited (to allow maximal
-concurrency). For conditional execution, use an <tt>if</tt> statement.</p></div>
+concurrency). For conditional execution, use an <code>if</code> statement.</p></div>
<div class="paragraph"><p>The following unary operators are defined:</p></div>
-<div class="paragraph"><p><tt>-</tt> (negate), <tt>!</tt> (boolean not)</p></div>
-<div class="paragraph"><p>String concatenation is also performed with <tt>+</tt> (plus). <tt>==</tt> and
-<tt>!=</tt> may also be used on strings. Operator <tt>s1/s2</tt> is equivalent to
-<tt>s1+"/"+s2</tt>.</p></div>
+<div class="paragraph"><p><code>-</code> (negate), <code>!</code> (boolean not)</p></div>
+<div class="paragraph"><p>String concatenation is also performed with <code>+</code> (plus). <code>==</code> and
+<code>!=</code> may also be used on strings. Operator <code>s1/s2</code> is equivalent to
+<code>s1+"/"+s2</code>.</p></div>
</div>
</div>
<div class="sect1">
@@ -1928,17 +1924,17 @@
<div class="sectionbody">
<div class="paragraph"><p>Each category of function is shown with the required import
statement, if necessary.</p></div>
-<div class="paragraph"><p>Functions that accept an input of any type are denoted <tt>anything</tt>.
+<div class="paragraph"><p>Functions that accept an input of any type are denoted <code>anything</code>.
Functions that accept variable numbers of arguments are denoted with
-ellipsis <tt>…</tt>.</p></div>
-<div class="paragraph"><p>A function that accepts more than one type is denoted as <tt>f(int|string)</tt>.</p></div>
+ellipsis <code>…</code>.</p></div>
+<div class="paragraph"><p>A function that accepts more than one type is denoted as <code>f(int|string)</code>.</p></div>
<div class="paragraph"><p>If a function is described below an <strong>Import:</strong> label, be sure to
-<tt>import</tt> that package.</p></div>
+<code>import</code> that package.</p></div>
<div class="sect2">
<h3 id="_general">12.1. General</h3>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>xor(boolean,boolean) → boolean</tt>
+<code>xor(boolean,boolean) → boolean</code>
</dt>
<dd>
<p>
@@ -1946,7 +1942,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>make_void() → void</tt>
+<code>make_void() → void</code>
</dt>
<dd>
<p>
@@ -1954,21 +1950,21 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>size(A[]) → int</tt>
+<code>size(A[]) → int</code>
</dt>
<dd>
<p>
-Obtain the size of array <tt>A</tt>
+Obtain the size of array <code>A</code>
</p>
</dd>
<dt class="hdlist1">
-<tt>contains(A[], key) → boolean</tt>
+<code>contains(A[], key) → boolean</code>
</dt>
<dd>
<p>
-Test that future <tt>A[key]</tt> exists.
-This function blocks until <tt>A</tt> is closed. Consumers of <tt>A[key]</tt> may
-block again until <tt>A[key]</tt> is stored.
+Test that future <code>A[key]</code> exists.
+This function blocks until <code>A</code> is closed. Consumers of <code>A[key]</code> may
+block again until <code>A[key]</code> is stored.
</p>
</dd>
</dl></div>
@@ -1977,7 +1973,7 @@
<h3 id="_type_conversion">12.2. Type conversion</h3>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>fromint(int) → string</tt>
+<code>fromint(int) → string</code>
</dt>
<dd>
<p>
@@ -1985,7 +1981,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>toint(string) → int</tt>
+<code>toint(string) → int</code>
</dt>
<dd>
<p>
@@ -1993,7 +1989,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>fromfloat(float) → string</tt>
+<code>fromfloat(float) → string</code>
</dt>
<dd>
<p>
@@ -2001,7 +1997,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>tofloat(string) → float</tt>
+<code>tofloat(string) → float</code>
</dt>
<dd>
<p>
@@ -2009,7 +2005,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>itof(int) → float</tt>
+<code>itof(int) → float</code>
</dt>
<dd>
<p>
@@ -2022,113 +2018,112 @@
<h3 id="_output">12.3. Output</h3>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>trace(anything, anything, …)</tt>
+<code>trace(anything, anything, …)</code>
</dt>
<dd>
<p>
Report the value of any variable
</p>
-<div class="literalblock">
-<div class="content">
-<pre><tt>import io;</tt></pre>
-</div></div>
</dd>
+</dl></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>io</code></p></div>
+<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>printf(string format, int|float|string|boolean…)</tt>
+<code>printf(string format, int|float|string|boolean…)</code>
</dt>
<dd>
<p>
-As <tt>printf()</tt> in C
+As <code>printf()</code> in C
</p>
</dd>
</dl></div>
</div>
<div class="sect2">
<h3 id="_string_functions">12.4. String functions</h3>
-<div class="paragraph"><p><tt>strcat(string,string)</tt>: Concatenation</p></div>
-<div class="paragraph"><p><strong>Import:</strong> <tt>string</tt></p></div>
+<div class="paragraph"><p><code>strcat(string,string)</code>: Concatenation</p></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>string</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>substring(string s, int start, int length) → string</tt>
+<code>substring(string s, int start, int length) → string</code>
</dt>
<dd>
<p>
-Obtain substring of given string <tt>s</tt> starting at character <tt>start</tt> and of
-length <tt>length</tt>
+Obtain substring of given string <code>s</code> starting at character <code>start</code> and of
+length <code>length</code>
</p>
</dd>
<dt class="hdlist1">
-<tt>find(string s, string substring, int start_index, int end_index) → int</tt>
+<code>find(string s, string substring, int start_index, int end_index) → int</code>
</dt>
<dd>
<p>
-Find the index of the first occurence of the string <tt>substring</tt> within
-the string <tt>s</tt> between the indices <tt>start_index</tt> and <tt>end_index</tt>. Here
-an index of <tt>-1</tt> passed to <tt>end_index</tt> results in <tt>end_index</tt> being
-treated as the length of the string <tt>s</tt>. <tt>find</tt> returns <tt>-1</tt> in case
-there is no occurence of <tt>substring</tt> in <tt>s</tt> in the specified range.
+Find the index of the first occurence of the string <code>substring</code> within
+the string <code>s</code> between the indices <code>start_index</code> and <code>end_index</code>. Here
+an index of <code>-1</code> passed to <code>end_index</code> results in <code>end_index</code> being
+treated as the length of the string <code>s</code>. <code>find</code> returns <code>-1</code> in case
+there is no occurence of <code>substring</code> in <code>s</code> in the specified range.
</p>
</dd>
<dt class="hdlist1">
-<tt>string_count(string s, string substring, int start_index, int end_index) → int</tt>
+<code>string_count(string s, string substring, int start_index, int end_index) → int</code>
</dt>
<dd>
<p>
-Counts the occurences of the string <tt>substring</tt> within the string <tt>s</tt>
-between the indices <tt>start_index</tt> and <tt>end_index</tt>. Here an index of
-<tt>-1</tt> passed to <tt>end_index</tt> results in <tt>end_index</tt> being treated as the
-length of the string <tt>s</tt>
+Counts the occurences of the string <code>substring</code> within the string <code>s</code>
+between the indices <code>start_index</code> and <code>end_index</code>. Here an index of
+<code>-1</code> passed to <code>end_index</code> results in <code>end_index</code> being treated as the
+length of the string <code>s</code>
</p>
</dd>
<dt class="hdlist1">
-<tt>is_int(string s) → boolean</tt>
+<code>is_int(string s) → boolean</code>
</dt>
<dd>
<p>
-Returns true if string <tt>s</tt> is a number, else false.
+Returns true if string <code>s</code> is a number, else false.
</p>
</dd>
<dt class="hdlist1">
-<tt>replace(string s, string substring, string rep_string, int start_index) → string</tt>
+<code>replace(string s, string substring, string rep_string, int start_index) → string</code>
</dt>
<dd>
<p>
Obtain the string created by replacing the first occurence of the
-string <tt>substring</tt> within string <tt>s</tt>, after the index <tt>start_index</tt>,
-with the string <tt>rep_string</tt>. In case there is no such occurence of
-the string <tt>substring</tt> in string <tt>s</tt>, the original string <tt>s</tt> is
+string <code>substring</code> within string <code>s</code>, after the index <code>start_index</code>,
+with the string <code>rep_string</code>. In case there is no such occurence of
+the string <code>substring</code> in string <code>s</code>, the original string <code>s</code> is
returned unmodified.
</p>
</dd>
<dt class="hdlist1">
-<tt>replace_all(string s, string substring, string rep_string, int start_index) → string</tt>
+<code>replace_all(string s, string substring, string rep_string, int start_index) → string</code>
</dt>
<dd>
<p>
Obtain the string created by replacing all the occurences of the
-string <tt>substring</tt> within string <tt>s</tt>, after the index <tt>start_index</tt>,
-with the string <tt>rep_string</tt>. In case no such occurence of <tt>substring</tt>
-exists in <tt>s</tt>, the original string <tt>s</tt> is returned unmodified.
+string <code>substring</code> within string <code>s</code>, after the index <code>start_index</code>,
+with the string <code>rep_string</code>. In case no such occurence of <code>substring</code>
+exists in <code>s</code>, the original string <code>s</code> is returned unmodified.
</p>
</dd>
<dt class="hdlist1">
-<tt>split(string s, string delimiter) → string[]</tt>
+<code>split(string s, string delimiter) → string[]</code>
</dt>
<dd>
<p>
-Tokenize string <tt>s</tt> with given delimiter
+Tokenize string <code>s</code> with given delimiter
</p>
</dd>
<dt class="hdlist1">
-<tt>trim(string s) → string</tt>
+<code>trim(string s) → string</code>
</dt>
<dd>
<p>
-Remove leading and trailing whitespace from <tt>s</tt>
+Remove leading and trailing whitespace from <code>s</code>
</p>
</dd>
<dt class="hdlist1">
-<tt>strlen(string) → int</tt>
+<code>strlen(string) → int</code>
</dt>
<dd>
<p>
@@ -2136,7 +2131,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>hash(string) → int</tt>
+<code>hash(string) → int</code>
</dt>
<dd>
<p>
@@ -2144,19 +2139,19 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>sprintf(string format, int|float|string|boolean…)</tt>
+<code>sprintf(string format, int|float|string|boolean…)</code>
</dt>
<dd>
<p>
-As <tt>sprintf()</tt> in C
+As <code>sprintf()</code> in C
</p>
</dd>
<dt class="hdlist1">
-<tt>string_join(string A[], string separator) → string</tt>
+<code>string_join(string A[], string separator) → string</code>
</dt>
<dd>
<p>
-Join strings in <tt>A</tt> with given separator. The separator may be the
+Join strings in <code>A</code> with given separator. The separator may be the
empty string
</p>
</dd>
@@ -2166,7 +2161,7 @@
<h3 id="_math">12.5. Math</h3>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>max|min_integer(int,int) → int</tt>
+<code>max|min_integer(int,int) → int</code>
</dt>
<dd>
<p>
@@ -2175,7 +2170,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>max|min_float(float,float) → float</tt>
+<code>max|min_float(float,float) → float</code>
</dt>
<dd>
<p>
@@ -2184,7 +2179,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>pow_integer(int b,int x)</tt>
+<code>pow_integer(int b,int x)</code>
</dt>
<dd>
<p>
@@ -2192,7 +2187,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>pow_float(float b,float x)</tt>
+<code>pow_float(float b,float x)</code>
</dt>
<dd>
<p>
@@ -2200,10 +2195,10 @@
</p>
</dd>
</dl></div>
-<div class="paragraph"><p><strong>Import:</strong> <tt>math</tt></p></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>math</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>floor(float) → int</tt>
+<code>floor(float) → int</code>
</dt>
<dd>
<p>
@@ -2211,7 +2206,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>ceil(float) → int</tt>
+<code>ceil(float) → int</code>
</dt>
<dd>
<p>
@@ -2219,7 +2214,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>round(float) → int</tt>
+<code>round(float) → int</code>
</dt>
<dd>
<p>
@@ -2227,7 +2222,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>log(float) → float</tt>
+<code>log(float) → float</code>
</dt>
<dd>
<p>
@@ -2235,7 +2230,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>exp(float) → float</tt>
+<code>exp(float) → float</code>
</dt>
<dd>
<p>
@@ -2243,7 +2238,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>sqrt(float) → float</tt>
+<code>sqrt(float) → float</code>
</dt>
<dd>
<p>
@@ -2251,7 +2246,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>is_nan(float) → boolean</tt>
+<code>is_nan(float) → boolean</code>
</dt>
<dd>
<p>
@@ -2259,7 +2254,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>abs_integer(int) → int</tt>
+<code>abs_integer(int) → int</code>
</dt>
<dd>
<p>
@@ -2267,7 +2262,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>abs_float(float) → float</tt>
+<code>abs_float(float) → float</code>
</dt>
<dd>
<p>
@@ -2275,10 +2270,10 @@
</p>
</dd>
</dl></div>
-<div class="paragraph"><p><strong>Import:</strong> <tt>random</tt></p></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>random</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>random() → float</tt>
+<code>random() → float</code>
</dt>
<dd>
<p>
@@ -2286,18 +2281,18 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>randint(int start, int end)</tt>
+<code>randint(int start, int end)</code>
</dt>
<dd>
<p>
-Obtain random integer from <tt>start</tt>, inclusive, to <tt>end</tt>, exclusive
+Obtain random integer from <code>start</code>, inclusive, to <code>end</code>, exclusive
</p>
</dd>
</dl></div>
<div class="paragraph"><p><strong>Import:</strong> stats</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>sum_integer(int[]) → int</tt>
+<code>sum_integer(int[]) → int</code>
</dt>
<dd>
<p>
@@ -2305,7 +2300,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>avg(int|float[]) → float</tt>
+<code>avg(int|float[]) → float</code>
</dt>
<dd>
<p>
@@ -2316,10 +2311,10 @@
</div>
<div class="sect2">
<h3 id="_system">12.6. System</h3>
-<div class="paragraph"><p><strong>Import:</strong> <tt>sys</tt></p></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>sys</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>getenv(string) → string</tt>
+<code>getenv(string) → string</code>
</dt>
<dd>
<p>
@@ -2332,28 +2327,28 @@
<div class="paragraph"><p>Consider this command line:</p></div>
<div class="literalblock">
<div class="content">
-<pre><tt>turbine -l -n 3 program.tcl -v -a=file1.txt file2.txt --exec="prog thing1 thing2" --help file4.txt</tt></pre>
+<pre><code>turbine -l -n 3 program.tcl -v -a=file1.txt file2.txt --exec="prog thing1 thing2" --help file4.txt</code></pre>
</div></div>
-<div class="paragraph"><p>The arguments to <tt>program.tcl</tt> are just the tokens after <tt>program.tcl</tt></p></div>
+<div class="paragraph"><p>The arguments to <code>program.tcl</code> are just the tokens after <code>program.tcl</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>args() → string</tt>
+<code>args() → string</code>
</dt>
<dd>
<p>
Obtain all arguments as single string
</p>
-<div class="paragraph"><p>E.g., <tt>"-v -a=file1.txt file2.txt --exec="prog thing1 thing2" --help file4.txt"</tt></p></div>
+<div class="paragraph"><p>E.g., <code>"-v -a=file1.txt file2.txt --exec="prog thing1 thing2" --help file4.txt"</code></p></div>
</dd>
</dl></div>
<div class="paragraph"><p>The remaining functions are convenience functions oriented around
Swift conventions. Under these conventions, the example command above
-has <em>flagged</em> arguments <tt>v</tt>, <tt>a=file.txt</tt>, <tt>exec="prog thing1
-thing2"</tt>, and <tt>help</tt>. The command has <em>unflagged</em> arguments
-<tt>file2.txt</tt> and <tt>file4.txt</tt></p></div>
+has <em>flagged</em> arguments <code>v</code>, <code>a=file.txt</code>, <code>exec="prog thing1
+thing2"</code>, and <code>help</code>. The command has <em>unflagged</em> arguments
+<code>file2.txt</code> and <code>file4.txt</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>argc()</tt>
+<code>argc()</code>
</dt>
<dd>
<p>
@@ -2361,64 +2356,64 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>argv(string)</tt>
+<code>argv(string)</code>
</dt>
<dd>
<p>
<em>(argument-value)</em>
Given a string, returns the flagged argument with that key:
</p>
-<div class="paragraph"><p><tt>argv("a") → file1.txt</tt></p></div>
+<div class="paragraph"><p><code>argv("a") → file1.txt</code></p></div>
<div class="paragraph"><p>In addition to regular run-time arguments, the STC <em>compile-time
-arguments</em> feature allows <tt>argv()</tt> arguments to be provided at compile
+arguments</em> feature allows <code>argv()</code> arguments to be provided at compile
time. This allows a specialized, optimized version of code to be
-compiled for a particular set of arguments. See the <tt>-A
-<em>name</em>=<em>value</em></tt> <a href="#stc_arguments">argument</a> to <tt>stc</tt>. Note that if the
+compiled for a particular set of arguments. See the <code>-A
+<em>name</em>=<em>value</em></code> <a href="#stc_arguments">argument</a> to <code>stc</code>. Note that if the
argument is re-specified at run-time, an error will occur.</p></div>
</dd>
<dt class="hdlist1">
-<tt>argp(int)</tt>
+<code>argp(int)</code>
</dt>
<dd>
<p>
<em>(argument-positional)</em>
Given an integer, returns the unflagged argument at that index:
</p>
-<div class="paragraph"><p><tt>argp(2) → file4.txt</tt></p></div>
+<div class="paragraph"><p><code>argp(2) → file4.txt</code></p></div>
<div class="paragraph"><p>Given 0, returns the program name,</p></div>
-<div class="paragraph"><p><tt>argp(0) → /path/to/program.tcl</tt></p></div>
+<div class="paragraph"><p><code>argp(0) → /path/to/program.tcl</code></p></div>
</dd>
<dt class="hdlist1">
-<tt>argv_accept(string…)</tt>
+<code>argv_accept(string…)</code>
</dt>
<dd>
<p>
If program is given flagged command line arguments not contained in given
list, abort.
-E.g., <tt>argv_accept("x")</tt> would cause program failure at run time
+E.g., <code>argv_accept("x")</code> would cause program failure at run time
</p>
</dd>
<dt class="hdlist1">
-<tt>argv_contains(string) → boolean</tt>
+<code>argv_contains(string) → boolean</code>
</dt>
<dd>
<p>
Test if the command line contains the given flagged argument:
</p>
-<div class="paragraph"><p><tt>argv_contains("v") → true</tt></p></div>
+<div class="paragraph"><p><code>argv_contains("v") → true</code></p></div>
</dd>
</dl></div>
</div>
<div class="sect3">
<h4 id="_debugging">12.6.2. Debugging</h4>
-<div class="paragraph"><p><strong>Import:</strong> <tt>assert</tt></p></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>assert</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>assert(boolean condition, string message)</tt>
+<code>assert(boolean condition, string message)</code>
</dt>
<dd>
<p>
-If condition is false, report <tt>message</tt> and exit immediately.
+If condition is false, report <code>message</code> and exit immediately.
</p>
</dd>
</dl></div>
@@ -2427,7 +2422,7 @@
<h4 id="Turbine_information">12.6.3. Turbine information</h4>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>adlb_servers() → int</tt>
+<code>adlb_servers() → int</code>
</dt>
<dd>
<p>
@@ -2435,18 +2430,10 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>turbine_engines() → int</tt>
+<code>turbine_workers() → int</code>
</dt>
<dd>
<p>
-Number of Turbine engines
-</p>
-</dd>
-<dt class="hdlist1">
-<tt>turbine_workers() → int</tt>
-</dt>
-<dd>
-<p>
Number of Turbine workers
</p>
</dd>
@@ -2457,7 +2444,7 @@
<h3 id="_files_2">12.7. Files</h3>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>filename(file) → string</tt>
+<code>filename(file) → string</code>
</dt>
<dd>
<p>
@@ -2465,45 +2452,45 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>input(string) → file</tt>
+<code>input(string) → file</code>
</dt>
<dd>
<p>
-Obtain a <tt>file</tt>. At run time, the
+Obtain a <code>file</code>. At run time, the
filesystem is checked for the given file name
</p>
</dd>
<dt class="hdlist1">
-<tt>input_file(string) → file</tt>
+<code>input_file(string) → file</code>
</dt>
<dd>
<p>
-Alias for <tt>input()</tt>
+Alias for <code>input()</code>
</p>
</dd>
<dt class="hdlist1">
-<tt>input_url(string) → file</tt>
+<code>input_url(string) → file</code>
</dt>
<dd>
<p>
-Obtain a <tt>file</tt>. Some
+Obtain a <code>file</code>. Some
automatic operations and optimizations are disabled
</p>
</dd>
<dt class="hdlist1">
-<tt>urlname(file) → string</tt>
+<code>urlname(file) → string</code>
</dt>
<dd>
<p>
Obtain the name of a file created with
-<tt>input_url()</tt>
+<code>input_url()</code>
</p>
</dd>
</dl></div>
-<div class="paragraph"><p><strong>Import:</strong> <tt>files</tt></p></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>files</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>read(file) → string</tt>
+<code>read(file) → string</code>
</dt>
<dd>
<p>
@@ -2511,7 +2498,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>write(string) → file</tt>
+<code>write(string) → file</code>
</dt>
<dd>
<p>
@@ -2519,37 +2506,47 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>glob(string) → file[]</tt>
+<code>file_lines(file) → string[]</code>
</dt>
<dd>
<p>
+Reads the whole file, returning each line as a separate entry in the
+output array. Comments with <code>#</code> are excised, leading and trailing
+whitespace is trimmed, and blank lines are omitted.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>glob(string) → file[]</code>
+</dt>
+<dd>
+<p>
Perform glob operation, returning files
that match. Available glob symbols include:
</p>
<div class="ulist"><ul>
<li>
<p>
-<tt>*</tt>: any character sequence (including the zero-length sequence)
+<code>*</code>: any character sequence (including the zero-length sequence)
</p>
</li>
<li>
<p>
-<tt>?</tt>: any character
+<code>?</code>: any character
</p>
</li>
<li>
<p>
-<tt>[chars]</tt>: any of the given characters
+<code>[chars]</code>: any of the given characters
</p>
</li>
<li>
<p>
-<tt>\x</tt>: character <tt>x</tt>
+<code>\x</code>: character <code>x</code>
</p>
</li>
<li>
<p>
-<tt>{a,b,c,…}</tt> any of <tt>a</tt>, <tt>b</tt>, <tt>c</tt>, etc.
+<code>{a,b,c,…}</code> any of <code>a</code>, <code>b</code>, <code>c</code>, etc.
</p>
</li>
</ul></div>
@@ -2558,10 +2555,10 @@
</div>
<div class="sect2">
<h3 id="_blobs_2">12.8. Blobs</h3>
-<div class="paragraph"><p><strong>Import:</strong> <tt>blob</tt></p></div>
+<div class="paragraph"><p><strong>Import:</strong> <code>blob</code></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>blob_size(blob) → int</tt>
+<code>blob_size(blob) → int</code>
</dt>
<dd>
<p>
@@ -2569,7 +2566,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>blob_null() → blob</tt>
+<code>blob_null() → blob</code>
</dt>
<dd>
<p>
@@ -2577,7 +2574,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>blob_from_string(string) → blob</tt>
+<code>blob_from_string(string) → blob</code>
</dt>
<dd>
<p>
@@ -2585,7 +2582,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>string_from_blob(blob) → string</tt>
+<code>string_from_blob(blob) → string</code>
</dt>
<dd>
<p>
@@ -2595,7 +2592,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>blob_from_floats(float[]) → blob</tt>
+<code>blob_from_floats(float[]) → blob</code>
</dt>
<dd>
<p>
@@ -2605,7 +2602,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>blob_from_floats(blob) → float[]</tt>
+<code>blob_from_floats(blob) → float[]</code>
</dt>
<dd>
<p>
@@ -2615,7 +2612,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>blob_from_ints(int i[]) → blob</tt>
+<code>blob_from_ints(int i[]) → blob</code>
</dt>
<dd>
<p>
@@ -2625,7 +2622,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>blob_from_file(file) → blob</tt>
+<code>blob_from_file(file) → blob</code>
</dt>
<dd>
<p>
@@ -2671,7 +2668,7 @@
<li>
<p>
The requisite files required to build a Tcl package
- (e.g <tt>pkgIndex.tcl</tt>)
+ (e.g <code>pkgIndex.tcl</code>)
</p>
</li>
<li>
@@ -2687,71 +2684,71 @@
string:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>() my_output (string s) "turbine" "0.0" [
+<pre><code>() my_output (string s) "turbine" "0.0" [
"puts <<s>>"
];
main {
my_output("HELLO");
-}</tt></pre>
+}</code></pre>
</div></div>
-<div class="paragraph"><p><tt>puts</tt> is the Tcl builtin for screen output, like <tt>puts()</tt> in C.</p></div>
+<div class="paragraph"><p><code>puts</code> is the Tcl builtin for screen output, like <code>puts()</code> in C.</p></div>
<div class="paragraph"><p>The above definition has, from left to right, the output arguments
(none), the name of the new Swift function, input arguments, the name
of the Tcl package containing the file (here, none, so we use
-<tt>turbine</tt>), and the minimum version of that package (here, 0.0).</p></div>
+<code>turbine</code>), and the minimum version of that package (here, 0.0).</p></div>
<div class="paragraph"><p>We tell the compiler how to call our Tcl function using inline
-Tcl code as a template with variable names surrounded by <tt><< >></tt>
+Tcl code as a template with variable names surrounded by <code><< >></code>
indicating where variables should be substituted.</p></div>
</div>
<div class="sect3">
<h4 id="_simple_tcl_package_example">13.1.2. Simple Tcl package example</h4>
<div class="paragraph"><p>In this first example we will implement a trivial Tcl extension function
that doubles an integer. Here is the Tcl code that will go in
-<tt>myextension.tcl</tt>:</p></div>
+<code>myextension.tcl</code>:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>namespace eval myextension {
+<pre><code>namespace eval myextension {
proc double { x } {
return [ expr $x * 2 ]
}
-}</tt></pre>
+}</code></pre>
</div></div>
-<div class="paragraph"><p>Here is the Swift function definition that will go in <tt>myextension.swift</tt>:</p></div>
+<div class="paragraph"><p>Here is the Swift function definition that will go in <code>myextension.swift</code>:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>@pure
+<pre><code>@pure
(int o) double (int i) "myextension" "0.0.1" [
"set <<o>> [ myextension::double <<i>> ]"
-];</tt></pre>
+];</code></pre>
</div></div>
<div class="paragraph"><p>We can also tell the Swift compiler a little about the function so
-that it can better optimize your programs. For example, <tt>double</tt> has
+that it can better optimize your programs. For example, <code>double</code> has
no side-effects and produces the same result each time for the same
-arguments (i.e. is deterministic), so we can annotate it as a <tt>@pure</tt>
+arguments (i.e. is deterministic), so we can annotate it as a <code>@pure</code>
function.</p></div>
<div class="paragraph"><p>If your function has a long running time and should be dispatched to a
worker process for execution, then you need to label the function as a
-leaf function, for example:</p></div>
+worker function, for example:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>@dispatch=LEAF
+<pre><code>@dispatch=WORKER
(int o) process (int i) "pkg" "0.0.1" [
"set <<o>> [ pkg::process <<i>> ]"
-];</tt></pre>
+];</code></pre>
</div></div>
<div class="paragraph"><p>Tcl code is conventionally placed into <em>packages</em>. In this example,
-<tt>myextension.tcl</tt> would be part of the package.</p></div>
+<code>myextension.tcl</code> would be part of the package.</p></div>
<div class="paragraph"><p>More information about building Tcl packages may be found
<a href="http://www.tcl.tk/man/tcl8.5/TclCmd/pkgMkIndex.htm">here</a>. Ultimately,
-you produce a <tt>pkgIndex.tcl</tt> file that contains necessary information
+you produce a <code>pkgIndex.tcl</code> file that contains necessary information
about the package.</p></div>
<div class="paragraph"><p>To ensure that Swift can find your package, use</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>stc -r <package directory> ...</tt></pre>
+<pre><code>stc -r <package directory> ...</code></pre>
</div></div>
-<div class="paragraph"><p>or set <tt>TURBINE_USER_LIB</tt> at run time.</p></div>
+<div class="paragraph"><p>or set <code>TURBINE_USER_LIB</code> at run time.</p></div>
<div class="ulist"><ul>
<li>
<p>
@@ -2768,7 +2765,7 @@
<div class="ulist"><ul>
<li>
<p>
-<tt>int</tt>/<tt>float</tt>/<tt>string</tt>/<tt>bool</tt> are converted to the standard
+<code>int</code>/<code>float</code>/<code>string</code>/<code>bool</code> are converted to the standard
Tcl representations
</p>
</li>
@@ -2807,13 +2804,13 @@
directly passed references to data in Swift’s global data store. In
this case your function must manually retrieve/store data from/to the
global distributed data store. In this case, you do not use the STC
-Tcl argument substitution syntax (<tt><<<tt>i</tt>>></tt>).</p></div>
+Tcl argument substitution syntax (<code><<<code>i</code>>></code>).</p></div>
<div class="paragraph"><p>Consider this custom Swift→Tcl binding:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>(int o) complex_function (int arr[]) "pkg" "0.0.1" "complex";</tt></pre>
+<pre><code>(int o) complex_function (int arr[]) "pkg" "0.0.1" "complex";</code></pre>
</div></div>
-<div class="paragraph"><p>This function jumps into Tcl function <tt>complex</tt>, which must
+<div class="paragraph"><p>This function jumps into Tcl function <code>complex</code>, which must
perform its own data dependency management.</p></div>
<div class="paragraph"><p>See the <a href="leaf.html">Swift/T Leaf Function Guide</a> for more
information about this process.</p></div>
@@ -2830,7 +2827,7 @@
<p>
The standard components of a Swift function declaration: input and
output arguments and the function name. Note that the output
- variable types are restricted to individual <tt>file</tt>s.
+ variable types are restricted to individual <code>file</code>s.
</p>
</li>
<li>
@@ -2867,13 +2864,13 @@
</li>
</ul></div>
<div class="paragraph"><p>Standard input, output and error can be redirected to files via
-<tt>@stdin=</tt>, <tt>@stdout=</tt>, and <tt>@stderr=</tt> expressions. If used, these should point
-to a <tt>file</tt>.</p></div>
+<code>@stdin=</code>, <code>@stdout=</code>, and <code>@stderr=</code> expressions. If used, these should point
+to a <code>file</code>.</p></div>
<div class="paragraph"><p>Here is an example of an app function that joins multiple files
-with the <tt>cat</tt> utility:</p></div>
+with the <code>cat</code> utility:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>import files;
+<pre><code>import files;
app (file out) cat (file inputs[]) {
"/bin/cat" inputs @stdout=out
@@ -2881,13 +2878,13 @@
main {
file joined <"joined.txt"> = cat(glob("*.txt"));
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>Here is an example of an app function that sleeps for an arbitrary
amount of time:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>app (void signal) sleep (int secs) {
+<pre><code>app (void signal) sleep (int secs) {
"/bin/sleep" secs
}
@@ -2899,7 +2896,7 @@
trace("Slept " + fromint(time));
}
}
-}</tt></pre>
+}</code></pre>
</div></div>
</div>
<div class="sect2">
@@ -2913,30 +2910,30 @@
<div class="paragraph"><p>Consider the following Swift script:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>import io;
+<pre><code>import io;
import python;
main {
- i = python("print(\"python works\")\n2+2");
+ i = python("print(\"python works\")\nrepr(2+2)");
printf("i: %s", i);
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>This simply evaluates the Python code line by line. The last line must
return a Python string to Swift, in this case, the Python string
-<tt>'4'</tt>. The expected output is shown below:</p></div>
+<code>'4'</code>. The expected output is shown below:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>python works
-i: 4</tt></pre>
+<pre><code>python works
+i: 4</code></pre>
</div></div>
<div class="paragraph"><p>Swift multi-line strings may be used to enter more complex Python code
-without the explicit use of <tt>\n</tt>.</p></div>
+without the explicit use of <code>\n</code>.</p></div>
<div class="paragraph"><p>Additionally, you can call Python libraries such as
<a href="http://www.numpy.org">Numpy</a> if available on your system. The
following code adds matrices <em>I</em><sub>3</sub> + <em>I</em><sub>3</sub> using Numpy arrays.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>import io;
+<pre><code>import io;
import python;
import string;
@@ -2966,17 +2963,17 @@
matrix A2 = eye(3);
matrix sum = add(A1, A2);
printf("2*eye(3)=%s", sum);
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>An Python script template is created that imports Numpy and performs
some simple calculations. This code is represented in a Swift string.
-The template is filled in by the Swift call to <tt>sprintf()</tt>. Then, the
+The template is filled in by the Swift call to <code>sprintf()</code>. Then, the
code is passed to Python for evaluation. The output is:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>2*eye(3)=array([[ 2., 0., 0.],
+<pre><code>2*eye(3)=array([[ 2., 0., 0.],
[ 0., 2., 0.],
- [ 0., 0., 2.]])</tt></pre>
+ [ 0., 0., 2.]])</code></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
@@ -2984,11 +2981,11 @@
<div class="title">Note</div>
</td>
<td class="content">To use this, Turbine must be configured with Python enabled
- before compiling, by setting <tt>ENABLE_PYTHON=1</tt>
- in <tt>exm-settings.sh</tt>, or by providing the <tt>--enable-python</tt> argument
- to <tt>configure</tt>. This feature is implemented by linking to Python
+ before compiling, by setting <code>ENABLE_PYTHON=1</code>
+ in <code>exm-settings.sh</code>, or by providing the <code>--enable-python</code> argument
+ to <code>configure</code>. This feature is implemented by linking to Python
as a shared library, enabling better performance than calling the
- <tt>python</tt> program (which may be done by using a normal Swift
+ <code>python</code> program (which may be done by using a normal Swift
<a href="#app_functions">app function</a>). Error messages for minor coding
mistakes may be badly mangled and refer to missing Python symbols-
refer to the first error in the Python stack trace.</td>
@@ -3000,7 +2997,7 @@
<div class="paragraph"><p>Consider the following Swift script:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>import io;
+<pre><code>import io;
import string;
import R;
@@ -3017,51 +3014,100 @@
code = sprintf(template, 4);
s = R(code);
printf("the answer was: %i", s);
-}</tt></pre>
+}</code></pre>
</div></div>
<div class="paragraph"><p>An <a href="http://www.r-project.org">R language</a> script template is placed in a
Swift string. The template is filled in with the value 4 by the Swift
-call to <tt>sprintf()</tt> (note the <tt>%i</tt> conversion specifier). Then, the
+call to <code>sprintf()</code> (note the <code>%i</code> conversion specifier). Then, the
code is passed to R for evaluation. The output is:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>the answer is: 104
-the answer was: 104</tt></pre>
+<pre><code>the answer is: 104
+the answer was: 104</code></pre>
</div></div>
-<div class="paragraph"><p>As coded here, both R and Swift report the value of <tt>a</tt>.</p></div>
+<div class="paragraph"><p>As coded here, both R and Swift report the value of <code>a</code>.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">To use this, Turbine must be configured with R enabled
- before compiling, by setting <tt>ENABLE_R=1</tt>
- in <tt>exm-settings.sh</tt>, or by providing the <tt>--enable-r</tt> argument
- to <tt>configure</tt>. This feature is implemented by linking to R as a shared
- library, enabling better performance than calling the <tt>R</tt> program
- (which may be done by using a normal Swift <a href="#app_functions">app function</a>). When installing R, be sure to include the <tt>devel</tt>
+ before compiling, by setting <code>ENABLE_R=1</code>
+ in <code>exm-settings.sh</code>, or by providing the <code>--enable-r</code> argument
+ to <code>configure</code>. This feature is implemented by linking to R as a shared
+ library, enabling better performance than calling the <code>R</code> program
+ (which may be done by using a normal Swift <a href="#app_functions">app function</a>). When installing R, be sure to include the <code>devel</code>
package. When installing R from source, configure with
- <tt>--enable-R-shlib</tt>. You may need to set the environment variable
- <tt>R_HOME</tt> to the directory containing the R installation. For the APT
- package, this is <tt>/usr/lib/R</tt>.</td>
+ <code>--enable-R-shlib</code>. You may need to set the environment variable
+ <code>R_HOME</code> to the directory containing the R installation. For the APT
+ package, this is <code>/usr/lib/R</code>.</td>
</tr></table>
</div>
</div>
+<div class="sect3">
+<h4 id="_calling_julia">13.3.3. Calling Julia</h4>
+<div class="paragraph"><p>Consider the following Swift script:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>import io;
+import julia;
+import string;
+import sys;
+
+main {
+ start = clock();
+ f =
+"""
+begin
+ f(x) = begin
+ sleep(1)
+ x+1
+ end
+ f(%s)
+end
+""";
+ s1 = julia(sprintf(f, 1));
+ s2 = julia(sprintf(f, 2));
+ s3 = julia(sprintf(f, 3));
+ printf("julia results: %s %s %s", s1, s2, s3);
+ wait (s1, s2, s3) {
+ printf("duration: %0.2f", clock()-start);
+ }
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>In this example, a <a href="http://julialang.org">Julia</a> script is placed in
+string <code>f</code>. It is parameterized three times by <code>sprintf()</code>. Each
+Julia invocation runs concurrently (if enough processes are provided
+to Swift/T).</p></div>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">To use this, Turbine must be configured with Julia enabled
+ before compiling, by providing the <code>--enable-julia</code> argument
+ to <code>configure</code>. This feature is implemented by linking to Julia
+ as a shared library, enabling better performance than calling the
+ <code>julia</code> program (which may be done by using a normal Swift
+ <a href="#app_functions">app function</a>).</td>
+</tr></table>
</div>
</div>
</div>
+</div>
+</div>
<div class="sect1">
<h2 id="Optimizations">14. Optimizations</h2>
<div class="sectionbody">
<div class="paragraph"><p>STC performs a range of compiler optimizations that can significantly
speed up most Swift programs. The optimization level can be controlled
-by the <tt>-O</tt> command line option. The default optimization
-level <tt>-O2</tt>, or the increased optimization level <tt>-O3</tt> are usually
-the best choices. Some applications benefit markedly from <tt>-O3</tt>,
+by the <code>-O</code> command line option. The default optimization
+level <code>-O2</code>, or the increased optimization level <code>-O3</code> are usually
+the best choices. Some applications benefit markedly from <code>-O3</code>,
while others do not, and compile times can increase slightly.</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt># No optimizations at all (not recommended)
+<pre><code># No optimizations at all (not recommended)
stc -O0 example.swift example.tcl
# Basic optimizations (not recommended)
@@ -3073,15 +3119,15 @@
stc -O2 example.swift example.tcl
# All optimizations (also recommended)
-stc -O3 example.swift example.tcl</tt></pre>
+stc -O3 example.swift example.tcl</code></pre>
</div></div>
-<div class="paragraph"><p>Individual optimizations can be toggled on using <tt>-T <opt name></tt>
-or off with <tt>-t <opt name></tt>, but this typically is only useful for
+<div class="paragraph"><p>Individual optimizations can be toggled on using <code>-T <opt name></code>
+or off with <code>-t <opt name></code>, but this typically is only useful for
debugging. You can find an up-to-date list of optimizations in
the stc command-line help:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>stc -h</tt></pre>
+<pre><code>stc -h</code></pre>
</div></div>
</div>
</div>
@@ -3094,22 +3140,14 @@
<div class="paragraph"><p>Turbine runs as an MPI program consisting of many processes. Turbine
programs are ADLB programs. Thus, they produce and execute discrete
tasks that are distributed and load balanced at run time.</p></div>
-<div class="paragraph"><p>Each process runs in a <em>mode</em>: <em>engine</em>, <em>worker</em>, or <em>server</em>.</p></div>
+<div class="paragraph"><p>Each process runs in a <em>mode</em>: <em>worker</em>, or <em>server</em>.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-Engines
-</dt>
-<dd>
-<p>
-Evaluate the Swift logic. Produces tasks
-</p>
-</dd>
-<dt class="hdlist1">
Workers
</dt>
<dd>
<p>
-Performs tasks
+Evaluate the Swift logic. Produce tasks. Execute tasks.
</p>
</dd>
<dt class="hdlist1">
@@ -3117,14 +3155,13 @@
</dt>
<dd>
<p>
-Distributes tasks
+Distributes tasks. Manages data.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>Typical Swift programs perform compute-intensive work in leaf
-functions. These always execute on workers.</p></div>
-<div class="paragraph"><p>Engines split up the control logic work among themselves. This
-results in the generation of calls to extension functions.</p></div>
+functions that execute on workers.
+Execution of the Swift logic is split and distributed among workers.</p></div>
<div class="paragraph"><p>Servers distribute tasks in a scalable, load balanced manner. They
also store Swift data (integers, strings, etc.).</p></div>
</div>
@@ -3136,7 +3173,7 @@
<li>
<p>
The available concurrency in the Swift logic. Sequential
- dependencies will be evaluated sequentially. <tt>foreach</tt> loops and
+ dependencies will be evaluated sequentially. <code>foreach</code> loops and
branching function calls may be evaluated concurrently
</p>
</li>
@@ -3148,9 +3185,9 @@
</li>
<li>
<p>
-The number of engines and servers available to control the Turbine
- run. Adding more engines and servers usually improves performance
- but costs processes
+The number of servers available to control the Turbine run.
+ Adding more servers can improve performance for applications with
+ small tasks or complex data dependencies but ties up processes
</p>
</li>
</ul></div>
@@ -3158,24 +3195,24 @@
<div class="sect2">
<h3 id="_invocation">15.3. Invocation</h3>
<div class="paragraph"><p>The form of a Turbine invocation for STC-generated
-<tt>program.tcl</tt> is:</p></div>
+<code>program.tcl</code> is:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>turbine <turbine arguments> <program.tcl> <program arguments></tt></pre>
+<pre><code>turbine <turbine arguments> <program.tcl> <program arguments></code></pre>
</div></div>
<div class="paragraph"><p>The program arguments are available to Swift (<a href="#argv">[argv]</a>).</p></div>
<div class="paragraph"><p>Turbine accepts the following arguments:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>-f <file></tt>
+<code>-f <file></code>
</dt>
<dd>
<p>
-Provide a machine file to <tt>mpiexec</tt>
+Provide a machine file to <code>mpiexec</code>
</p>
</dd>
<dt class="hdlist1">
-<tt>-h</tt>
+<code>-h</code>
</dt>
<dd>
<p>
@@ -3183,15 +3220,15 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-l</tt>
+<code>-l</code>
</dt>
<dd>
<p>
-Enable <tt>mpiexec -l</tt> ranked output formatting
+Enable <code>mpiexec -l</code> ranked output formatting
</p>
</dd>
<dt class="hdlist1">
-<tt>-n <procs></tt>
+<code>-n <procs></code>
</dt>
<dd>
<p>
@@ -3199,7 +3236,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-v</tt>
+<code>-v</code>
</dt>
<dd>
<p>
@@ -3207,7 +3244,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-V</tt>
+<code>-V</code>
</dt>
<dd>
<p>
@@ -3215,7 +3252,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-x</tt>
+<code>-x</code>
</dt>
<dd>
<p>
@@ -3224,7 +3261,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-X</tt>
+<code>-X</code>
</dt>
<dd>
<p>
@@ -3237,18 +3274,10 @@
environment variables:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>TURBINE_ENGINES</tt>
+<code>ADLB_SERVERS</code>
</dt>
<dd>
<p>
-Number of Turbine engines
-</p>
-</dd>
-<dt class="hdlist1">
-<tt>ADLB_SERVERS</tt>
-</dt>
-<dd>
-<p>
Number of ADLB servers
</p>
</dd>
@@ -3257,17 +3286,17 @@
Swift (<a href="#Turbine_information">Turbine information</a>).</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>TURBINE_LOG=0</tt>
+<code>TURBINE_LOG=0</code>
</dt>
<dd>
<p>
-Disable logging. <tt>TURBINE_LOG=1</tt> or unset enables
+Disable logging. <code>TURBINE_LOG=1</code> or unset enables
logging, assuming logging was not disabled at configure time. Logging
goes to tandard output by default.
</p>
</dd>
<dt class="hdlist1">
-<tt>TURBINE_LOG_FILE=<file></tt>
+<code>TURBINE_LOG_FILE=<file></code>
</dt>
<dd>
<p>
@@ -3276,27 +3305,27 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>TURBINE_LOG_RANKS=1</tt>
+<code>TURBINE_LOG_RANKS=1</code>
</dt>
<dd>
<p>
-Using <tt>turbine -l</tt> or equivalent prepend the
+Using <code>turbine -l</code> or equivalent prepend the
MPI rank number to each output line. This works with typical MPICH or
OpenMPI systems, however, this is not available on some systems, so
set this to emulate the rank output on such systems.
</p>
</dd>
<dt class="hdlist1">
-<tt>ADLB_PRINT_TIME=1</tt>
+<code>ADLB_PRINT_TIME=1</code>
</dt>
<dd>
<p>
Enable a short report of total elapsed time (via
-<tt>MPI_Wtime()</tt>)
+<code>MPI_Wtime()</code>)
</p>
</dd>
<dt class="hdlist1">
-<tt>ADLB_PERF_COUNTERS=1</tt>
+<code>ADLB_PERF_COUNTERS=1</code>
</dt>
<dd>
<p>
@@ -3306,7 +3335,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>ADLB_EXHAUST_TIME</tt>
+<code>ADLB_EXHAUST_TIME</code>
</dt>
<dd>
<p>
@@ -3318,7 +3347,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>ADLB_REPORT_LEAKS=1</tt>
+<code>ADLB_REPORT_LEAKS=1</code>
</dt>
<dd>
<p>
@@ -3327,10 +3356,10 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>ADLB_TRACE=true</tt>
+<code>ADLB_TRACE=true</code>
</dt>
<dt class="hdlist1">
-<tt>ADLB_DEBUG=true</tt>
+<code>ADLB_DEBUG=true</code>
</dt>
<dd>
<p>
@@ -3339,33 +3368,33 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>TURBINE_LAUNCH_OPTIONS</tt>
+<code>TURBINE_LAUNCH_OPTIONS</code>
</dt>
<dd>
<p>
-Provide other arguments to <tt>mpiexec</tt>, such as a machine file, etc.
+Provide other arguments to <code>mpiexec</code>, such as a machine file, etc.
</p>
</dd>
<dt class="hdlist1">
-<tt>TURBINE_SRAND</tt>
+<code>TURBINE_SRAND</code>
</dt>
<dd>
<p>
If unset or empty, the random number generator seed will be set to the
process rank for each process, giving reproducible results. If set to
-an integer <tt>seed</tt>, the random number generator seed for each process
-will be set to <tt>seed</tt> + <tt>rank</tt>.
+an integer <code>seed</code>, the random number generator seed for each process
+will be set to <code>seed</code> + <code>rank</code>.
</p>
<div class="paragraph"><p>For non-reproducible random results, use the following shell commands:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>export TURBINE_SRAND=$( date +%s )
-turbine ...</tt></pre>
+<pre><code>export TURBINE_SRAND=$( date +%s )
+turbine ...</code></pre>
</div></div>
<div class="paragraph"><p>The seed is recorded in the log.</p></div>
</dd>
<dt class="hdlist1">
-<tt>ADLB_DEBUG_RANKS=1</tt>
+<code>ADLB_DEBUG_RANKS=1</code>
</dt>
<dd>
<p>
@@ -3375,7 +3404,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>ADLB_DEBUG_HOSTMAP=1</tt>
+<code>ADLB_DEBUG_HOSTMAP=1</code>
</dt>
<dd>
<p>
@@ -3384,7 +3413,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>ADLB_DISABLE_HOSTMAP=1</tt>
+<code>ADLB_DISABLE_HOSTMAP=1</code>
</dt>
<dd>
<p>
@@ -3399,10 +3428,10 @@
on more complex systems.</p></div>
<div class="sect3">
<h4 id="_build_troubleshooting">15.4.1. Build troubleshooting</h4>
-<div class="paragraph"><p>If <tt>exm-setup.zsh</tt> does not succeed, you may need to change how it
+<div class="paragraph"><p>If <code>exm-setup.zsh</code> does not succeed, you may need to change how it
tries to configure and compile Swift/T.</p></div>
<div class="paragraph"><p>Troubleshooting a build problem can require a few steps. The first
-step is to determine why the build failed. <tt>exm-setup.zsh</tt> will usually
+step is to determine why the build failed. <code>exm-setup.zsh</code> will usually
report the step at which configuration failed. For example, if it was unable
to locate a valid Tcl install, it will report this. Then you can try
these steps to resolve the problem:</p></div>
@@ -3415,15 +3444,15 @@
</li>
<li>
<p>
-Inspect <tt>exm-settings.sh</tt> settings related to the reported problem.
+Inspect <code>exm-settings.sh</code> settings related to the reported problem.
For example, if locating a Tcl install failed, setting
- the <tt>TCL_INSTALL</tt> and <tt>TCL_VERSION</tt> variables to the correct location
+ the <code>TCL_INSTALL</code> and <code>TCL_VERSION</code> variables to the correct location
and version may help.
</p>
</li>
<li>
<p>
-If the options in <tt>exm-settings.sh</tt> do not give sufficient control to
+If the options in <code>exm-settings.sh</code> do not give sufficient control to
fix the problem, you may need to manually configure some components
of Swift/T, as described in the next section.
</p>
@@ -3432,17 +3461,17 @@
</div>
<div class="sect3">
<h4 id="Manual_build_configuration">15.4.2. Manual configuration</h4>
-<div class="paragraph"><p><tt>exm-setup.zsh</tt> and <tt>exm-settings.sh</tt> provide a convenient way to install
+<div class="paragraph"><p><code>exm-setup.zsh</code> and <code>exm-settings.sh</code> provide a convenient way to install
Swift/T. However, this method does not allow full control over
the configuration. Swift/T is built with standard Ant (Java) and
Autotools/Makefile (C,Tcl) techniques. You can more directly control
-the configuration when building through the arguments to <tt>ant</tt> or
-<tt>configure</tt>.</p></div>
-<div class="paragraph"><p>To perform the installation using <tt>configure</tt>/<tt>make</tt>, simply untar the
+the configuration when building through the arguments to <code>ant</code> or
+<code>configure</code>.</p></div>
+<div class="paragraph"><p>To perform the installation using <code>configure</code>/<code>make</code>, simply untar the
distribution package and do:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>cd c-utils
+<pre><code>cd c-utils
./configure ...
make install
@@ -3455,12 +3484,12 @@
make install
cd ../stc
-ant install -Ddist.dir=... -Dturbine.home=...</tt></pre>
+ant install -Ddist.dir=... -Dturbine.home=...</code></pre>
</div></div>
<div class="ulist"><ul>
<li>
<p>
-You may use <tt>./configure --help</tt> and the
+You may use <code>./configure --help</code> and the
<a href="turbine-sites.html">Sites Guide</a> for further options.
</p>
</li>
@@ -3470,21 +3499,21 @@
<h4 id="_non_standard_mpi_locations">15.4.3. Non-standard MPI locations</h4>
<div class="paragraph"><p>Sometimes simply specifying the MPI directory is not enough to
configure Swift/T.</p></div>
-<div class="paragraph"><p>You can modify these settings in <tt>exm-settings.sh</tt> to more precisely
+<div class="paragraph"><p>You can modify these settings in <code>exm-settings.sh</code> to more precisely
define locations of MPI resources</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt>EXM_CUSTOM_MPI=1
+<pre><code>EXM_CUSTOM_MPI=1
MPI_INCLUDE=/path/to/mpi.h/include
MPI_LIB_DIR=/path/to/mpi_lib/lib
-MPI_LIB_NAME=funny.mpi.a</tt></pre>
+MPI_LIB_NAME=funny.mpi.a</code></pre>
</div></div>
<div class="paragraph"><p>If you are following the manual build process, configure Turbine with:</p></div>
<div class="listingblock">
<div class="content">
-<pre><tt> --enable-custom --with-mpi-include=/path/to/mpi.h/include
+<pre><code> --enable-custom --with-mpi-include=/path/to/mpi.h/include
--with-mpi-lib-dir=/path/to/mpi_lib/lib
- --with-mpi-lib-name=funny.mpi.a</tt></pre>
+ --with-mpi-lib-name=funny.mpi.a</code></pre>
</div></div>
</div>
</div>
@@ -3503,21 +3532,21 @@
<div class="ulist"><ul>
<li>
<p>
-Configure c-utils with <tt>--disable-log</tt>
+Configure c-utils with <code>--disable-log</code>
</p>
</li>
</ul></div>
</li>
<li>
<p>
-Specify <tt>EXM_OPT_BUILD=1</tt> in <tt>exm-settings.sh</tt> or configure everything
- with <tt>--enable-fast</tt>. This disables assertions and other checks
+Specify <code>EXM_OPT_BUILD=1</code> in <code>exm-settings.sh</code> or configure everything
+ with <code>--enable-fast</code>. This disables assertions and other checks
</p>
</li>
<li>
<p>
When making performance measurements, always subtract 0.1 seconds
- (or the value of <tt>ADLB_EXHAUST_TIME</tt>) from the Turbine run time
+ (or the value of <code>ADLB_EXHAUST_TIME</code>) from the Turbine run time
due to the ADLB shutdown protocol, which does not start until the
system is idle for that amount of time.
</p>
@@ -3533,7 +3562,7 @@
<li>
<p>
use the turbine_sh launcher in place of tclsh in submit script,
- or by specifying the <tt>-x</tt> argument to <tt>turbine</tt>
+ or by specifying the <code>-x</code> argument to <code>turbine</code>
</p>
</li>
<li>
@@ -3554,17 +3583,21 @@
static linking. If not, it is also possible to build an executable with
a subset of Tcl scripts and code linked in, providing some performance
benefits.</p></div>
+<div class="paragraph"><p>The provided <code>mkstatic.tcl</code> utility can produce a C source
+file with Tcl scripts bundled in, which can then be compiled and linked
+with a C compiler. This is a multi-step process that can be automated
+as part of your build process.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
-<td class="content">Ensure that static versions of the <tt>c-utils</tt>, <tt>lb</tt>, and <tt>turbine</tt> libraries
- were built, typically with a <tt>.a</tt> suffix, e.g. <tt>libadlb.a</tt>. These
- are created by default, unless you specified <tt>DISABLE_STATIC=0</tt> or
- <tt>--disable-static</tt>. To build a fully standalone
+<td class="content">Ensure that static versions of the <code>c-utils</code>, <code>lb</code>, and <code>turbine</code> libraries
+ were built, typically with a <code>.a</code> suffix, e.g. <code>libadlb.a</code>. These
+ are created by default, unless you specified <code>DISABLE_STATIC=0</code> or
+ <code>--disable-static</code>. To build a fully standalone
executable, you will also need to build a static version of Tcl
- (with the <tt>--disable-shared</tt> configure option), and static versions
+ (with the <code>--disable-shared</code> configure option), and static versions
of any other libraries your own code needs to link with, such
as your MPI distribution or application code.</td>
</tr></table>
@@ -3576,45 +3609,48 @@
</p>
<div class="listingblock">
<div class="content">
-<pre><tt>stc my.swift</tt></pre>
+<pre><code>stc my.swift</code></pre>
</div></div>
-<div class="paragraph"><p>producing the Turbine Tcl script <tt>my.tcl</tt>.</p></div>
+<div class="paragraph"><p>producing the Turbine Tcl script <code>my.tcl</code>.</p></div>
</li>
<li>
<p>
-Create a manifest file, e.g. <tt>my.manifest</tt>. This file describes the
+Create a manifest file, e.g. <code>my.manifest</code>. This file describes the
resources to be bundled, including the STC-generated code and any
user libraries.
</p>
-<div class="paragraph"><p>To do this, make a copy of <tt>scripts/mkstatic/example.manifest</tt> from
+<div class="paragraph"><p>To do this, make a copy of <code>scripts/mkstatic/example.manifest</code> from
the Turbine installation directory. This file contains examples and
-descriptions of all the the possible settings. Note that an empty
-manifest file corresponds to the <tt>turbine_sh</tt> utility, which is a
-replacement for <tt>tclsh</tt> with required Turbine libraries statically
-linked in.</p></div>
+descriptions of all the the possible settings.
+Note that an empty
+manifest file corresponds to the <code>turbine_sh</code> utility, which is a
+replacement for <code>tclsh</code> with required Turbine libraries statically
+linked in.
+For a simple Swift program with no user Tcl libraries,
+you only need to set <code>main_script = my.tcl</code>.</p></div>
</li>
<li>
<p>
-Invoke <tt>mkstatic.tcl</tt> (found under <tt>scripts/mkstatic/mkstatic.tcl</tt> in
+Invoke <code>mkstatic.tcl</code> (found under <code>scripts/mkstatic/mkstatic.tcl</code> in
the Turbine installation) to translate your Tcl script to a C main
- program (e.g., <tt>my_main.c</tt>) with Tcl source code included.
+ program (e.g., <code>my_main.c</code>) with Tcl source code included.
The minimal invocation is
</p>
<div class="listingblock">
<div class="content">
-<pre><tt>mkstatic.tcl my.manifest -c my_main.c</tt></pre>
+<pre><code>mkstatic.tcl my.manifest -c my_main.c</code></pre>
</div></div>
<div class="paragraph"><p>You will likely wish to include Tcl system libraries with
-<tt>--include-sys-lib /home/example/tcl-install/lib --tcl-version 8.6</tt>.
+<code>--include-sys-lib /home/example/tcl-install/lib --tcl-version 8.6</code>.
The Tcl system library directory can be identified by the fact that
-it contains the file <tt>init.tcl</tt>. This directory must be specified
-with a special flag so that <tt>mkstatic.tcl</tt> can correctly replace
+it contains the file <code>init.tcl</code>. This directory must be specified
+with a special flag so that <code>mkstatic.tcl</code> can correctly replace
the regular Tcl initialization process.</p></div>
<div class="paragraph"><p>You can include additional libraries and packages with
-<tt>--include-lib /home/example/tcl-lib/</tt>. Any <tt>.tcl</tt> or <tt>.tm</tt> source files
+<code>--include-lib /home/example/tcl-lib/</code>. Any <code>.tcl</code> or <code>.tm</code> source files
in the directory will be included. Source-only packages can
generally be completely linked into the executable, but if a package
-loads shared libraries, only the <tt>pkgIndex.tcl</tt> file will be linked
+loads shared libraries, only the <code>pkgIndex.tcl</code> file will be linked
into the executable. A package with compiled code can be converted to
support static linking by specifying a package init function, plus
static library or object files in the manifest file.</p></div>
@@ -3622,47 +3658,53 @@
<li>
<p>
Link together the compiled C main program with user libraries and
- Swift/T libraries to produce a final executable.
- The details vary depending on the compiler:
- we assume GCC. <tt>mkstatic.tcl</tt> may be used to obtain the required
- linker flags, for example:
+ Swift/T libraries to produce a final executable. The details of the
+ process vary depending on the compiler and system: we assume GCC.
+ You will need to provide the correct flags to link in all libraries
+ required by Swift/T or your own user code.
</p>
-<div class="listingblock">
-<div class="content">
-<pre><tt>mkstatic.tcl my.manifest --link-objs --link-flags</tt></pre>
-</div></div>
-<div class="paragraph"><p>produces the necessary linker flags for your manifest.</p></div>
-<div class="paragraph"><p>The Turbine distribution includes a helper script,
-<tt>turbine-build-config.sh</tt>, that can be sourced to obtain linker flags
-for Swift/T dependencies.</p></div>
<div class="ulist"><ul>
<li>
<p>
-Note that, in the case of static linking, if <strong>libA</strong> depends on <strong>libB</strong>,
- then the <tt>-lA</tt> flag must precede <tt>-lB</tt> on the command line. To
+<strong>User code:</strong> you must identify the libraries used by your application
+ and ensure link flags are provided. If linking static libraries, ensure
+ that any indirect dependencies of these libraries are also linked.
+</p>
+</li>
+<li>
+<p>
+<strong>Swift/T system:</strong> The Turbine distribution includes a helper script,
+ <code>turbine-build-config.sh</code>, that can be sourced to obtain linker flags
+ for Swift/T dependencies.
+</p>
+</li>
+<li>
+<p>
+<strong>Link order:</strong> In the case of static linking, if <strong>libA</strong> depends on <strong>libB</strong>,
+ then the <code>-lA</code> flag must precede <code>-lB</code> on the command line. To
actually do the linking, there are two further cases to consider:
</p>
<div class="ulist"><ul>
<li>
<p>
If building a fully static executable, you can
- provide the <tt>-static</tt> flag, plus all object files, plus <tt>-L</tt>
- and <tt>-l</tt> flags for all required library directories and libraries.
+ provide the <code>-static</code> flag, plus all object files, plus <code>-L</code>
+ and <code>-l</code> flags for all required library directories and libraries.
</p>
<div class="listingblock">
<div class="content">
-<pre><tt>gcc -static script_main.c file1.o file2.o -L/path/to/lib/dir -lsomething ...</tt></pre>
+<pre><code>gcc -static script_main.c file1.o file2.o -L/path/to/lib/dir -lsomething ...</code></pre>
</div></div>
</li>
<li>
<p>
If you are building an executable that depends on one or more shared
- libraries, you will need to provide the <tt>-dynamic</tt> flag, and then
+ libraries, you will need to provide the <code>-dynamic</code> flag, and then
ensure that static libraries are linked statically. If a shared
- version of a library is available, <tt>gcc</tt> will use that in preference
+ version of a library is available, <code>gcc</code> will use that in preference
to a static version. You can override this behaviour by specifying
- <tt>-Wl,-Bstatic</tt> on the command line before the flags for the libraries
- you wish to statically link, then <tt>-Wl,-Bdynamic</tt> to reset to
+ <code>-Wl,-Bstatic</code> on the command line before the flags for the libraries
+ you wish to statically link, then <code>-Wl,-Bdynamic</code> to reset to
dynamic linking for any libraries after those.
</p>
</li>
@@ -3672,11 +3714,11 @@
</li>
</ol></div>
<div class="paragraph"><p>We have described the most commonly-used options. A full list of options
-and descriptions can be obtained by invoking <tt>mkstatic.tcl -h</tt>.
+and descriptions can be obtained by invoking <code>mkstatic.tcl -h</code>.
Additional options include:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
-<tt>--main-script</tt>
+<code>--main-script</code>
</dt>
<dd>
<p>
@@ -3684,7 +3726,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-r</tt>
+<code>-r</code>
</dt>
<dd>
<p>
@@ -3692,7 +3734,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>-v</tt>
+<code>-v</code>
</dt>
<dd>
<p>
@@ -3700,7 +3742,7 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>--deps</tt>
+<code>--deps</code>
</dt>
<dd>
<p>
@@ -3708,18 +3750,10 @@
</p>
</dd>
<dt class="hdlist1">
-<tt>--link-deps</tt>
+<code>--ignore-no-manifest</code>
</dt>
<dd>
<p>
-Generate Makefile include for linking executable
-</p>
-</dd>
-<dt class="hdlist1">
-<tt>--ignore-no-manifest</tt>
-</dt>
-<dd>
-<p>
Pretend empty manifest present
</p>
</dd>
@@ -3731,7 +3765,7 @@
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
-Last updated 2014-05-06 12:09:00 CDT
+Last updated 2014-07-18 17:10:42 CDT
</div>
</div>
</body>
More information about the Swift-commit
mailing list