chapel.3

.\" Man page generated from reStructuredText.
.
.TH "CHAPEL" "1" "July 07, 2016" "" "Chapel Language Documentation 1.13"
.SH NAME
chapel \- Chapel Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH CHAPEL QUICKSTART INSTRUCTIONS
.sp
The following instructions are designed to help you build Chapel from
source.  If you haven\(aqt already downloaded Chapel, obtain the latest
release from \fI\%http://chapel.cray.com/download.html\fP, or refer to
\fI\%http://chapel.cray.com/install.html\fP for other installation options.
.sp
In the following instructions, note that building and using Chapel as
described in steps 1\-7 disables optional and advanced features in the
interest of getting you a clean build as quickly as possible.  Step 8
explains how to re\-build in the preferred configuration with these
additional features enabled.  Step 9 explains how to build Chapel for
distributed memory execution.
.INDENT 0.0
.IP 0. 4
See \fI\%doc/prereqs.rst\fP for more information about system tools and
packages you may need to have installed to build and run Chapel.
.UNINDENT
.INDENT 0.0
.IP 1. 3
Make sure that your shell is in the directory containing this
\fBQUICKSTART.rst\fP file.  For example:
.INDENT 3.0
.INDENT 3.5
\fBcd ~/chapel\-1.13.1\fP
.UNINDENT
.UNINDENT
.IP 2. 3
Set up your environment to use Chapel in "Quick Start" mode:
.UNINDENT
.TS
center;
|l|l|.
_
T{
\fBIf you use:\fP
T}	T{
\fBthen type:\fP
T}
_
T{
a bash\-compatible shell (bash/zsh)
T}	T{
\fBsource util/quickstart/setchplenv.bash\fP
T}
_
T{
a csh\-compatible shell (csh/tcsh)
T}	T{
\fBsource util/quickstart/setchplenv.csh\fP
T}
_
T{
the fish shell (fish)
T}	T{
\fB\&. util/quickstart/setchplenv.fish\fP
T}
_
T{
the Bourne shell (sh)
T}	T{
\fB\&. util/quickstart/setchplenv.sh\fP
T}
_
.TE
.INDENT 0.0
.INDENT 3.5
Note that there is no requirement to use these scripts long\-term,
they are merely designed to help new users get their environment
variables and paths set up quickly.  Long\-term, users may want to
copy and paste these settings into their dotfiles or set them in
other ways.  See \fI\%doc/chplenv.rst\fP for a complete description of
Chapel\(aqs environment variables and their expected values.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 3. 3
Build the compiler and runtime libraries using:
.INDENT 3.0
.INDENT 3.5
\fBgmake\fP
.UNINDENT
.UNINDENT
.sp
or if your default make is GNU make compatible (as on Mac OS X or
Cygwin), use:
.INDENT 3.0
.INDENT 3.5
\fBmake\fP
.UNINDENT
.UNINDENT
.sp
Parallel builds (e.g. \fBgmake \-j\fP) are also supported.
.IP 4. 3
\fBcsh\fP/\fBtcsh\fP users only: Update your shell\(aqs path hash table using:
.INDENT 3.0
.INDENT 3.5
\fBrehash\fP
.UNINDENT
.UNINDENT
.IP 5. 3
Optionally, check that your Chapel installation is working correctly:
.INDENT 3.0
.INDENT 3.5
\fBgmake check\fP
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 3.0
.INDENT 3.5
\fBmake check\fP
.UNINDENT
.UNINDENT
.IP 6. 3
Compile an example program:
.INDENT 3.0
.INDENT 3.5
\fBchpl \-o hello examples/hello.chpl\fP
.UNINDENT
.UNINDENT
.IP 7. 3
Run the resulting executable:
.INDENT 3.0
.INDENT 3.5
\fB\&./hello\fP
.UNINDENT
.UNINDENT
.IP 8. 3
Experiment with Chapel in this Quickstart mode to your heart\(aqs
content.  Once you are comfortable with Chapel and interested in
using a full\-featured version in the preferred configuration:
.INDENT 3.0
.IP a. 3
Open up a new shell to avoid inheriting the previous environment
settings.
.IP b. 3
Repeat steps 1\-7 above, but in Step 2, source \fButil/setchplenv.*\fP
instead of \fButil/quickstart/setchplenv.*\fP
.UNINDENT
.sp
This will set up your environment to use Chapel in the preferred
configuration.  Building this configuration involves compiling
third\-party packages, which will increase the overall build time.
If you run into any portability issues, please let us know via
\fI\%http://chapel.cray.com/bugs.html\fP\&.
.IP 9. 3
All of the instructions above describe how to run Chapel programs
in a single\-locale (shared\-memory) mode. To run using multiple
locales (distributed memory), please refer to \fI\%doc/multilocale.rst\fP\&.
.UNINDENT
.INDENT 0.0
.IP 10. 3
If you plan to do performance studies of Chapel programs, be sure
to (a) use the full\-featured version from steps 8\-9 and (b) read
\fB$CHPL_HOME/PERFORMANCE.md\fP to avoid common pitfalls.
.UNINDENT
.SS What\(aqs next?
.TS
center;
|l|l|.
_
T{
\fBFor more detailed information about:\fP
T}	T{
\fBrefer to:\fP
T}
_
T{
platform\-specific notes
T}	T{
\fI\%platforms\fP
T}
_
T{
online Chapel Documentation
T}	T{
\fI\%chapel.cray.com/docs\fP
T}
_
T{
example Chapel programs
T}	T{
\fBexamples/README\fP
T}
_
T{
setting Chapel environment variables
T}	T{
\fI\%doc/chplenv.rst\fP
T}
_
T{
building the compiler
T}	T{
\fI\%doc/building.rst\fP
T}
_
T{
compiling Chapel programs
T}	T{
\fI\%doc/compiling.rst\fP
T}
_
T{
executing Chapel programs
T}	T{
\fI\%doc/executing.rst\fP
T}
_
T{
debugging Chapel programs
T}	T{
\fI\%doc/debugging.rst\fP
T}
_
T{
reporting bugs
T}	T{
\fI\%doc/bugs.rst\fP
T}
_
T{
implementation status
T}	T{
\fBSTATUS\fP
T}
_
T{
performance status
T}	T{
\fBPERFORMANCE.md\fP
T}
_
T{
Chapel modes for emacs and vim
T}	T{
\fBhighlight/README.md\fP
T}
_
T{
Chapel\(aqs file and directory structure
T}	T{
\fBREADME.files\fP
T}
_
T{
changes since the last release
T}	T{
\fBCHANGES.md\fP
T}
_
.TE
.SH USING CHAPEL
.sp
Contents:
.SS Chapel Prerequisites
.sp
If you have a standard UNIX environment, a C/C++ compiler, some basic
scripting languages, a GNU\-compatible make, and awk installed you should
have no problems getting started with Chapel.
.SS Prerequisites
.sp
In slightly more detail, the following are prerequisites and assumptions
about your environment for using Chapel:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
You are using an environment that supports standard UNIX commands
such as: \fBcd, mkdir, rm, echo\fP
.IP \(bu 2
You have the Bourne shell available at \fB/bin/sh\fP, the C\-shell
available at \fB/bin/csh\fP, \(aqenv\(aq available at \fB/usr/bin/env\fP, and
that \(aqenv\(aq can locate Perl and Python on your system.
.IP \(bu 2
You have access to gmake or a GNU\-compatible version of make.
.IP \(bu 2
You have access to standard C and C++ compilers. We test our code
using a range of compilers on a nightly basis; these include
relatively recent versions of gcc/g++, clang, and compilers from
Cray, Intel, and PGI.
.IP \(bu 2
If you wish to use Chapel\(aqs test system, python\-setuptools and
python\-devel (or equivalent packages for your platform) are required.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Installation
.sp
We have used the following commands to install the above prerequisites:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
CentOS, Fedora 21:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
sudo yum install gcc gcc\-c++ perl python python\-devel python\-setuptools bash make gawk
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
Fedora 22:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
sudo dnf install gcc gcc\-c++ perl python python\-devel python\-setuptools bash make gawk
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
SLES, openSUSE:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
sudo zypper install gcc gcc\-c++ perl python python\-devel python\-setuptools bash make gawk
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
Debian, Ubuntu:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt\-get install gcc g++ perl python python\-dev python\-setuptools bash make mawk
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Setting up Your Environment for Chapel
.sp
To get started with Chapel, there are four environment settings that are
strongly recommended for effective use of the release, and a few other optional
settings that are useful for cross\-compiling or overriding the default
settings.  To check the values of the Chapel environment variables that are set
or can be inferred, run the script:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$CHPL_HOME/util/printchplenv
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBsetchplenv.*\fP source scripts in the \fB$CHPL_HOME/util/quickstart/\fP and
\fB$CHPL_HOME/util/\fP directories contain commands that set the following
variables for various shells and host platforms when they are sourced from the
\fB$CHPL_HOME\fP directory.  Frequent Chapel users may want to add such settings
to their shell\(aqs dotfile(s); but for getting started the setchplenv.* scripts
can be convenient.
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Setting up Your Environment for Chapel\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Recommended Settings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%CHPL_HOME\fP
.IP \(bu 2
\fI\%CHPL_HOST_PLATFORM\fP
.IP \(bu 2
\fI\%PATH\fP
.IP \(bu 2
\fI\%MANPATH\fP
.UNINDENT
.IP \(bu 2
\fI\%Optional Settings\fP
.INDENT 2.0
.IP \(bu 2
\fI\%CHPL_TARGET_PLATFORM\fP
.IP \(bu 2
\fI\%CHPL_*_COMPILER\fP
.IP \(bu 2
\fI\%CHPL_TARGET_ARCH\fP
.IP \(bu 2
\fI\%CHPL_MAKE\fP
.IP \(bu 2
\fI\%CHPL_MODULE_PATH\fP
.IP \(bu 2
\fI\%CHPL_LOCALE_MODEL\fP
.IP \(bu 2
\fI\%CHPL_TASKS\fP
.IP \(bu 2
\fI\%CHPL_COMM\fP
.IP \(bu 2
\fI\%CHPL_MEM\fP
.IP \(bu 2
\fI\%CHPL_LAUNCHER\fP
.IP \(bu 2
\fI\%CHPL_ATOMICS\fP
.IP \(bu 2
\fI\%CHPL_TIMERS\fP
.IP \(bu 2
\fI\%CHPL_GMP\fP
.IP \(bu 2
\fI\%CHPL_HWLOC\fP
.IP \(bu 2
\fI\%CHPL_REGEXP\fP
.IP \(bu 2
\fI\%CHPL_AUX_FILESYS\fP
.IP \(bu 2
\fI\%CHPL_LLVM\fP
.IP \(bu 2
\fI\%CHPL_WIDE_POINTERS\fP
.UNINDENT
.IP \(bu 2
\fI\%Compiler Command Line Option Defaults\fP
.UNINDENT
.UNINDENT
.SS Recommended Settings
.SS CHPL_HOME
.INDENT 0.0
.INDENT 3.5
Set the \fBCHPL_HOME\fP environment variable to point to the location of the
chapel/ directory that was created when you unpacked the release.
For example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_HOME=~/chapel\-1.13.1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This, and all other examples in the Chapel documentation, assumes you\(aqre
using the \fBbash\fP shell.  If using \fBcsh\fP or \fBtcsh\fP, mentally change
\fBexport FOO=BAR\fP to \fBsetenv FOO BAR\fP\&.  If using some other shell, make
the appropriate adjustment.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS CHPL_HOST_PLATFORM
.INDENT 0.0
.INDENT 3.5
Set the \fBCHPL_HOST_PLATFORM\fP environment variable to represent the platform on
which you\(aqre working.  For standard UNIX workstations, this can be done by
running the \fB$CHPL_HOME/util/chplenv/chpl_platform.py\fP script.  For
example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_HOST_PLATFORM=\(ga$CHPL_HOME/util/chplenv/chpl_platform.py\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For other platforms that appear very similar to a UNIX workstation from the
shell prompt (e.g., a Cray XK™), the value may need to be set
explicitly.  The strings for our currently\-supported host platforms are as
follows:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
cygwin32
T}	T{
x86 Cygwin (Windows) platforms
T}
_
T{
cygwin64
T}	T{
x86_64 Cygwin (Windows) platforms
T}
_
T{
darwin
T}	T{
Macintosh OS X platforms
T}
_
T{
linux32
T}	T{
32\-bit Linux platforms
T}
_
T{
linux64
T}	T{
64\-bit Linux platforms
T}
_
T{
marenostrum
T}	T{
BSC\(aqs MareNostrum platform
T}
_
T{
netbsd32
T}	T{
32\-bit NetBSD platforms
T}
_
T{
netbsd64
T}	T{
64\-bit NetBSD platforms
T}
_
T{
pwr5
T}	T{
IBM Power5 SMP cluster
T}
_
T{
pwr6
T}	T{
IBM Power6 SMP cluster
T}
_
T{
sunos
T}	T{
SunOS platforms
T}
_
T{
cray\-cs
T}	T{
Cray CS™
T}
_
T{
cray\-xc
T}	T{
Cray XC™
T}
_
T{
cray\-xe
T}	T{
Cray XE™
T}
_
T{
cray\-xk
T}	T{
Cray XK™
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
Platform\-specific documentation is available for most of these platforms in
platforms\-index\&.
.sp
The Chapel Makefiles and sources are designed to work for any UNIX\-compatible
environment that supports a GNU\-compatible make utility.  The list above
represents the set of platforms that we have access to and can test easily.
We are interested in making our code framework portable to other platforms \-\-
if you are using Chapel on a platform other than the ones listed above,
please refer to platform\-specific\-settings for ways to set up a
Makefile for this platform and/or contact us at: \fI\%chapel_info@cray.com\fP
.UNINDENT
.UNINDENT
.SS PATH
.INDENT 0.0
.INDENT 3.5
Set your \fBPATH\fP to include the directory
\fB$CHPL_HOME/bin/$CHPL_HOST_PLATFORM\fP which is created when you build the
compiler.  For example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export PATH="$PATH":"$CHPL_HOME/bin/$CHPL_HOST_PLATFORM"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS MANPATH
.INDENT 0.0
.INDENT 3.5
Set your man path to include the directory \fB$CHPL_HOME/man\fP\&.
For example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export MANPATH="$MANPATH":"$CHPL_HOME"/man
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Optional Settings
.SS CHPL_TARGET_PLATFORM
.INDENT 0.0
.INDENT 3.5
If you are cross\-compiling for a platform other than your
\fB$CHPL_HOST_PLATFORM\fP, set the \fBCHPL_TARGET_PLATFORM\fP environment
variable to describe that platform.  See \fI\%CHPL_HOST_PLATFORM\fP above for
legal values (though whether or not a given setting will support
cross\-compilation depends on your specific environment).
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If \fBCHPL_TARGET_PLATFORM\fP is not set, the target platform defaults to the
same value as \fB$CHPL_HOST_PLATFORM\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS CHPL_*_COMPILER
.INDENT 0.0
.INDENT 3.5
Optionally, you can set \fBCHPL_HOST_COMPILER\fP and/or
\fBCHPL_TARGET_COMPILER\fP to indicate the compiler suite to use in building
the sources.  \fBCHPL_HOST_COMPILER\fP is the compiler used to build the
Chapel compiler itself so that it will run on \fBCHPL_HOST_PLATFORM\fP\&.
\fBCHPL_TARGET_COMPILER\fP is the compiler used to build the runtime libraries
and generated code for \fBCHPL_TARGET_PLATFORM\fP\&.  Currently supported values
are as follows:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
clang
T}	T{
The Clang compiler suite \-\- clang and clang++
T}
_
T{
clang\-included
T}	T{
The Clang compiler in third\-party/llvm
T}
_
T{
cray\-prgenv\-cray
T}	T{
The Cray PrgEnv compiler using the Cray CCE backend
T}
_
T{
cray\-prgenv\-gnu
T}	T{
The Cray PrgEnv compiler using the GNU backend
T}
_
T{
cray\-prgenv\-intel
T}	T{
The Cray PrgEnv compiler using the Intel backend
T}
_
T{
cray\-prgenv\-pgi
T}	T{
The Cray PrgEnv compiler using the PGI backend
T}
_
T{
gnu
T}	T{
The GNU compiler suite \-\- gcc and g++
T}
_
T{
ibm
T}	T{
The IBM compiler suite \-\- xlc and xlC
T}
_
T{
intel
T}	T{
The Intel compiler suite \-\- icc and icpc
T}
_
T{
pgi
T}	T{
The PGI compiler suite \-\- pgcc and pgc++
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
The default for \fBCHPL_*_COMPILER\fP depends on the value of the corresponding
\fBCHPL_*_PLATFORM\fP environment variable:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Platform
T}	T{
Compiler
T}
_
T{
cray\-x*
T}	T{
.INDENT 0.0
.IP \(bu 2
gnu (for \fBCHPL_HOST_COMPILER\fP)
.IP \(bu 2
cray\-prgenv\-$PE_ENV (for \fBCHPL_TARGET_COMPILER\fP,
where PE_ENV is set by PrgEnv\-* modules)
.UNINDENT
T}
_
T{
darwin
T}	T{
clang if available, otherwise gnu
T}
_
T{
marenostrum
T}	T{
ibm
T}
_
T{
pwr5, pwr6
T}	T{
ibm
T}
_
T{
other
T}	T{
gnu
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If \fBCHPL_HOST_PLATFORM == CHPL_TARGET_PLATFORM\fP and is not \fBcray\-x*\fP,
\fBCHPL_TARGET_COMPILER\fP will default to the same value as \fBCHPL_HOST_COMPILER\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Note that builds with readme\-llvm (i.e. when \fBCHPL_LLVM=llvm\fP)
will build the runtime twice: once with the compiler as described above and
once with clang\-included. We do this in order to avoid issues in linking
objects built by different compilers.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS CHPL_TARGET_ARCH
.INDENT 0.0
.INDENT 3.5
Optionally, set the \fBCHPL_TARGET_ARCH\fP environment variable to indicate
that the target executable should be specialized to the given architecture
when using \fB\-\-specialize\fP (and \fB\-\-fast\fP). Valid options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
native
T}	T{
The C compiler will attempt to detect the architecture on the
machine that is compiling the target executable. This is a
good choice if you will be running on the same machine that
you are compiling on.  If you are not, see the options below.
T}
_
T{
unknown
T}	T{
No specialization will be performed
T}
_
T{
none
T}	T{
No specialization will be performed (will not warn)
T}
_
.TE
.sp
\fBArchitecture\-specific values\fP
.TS
center;
|l|l|.
_
T{
intel
T}	T{
amd
T}
_
T{
core2
T}	T{
k8
T}
_
T{
nehalem
T}	T{
k8sse3
T}
_
T{
westmere
T}	T{
barcelona
T}
_
T{
sandybridge
T}	T{
bdver1
T}
_
T{
ivybridge
T}	T{
bdver2
T}
_
T{
haswell
T}	T{
bdver3
T}
_
T{
broadwell
T}	T{
bdver4
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
These values are defined to be the same as in GCC 4.9:
.INDENT 0.0
.INDENT 3.5
\fI\%https://gcc.gnu.org/onlinedocs/gcc\-4.9.0/gcc/i386\-and\-x86\-64\-Options.html\fP
.UNINDENT
.UNINDENT
.sp
If you do not want \fBCHPL_TARGET_ARCH\fP to have any effect, you can set it
to either \fBunknown\fP or \fBnone\fP\&. Both will disable specialization, but the
latter will not warn if \fB\-\-specialize\fP is used.
.sp
Setting \fBCHPL_TARGET_ARCH\fP to an incorrect value for your processor may
result in an invalid binary that will not run on the intended machine.
Special care should be taken to select the lowest common denominator when
running on machines with heterogeneous processor architectures.
.sp
The default value for this setting will vary based on settings in your
environment, in order of application these rules are:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
If \fI\%CHPL_TARGET_COMPILER\fP is \fBcray\-prgenv\-*\fP you do not need to
set anything in \fBCHPL_TARGET_ARCH\fP\&. One of the \fBcraype\-*\fP modules
(e.g.  \fBcraype\-sandybridge\fP) should be loaded to provide equivalent
functionality. Once the proper module is loaded, \fBCRAY_CPU_TARGET\fP
will have the architecture being used in it.
.IP \(bu 2
If \fBCHPL_TARGET_COMPILER\fP is \fBcray\fP, \fBpgi\fP, or \fBibm\fP,
\fBCHPL_TARGET_ARCH\fP will be set to \fBnone\fP and no specialization
will occur.
.IP \(bu 2
If \fI\%CHPL_COMM\fP is set, no attempt to set a useful value will be
made, \fBCHPL_TARGET_ARCH\fP will be \fBunknown\fP\&.
.IP \(bu 2
If \fI\%CHPL_TARGET_PLATFORM\fP is \fBdarwin\fP, \fBlinux*\fP, or
\fBcygwin*\fP \fBCHPL_TARGET_ARCH\fP will be \fBnative\fP, passing the
responsibility off to the backend C compiler to detect the specifics
of the hardware.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS CHPL_MAKE
.INDENT 0.0
.INDENT 3.5
Optionally, set the \fBCHPL_MAKE\fP environment variable to indicate the
GNU\-compatible make utility that you want the compiler back\-end to invoke
when compiling the generated C code.  If not set, this will default to a
value based on \fB$CHPL_HOST_PLATFORM\fP:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
platform
T}	T{
make utility
T}
_
T{
cygwin*, darwin
T}	T{
make
T}
_
T{
linux32, linux64
T}	T{
gmake if available, otherwise make
T}
_
T{
other
T}	T{
gmake
T}
_
.TE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS CHPL_MODULE_PATH
.INDENT 0.0
.INDENT 3.5
Optionally, set the \fBCHPL_MODULE_PATH\fP environment variable to provide a
list of directories to be added to the readme\-module_search\&.  The
value of this environment variable should be a colon\-separated list of
directory paths.
.sp
The module search path is used to satisfy \(aquse\(aq statements in the Chapel
program.  The complete search path can be displayed using the compiler option
\fB\-\-print\-search\-dirs\fP\&.  It will also include the compiler\(aqs standard module
search paths, those introduced by the \fB\-M\fP flag on the command line and
directories containing the .chpl files named explicitly on the compiler
command line.
.UNINDENT
.UNINDENT
.SS CHPL_LOCALE_MODEL
.INDENT 0.0
.INDENT 3.5
Optionally, set the \fBCHPL_LOCALE_MODEL\fP environment variable to
indicate the locale model you want to use.  Current options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
flat
T}	T{
top\-level locales are not further subdivided
T}
_
T{
numa
T}	T{
top\-level locales are further subdivided into
sublocales, each one a NUMA domain
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, \fBCHPL_LOCALE_MODEL\fP defaults to \fBflat\fP\&.
.sp
See readme\-localeModels for more information about
locale models.
.UNINDENT
.UNINDENT
.SS CHPL_TASKS
.INDENT 0.0
.INDENT 3.5
Optionally, set the \fBCHPL_TASKS\fP environment variable to indicate what
tasking layer you want to use to implement intra\-locale parallelism (see
readme\-tasks for more information on this option).  Current options
are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
qthreads
T}	T{
use Sandia\(aqs Qthreads package
T}
_
T{
fifo
T}	T{
use POSIX threads
T}
_
T{
massivethreads
T}	T{
use U Tokyo\(aqs MassiveThreads package
T}
_
T{
muxed
T}	T{
use Cray\-specific lightweight threading (with Cray
pre\-built module only)
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If \fBCHPL_TASKS\fP is not set it defaults to \fBqthreads\fP in all cases
except for a few specific configurations in which it defaults to
\fBfifo\fP:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
target platform is \fBcygwin*\fP
.IP \(bu 2
target platform is \fBnetbsd*\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Note that the Chapel \fButil/quickstart/setchplenv.*\fP source scripts set
\fBCHPL_TASKS\fP to \fBfifo\fP to reduce build\-time and third\-party dependences,
while the \fButil/setchplenv.*\fP versions leave it unset, resulting in the
behavior described just above.
.UNINDENT
.UNINDENT
.sp
See readme\-tasks for more information about executing using the
various \fBCHPL_TASKS\fP options.  See also readme\-cray for more
information about Cray\-specific runtime layers.
.UNINDENT
.UNINDENT
.SS CHPL_COMM
.INDENT 0.0
.INDENT 3.5
Optionally, set the \fBCHPL_COMM\fP environment variable to indicate what
communication layer you want to use to implement inter\-locale communication.
Current options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
none
T}	T{
only supports single\-locale execution
T}
_
T{
gasnet
T}	T{
use the GASNet\-based communication layer
T}
_
T{
ugni
T}	T{
Cray\-specific native communications (with
Cray pre\-built module only)
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, \fBCHPL_COMM\fP defaults to \fBnone\fP in most cases.  On a Cray
system it defaults to \fBgasnet\fP except when using a pre\-built module on a
Cray XC or XE™ system, where it defaults to \fBugni\fP\&.  See
readme\-multilocale for more information on executing Chapel programs
using multiple locales.  See also readme\-cray for more information
about Cray\-specific runtime layers.
.UNINDENT
.UNINDENT
.SS CHPL_MEM
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_MEM\fP environment variable can be used to select
a memory management layer.  Current options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
cstdlib
T}	T{
use the standard C malloc/free commands
T}
_
T{
jemalloc
T}	T{
use Jason Evan\(aqs memory allocation package
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, \fBCHPL_MEM\fP defaults to \fBjemalloc\fP for most configurations.
If the target platform is \fBcygwin*\fP, the target compiler is \fB*pgi\fP,
or the target platform is \fBdarwin\fP and the target compiler is \fBgnu\fP
it defaults to \fBcstdlib\fP
.UNINDENT
.UNINDENT
.SS CHPL_LAUNCHER
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_LAUNCHER\fP environment variable can be used to select
a launcher to get your program up and running.  See readme\-launcher
for more information on this variable\(aqs default and possible settings.
.UNINDENT
.UNINDENT
.SS CHPL_ATOMICS
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_ATOMICS\fP environment variable can be used to
select an implementation for atomic operations in the runtime.  Current
options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
intrinsics
T}	T{
implement atomics using target compiler intrinsics
(which typically map down to hardware capabilities)
T}
_
T{
locks
T}	T{
implement atomics by using Chapel sync variables to
protect normal operations
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, CHPL_ATOMICS defaults to \fBintrinsics\fP for most configurations.
On some 32 bit platforms, or if the target compiler is \fBpgi\fP or
\fBcray\-prgenv\-pgi\fP it defaults to \fBlocks\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
gcc 4.8.1 added support for 64 bit atomics on 32 bit platforms.  We
default to \fBintrinsics\fP for 32 bit platforms when using the target
compiler \fBgnu\fP with a recent enough version of gcc.  For older versions
or other target compilers we default to \fBlocks\fP
.UNINDENT
.UNINDENT
.sp
See the Chapel Language Specification for more information about atomic
operations in Chapel or readme\-atomics for more information about the
runtime implementation.
.UNINDENT
.UNINDENT
.SS CHPL_TIMERS
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_TIMERS\fP environment variable can be used to
select an implementation for Chapel\(aqs timers.  Current options are:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B generic
use a \fBgettimeofday()\fP\-based implementation
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If unset, \fBCHPL_TIMERS\fP defaults to \fBgeneric\fP
.UNINDENT
.UNINDENT
.SS CHPL_GMP
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_GMP\fP environment variable can select between
no GMP support, using the GMP distributed with Chapel in third\-party, or
using a system GMP. Current options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
system
T}	T{
assume GMP is already installed (#include gmp.h, \-lgmp)
T}
_
T{
none
T}	T{
do not build GMP support into the Chapel runtime
T}
_
T{
gmp
T}	T{
use the GMP distribution bundled with Chapel in third\-party
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, Chapel will attempt to build GMP using
\fI\%CHPL_TARGET_COMPILER\fP (noting that the bundled version
may not be supported by all compilers).  Based on the outcome, Chapel will
default to:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
gmp
T}	T{
if the build was successful
T}
_
T{
system
T}	T{
if unsuccessful and \fI\%CHPL_TARGET_PLATFORM\fP is cray\-x*
T}
_
T{
none
T}	T{
otherwise
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Note that the Chapel \fButil/quickstart/setchplenv.*\fP source scripts set
\fBCHPL_GMP\fP to \fBnone\fP while the \fButil/setchplenv.*\fP versions leave it
unset, resulting in the behavior described just above.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS CHPL_HWLOC
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_HWLOC\fP environment variable can select between
no hwloc support or using the hwloc package distributed with Chapel in
third\-party.  Note that hwloc is only used by the qthreads tasking layer,
and does not need to be built for other tasking layers.  Current options
are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
none
T}	T{
do not build hwloc support into the Chapel runtime
T}
_
T{
hwloc
T}	T{
use the hwloc distribution bundled with Chapel in third\-party
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, \fBCHPL_HWLOC\fP defaults to \fBhwloc\fP if \fI\%CHPL_TASKS\fP is
\fBqthreads\fP\&.  In all other cases it defaults to \fBnone\fP\&.  In the unlikely
event the bundled hwloc distribution does not build successfully, it should
still be possible to use qthreads.  To do this, manually set \fBCHPL_HWLOC\fP
to \fBnone\fP and rebuild (and please file a bug with the Chapel team.) Note
that building without hwloc will have a negative impact on performance.
.UNINDENT
.UNINDENT
.SS CHPL_REGEXP
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_REGEXP\fP environment variable can be used to enable
regular expression operations as defined in \fBRegexp\fP\&.  Current
options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
re2
T}	T{
use the re2 distribution in third\-party
T}
_
T{
none
T}	T{
do not support regular expression operations
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, Chapel will attempt to build RE2 using \fI\%CHPL_TARGET_COMPILER\fP
(noting that the bundled version may not be supported by all compilers).
Based on the outcome, Chapel will default to:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
re2
T}	T{
if the build was successful
T}
_
T{
none
T}	T{
otherwise
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Note that the Chapel \fButil/quickstart/setchplenv.*\fP source scripts set
\fBCHPL_REGEXP\fP to \fB\(aqnone\fP while the \fButil/setchplenv.*\fP versions
leave it unset, resulting in the behavior described just above.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS CHPL_AUX_FILESYS
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_AUX_FILESYS\fP environment variable can be used to
request that runtime support for filesystems beyond the usual Linux one be
present.  Current options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
none
T}	T{
only support traditional Linux filesystems
T}
_
T{
hdfs
T}	T{
also support HDFS filesystems using Apache Hadoop libhdfs
T}
_
T{
hdfs3
T}	T{
support for HDFS filesystems using Pivotal libhdfs3
T}
_
T{
curl
T}	T{
also support CURL as a filesystem interface
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, \fBCHPL_AUX_FILESYS\fP defaults to \fBnone\fP\&.
.sp
See readme\-auxIO, \fBHDFS\fP, and \fBCurl\fP for more
information about HDFS and CURL support.
.UNINDENT
.UNINDENT
.SS CHPL_LLVM
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_LLVM\fP environment variable can be used to
enable support for the LLVM back\-end to the Chapel compiler (see
readme\-llvm) or to support extern blocks in Chapel code via
the Clang compiler (see readme\-extern).  Current options are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
llvm
T}	T{
use the llvm/clang distribution in third\-party
T}
_
T{
none
T}	T{
do not support llvm\-/clang\-related features
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
If unset, \fBCHPL_LLVM\fP defaults to \fBllvm\fP if you\(aqve already installed
llvm in third\-party and \fBnone\fP otherwise.
.UNINDENT
.UNINDENT
.SS CHPL_WIDE_POINTERS
.INDENT 0.0
.INDENT 3.5
Optionally, the \fBCHPL_WIDE_POINTERS\fP environment variable can be used to
specify the wide pointer format for multilocale programs.  Current options
are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Value
T}	T{
Description
T}
_
T{
struct
T}	T{
store wide pointers in structures which may span more than
one word
T}
_
T{
nodeN
T}	T{
("N" a number, 2 <= N <= 60) store wide pointers in single
words, with N bits used to store the node (top level locale)
number and the rest containing the address on that node
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
\fBCHPL_WIDE_POINTERS\fP is used to select between two modes of operation.  One is
universally applicable; the other has restricted applicability but may
reduce remote communication.
.sp
If unset, \fBCHPL_WIDE_POINTERS\fP defaults to \fBstruct\fP\&.  This setting works in
all situations and in particular, it is compatible with all locale models
including the hierarchical ones.  The \fBnodeN\fP option does not work with
hierarchical locale models and is only useful with the LLVM backend, which
is currently experimental.  However, when used, it allows LLVM to understand
and optimize remote transfers, potentially reducing the amount of
communication a program performs.  See readme\-llvm for more
information about \fBCHPL_WIDE_POINTERS=nodeN\fP\&.
.UNINDENT
.UNINDENT
.SS Compiler Command Line Option Defaults
.sp
Most of the compiler\(aqs command line options support setting a default value for
the option via an environment variable.  To see a list of the environment
variables that support each option, run the compiler with the \fB\-\-help\-env\fP
flag.  For boolean flags and toggles, setting the environment variable to any
value selects that flag.
.SS Building Chapel
.sp
To build the Chapel compiler, set up your environment as described in
chapelhome\-quickstart (or readme\-chplenv for more
settings), cd to \fB$CHPL_HOME\fP, and type:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmake
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
(or simply "make" if your make utility is gmake\-compatible, as on
Cygwin platforms).
.sp
If everything works as intended, you ought to see:
.INDENT 0.0
.IP 1. 3
each of the compiler source subdirectories being compiled
.IP 2. 3
the compiler binary getting linked and stored as:
.INDENT 3.0
.INDENT 3.5
\fB$CHPL_HOME/bin/$CHPL_HOST_PLATFORM/chpl\fP
.UNINDENT
.UNINDENT
.IP 3. 3
the runtime support libraries being compiled, archived, and stored
in a configuration\-specific subdirectory under:
.INDENT 3.0
.INDENT 3.5
\fB$CHPL_HOME/lib/$CHPL_TARGET_PLATFORM.$CHPL_TARGET_COMPILER.../\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If you get an error or failure during the make process, first
double\-check that you have the required prerequisites (see
readme\-prereqs). If you do, please let us know about the failure
at: \fI\%chapel\-bugs@lists.sourceforge.net\fP (as well as information about your
system as described in readme\-bugs and any workaround that you
come up with).
.sp
Note that each make command only builds the compiler and runtime for
the current set of \fBCHPL_\fP environment variables defined by (and
inferred for) your environment.  Thus, while the directory structure
above supports the ability to have multiple versions of the compiler
and runtime built simultaneously, only one version will be created for
each make command.  To support additional host/target platforms,
host/target compilers, or threading/communication layers, you will
need to reset your environment variables and re\-make.
.sp
After a successful build, you should be able to run the compiler and
display its help message using:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-\-help
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In which case, you will be ready to move on to compiling with the
Chapel compiler (see readme\-compiling).  The rest of this
file gives more information about Chapel\(aqs Makefiles for advanced
users or developers of Chapel.
.SS Platform Support
.sp
Currently supported platforms include 32\- and 64\-bit Linux, Mac OS X,
Cygwin (Windows), SunOS, a variety of current Cray platforms, and a
few systems by other vendors.  Most UNIX\-based environments ought to
support Chapel (subject to the assumptions in readme\-prereqs), but may
not be supported "out\-of\-the\-box" by our current Makefile structure.
See the section below on platform\-specific settings for more
information on adding support for additional UNIX\-compatible
environments.
.sp
Note that a single Chapel installation can simultaneously support
Chapel for multiple platforms and compiler options because all
platform\-specific binary files and executables are stored in
subdirectories named by \fBCHPL_\fP environment variables.
.SS Makefile Targets
.sp
The Chapel sources are structured so that a GNU\-compatible make
utility can be used in any source directory to build the sources
contained in that directory and its subdirectories.  All of these
Makefiles support the following targets:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Target
T}	T{
Action
T}
_
T{
(nothing)
default
all
T}	T{
Build the appropriate output files e.g. objects,
libraries, executables
T}
_
T{
clean
T}	T{
Remove the intermediate files for this configuration
T}
_
T{
cleanall
T}	T{
Remove the intermediate files for all configurations
T}
_
T{
clobber
T}	T{
Remove everything created by the Makefiles
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
Each target processes all subdirectories then the current directory.
.SS Makefile Options
.sp
The Chapel makefiles have a few options that enable or disable optimization,
debugging support, profiling, and backend C compiler warnings. The variables
are described below. Set the value to 1 to enable the feature.
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Option
T}	T{
Effect
T}
_
T{
DEBUG
T}	T{
Generate debug information (e.g. add \-g to C compiler).
T}
_
T{
OPTIMIZE
T}	T{
Enable optimizations (e.g. add \-O3 to C compiler).
T}
_
T{
PROFILE
T}	T{
Enable profiling support (e.g. add \-pg to C compiler).
T}
_
T{
WARNINGS
T}	T{
Promote backend C compiler warnings to errors.
T}
_
.TE
.UNINDENT
.UNINDENT
.SS Platform\-specific Settings
.sp
The structure of Chapel\(aqs Makefiles is designed to factor any
compiler\-specific settings in
\fB$CHPL_HOME/make/compiler/Makefile.<compiler>\fP where \fB<compiler>\fP refers
to \fB$CHPL_HOST_COMPILER\fP for the compiler sources and
\fB$CHPL_TARGET_COMPILER\fP for the runtime sources and generated code.
Refer to readme\-chplenv for more information about these variables and
their default settings.
.sp
In addition, any architecture\-specific settings are defined in
\fB$CHPL_HOME/make/platform/Makefile.<platform>\fP, where \fB<platform>\fP refers
to \fB$CHPL_HOST_PLATFORM\fP for the compiler sources and
\fB$CHPL_TARGET_PLATFORM\fP for the runtime sources and generated code.
Again, readme\-chplenv details these variables and their default
settings.
.sp
If you try making the compiler and runtime for an unknown platform, it
will assume that you want to use gcc/g++ to compile the code and that
you require no platform\-specific settings.  You can add support for a
new build environment by creating \fBMakefile.<compiler>\fP and/or
\fBMakefile.<platform>\fP files and setting your environment variables to
refer to those files.  If you do develop new build environment support
that you would like to contribute back to the community, we encourage
you to send your changes back to us at: \fI\%chapel_info@cray.com\fP
.SS Compiling Chapel Programs
.sp
The Chapel compiler converts programs expressed in Chapel source code
into the corresponding executable form.  This document briefly discusses
running the Chapel compiler.
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Compiling Chapel Programs\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Getting Help\fP
.IP \(bu 2
\fI\%Most Useful Flags\fP
.UNINDENT
.UNINDENT
.SS Getting Help
.sp
If you have set up your environment as described in readme\-chplenv and
built the compiler as described in readme\-building, you can see the
Chapel compiler\(aqs help message using:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-\-help
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
This displays the compiler\(aqs command\-line flags sorted by category.
For each flag, the short one\-letter form is given (if one exists),
followed by the long form of the flag.  Next, the pattern for any
arguments to the flag are given.  And finally a brief description of
the flag is provided.  A flag may have a corresponding environment
variable, setting which is equivalent to passing the flag.  These
variables are listed by the \fB\-\-help\-env\fP option.  The flags\(aq current
settings are listed by \fB\-\-help\-settings\fP\&.
.sp
More detailed information about the compiler and its command\-line
flags is also available on its \fBman page\fP, which can be viewed from
the command\-line using:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
man chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Most Useful Flags
.sp
We note some of the most useful flags here:
.TS
center;
|l|l|.
_
T{
Flags
T}	T{
Description
T}
_
T{
\fB\-o <filename>\fP
T}	T{
specify the filename of the generated
executable, otherwise ./a.out is used by default
T}
_
T{
\fB\-\-no\-checks\fP
T}	T{
turns off runtime semantic checks like bounds
checking and nil class instance dereferencing
T}
_
T{
\fB\-O\fP
T}	T{
turns on optimization of the generated C code
T}
_
T{
\fB\-\-fast\fP
T}	T{
turns on \fB\-\-no\-checks\fP, \fB\-O\fP, and enables
many other optimizations
T}
_
T{
\fB\-\-savec <dir>\fP
T}	T{
saves the generated C code in the specified
directory
T}
_
T{
\fB\-g\fP
T}	T{
support debugging of the generated C code
T}
_
T{
\fB\-\-ccflags <flags>\fP
T}	T{
specify flags that should be used when invoking
the back\-end C compiler
T}
_
T{
\fB\-\-ldflags <flags>\fP
T}	T{
specify flags that should be used when invoking
the back\-end linker
T}
_
T{
\fB\-s <name[=expr]>\fP
T}	T{
set a config variable with the given expression
as its default value (config params must be set
to values that are known at compile time)
T}
_
T{
\fB\-\-print\-passes\fP
T}	T{
print the compiler passes as they execute
T}
_
T{
\fB\-\-print\-commands\fP
T}	T{
print the system commands that the compiler
executes
T}
_
T{
\fB\-\-print\-code\-size\fP
T}	T{
prints some code size statistics about the
number of lexical tokens per line, as well as
the number of code, comment, and blank lines
T}
_
T{
\fB\-\-version\fP
T}	T{
print the Chapel compiler version number
T}
_
T{
\fB\-\-help\fP
T}	T{
print a brief overview of the command\-line
options
T}
_
T{
\fB\-\-help\-env\fP
T}	T{
lists the environment variables for each
command\-line flag
T}
_
T{
\fB\-\-help\-settings\fP
T}	T{
lists the current setting of each command\-line
flag
T}
_
.TE
.SS chpl
.SS SYNOPSIS
.nf
\fBchpl\fP [\fB\-O\fP] [\fB\-\-no\-checks\fP] [\fB\-\-fast\fP]
.in +2
[\fB\-g\fP] [\fB\-\-savec\fP \fIdirectory\fP]
[\fB\-M\fP \fIdirectory\fP\&...] [\fB\-\-main\-module\fP \fImod\fP]
[\fB\-o\fP \fIoutfile\fP] [\fIoptions\fP] source\-files...

.in -2
.fi
.sp
.SS DESCRIPTION
.sp
The \fBchpl\fP command invokes the Chapel compiler. \fBchpl\fP converts one
or more Chapel source files into an executable. It does this by
compiling Chapel code to C99 code and then invoking the target
platform\(aqs C compiler to create the executable. However, most users will
not need to be aware of the use of C as an intermediate format during
compilation.
.SS SOURCE FILES
.sp
Chapel recognizes four source file types: \fB\&.chpl\fP, .c, .h, and .o.
.sp
\fBfoo.chpl\fP
.INDENT 0.0
.INDENT 3.5
Chapel sources are compiled by the Chapel compiler into C intermediate
code, which is then passed to the target compiler to be compiled into
object code.
.UNINDENT
.UNINDENT
.sp
\fBfoo.c\fP
.INDENT 0.0
.INDENT 3.5
C source files are passed directly to the target C compiler.
.UNINDENT
.UNINDENT
.sp
\fBfoo.h\fP
.INDENT 0.0
.INDENT 3.5
C header files are included in the generated C code.
.UNINDENT
.UNINDENT
.sp
\fBfoo.o\fP
.INDENT 0.0
.INDENT 3.5
Object files are passed directly to the target linker.
.UNINDENT
.UNINDENT
.SS OPTIONS
.sp
\fIModule Processing Options\fP
.sp
\fB\-\-[no\-]count\-tokens\fP
.INDENT 0.0
.INDENT 3.5
Prints the total number of static lexical tokens in the Chapel code
files named on the command line.
.UNINDENT
.UNINDENT
.sp
\fB\-\-main\-module <module>\fP
.INDENT 0.0
.INDENT 3.5
For programs that supply multiple possible entry points (main()
functions or module initializers that can serve as an entry point), this
option can be used to specify which module should serve as the starting
point for program execution.
.UNINDENT
.UNINDENT
.sp
\fB\-M, \-\-module\-dir <\fP\fIdirectory\fP\fB>\fP
.INDENT 0.0
.INDENT 3.5
Add the specified \fIdirectory\fP to the module search path. The module
search path is used to satisfy module \(aquse\(aq statements. In the current
implementation, the compiler tries to locate unresolved modules by
searching for a filename whose name matches that of the module. For
example, if the user program contains \(aquse foo\(aq and the .\fBchpl\fP
files listed by the programmer on the compiler\(aqs command line do not
define a module named \(aqfoo\(aq, the compiler will search for files named
\(aqfoo.chpl\(aq in the module search path. The complete path that will be
searched can be displayed using the \fB\-\-print\-search\-dirs\fP flag and is
composed of (1) the directories containing the .\fBchpl\fP files that
were specified on the compiler command\-line (in left\-to\-right order),
(2) all directories specified by \fB\-M\fP flags (in left\-to\-right order),
(3) all directories specified by the $CHPL_MODULE_PATH environment
variable (colon\-separated directories), (4) the compiler\(aqs standard
module search path.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]print\-code\-size\fP
.INDENT 0.0
.INDENT 3.5
Prints out the size of the Chapel code files named on the command line
in great detail: For each code file, first the code is echoed back to
the screen, prefixing each line with the number of lexical tokens it
contains, or *C* if the line only contains comments, or *B* if the
line is blank. Next, the total number of tokens for the file is printed.
Then the number of lines is displayed, broken down into code lines,
comment\-only lines, and blank lines. Then the maximum and average number
of tokens per line is displayed. Finally, a histogram of the number of
tokens per line is shown. After this information is printed for each
file, a grand total of the number of tokens across all the files is
displayed.
.UNINDENT
.UNINDENT
.sp
\fB\-\-print\-module\-files\fP
.INDENT 0.0
.INDENT 3.5
Prints the Chapel module source files parsed by the Chapel compiler.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]print\-search\-dirs\fP
.INDENT 0.0
.INDENT 3.5
Print the module search path used to resolve module for further details.
.UNINDENT
.UNINDENT
.sp
\fIParallelism Control Options\fP
.sp
\fB\-\-[no\-]local\fP
.INDENT 0.0
.INDENT 3.5
Compile code for single/[multi\-] \fIlocale\fP execution, changing \fIon
blocks\fP to normal blocks, evaluating the \fIlocale\fP expression for side
effects, and optimizing away all remote references in the code. When
$CHPL_COMM is set to "none", \fB\-\-local\fP is the default; otherwise
\fB\-\-no\-local\fP is the default.
.UNINDENT
.UNINDENT
.sp
\fIOptimization Control Options\fP
.sp
\fB\-\-baseline\fP
.INDENT 0.0
.INDENT 3.5
Turns off all optimizations in the Chapel compiler and generates naive C
code with many temporaries.
.UNINDENT
.UNINDENT
.sp
\fB\-\-cache\-remote\fP
.INDENT 0.0
.INDENT 3.5
Enables the cache for remote data. This cache can improve communication
performance for some programs by adding aggregation, write behind, and
read ahead. This cache is not enabled by any other optimization
\fIoptions\fP such as \fB\-\-fast\fP\&.
.UNINDENT
.UNINDENT
.sp
\fB\-\-conditional\-dynamic\-dispatch\-limit\fP
.INDENT 0.0
.INDENT 3.5
When greater than zero, this limit controls when the compiler will
generate code to handle dynamic dispatch with conditional statements. If
the number of possible method calls is less than or equal to this limit,
a (possibly nested) conditional statement will be used for dynamic
dispatch instead of the virtual method table. The default is zero.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]copy\-propagation\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] copy propagation.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]dead\-code\-elimination\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] dead code elimination.
.UNINDENT
.UNINDENT
.sp
\fB\-\-fast\fP
.INDENT 0.0
.INDENT 3.5
Turns off all runtime checks using \fB\-\-no\-checks\fP, turns on \fB\-O\fP,
\fB\-\-specialize\fP, and \fB\-\-vectorize\fP\&.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]fast\-followers\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] the fast follower optimization in which fast
implementations of followers will be invoked for specific leaders.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]ieee\-float\fP
.INDENT 0.0
.INDENT 3.5
Disable [enable] optimizations that may affect IEEE floating point
conformance. The default is whatever level of optimization/IEEE floating
point support your C compiler provides at the optimization level
provided by \(aq\fBchpl\fP\(aq.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]loop\-invariant\-code\-motion\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] the optimization that moves loop invariant code from
loop runs into the loop\(aqs "pre\-header." By default invariant code is
moved. This is currently a rather conservative pass in the sense that it
may not identify all code that is truly invariant.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]ignore\-local\-classes\fP
.INDENT 0.0
.INDENT 3.5
Disable [enable] local classes
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]inline\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] function inlining.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]inline\-iterators\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] iterator inlining. When possible, the compiler
optimizes the invocation of an iterator in a loop header by inlining the
iterator\(aqs definition around the loop body.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]live\-analysis\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] live variable analysis, which is currently only used to
optimize iterators that are not inlined.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]optimize\-loop\-iterators\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] optimizations to aggressively optimize iterators that
are defined in terms of a single loop. By default this is enabled.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]vectorize\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] generating vectorization hints for target compiler. If
enabled, hints will always be generated, but the effects will vary based
on the target compiler.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]optimize\-on\-clauses\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] optimization of on clauses in which qualifying on
statements may be optimized in the runtime if supported by the
$CHPL_COMM layer.
.UNINDENT
.UNINDENT
.sp
\fB\-\-optimize\-on\-clause\-limit\fP
.INDENT 0.0
.INDENT 3.5
Limit on the function call depth to allow for on clause optimization.
The default value is 20.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]privatization\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] privatization of distributed arrays and domains if the
distribution supports it.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]remove\-copy\-calls\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] removal of copy calls (including calls to what amounts
to a copy constructor for records) that ensure Chapel semantics but
which can often be optimized away.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]remote\-value\-forwarding\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] remote value forwarding of read\-only values to remote
threads if reading them early does not violate program semantics.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]scalar\-replacement\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] scalar replacement of records and classes for some
compiler\-generated data structures that support language features such
as tuples and iterators.
.UNINDENT
.UNINDENT
.sp
\fB\-\-scalar\-replace\-limit\fP
.INDENT 0.0
.INDENT 3.5
Limit on the size of tuples being replaced during scalar replacement.
The default value is 8.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]tuple\-copy\-opt\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] the tuple copy optimization in which whole tuple copies
of homogeneous tuples are replaced with explicit assignment of each
tuple component.
.UNINDENT
.UNINDENT
.sp
\fB\-\-tuple\-copy\-limit\fP
.INDENT 0.0
.INDENT 3.5
Limit on the size of tuples considered for the tuple copy optimization.
The default value is 8.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]use\-noinit\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] ability to skip default initialization through the
keyword noinit
.UNINDENT
.UNINDENT
.sp
\fIRun\-time Semantic Check Options\fP
.sp
\fB\-\-no\-checks\fP
.INDENT 0.0
.INDENT 3.5
Turns off all of the run\-time checks in this section of the man page.
Currently, it is typically necessary to use this flag (or \fB\-\-fast\fP,
which implies \fB\-\-no\-checks\fP) to achieve performance competitive with
hand\-coded C or Fortran.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]bounds\-checks\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] run\-time bounds checking, e.g. during slicing and array
indexing.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]formal\-domain\-checks\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] run\-time checks to ensure that an actual array
argument\(aqs domain matches its formal array argument\(aqs domain in terms of
(a) describing the same index set and (b) having an equivalent domain
map (if the formal domain explicitly specifies a domain map).
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]local\-checks\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] run\-time checking of the locality of references within
local blocks.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]nil\-checks\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] run\-time checking for accessing nil object references.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]stack\-checks\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] run\-time checking for stack overflow.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]cast\-checks\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] run\-time checks in safeCast calls for casts that
wouldn\(aqt preserve the logical value being cast.
.UNINDENT
.UNINDENT
.sp
\fIC Code Generation Options\fP
.sp
\fB\-\-[no\-]codegen\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] generating C code and the binary executable. Disabling
code generation is useful to reduce compilation time, for example, when
only Chapel compiler warnings/errors are of interest.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]cpp\-lines\fP
.INDENT 0.0
.INDENT 3.5
Causes the compiler to emit cpp #line directives into the generated code
in order to help map generated C code back to the Chapel source code
that it implements. The [no\-] version of this flag turns this feature
off.
.UNINDENT
.UNINDENT
.sp
\fB\-\-max\-c\-ident\-len\fP
.INDENT 0.0
.INDENT 3.5
Limits the length of identifiers in the generated code, except when set
to 0. The default is 0, except when $CHPL_TARGET_COMPILER indicates a
PGI compiler (pgi or cray\-prgenv\-pgi), in which case the default is
1020.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]munge\-user\-idents\fP
.INDENT 0.0
.INDENT 3.5
By default, \fBchpl\fP munges all user identifiers in the generated C code
in order to minimize the chances of conflict with an identifier or
keyword in C (in the current implementation, this is done by appending
\(aq_chpl\(aq to the identifier). This flag provides the ability to disable
this munging. Note that whichever mode, the flag is in, \fBchpl\fP may
perform additional munging in order to implement Chapel semantics in C,
or for other reasons.
.UNINDENT
.UNINDENT
.sp
\fB\-\-savec <dir>\fP
.INDENT 0.0
.INDENT 3.5
Saves the compiler\-generated C code in the specified \fIdirectory\fP,
creating the \fIdirectory\fP if it does not already exist. This option may
overwrite existing files in the \fIdirectory\fP\&.
.UNINDENT
.UNINDENT
.sp
\fIC Code Compilation Options\fP
.sp
\fB\-\-ccflags <flags>\fP
.INDENT 0.0
.INDENT 3.5
Add the specified flags to the C compiler command line when compiling
the generated code. Multiple \fB\-\-ccflags\fP \fIoptions\fP can be provided and
in that case the combination of the flags will be forwarded to the C
compiler.
.UNINDENT
.UNINDENT
.sp
\fB\-g, \-\-[no\-]debug\fP
.INDENT 0.0
.INDENT 3.5
Causes the generated C code to be compiled with debugging turned on. If
you are trying to debug a Chapel program, this flag is virtually
essential along with the \fB\-\-savec\fP flag. This flag also turns on the
\fB\-\-cpp\-lines\fP option unless compiling as a developer (for example, via
\fB\-\-devel\fP).
.UNINDENT
.UNINDENT
.sp
\fB\-\-dynamic\fP
.INDENT 0.0
.INDENT 3.5
Use dynamic linking when generating the final binary. If neither
\fB\-\-dynamic\fP or \fB\-\-static\fP are specified, use the backend compiler\(aqs
default.
.UNINDENT
.UNINDENT
.sp
\fB\-I, \-\-hdr\-search\-path <dir>\fP
.INDENT 0.0
.INDENT 3.5
Add dir to the back\-end C compiler\(aqs search path for header files.
.UNINDENT
.UNINDENT
.sp
\fB\-\-ldflags <flags>\fP
.INDENT 0.0
.INDENT 3.5
Add the specified flags to the C compiler link line when linking the
generated code. Multiple \fB\-\-ldflags\fP \fIoptions\fP can be provided and in
that case the combination of the flags will be forwarded to the C
compiler.
.UNINDENT
.UNINDENT
.sp
\fB\-l, \-\-lib\-linkage <library>\fP
.INDENT 0.0
.INDENT 3.5
Specify a C library to link in on the C compiler command line.
.UNINDENT
.UNINDENT
.sp
\fB\-L, \-\-lib\-search\-path <dir>\fP
.INDENT 0.0
.INDENT 3.5
Specify a C library search path on the C compiler command line.
.UNINDENT
.UNINDENT
.sp
\fB\-O, \-\-[no\-]optimize\fP
.INDENT 0.0
.INDENT 3.5
Causes the generated C code to be compiled with [without] optimizations
turned on. The specific set of flags used by this option is
platform\-dependent; use the \fB\-\-print\-commands\fP option to view the C
compiler command used. If you would like additional flags to be used
with the C compiler command, use the \fB\-\-ccflags\fP option.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]specialize\fP
.INDENT 0.0
.INDENT 3.5
Causes the generated C code to be compiled with flags that specialize
the executable to the architecture that is defined by
CHPL_TARGET_ARCH. The effects of this flag will vary based on choice
of back\-end compiler and the value of CHPL_TARGET_ARCH.
.UNINDENT
.UNINDENT
.sp
\fB\-o, \-\-output <filename>\fP
.INDENT 0.0
.INDENT 3.5
Specify the name of the compiler\-generated executable (defaults to a.out
if unspecified).
.UNINDENT
.UNINDENT
.sp
\fB\-\-static\fP
.INDENT 0.0
.INDENT 3.5
Use static linking when generating the final binary. If neither
\fB\-\-static\fP or \fB\-\-dynamic\fP are specified, use the backend compiler\(aqs
default.
.UNINDENT
.UNINDENT
.sp
\fILLVM Code Generation Options\fP
.sp
\fB\-\-[no\-]llvm\fP
.INDENT 0.0
.INDENT 3.5
Use LLVM as the code generation target rather than C. See
$CHPL_HOME/doc/technotes/llvm.rst for details.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]llvm\-wide\-opt\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] LLVM wide pointer communication optimizations. This
option requires \fB\-\-llvm\fP and packed wide pointers. Packed wide
pointers are enabled by setting CHPL_WIDE_POINTERS = node16. You must
also supply \fB\-\-fast\fP to enable wide pointer optimizations. This flag
allows existing LLVM optimizations to work with wide pointers \- for
example, they might be able to hoist a \(aqget\(aq out of a loop. See
$CHPL_HOME/doc/technotes/llvm.rst for details.
.UNINDENT
.UNINDENT
.sp
\fICompilation Trace Options\fP
.sp
\fB\-\-[no\-]print\-commands\fP
.INDENT 0.0
.INDENT 3.5
Prints the system commands that the compiler executes in order to
compile the Chapel program.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]print\-passes\fP
.INDENT 0.0
.INDENT 3.5
Prints the compiler passes during compilation and the amount of wall
clock time required for the pass. After compilation is complete two
tables are produced that provide more detail of how time is spent in
each pass (compiling, verifying, and memory management) and the
percentage of the total time that is attributed to each pass. The first
table is sorted by pass and the second table is sorted by the time for
the pass in descending order.
.UNINDENT
.UNINDENT
.sp
\fB\-\-print\-passes\-file <filename>\fP
.INDENT 0.0
.INDENT 3.5
Saves the compiler passes and the amount of wall clock time required for
the pass to <filename>. An error is displayed if the file cannot be
opened but no recovery attempt is made.
.UNINDENT
.UNINDENT
.sp
\fIMiscellaneous Options\fP
.sp
\fB\-\-[no\-]devel\fP
.INDENT 0.0
.INDENT 3.5
Puts the compiler into [out of] developer mode, which takes off some of
the safety belts, changes default behaviors, and exposes additional
undocumented command\-line \fIoptions\fP\&. Use at your own risk and direct any
questions to the Chapel team.
.UNINDENT
.UNINDENT
.sp
\fB\-\-explain\-call <call>[:<module>][:<line>]\fP
.INDENT 0.0
.INDENT 3.5
Helps explain the function resolution process for the named function by
printing out the visible and candidate functions. Specifying a module
name and/or line number can focus the explanation to those calls within
a specific module or at a particular line number.
.UNINDENT
.UNINDENT
.sp
\fB\-\-explain\-instantiation <function|type>[:<module>][:<line>]\fP
.INDENT 0.0
.INDENT 3.5
Lists all of the instantiations of a function or type. The location of
one of possibly many points of instantiation is shown. Specifying a
module name and/or line number can focus the explanation to those calls
within a specific module or at a particular line number.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]explain\-verbose\fP
.INDENT 0.0
.INDENT 3.5
In combination with explain\-call or explain\-instantiation, causes the
compiler to output more debug information related to disambiguation.
.UNINDENT
.UNINDENT
.sp
\fB\-\-instantiate\-max <max>\fP
.INDENT 0.0
.INDENT 3.5
In order to avoid infinite loops when instantiating generic functions,
the compiler limits the number of times a single function can be
instantiated. This flag raises that maximum in the event that a legal
instantiation is being pruned too aggressively.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]print\-callstack\-on\-error\fP
.INDENT 0.0
.INDENT 3.5
Accompany certain error and warning messages with the Chapel call stack
that the compiler was working on when it reached the error or warning
location. This is useful when the underlying cause of the issue is in
one of the callers.
.UNINDENT
.UNINDENT
.sp
\fB\-s, \-\-set <config param>[=<value>]\fP
.INDENT 0.0
.INDENT 3.5
Overrides the default value of a configuration parameter in the code.
For boolean configuration variables, the value can be omitted, causing
the default value to be toggled.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]task\-tracking\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] the Chapel\-implemented task tracking table that
supports the execution\-time \fB\-b\fP / \fB\-t\fP flags. This option is
currently only useful when $CHPL_TASKS is set or inferred to \(aqfifo\(aq and
adds compilation\-time overhead when it will not be used, so is off by
default.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]warn\-const\-loops\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] warnings for \(aqwhile\(aq loops whose condition is a \(aqconst\(aq
variable, because such a loop condition is likely unintended. \(aqWhile\(aq
loops with \(aqparam\(aq conditions do not trigger this warning.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]warn\-special\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] all special compiler warnings issued due to syntax and
other language changes. Currently, these include
\-\-[no\-]warn\-domain\-literal and \-\-[no\-]warn\-tuple\-iteration.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]warn\-domain\-literal\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] compiler warnings regarding the potential use of the
old\-style domain literal syntax (e.g. [1..2, 3..4]). All array literals
with range elements will result in warnings.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]warn\-tuple\-iteration\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] compiler warnings regarding the potential use of
old\-style zippering syntax. All uses of tuple iteration will produce
warnings.
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]warnings\fP
.INDENT 0.0
.INDENT 3.5
Enable [disable] the printing of compiler warnings. Defaults to printing
warnings.
.UNINDENT
.UNINDENT
.sp
\fICompiler Configuration Options\fP
.sp
\fB\-\-home <path>\fP
.INDENT 0.0
.INDENT 3.5
Specify the location of the Chapel installation \fIdirectory\fP\&. This flag
corresponds with and overrides the $CHPL_HOME environment variable.
.UNINDENT
.UNINDENT
.sp
\fB\-\-atomics <atomics\-impl>\fP
.INDENT 0.0
.INDENT 3.5
Specify the implementation to use for Chapel\(aqs atomic variables. This
flag corresponds with and overrides the $CHPL_ATOMICS environment
variable. (defaults to a best guess based on $CHPL_TARGET_COMPILER,
$CHPL_TARGET_PLATFORM, and $CHPL_COMM)
.UNINDENT
.UNINDENT
.sp
\fB\-\-network\-atomics <network>\fP
.INDENT 0.0
.INDENT 3.5
Specify the network atomics implementation for all atomic variables.
This flag corresponds with and overrides the $CHPL_NETWORK_ATOMICS
environment variable (defaults to best guess based on $CHPL_COMM).
.UNINDENT
.UNINDENT
.sp
\fB\-\-aux\-filesys <aio\-system>\fP
.INDENT 0.0
.INDENT 3.5
Specify runtime support for additional file systems. This flag
corresponds with and overrides the $CHPL_AUX_FILESYS environment
variable (defaults to \(aqnone\(aq).
.UNINDENT
.UNINDENT
.sp
\fB\-\-comm <comm\-impl>\fP
.INDENT 0.0
.INDENT 3.5
Specify the communication implementation to use for inter\-\fIlocale\fP
data transfers. This flag corresponds with and overrides the $CHPL_COMM
environment variable (defaults to \(aqnone\(aq).
.UNINDENT
.UNINDENT
.sp
\fB\-\-comm\-substrate <conduit>\fP
.INDENT 0.0
.INDENT 3.5
Specify the communication conduit for the communication implementation.
This flag corresponds with and overrides the $CHPL_COMM_SUBSTRATE
environment variable (defaults to best guess based on
$CHPL_TARGET_PLATFORM).
.UNINDENT
.UNINDENT
.sp
\fB\-\-gasnet\-segment <segment>\fP
.INDENT 0.0
.INDENT 3.5
Specify memory segment to use with GASNet. This flag corresponds with
and overrides the $CHPL_GASNET_SEGMENT environment variable. (defaults
to best guess based on $CHPL_COMM_SUBSTRATE).
.UNINDENT
.UNINDENT
.sp
\fB\-\-gmp <gmp\-version>\fP
.INDENT 0.0
.INDENT 3.5
Specify the GMP library implementation to be used by the GMP module.
This flag corresponds with and overrides the $CHPL_GMP environment
variable (defaults to best guess based on $CHPL_TARGET_PLATFORM and
whether you\(aqve built the included GMP library in the third\-party
\fIdirectory\fP).
.UNINDENT
.UNINDENT
.sp
\fB\-\-hwloc <hwloc\-impl>\fP
.INDENT 0.0
.INDENT 3.5
Specify whether or not to use the hwloc library. This flag corresponds
with and overrides the $CHPL_HWLOC environment variable (defaults to a
best guess based on whether you\(aqve built the included library in the
third\-party hwloc \fIdirectory\fP).
.UNINDENT
.UNINDENT
.sp
\fB\-\-launcher <launcher\-system>\fP
.INDENT 0.0
.INDENT 3.5
Specify the launcher, if any, used to start job execution. This flag
corresponds with and overrides the $CHPL_LAUNCHER environment variable
(defaults to a best guess based on $CHPL_COMM and
$CHPL_TARGET_PLATFORM).
.UNINDENT
.UNINDENT
.sp
\fB\-\-locale\-model <locale\-model>\fP
.INDENT 0.0
.INDENT 3.5
Specify the \fIlocale\fP model to use for describing your \fIlocale\fP
architecture. This flag corresponds with and overrides the
$CHPL_LOCALE_MODEL environment variable (defaults to \(aqflat\(aq).
.UNINDENT
.UNINDENT
.sp
\fB\-\-make <make utility>\fP
.INDENT 0.0
.INDENT 3.5
Specify the GNU compatible make utility. This flag corresponds with and
overrides the $CHPL_MAKE environment variable (defaults to a best guess
based on $CHPL_HOST_PLATFORM).
.UNINDENT
.UNINDENT
.sp
\fB\-\-mem <mem\-impl>\fP
.INDENT 0.0
.INDENT 3.5
Specify the memory allocator used for dynamic memory management. This
flag corresponds with and overrides the $CHPL_MEM environment variable
(defaults to a best guess based on $CHPL_COMM).
.UNINDENT
.UNINDENT
.sp
\fB\-\-regexp <regexp>\fP
.INDENT 0.0
.INDENT 3.5
Specify the regular expression library to use. This flag corresponds
with and overrides the $CHPL_REGEXP environment variable (defaults to
\(aqnone\(aq or \(aqre2\(aq if you\(aqve installed the re2 package in the third\-party
\fIdirectory\fP).
.UNINDENT
.UNINDENT
.sp
\fB\-\-target\-arch <architecture>\fP
.INDENT 0.0
.INDENT 3.5
Specify the architecture that the compiled executable will be
specialized to when \fB\-\-specialize\fP is enabled. This flag corresponds
with and overrides the $CHPL_TARGET_ARCH environment variable
(defaults to a best guess based on $CHPL_COMM, $CHPL_TARGET_COMPILER,
and $CHPL_TARGET_PLATFORM).
.UNINDENT
.UNINDENT
.sp
\fB\-\-target\-compiler <compiler>\fP
.INDENT 0.0
.INDENT 3.5
Specify the compiler suite that should be used to build the generated C
code for a Chapel program and the Chapel runtime. This flag corresponds
with and overrides the $CHPL_TARGET_COMPILER environment variable
(defaults to a best guess based on $CHPL_HOST_PLATFORM,
$CHPL_TARGET_PLATFORM, and $CHPL_HOST_COMPILER).
.UNINDENT
.UNINDENT
.sp
\fB\-\-target\-platform <platform>\fP
.INDENT 0.0
.INDENT 3.5
Specify the platform on which the target executable is to be run for the
purposes of cross\-compiling. This flag corresponds with and overrides
the $CHPL_TARGET_PLATFORM environment variable (defaults to
$CHPL_HOST_PLATFORM).
.UNINDENT
.UNINDENT
.sp
\fB\-\-tasks <task\-impl>\fP
.INDENT 0.0
.INDENT 3.5
Specify the tasking layer to use for implementing tasks. This flag
corresponds with and overrides the $CHPL_TASKS environment variable
(defaults to a best guess based on $CHPL_TARGET_PLATFORM).
.UNINDENT
.UNINDENT
.sp
\fB\-\-timers <timer\-impl>\fP
.INDENT 0.0
.INDENT 3.5
Specify a timer implementation to be used by the Time module. This flag
corresponds with and overrides the $CHPL_TIMERS environment variable
(defaults to \(aqgeneric\(aq).
.UNINDENT
.UNINDENT
.sp
\fB\-\-wide\-pointers <format>\fP
.INDENT 0.0
.INDENT 3.5
Specify the wide pointer format format. This flag corresponds with and
overrides the $CHPL_WIDE_POINTERS environment variable (defaults to
\(aqstruct\(aq).
.UNINDENT
.UNINDENT
.sp
\fICompiler Information Options\fP
.sp
\fB\-\-copyright\fP
.INDENT 0.0
.INDENT 3.5
Print the compiler\(aqs copyright information.
.UNINDENT
.UNINDENT
.sp
\fB\-h, \-\-help\fP
.INDENT 0.0
.INDENT 3.5
Print a list of the command line \fIoptions\fP, indicating the arguments
that they expect and a brief summary of their purpose.
.UNINDENT
.UNINDENT
.sp
\fB\-\-help\-env\fP
.INDENT 0.0
.INDENT 3.5
Print the command line option help message, listing the environment
variable equivalent for each flag (see ENVIRONMENT) and its current
value.
.UNINDENT
.UNINDENT
.sp
\fB\-\-help\-settings\fP
.INDENT 0.0
.INDENT 3.5
Print the command line option help message, listing the current setting
of each option as specified by environment variables and other flags on
the command line.
.UNINDENT
.UNINDENT
.sp
\fB\-\-license\fP
.INDENT 0.0
.INDENT 3.5
Print the compiler\(aqs license information.
.UNINDENT
.UNINDENT
.sp
\fB\-\-version\fP
.INDENT 0.0
.INDENT 3.5
Print the version number of the compiler.
.UNINDENT
.UNINDENT
.SS ENVIRONMENT
.sp
Most compiler command\-line \fIoptions\fP have an environment variable that
can be used to specify a default value. Use the \fB\-\-help\-env\fP option to
list the environment variable equivalent for each option. Command\-line
\fIoptions\fP will always override environment variable settings in the
event of a conflict, except for ccflags and ldflags, which stack.
.sp
If the environment variable equivalent is set to empty, it is considered
unset. This does not apply to \fIoptions\fP expecting a string or a path.
.sp
For \fIoptions\fP that can be used with or without the leading \fB\-\-no\fP
(they are shown with "[no\-]" in the help text), the environment variable
equivalent, when set to a non\-empty string, has the following effect.
When the first character of the string is one of:
.nf

.fi
.sp
.INDENT 0.0
.INDENT 3.5
Y y T t 1 \- same as passing the option without \-\-no,
.sp
N n F f 0 \- same as passing the option with \-\-no,
.sp
anything else \- generates an error.
.UNINDENT
.UNINDENT
.sp
For the other \fIoptions\fP that enable, disable or toggle some feature, any
non\-empty value of the environment variable equivalent has the same
effect as passing that option once.
.SS BUGS
.sp
See $CHPL_HOME/STATUS for a list of known bugs and
$CHPL_HOME/doc/bugs.rst for instructions on reporting bugs.
.SS SEE ALSO
.sp
$CHPL_HOME/QUICKSTART.rst for more information on how to get started with
Chapel.
.SS AUTHORS
.sp
See $CHPL_HOME/CONTRIBUTORS.md for a list of contributors to Chapel.
.SS COPYRIGHT
.sp
Copyright (c) 2004\-2016 Cray Inc. (See $CHPL_HOME/LICENSE for more
details.)
.SS Executing Chapel Programs
.sp
Once you have compiled a Chapel program using the chpl compiler, you
can execute it from the command\-line like any other program.  This
document discusses command line options, environment variables, and
other topics having to do with running programs written in Chapel.
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Executing Chapel Programs\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Getting Help\fP
.IP \(bu 2
\fI\%Setting Configuration Variables\fP
.IP \(bu 2
\fI\%Setting the Number of Locales\fP
.IP \(bu 2
\fI\%Controlling Degree of Data Parallelism\fP
.IP \(bu 2
\fI\%Environment Variable Control over Chapel Behavior\fP
.IP \(bu 2
\fI\%Controlling the Call Stack Size\fP
.IP \(bu 2
\fI\%Controlling the Number of Threads\fP
.IP \(bu 2
\fI\%Controlling the Amount of Non\-User Output\fP
.IP \(bu 2
\fI\%Launcher Support\fP
.UNINDENT
.UNINDENT
.SS Getting Help
.sp
Using the \fB\-h\fP or \fB\-\-help\fP flags will print out help for the
executable.  For example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./a.out \-\-help
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
This flag lists all of the standard flags that can be used with a
Chapel program, as well as a list of the configuration variables
defined by the program and their types.  If the configuration variable
has been set on the command line, its value is also shown.
.SS Setting Configuration Variables
.sp
Configuration constants and variables defined in a Chapel program can
have their default values overridden on the command line using the \fB\-s\fP
or \fB\-\-\fP flags.  Either flag takes the name of the configuration variable
followed by an equals character (\fB=\fP) and the value to assign to it.
This value must be a legal Chapel literal for the type of the variable.
(Exception: for a string literal, the surrounding quotes are implicit.)
In our current implementation, no extra spaces may appear between
these elements.  Thus, the general form is:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./a.out \-\-<cfgVar>=<val>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./a.out \-s<cfgVar>=<val>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
As an example, compile the hello2\-module.chpl example which prints a
user\-definable message:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-o hello2\-module $CHPL_HOME/examples/hello2\-module.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
This program defines a configuration constant, \fBmessage\fP, indicating
the string to print to the console, set to \fB"Hello, world!"\fP by
default.  To override the default, you can use:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./hello2\-module \-\-message=\(aqHello, Chapel users!\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./hello2\-module \-smessage=\(aqHello, Chapel users!\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The default value of a configuration constant or variable can also be
overridden at compilation time with a \fB\-s\fP option. (The surrounding
quotes must be provided for a string literal.) For example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME/examples
chpl \-smessage=\(aq"Hello from the Chapel compiler"\(aq hello2\-module.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-s message="\(aqHello from the Chapel compiler\(aq" hello2\-module.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The compiler\-established default can still be overridden when
executing the program, as shown above.
.sp
Chapel programs can also accept C\-like command line arguments to their
\fBmain()\fP procedure in addition to the aforementioned configuration
variables. See readme\-main for more
information.
.SS Setting the Number of Locales
.sp
For multi\-locale Chapel executions, the number of locales on which to
execute a program is specified on the executable\(aqs command\-line.  This
can be set either using the \-nl flag, or by assigning to the built\-in
numLocales configuration constant using the normal mechanisms.  So, to
execute on four locales, one could use:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./a.out \-nl 4
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./a.out \-\-numLocales=4
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./a.out \-snumLocales=4
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For users running with \fBCHPL_COMM=none\fP (the default), only one
locale can be used.  See readme\-multilocale for more
information about executing on multiple locales.
.sp
Multi\-locale programs often use a launcher executable to do some initial
command\-line checking before spawning the real program, which is then
stored in a second binary named \fB<original_binary_name>_real\fP\&.  See
readme\-launcher for more information about the launcher executable.
.SS Controlling Degree of Data Parallelism
.sp
Data parallel operations over ranges, default domains, and default
arrays permit the number of tasks used to implement the data
parallelism to be specified using the following built\-in configuration
constants:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBdataParTasksPerLocale\fP
Number of Chapel tasks to use to execute forall loops (default:
number of physical CPUs on the node, which may be reduced by
\fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP\&.  When \fBCHPL_TASKS=qthreads\fP,
\fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP can also increase this, up to the
number of logical CPUs).
.TP
.B \fBdataParIgnoreRunningTasks\fP
If \fBtrue\fP, always use \fBdataParTasksPerLocale\fP tasks to execute
forall loops.  If \fBfalse\fP, reduce the number of tasks used by the
number of tasks already running (default: \fBfalse\fP).
.TP
.B \fBdataParMinGranularity\fP
The number of tasks used to execute forall loops should be reduced
such that the number of iterations per task is never less than the
specified value (default: \fB1\fP).
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Most Chapel standard distributions also use identically named
constructor arguments to control the degree of data parallelism within
each locale when iterating over its domains and arrays.  The default
values for these arguments are set to the corresponding global
configuration constants.
.SS Environment Variable Control over Chapel Behavior
.sp
Chapel uses environment variables to control the number of threads used
at execution time and the call stack size, among other things.  In many
cases third\-party packages used by Chapel define their own environment
variables to provide the same or similar control.  When this is the
case, the Chapel environment variable has precedence over the
third\-party package environment variable, which in turn has precedence
over the Chapel default.
.sp
As an example, with \fBCHPL_TASKS=qthreads\fP, Chapel and Qthreads both
have environment variables that can be used to set the task stack size.
In this case the Chapel \fBCHPL_RT_CALL_STACK_SIZE\fP environment variable
will override the Qthreads \fBQT_STACK_SIZE\fP environment variable if
both are set.  However, if only \fBQT_STACK_SIZE\fP is set it will
override the Chapel default call stack size.
.sp
The Chapel environment variables that control execution time behavior
are as follows:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBCHPL_RT_CALL_STACK_SIZE\fP
size of the call stack for a task
.TP
.B \fBCHPL_RT_MAX_HEAP_SIZE\fP
per\-locale size of the heap used for dynamic allocation in
multilocale programs
.TP
.B \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP
number of threads used to execute tasks
.UNINDENT
.UNINDENT
.UNINDENT
.sp
There is a bit more information on \fBCHPL_RT_CALL_STACK_SIZE\fP and
\fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP below, and more detailed discussion
of all of these in readme\-tasks and readme\-cray\&.
.SS Controlling the Call Stack Size
.sp
The main Chapel program requires space for its call stack, as does any
task created by it.  This stack space has a fixed size.  It is created
automatically when the program or task starts executing, and remains in
existence until it completes.  The default call stack size is 8 MiB on
Linux\-based systems, since this is a common value for the process stack
limit on such systems.  On Cygwin systems the default call stack size is
2 MiB.
.sp
The default call stack size may not be appropriate in all cases.  For
programs in which some tasks have large stack frames or deep call trees
it may be too small, leading to stack overflow.  For programs which use
tasks only for data parallelism it may be unnecessarily large.  Stacks
that are unnecessarily large are typically only a problem for programs
in which many tasks (thus their stacks) exist at once, when using a comm
layer that has to pre\-register memory.  For the particular case of using
the native runtime communication and tasking layers on Cray X* systems,
further discussion about this can be found in readme\-cray\&.
.sp
The following environment variable can be used to change the task call
stack size.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBCHPL_RT_CALL_STACK_SIZE\fP
Size of the call stack for a task.  A plain numeric value indicates
bytes.  A suffix can be appended to indicate larger units:
.INDENT 7.0
.INDENT 3.5
.nf
\fBk\fP, \fBK\fP: KiB (2**10 bytes)
\fBm\fP, \fBM\fP: MiB (2**20 bytes)
\fBg\fP, \fBG\fP: GiB (2**30 bytes)
.fi
.sp
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Controlling the Number of Threads
.sp
The following environment variable can be used to change the number of
system threads used by a program.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP
Controls the number of threads used on each locale when running the
program.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
See readme\-tasks for more information on the role of
this variable in creating threads and executing tasks for the various
tasking layers.
.SS Controlling the Amount of Non\-User Output
.sp
The compiler\-generated executable supports \fIverbose\fP and \fIquiet\fP modes
that control the amount of Chapel\-generated information printed by the
executable.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-v\fP,\fB  \-\-verbose
Print more information. For example, print the
launcher commands used to start the program (if any)
and print a message from each locale when the program
starts executing there.
.TP
.B \-q\fP,\fB  \-\-quiet
Print less information. For example, suppress run\-time
warnings that are printed by default.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Launcher Support
.sp
For multilocale execution (see readme\-multilocale),
Chapel programs are executed indirectly by a launcher.  This section
covers command line options that assist launchers in doing their job.
These options are not supported for general use.  We document them here
so that their presence in, say, the verbose output produced by \fB\-v\fP
can be understood.
.sp
At present there is only one launcher support option:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.BI \-E \ <envVar=val>
set the given environment variable \fIenvVar\fP to \fIval\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Multilocale Chapel Execution
.sp
To run Chapel on multiple locales, the following steps are required:
.INDENT 0.0
.IP 0. 5
The following information describes a fairly generic use of
multi\-locale Chapel, suitable for networked workstations and
generic parallel platforms.  For other platforms, refer to the
platform\-specific documentation for
additional tips.
.IP 1. 5
Set your \fBCHPL_COMM\fP environment variable to "gasnet".  For example:
.INDENT 5.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_COMM=gasnet
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This specifies that you wish to use the GASNet library for
inter\-locale communication.  GASNet is a one\-sided communication
and active message layer being developed by Lawrence Berkeley
National Lab and UC Berkeley.  For details, refer to:
.INDENT 5.0
.IP \(bu 2
\fB$CHPL_HOME/third\-party/gasnet/README\fP and
.IP \(bu 2
\fB$CHPL_HOME/third\-party/README\fP
.UNINDENT
.IP 2. 5
Advanced users can set \fBCHPL_COMM_SUBSTRATE\fP to indicate the GASNet
conduit that they wish to use.  Novice users can leave this unset
and Chapel will make a choice for them.  Current defaults are:
.INDENT 5.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
CHPL_TARGET_PLATFORM
T}	T{
CHPL_COMM_SUBSTRATE
T}
_
T{
cray\-cs
T}	T{
ibv
T}
_
T{
cray\-xc
T}	T{
aries
T}
_
T{
cray\-xe
T}	T{
gemini
T}
_
T{
cray\-xk
T}	T{
gemini
T}
_
T{
cray\-xt
T}	T{
mpi
T}
_
T{
pwr5
T}	T{
lapi
T}
_
T{
pwr6
T}	T{
ibv
T}
_
T{
other
T}	T{
udp
T}
_
.TE
.UNINDENT
.UNINDENT
.IP 3. 5
Advanced GASNet users can set \fBCHPL_GASNET_SEGMENT\fP to choose a
memory segment to use with GASNet.  Current defaults are:
.INDENT 5.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
CHPL_COMM_SUBSTRATE
T}	T{
CHPL_GASNET_SEGMENT
T}
_
T{
aries
T}	T{
fast
T}
_
T{
gemini
T}	T{
fast
T}
_
T{
ibv
T}	T{
large
T}
_
T{
portals
T}	T{
fast
T}
_
T{
other
T}	T{
everything
T}
_
.TE
.UNINDENT
.UNINDENT
.IP 4. 5
Re\-make the compiler and runtime from \fBCHPL_HOME\fP:
.INDENT 5.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME
gmake
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or:
.INDENT 5.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME
make
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the runtime libraries used by the Chapel compiler are
based on your choices of conduit, substrate, and debugging mode
(see \fI\%set\-comm\-conduit\fP, \fI\%set\-comm\-segment\fP, and \fI\%set\-comm\-debugging\fP),
so the runtime directory will need to be recompiled for each
variation in these settings that you use for a given choice of
target platform, compiler, and launcher.
.IP 5. 5
Set up GASNet environment variables for execution:
.INDENT 5.0
.IP a. 3
If you are using GASNet\(aqs udp conduit, set up variables telling GASNet
how to spawn program instances.  Most of our experience to date has been
with two options:
.INDENT 5.0
.IP i. 5
To run on a network of workstations to which you have
access via ssh, configure GASNet as follows:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export GASNET_SPAWNFN=S
export GASNET_SSH_SERVERS="host1 host2 host3 ..."
export GASNET_SSH_CMD=ssh
export GASNET_SSH_OPTIONS=\-x
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where host1, host2, host3, ... are the names of the
workstations that will serve as your Chapel locales.  In
order to run your Chapel program on k locales, you must
have k entries in the \fBGASNET_SSH_SERVERS\fP variable.  To avoid
typing in passwords for each node, you will probably want
to use normal ssh\-agent/ssh\-add capabilities to support
password\-less ssh\-ing.
.sp
Also note that if you are using SSH to launch jobs, you might get a
login banner printed out along with your program\(aqs output. We have
found the following setting useful to disable such printing:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export GASNET_SSH_OPTIONS="\-o LogLevel=Error"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is also possible to configure GASNet/UDP to launch jobs with
SLURM using the following command:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export GASNET_SPAWNFN=C
export GASNET_CSPAWN_CMD="srun \-N%N %C"
.ft P
.fi
.UNINDENT
.UNINDENT
.IP ii. 5
To simulate multiple Chapel locales with one workstation,
you can request that GASNet spawn its child functions on
your local machine using:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export GASNET_SPAWNFN=L
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have problems with the local spawn, you may need to
set \fBGASNET_MASTERIP\fP to your IP address.
.IP iii. 5
For other options, please refer to:
.sp
\fB$CHPL_HOME/third\-party/gasnet/gasnet\-src/udp\-conduit/README\fP
.UNINDENT
.IP b. 3
If you are using GASNet\(aqs ibv conduit, configure the environment to
launch program instances.  We have experience with these configurations:
.INDENT 5.0
.IP i. 5
For clusters using SLURM, enable slurm\-gasnetrun_ibv:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER=slurm\-gasnetrun_ibv
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See readme\-launcher for other options available, such
as setting the time limit or selecting the type of node.
.IP ii. 5
To launch InfiniBand jobs with SSH, use the following
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER=gasnetrun_ibv
export GASNET_SSH_SERVERS="host1 host2 host3 ..."
export GASNET_IBV_SPAWNER=ssh
.ft P
.fi
.UNINDENT
.UNINDENT
.IP iii. 5
We\(aqve observed job launch hangs in some systems with InfiniBand
that were resolved by limiting the memory available for
communication, for example with:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export GASNET_PHYSMEM_MAX=1G
.ft P
.fi
.UNINDENT
.UNINDENT
.IP iv. 5
For more information on these and other available GASNet options
other options, including configuring to launch through MPI,
please refer to:
.sp
\fB$CHPL_HOME/third\-party/gasnet/gasnet\-src/ibv\-conduit/README\fP
.UNINDENT
.IP c. 3
If you are trying to debug job launch, try adding \fB\-v\fP to your
program\(aqs command line and set:
.INDENT 5.0
.INDENT 3.5
.sp
.nf
.ft C
export GASNET_VERBOSEENV=1
.ft P
.fi
.UNINDENT
.UNINDENT
.IP d. 3
We\(aqve had best results with console I/O using:
.INDENT 5.0
.INDENT 3.5
.sp
.nf
.ft C
export GASNET_ROUTE_OUTPUT=0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
but your mileage may vary.
.UNINDENT
.IP 6. 5
Compile your Chapel program as usual:
.INDENT 5.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-o hello6\-taskpar\-dist $CHPL_HOME/examples/hello6\-taskpar\-dist.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 7. 5
When you compile a Chapel program for multiple locales, you should
typically see two binaries (e.g., hello6\-taskpar\-dist and
hello6\-taskpar\-dist_real).  The first binary contains code to
launch the Chapel program onto the compute nodes using a GASNet run
command.  The second contains the program code itself.  You can use
the \fB\-v\fP flag to see the commands used to launch your program.  See
readme\-launcher for further details.
.IP 8. 5
Multi\-locale executions require the number of locales to be
specified on the command line.  Other than this, execute your
Chapel program as usual.  For example:
.INDENT 5.0
.INDENT 3.5
.sp
.nf
.ft C
\&./hello6\-taskpar\-dist \-nl 2
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 9. 5
Advanced users may want to set \fBCHPL_COMM_DEBUG\fP in order to enable
GASNet\(aqs internal sanity checking. (It is off by default.)
You need to re\-make the compiler and runtime when changing
this setting (see \fI\%remake\-the\-compiler\fP).
.UNINDENT
.SS Chapel Launchers
.sp
When compiling Chapel programs for multiple locales, a launcher binary
is typically created that will execute the appropriate command(s) to
get your program started. For example, when compiling for multiple
locales, typically two binaries will be generated by the compiler
(e.g., a.out and a.out_real). The first binary contains code to get
your program up and running on multiple locales while the second
contains your actual program code.
.sp
The goals of the launcher binary are:
.INDENT 0.0
.IP 1. 3
to wrap details of job startup in a portable way so that new users
can quickly get Chapel programs up and running on an unfamiliar
platform.
.IP 2. 3
to perform command\-line parsing and error checking prior to
waiting in a queue or firing off a parallel job in order to save
time and resources related to simple errors/typos in the command
line.
.IP 3. 3
to preserve Chapel\(aqs global\-view programming model by permitting
the user to run their program using a single binary (corresponding
to the single logical task that executes main()) without getting
bogged down in questions of numbers of nodes, numbers of cores per
node, numbers of program instances to start up, etc.
.IP 4. 3
if necessary, to coordinate runtime functional activity, such as
I/O.
.UNINDENT
.sp
Executing a Chapel program using the verbose (\fB\-v\fP) flag will typically
print out the command(s) used to launch the program.
.sp
Executing using the help (\fB\-h\fP/\fB\-\-help\fP) flag will typically print out
any launcher\-specific options in addition to the normal help message for
the program itself.
.sp
Currently supported launchers include:
.TS
center;
|l|l|.
_
T{
Launcher Name
T}	T{
Description
T}
_
T{
amudprun
T}	T{
GASNet launcher for programs running over UDP
T}
_
T{
aprun
T}	T{
Cray application launcher using aprun
T}
_
T{
gasnetrun_ibv
T}	T{
GASNet launcher for programs running over Infiniband
T}
_
T{
gasnetrun_mpi
T}	T{
GASNet launcher for programs using the MPI conduit
T}
_
T{
lsf\-gasnetrun_ibv
T}	T{
GASNet launcher using LSF (bsub) over Infiniband
T}
_
T{
pbs\-aprun
T}	T{
Cray application launcher using PBS (qsub) + aprun
T}
_
T{
pbs\-gasnetrun_ibv
T}	T{
GASNet launcher using PBS (qsub) over Infiniband
T}
_
T{
slurm\-gasnetrun_ibv
T}	T{
GASNet launcher using SLURM over Infiniband
T}
_
T{
slurm\-srun
T}	T{
native SLURM launcher
T}
_
T{
none
T}	T{
do not use a launcher
T}
_
.TE
.sp
A specific launcher can be explicitly requested by setting the
\fBCHPL_LAUNCHER\fP environment variable. If left unset, a default is picked as
follows:
.INDENT 0.0
.IP \(bu 2
if \fBCHPL_PLATFORM\fP is cray\-xc, cray\-xe, cray\-xk, or cray\-xt:
.TS
center;
|l|l|.
_
T{
If
T}	T{
CHPL_LAUNCHER
T}
_
T{
both aprun and srun in user\(aqs path
T}	T{
none
T}
_
T{
aprun in user\(aqs path
T}	T{
aprun
T}
_
T{
srun in user\(aqs path
T}	T{
slurm\-srun
T}
_
T{
otherwise
T}	T{
none
T}
_
.TE
.IP \(bu 2
otherwise, if \fBCHPL_COMM\fP is gasnet:
.TS
center;
|l|l|.
_
T{
If
T}	T{
CHPL_LAUNCHER
T}
_
T{
CHPL_COMM_SUBSTRATE=ibv
T}	T{
gasnetrun_ibv
T}
_
T{
CHPL_COMM_SUBSTRATE=mpi
T}	T{
gasnetrun_mpi
T}
_
T{
CHPL_COMM_SUBSTRATE=mxm
T}	T{
gasnetrun_ibv
T}
_
T{
CHPL_COMM_SUBSTRATE=udp
T}	T{
amudprun
T}
_
T{
otherwise
T}	T{
none
T}
_
.TE
.IP \(bu 2
otherwise \fBCHPL_LAUNCHER\fP is set to none
.UNINDENT
.sp
If the launcher binary does not work for your system (due to an
installation\-specific configuration, e.g.), you can often use the \fB\-v\fP
flag to capture the commands that the launcher executes on your behalf
and customize them for your needs.
.SS Forwarding Environment Variables
.sp
Chapel launchers generally arrange for environment variables to be
forwarded to worker processes. However, this strategy is not always
reliable. The remote system may override some environment variables, and
some launchers might not correctly forward all environment variables.  In
particular, the amudprun launcher will not forward environment variables
containing backticks (\(ga).
.SS _real binary suffix for execution
.sp
In order to support profiling tools that produce new binaries for the
launcher to execute, the suffix of the real binary executed by the
launcher may be changed with the \fBCHPL_LAUNCHER_SUFFIX\fP environment
variable. If this variable is unset, the suffix defaults to "_real",
matching the compiler\(aqs output.
.SS Bypassing the launcher
.sp
If the Chapel launcher capability fails you completely, set
\fBCHPL_LAUNCHER\fP to none, recompile, and execute the a.out binary
according to the following rules using tools and queueing mechanisms
appropriate for your system:
.INDENT 0.0
.IP \(bu 2
on most systems, the number of locales should be equal to the number
of nodes on which you execute which should be equal to the number of
copies of a.out (or a.out_real using a launcher) that you are
running.
.IP \(bu 2
some queueing systems require you to specify the number of cores to
use per node. For best results, you will typically want to use all
of them. All intra\-node parallelism is typically implemented using
Chapel\(aqs threading layer (e.g., pthreads), so extra copies of the
binary are not required per core.
.UNINDENT
.SS SLURM notes
.sp
Prerequisites:
.INDENT 0.0
.INDENT 3.5
To use native SLURM, set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER=slurm\-srun
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will happen automatically if srun is found in your path, but
not when both srun and aprun are found in your path.
.sp
To use SLURM using GASNet over Infiniband, set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER=slurm\-gasnetrun_ibv
export CHPL_COMM=gasnet
export CHPL_COMM_SUBSTRATE=ibv
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To have GASNet use mpirun to launch your program, set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export GASNET_IBV_SPAWNER=mpi
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
At this point, rebuild your Chapel runtime (\(aqmake\(aq from \fB$CHPL_HOME\fP),
and compile your program.
.UNINDENT
.UNINDENT
.sp
Settings:
.INDENT 0.0
.INDENT 3.5
Before running, you will need to set the amount of time to request
from SLURM. For example, the following requests 15 minutes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER_WALLTIME=00:15:00
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If needed, you can request a specific node feature from SLURM by putting
it in the \fBCHPL_LAUNCHER_CONSTRAINT\fP environment variable. For example,
to use nodes with the \(aqcal\(aq feature (as defined in the slurm.conf
file), set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER_CONSTRAINT=cal
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If this environment variable is undefined, SLURM may use any node in
the computer.
.sp
If the environment variable \fBCHPL_LAUNCHER_USE_SBATCH\fP is defined then
sbatch is used to launch the job to the queue system, rather than
running it interactively as usual. In this mode, the output will be
written by default to a file called <executableName>.<jobID>.out. The
environment variable \fBCHPL_LAUNCHER_SLURM_OUTPUT_FILENAME\fP can be used
to specify a different filename for the output.
.sp
Other SLURM variables will have an impact; for example, the SLURM
partition can be set to \(aqdebug\(aq with the command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export SLURM_PARTITION=debug
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Additional launchers
.sp
In addition to the launchers listed above there are several others that
are not actively maintained but may still work.
.TS
center;
|l|l|.
_
T{
Launcher Name
T}	T{
Description
T}
_
T{
loadleveler
T}	T{
launch using IBM loadleveler (still needs refining)
T}
_
T{
marenostrum
T}	T{
launch using MareNostrum\(aqs mnsubmit script
T}
_
T{
mpirun
T}	T{
launch using mpirun (no mpi comm currently)
T}
_
.TE
.sp
These launchers are the default for the following configurations:
.TS
center;
|l|l|.
_
T{
If
T}	T{
CHPL_LAUNCHER
T}
_
T{
CHPL_PLATFORM=marenostrum
T}	T{
marenostrum
T}
_
.TE
.SS Chapel Tasks
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Chapel Tasks\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Overview\fP
.IP \(bu 2
\fI\%Task Implementation Layers\fP
.INDENT 2.0
.IP \(bu 2
\fI\%CHPL_TASKS == qthreads\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Stack overflow detection\fP
.IP \(bu 2
\fI\%Environment variables\fP
.IP \(bu 2
\fI\%Worker affinity and number\fP
.IP \(bu 2
\fI\%Overloading system nodes\fP
.IP \(bu 2
\fI\%Hwloc\fP
.IP \(bu 2
\fI\%Further information\fP
.UNINDENT
.IP \(bu 2
\fI\%CHPL_TASKS == fifo\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Stack overflow detection\fP
.UNINDENT
.IP \(bu 2
\fI\%CHPL_TASKS == massivethreads\fP
.UNINDENT
.IP \(bu 2
\fI\%Controlling the Number of Threads\fP
.INDENT 2.0
.IP \(bu 2
\fI\%CHPL_TASKS == fifo\fP
.IP \(bu 2
\fI\%CHPL_TASKS == qthreads\fP
.IP \(bu 2
\fI\%CHPL_TASKS == massivethreads\fP
.UNINDENT
.IP \(bu 2
\fI\%Task Call Stacks\fP
.INDENT 2.0
.IP \(bu 2
\fI\%CHPL_TASKS == fifo\fP
.IP \(bu 2
\fI\%CHPL_TASKS == qthreads\fP
.IP \(bu 2
\fI\%CHPL_TASKS == massivethreads\fP
.UNINDENT
.IP \(bu 2
\fI\%Task\-Related Quantification Methods on Locales\fP
.IP \(bu 2
\fI\%Future Tasking Directions\fP
.UNINDENT
.UNINDENT
.SS Overview
.sp
Chapel programs create new tasks via the begin, cobegin, and coforall
statements.  Tasks are computations that can conceptually execute
concurrently, though they may or may not do so in practice.
.sp
An implementation of Chapel must include at least one tasking layer.
A tasking layer will in turn implement \fIthreads\fP which are a mechanism
for executing work in parallel.
.sp
All tasking layers support configuration constants to control system
resources such as the number of threads that are available to execute
tasks and the amount of call stack space reserved for each task.  Generally
speaking, the Chapel programmer can make no assumptions about the
scheduling of threads or the mapping of tasks to threads other than
those semantics defined by the language specification.
.sp
This document describes the currently\-supported tasking options in more
detail.  The rest of this document includes:
.INDENT 0.0
.IP \(bu 2
an overview of the different tasking options
.IP \(bu 2
a detailed description of each tasking option
.IP \(bu 2
a discussion of the number of threads used by each tasking option
.IP \(bu 2
a discussion of call stack sizes and overflow handling
.IP \(bu 2
a list of tasking\-related methods on the locale type
.IP \(bu 2
a brief description of future directions for the tasking layer
.UNINDENT
.sp
If you have questions about tasks that are not covered in the following,
please send them to \fI\%chapel_info@cray.com\fP\&.
.SS Task Implementation Layers
.sp
This release contains four distinct tasking layers for Chapel tasks.
The user can select between these options by setting the \fBCHPL_TASKS\fP
environment variable to one of the following values:
.INDENT 0.0
.TP
.B qthreads
best performance; default for most targets
.TP
.B fifo
most portable, but heavyweight; default for NetBSD and Cygwin
.TP
.B massivethreads
based on U Tokyo\(aqs MassiveThreads library
.TP
.B muxed
available only on Cray Inc. systems; not documented here,
see readme\-cray instead
.UNINDENT
.sp
Each tasking layer is described in more detail below:
.SS CHPL_TASKS == qthreads
.sp
Chapel\(aqs default tasking layer implementation for most targets is based
on the Qthreads user\-level threading package from Sandia National Labs.
This provides a lightweight implementation of Chapel tasking and will
also ultimately provide an optimized implementation of sync variables.
To use qthreads tasking, please take the following steps:
.INDENT 0.0
.IP 1. 3
Ensure that the environment variable \fBCHPL_HOME\fP points to the
top\-level Chapel directory.
.IP 2. 3
Set up your environment to use Qthreads:
.sp
ensure \fBCHPL_TASKS\fP is not set (if qthreads is the default)
.sp
\-\- or \-\-
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_TASKS=qthreads
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Follow the instructions in readme\-chplenv to set up,
compile and run your Chapel programs.
.UNINDENT
.sp
Please report any apparent bugs in Qthreads tasking to the Chapel team.
.SS Stack overflow detection
.sp
The qthreads tasking implementation can arrange to halt programs when
any task overflows its call stack (see \fI\%Task Call Stacks\fP).
It does this by placing a guard page, which cannot be referenced, at the
end of each task stack.  When a task tries to extend its stack onto a
guard page, it fails with a segfault.
.sp
Normally guard pages for stack overflow detection are configured and
enabled.  There is a performance cost for this, however.  We do not have
a quantitative estimate for this cost, but it is a fixed overhead (a
couple of system calls) added to the time needed to run every task, so
qualitatively speaking it will have a greater effect on programs which
create more or shorter\-lived tasks than on programs which create fewer
or longer\-lived ones.
.sp
As described in \fI\%Task Call Stacks\fP, the execution\-time default for
stack overflow checking can be set by using the \fB\-\-[no\-]stack\-checks\fP
compiler option.  But whatever the default is, at execution time stack
overflow detection can be turned off by setting the environment variable
\fBQT_GUARD_PAGES\fP to any of the values "0", "no", or "false", or on by
setting it to any of "1", "yes", or "true".  When it is off the execution
overhead is negligible (just a couple of scalar tests).  Developers
who wish to remove even this small cost can disable guard pages by
building qthreads with guard pages entirely configured out, as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME/third\-party/qthread
make CHPL_QTHREAD_NO_GUARD_PAGES=yes ... clean all
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As noted, running without guard pages can improve performance and thus
may be desirable for production work.  However, if this is done, test
runs at similar scale with guard pages turned on to check for stack
overflow should be done beforehand if possible, because undetected stack
overflows can cause subtle and intermittent errors in execution.
.SS Environment variables
.sp
Qthreads provides a number of environment variables that can be used to
configure its behavior at execution time.  An introduction to these can
be found in the ENVIRONMENT section of the qthread_init man page.  (Note
that although this man page documents variables named \fBQTHREAD_*\fP, each
variable is actually present in both \fBQT_*\fP and \fBQTHREAD_*\fP forms,
with the former superseding the latter.)  The qthreads man pages are
available by means of the man(1) \-m option, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
man \-M $CHPL_HOME/third\-party/qthread/qthread\-*/man qthread_init
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that in some cases there are Chapel environment variables that
override Qthreads counterparts. \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP overrides
\fBQT_HWPAR\fP, for example.  Whenever a Chapel variable overrides a Qthreads
variable, you should use the Chapel one.
.SS Worker affinity and number
.sp
Simplistically, there are two kinds of threads in Qthreads: shepherds
that manage work distribution, and workers that host qthreads (Chapel
tasks, for our purposes).  The execution\-time environment variable
\fBQT_WORKER_UNIT\fP controls how worker threads are distributed on hardware
processors.  The default is "core" to distribute workers across CPU
cores (physical processors).  An alternative is "pu", which distributes
workers across processing units.  These are instances of the processor
architecture, or hardware threads if the cores have those.  Note that
"pu" will be automatically selected if \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP
is set to anything larger than the number of cores, so it usually isn\(aqt
necessary to set \fBQT_WORKER_UNIT\fP\&.
.SS Overloading system nodes
.sp
By default the qthreads tasking implementation is set up to assume that
its process is not competing with anything else for system resources
(CPUs and memory) on its system node.  In this mode, qthreads optimizes
its internal behavior to favor performance over load balancing.  This
works out well for Chapel programs, because normally Chapel runs with
one process (locale) per system node.  However, with \fBCHPL_COMM=gasnet\fP
one can run multiple Chapel locales on a single system node, say for
doing multilocale functional correctness testing with limited system
resources.  (See readme\-multilocale for more details.)  When this is
done qthreads\(aq optimization for performance can actually greatly reduce
performance, due to resource starvation among the multiple Chapel
processes.  If you need qthreads to share system resources more
cooperatively with other processes, you can build it to optimize its
behavior to favor load balancing over performance.  To do this, build
qthreads with \fBCHPL_QTHREAD_ENABLE_OVERSUBSCRIPTION\fP turned on like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME/third\-party/qthread
make CHPL_QTHREAD_ENABLE_OVERSUBSCRIPTION=yes ... clean all
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Hwloc
.sp
When \fBCHPL_TASKS=qthreads\fP, the default for \fBCHPL_HWLOC\fP becomes "hwloc",
and the hwloc third\-party package will be built.  Qthreads depends on
this package to provide it with a description of the locale hardware, to
support locality and affinity operations.  This is especially important
when \fBCHPL_LOCALE_MODEL=numa\fP, and will become more so in the future.
.SS Further information
.sp
For more information on Qthreads, see $CHPL_HOME/third\-party/README.
.SS CHPL_TASKS == fifo
.sp
FIFO tasking over POSIX threads (or pthreads) works on all
platforms and is the default for Cygwin and NetBSD. It is
attractive in its portability, though on most platforms it will
tend to be heavier weight than Chapel strictly requires.  FIFO
tasking is also used when Chapel is configured in \(aqQuick Start\(aq
mode (see chapelhome\-quickstart).  To use FIFO tasking,
please take the following steps:
.INDENT 0.0
.IP 1. 3
Ensure that the environment variable \fBCHPL_HOME\fP points to the
top\-level Chapel directory.
.IP 2. 3
Set up your environment to use FIFO tasking:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_TASKS=fifo
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Follow the instructions in readme\-chplenv to set up,
compile and run your Chapel programs.
.UNINDENT
.sp
In the FIFO tasking implementation, Chapel tasks are mapped to threads
such that each task is executed by a single thread and is run to
completion before giving up that thread.  As a result, a program can
have no more tasks active (that is, created and started) at any given
time than it has threads on which to run those tasks.  It can create
more tasks than threads, but no more tasks will be run at any time
than there are threads.  Excess tasks are placed in a pool where they
will be picked up and started by threads as they complete their tasks.
.sp
The threading implementation uses POSIX threads (pthreads) to run Chapel
tasks.  Because pthreads are relatively expensive to create, it does not
destroy them when there are no tasks for them to execute.  Instead they
stay around and continue to check the task pool for tasks to execute.
Setting the number of pthreads is described in \fI\%Controlling the Number of Threads\fP\&.
.SS Stack overflow detection
.sp
The fifo tasking implementation can arrange to halt programs when any
task overflows its call stack (see \fI\%Task Call Stacks\fP).  It does
this by placing a guard page, which cannot be referenced, at the end of
each task stack.  When a task tries to extend its stack onto a guard
page, it fails with a segfault.
.sp
This feature is enabled in fifo tasking and cannot currently be turned
off.  There is a performance cost for it, which we expect to be small in
most cases.  We do not have a quantitative estimate for this cost, but
it is a fixed overhead (a couple of system calls) added to the time
needed to start each pthread.  Since the pthreads in fifo tasking are
long\-lived and can host many tasks over their lifespan, on a per\-task
basis we don\(aqt expect stack overflow detection to be expensive.
.SS CHPL_TASKS == massivethreads
.sp
The MassiveThreads team at the University of Tokyo has provided an
implementation of Chapel tasking via their MassiveThreads library
(\(aqmassivethreads\(aq) in order to create a lighter\-weight implementation
of Chapel tasks.  To try MassiveThreads tasking, please take the
following steps:
.INDENT 0.0
.IP 1. 3
Ensure that the environment variable \fBCHPL_HOME\fP points to the
top\-level Chapel directory.
.IP 2. 3
Set up your environment to use MassiveThreads:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_TASKS=massivethreads
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Follow the chapelhome\-quickstart
to set up, compile and run your Chapel programs.
.UNINDENT
.sp
For more information on MassiveThreads, please see its entry in:
$CHPL_HOME/third\-party/README.
.SS Controlling the Number of Threads
.sp
The number of threads per compute node used to implement a Chapel
program can be controlled by the \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP
environment variable.  This may be set to either an explicit number
or one of the following symbolic strings:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \(aqMAX_PHYSICAL\(aq
number of physical CPUs (cores) on the node
.TP
.B \(aqMAX_LOGICAL\(aq
number of logical CPUs (hyperthreads) on the node
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP is not set, the number of threads is
left up to the tasking layer.  See the case\-by\-case discussions below
for more details.
.sp
The Chapel program will generate an error if the requested number of
threads per locale is too large.  For example, when running multi\-locale
programs, the GASNet communication layer typically places an upper bound
of 127 or 255 on the number of threads per locale (There are ways to
work around this assumption on certain platforms \-\- please contact us at
\fI\%chapel_info@cray.com\fP or peruse the GASNet documentation if you need to
do so.)
.SS CHPL_TASKS == fifo
.INDENT 0.0
.INDENT 3.5
The value of \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP indicates the maximum
number of threads that the fifo tasking layer can create on each
locale to execute tasks.  These threads are created on a demand\-driven
basis, so a program with a small number of concurrent tasks may never
create the specified number.  If the value is zero, then the number of
threads will be limited by system resources and other constraints
(such as GASNet\(aqs configuration\-time limit).
.sp
The value of \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP can have a major impact on
performance for fifo tasking.  For programs with few inter\-task
dependences and high computational intensity, setting it roughly equal
to the number of physical CPUs on each locale can lead to near\-optimal
performance.  However, for programs with lots of fine\-grained
synchronization in which tasks frequently block on sync or single
variables, \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP can often exceed the number
of physical CPUs without an adverse effect on performance since
blocked threads will not consume the CPU\(aqs cycles.
.sp
Note that setting \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP too low can result in
program deadlock for fifo tasking.  For example, for programs written
with an assumption that some minimum number of tasks are executing
concurrently, setting \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP lower than this
can result in deadlock if there are not enough threads to implement
all of the required tasks.  The \fB\-b/\-\-blockreport\fP flag can help debug
programs like this that appear to be deadlocked.
.UNINDENT
.UNINDENT
.SS CHPL_TASKS == qthreads
.INDENT 0.0
.INDENT 3.5
In the Qthreads tasking layer, \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP
specifies the number of system threads used to execute tasks.  The
default is to use a number of threads equal to the number of physical
CPUs on the locale.
.UNINDENT
.UNINDENT
.SS CHPL_TASKS == massivethreads
.INDENT 0.0
.INDENT 3.5
In the MassiveThreads tasking layer, \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP
specifies the number of system threads used to execute tasks.  If the
value is 0, the massivethreads tasking layer will create a number of
threads equal to the number of logical CPUs on the locale.
.UNINDENT
.UNINDENT
.SS Task Call Stacks
.sp
Each task including the main Chapel program has an associated call
stack.  As documented in readme\-executing, the \fBCHPL_RT_CALL_STACK_SIZE\fP
environment variable can be used to specify how big these call stacks
will be during execution.  See there for a full description of this
environment variable and the values it can take.
.sp
When a task\(aqs call chain becomes so deep that it needs more space than
the size of its call stack, stack overflow occurs.  Whether or not a
program checks for stack overflow checking at execution time can be
specified when it is compiled, via the \fB\-\-[no\-]stack\-checks\fP compilation
option.  The compile\-time default is \fB\-\-stack\-checks\fP; \fB\-\-no\-stack\-checks\fP
can be given directly, and is also implied by \fB\-\-no\-checks\fP, which in turn
is implied by \fB\-\-fast\fP\&.  By default stack overflow checks are enabled.
.sp
Chapel does not yet have a consistent, implementation\-independent way to
deal with call stack overflow.  Each tasking layer implementation
handles stacks and stack overflow in its own way, as described below.
.SS CHPL_TASKS == fifo
.INDENT 0.0
.INDENT 3.5
In fifo tasking, Chapel tasks use their host pthreads\(aq stacks when
executing.  If stack checks are enabled, these stacks are created with
an additional memory page called a "guard page" beyond their end, that
is marked so that it cannot be referenced.  When stack overflow occurs
the task\(aqs attempt to reference the guard page will cause the OS to
react as it usually does when bad memory references are done.  On
Linux, for example, it will kill the program with this message:
.INDENT 0.0
.INDENT 3.5
Segmentation fault
.UNINDENT
.UNINDENT
.sp
Unfortunately, many other things that cause improper memory references
result in this same kind of program termination, so as a diagnostic it
is ambiguous.  However, it does at least prevent the program from
continuing on in an erroneous state.
.UNINDENT
.UNINDENT
.SS CHPL_TASKS == qthreads
.INDENT 0.0
.INDENT 3.5
Like fifo tasks (see above), qthreads tasking can place guard pages
beyond the ends of task stacks.  Stack overflow then results in the
system\(aqs usual response to referencing memory that cannot be reached.
With qthreads tasking, the compiler \fB\-\-stack\-checks\fP setting specifies
the default setting for execution\-time stack overflow checking.  Final
control over stack overflow checks is provided by the \fBQT_GUARD_PAGE\fP
environment variable.  See the qthreads subsection of \fI\%Task
Implementation Layers\fP for more information.
.UNINDENT
.UNINDENT
.SS CHPL_TASKS == massivethreads
.INDENT 0.0
.INDENT 3.5
No stack overflow detection is available.  If the \fB\-\-stack\-checks\fP
option is given to the compiler and \fBCHPL_TASKS==massivethreads\fP,
the compiler emits a warning that stack checks cannot be done.
.UNINDENT
.UNINDENT
.SS Task\-Related Quantification Methods on Locales
.sp
Several methods on the locale type are available to query the state of
the program with respect to its tasks.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B queuedTasks()
returns the number of tasks that are ready to run, but
have not yet begun executing.
.TP
.B runningTasks()
returns the number of tasks that have begun executing,
but have not yet finished.  Note that this number can exceed the
number of non\-idle threads because there are cases in which a thread
is working on more than one task.  As one example, in fifo tasking,
when a parent task creates child tasks to execute the iterations of
a coforall construct, the thread the parent is running on may
temporarily suspend executing the parent task in order to help with
the child tasks, until the construct completes.  When this occurs
the count of running tasks can include both the parent task and a
child, although strictly speaking only the child is executing
instructions.
.sp
As another example, any tasking implementation in which threads can
switch from running one task to running another, such as qthreads,
can have more tasks running than threads on which to run them.
.TP
.B blockedTasks()
returns the number of tasks that are blocked because
they are waiting on a sync or single variable.  In order to avoid
unnecessary overheads, in the implementations this method will not
generate meaningful information unless the program was run with the
\fB\-b/\-\-blockreport\fP flag.
.TP
.B totalThreads()
returns the number of threads that have been created
since the program started executing, regardless of whether they
are busy or idle.
.TP
.B idleThreads()
returns the number of threads are idle, i.e., not assigned to any task.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
In order to use these methods, you have to specify the locale you wish
to query, as in here.runningTasks(), where \(aqhere\(aq is the current
locale.
.sp
(Note that these methods are available for all tasking options, but
currently only runningTasks() returns meaningful values for all options.
The others only return meaningful values for \fBCHPL_TASKS=fifo\fP\&.)
.SS Future Tasking Directions
.sp
As Chapel\(aqs task parallel implementation matures, we expect to have
multiple task\->thread scheduling policies, from literally creating and
destroying new threads with each task (for programmers who want full
control over a thread\(aqs lifetime) to automated work stealing and load
balancing at the other end of the spectrum (for programmers who would
prefer not to manage threads or whose programs cannot trivially be
load balanced manually).  Our hope is to leverage existing open source
threading and task management software and to collaborate with others
in these areas, so please contact us at \fI\%chapel_info@cray.com\fP if you\(aqd
like to work with us in this area.
.SS Debugging Chapel Programs
.sp
This document discusses support for debugging your Chapel program and a set of
experimental flags and configuration constants to enable task monitoring and
memory tracking.
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Debugging Chapel Programs\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Running in gdb\fP
.IP \(bu 2
\fI\%Flags for Tracking Tasks\fP
.IP \(bu 2
\fI\%Configuration Constants for Tracking Memory\fP
.UNINDENT
.UNINDENT
.SS Running in gdb
.sp
The compiler\-generated executable has a \fB\-\-gdb\fP flag that can be used
to launch the program within a \fBgdb\fP session.  For best results, make
sure that your program has been compiled using the chpl compiler\(aqs
\fB\-g\fP flag.  With \fBCHPL_COMM=gasnet\fP when using the \fBamudprun\fP
launcher, you can launch \fBgdb\fP by setting the environment variable
\fBCHPL_COMM_USE_GDB\fP when running the program.  This will open up a
separate xterm for each locale, running the designated debugger.  On the
Mac OS X (darwin) platform, you can launch \fBlldb\fP instead, by setting
the \fBCHPL_COMM_USE_LLDB\fP environment variable.
.sp
The utility of this feature depends greatly on your familiarity with
the Chapel generated code.  However, if your program is crashing or
running into a runtime error, you can often determine where that is
taking place by looking at a stack trace within \fBgdb\fP\&.
.sp
When debugging Chapel, it is useful to know that in generating its code,
the Chapel compiler renames user identifiers.  By default, the Chapel
compiler munges all user identifiers, such that a variable named \fBx\fP
would be code generated as \fBx_chpl\fP\&.  This munging can be controlled
using the \fB\-\-[no\-]munge\-user\-idents\fP flag (see the \fBchpl\fP man page
for more information).  In some cases, additional munging may be
required or applied that cannot be turned off.
.sp
The net effect of this is that Chapel variables can often be inspected
using \fBp\fP \fIname\fP\fB_chpl\fP (or \fBp\fP \fIname\fP\fB_chpl<TAB>\fP in cases
where the compiler has further renamed the variable).  If the
\fB\-\-no\-munge\-user\-idents\fP flag is used, \fBp\fP \fIname\fP or
\fBp\fP \fIname\fP\fB<TAB>\fP should work in most cases.
.sp
Over time, we plan to improve our ability to debug the generated C
code for a Chapel program.  If you find yourself debugging the
generated code a lot and need help or have requests for better
support, please let us know so that we can prioritize accordingly.
.SS Flags for Tracking Tasks
.sp
For certain tasking layers, Chapel supports a few experimental
capabilities for tracking the status of tasks, primarily designed for
use in a single\-locale execution.  To enable this capability, your
program must be compiled with the \fB\-\-task\-tracking\fP flag.  These flags
add a fair amount of runtime overhead to task\-parallel programs. The
flags are as follows:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-b\fP,\fB  \-\-blockreport
When \fB<CTRL\-C>\fP is entered during a program
executing under this flag, it will display a list
of where tasks are blocked on a synchronization
variable.  Running with this flag will also cause
the executable to attempt to automatically detect
deadlock for single\-locale executions.  This is
only supported with \fBCHPL_TASKS=qthreads\fP or
\fBCHPL_TASKS=fifo\fP\&.
.TP
.B \-t\fP,\fB  \-\-taskreport
When \fB<CTRL\-C>\fP is entered during a program
executing under this flag, a list of pending and
executing tasks will be printed to the console,
giving an indication of which tasks are at which
source locations.  This is only supported with
\fBCHPL_TASKS=fifo\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Configuration Constants for Tracking Memory
.sp
Chapel supports a number of configuration constants related to dynamic
memory allocation for the compiler\-generated executable, currently
designed for use primarily by the development team to track memory
usage in tests.  Please note that our generated code currently
contains memory leaks, so you should not be surprised if your program
requires more memory than it seems it should.
.sp
For full information on these configuration constants consult
\fBMemory\fP\&.
.sp
A brief synopsis of these configuration constants is as follows:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-\-memTrack
turn on memory tracking and enable reporting
.TP
.B \-\-memStats
call \fBprintMemAllocStats()\fP on normal termination
.TP
.B \-\-memLeaksByType
call \fBprintMemAllocsByType()\fP on normal termination
.TP
.B \-\-memLeaks
call \fBprintMemAllocs()\fP on normal termination
.TP
.BI \-\-memMax\fB= int
set maximum level of allocatable memory
.TP
.BI \-\-memThreshold\fB= int
set minimum threshold for memory tracking
.TP
.BI \-\-memLog\fB= string
file to contain all memory reporting
.TP
.BI \-\-memLeaksLog\fB= string
if set, append final stats and leaks\-by\-type here
.UNINDENT
.UNINDENT
.UNINDENT
.SS Reporting Chapel Bugs
.sp
If you encounter a bug, internal error, or unclear error message when
using Chapel, please do not hesitate to send a bug report to the
Chapel team.  Do so by sending mail to one of the following mailing
lists:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%chapel\-bugs@lists.sourceforge.net\fP : for bugs that are suitable for \fI\%public archive\fP
.IP \(bu 2
\fI\%chapel_bugs@cray.com\fP              : for bugs that the Chapel team at Cray Inc. should keep private
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Please include the following information in your email:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
the version number of your Chapel compiler (\fBchpl \-\-version\fP)
.IP 2. 3
the output of the \fB$CHPL_HOME/util/printchplenv\fP script
.IP 3. 3
the back\-end C compiler you are using and its version (e.g., \fBgcc \-\-version\fP)
.IP 4. 3
the output of \fBmodule list\fP (if using a Cray system)
.IP 5. 3
one of the following:
.INDENT 3.0
.IP a. 3
preferably, a reduced program demonstrating the issue
.IP b. 3
alternatively, the original program demonstrating the issue
.IP c. 3
as a last resort, a description of how to recreate the issue
.UNINDENT
.IP 6. 3
any helper modules or input files required to reproduce the issue
.IP 7. 3
a description of the behavior you are seeing
.UNINDENT
.UNINDENT
.UNINDENT
.sp
A list of known bugs and unimplemented features can be found in
\fB$CHPL_HOME/STATUS\fP\&.  Even if you run into a known issue, we
encourage you to send us a bug report, particularly if it is impeding
your progress.  Depending on the issue, we may be able to suggest a
workaround or to prioritize the development of a fix.
.SS Filing Futures
.sp
If you are a Chapel contributor and familiar with the \fI\%Chapel Testing
System\fP, you can file bugs by submitting \fI\%Future tests\fP\&.
.SS JIRA Issues
.sp
The Chapel team is working to bring our \fI\%JIRA issues site\fP up to
date. Bugs can be viewed without creating an account.
.SH PLATFORM-SPECIFIC NOTES
.sp
Contents:
.SS Using Chapel on Cray Systems
.sp
The following information is assembled to help Chapel users get up and running
on Cray® systems including the Cray XC™, XE™, XK™, and CS™ series systems.
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Using Chapel on Cray Systems\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Getting Started with Chapel on Cray X\-Series Systems\fP
.IP \(bu 2
\fI\%Getting Started with Chapel on Cray CS Systems\fP
.IP \(bu 2
\fI\%Building Chapel for a Cray System from Source\fP
.IP \(bu 2
\fI\%Using Chapel on a Cray System\fP
.IP \(bu 2
\fI\%Cray File Systems and Chapel execution\fP
.IP \(bu 2
\fI\%Special Notes for Cray XC, XE, and XK Series Systems\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Controlling the Heap Size\fP
.IP \(bu 2
\fI\%Native Runtime Layers\fP
.IP \(bu 2
\fI\%Using the ugni Communications Layer\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Communication Layer Concurrency\fP
.IP \(bu 2
\fI\%Communication Layer Concurrency and Slurm\fP
.UNINDENT
.IP \(bu 2
\fI\%Using the muxed Tasking Layer\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Controlling the Call Stack Size\fP
.IP \(bu 2
\fI\%Stack Overflow Checking\fP
.IP \(bu 2
\fI\%Number of Threads per Locale\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
\fI\%Network Atomics\fP
.IP \(bu 2
\fI\%Known Constraints and Bugs\fP
.IP \(bu 2
\fI\%NCCS user notes\fP
.UNINDENT
.UNINDENT
.SS Getting Started with Chapel on Cray X\-Series Systems
.sp
Chapel is available as a module for Cray X\-series systems.  When it is
installed on your system, you do not need to build Chapel from the
source release (though you can). To use Chapel with the default settings and
confirm it is correctly installed, do the following:
.INDENT 0.0
.IP 1. 3
Load the Chapel module:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
module load chapel
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Compile an example program using:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-o hello6\-taskpar\-dist $CHPL_HOME/examples/hello6\-taskpar\-dist.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 3. 3
Execute the resulting executable (on four locales):
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
\&./hello6\-taskpar\-dist \-nl 4
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
This may be all that is necessary to use Chapel on a Cray X\-Series system.
If the installation setup by your system administrator deviates from
the default settings, or you are interested in other configuration
options, see \fI\%Using Chapel on a Cray System\fP below.  If instead you wish to
build Chapel from source, continue on to
\fI\%Building Chapel for a Cray System from Source\fP just below.
.sp
For information on obtaining and installing the Chapel module please
contact your system administrator.
.SS Getting Started with Chapel on Cray CS Systems
.sp
On Cray CS systems, Chapel is not currently available as a module due
to the wide diversity of software packages that Cray CS customers may
choose to install on their system.  For this reason, Chapel must be
built from source on Cray CS systems using the
\fI\%Building Chapel for a Cray System from Source\fP instructions just below.
.SS Building Chapel for a Cray System from Source
.INDENT 0.0
.IP 1. 3
If using a XC, XE, or XK system, continue to step 2. If using a
CS series system, set \fBCHPL_HOST_PLATFORM\fP to \fBcray\-cs\fP\&.
.sp
For example:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_HOST_PLATFORM=cray\-cs
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
These are the supported systems and strings.  Note that these values
are used by default when building on the given systems.  They can
also be set manually.  Also note that the \fBcray\-xe\fP configuration
covers Cray XK systems as well as Cray XE systems.
.INDENT 3.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
System
T}	T{
CHPL_HOST_PLATFORM
T}
_
T{
CS series
T}	T{
cray\-cs
T}
_
T{
XC series
T}	T{
cray\-xc
T}
_
T{
XE series
T}	T{
cray\-xe
T}
_
T{
XK series
T}	T{
cray\-xe
T}
_
.TE
.UNINDENT
.UNINDENT
.IP 2. 3
Optionally, set the \fBCHPL_LAUNCHER\fP environment variable to indicate
how Chapel should launch jobs on your system:
.INDENT 3.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
On a Cray CS system, to...
T}	T{
set CHPL_LAUNCHER to...
T}
_
T{
\&...run jobs interactively on your system
T}	T{
gasnetrun_ibv
T}
_
T{
\&...queue jobs using PBSPro (qsub)
T}	T{
pbs\-gasnetrun_ibv
T}
_
T{
\&...queue jobs using SLURM (sbatch)
T}	T{
slurm\-gasnetrun_ibv
T}
_
T{
\&...queue jobs using LSF (bsub)
T}	T{
lsf\-gasnetrun_ibv
T}
_
.TE
.TS
center;
|l|l|.
_
T{
On a Cray X\-series system, to...
T}	T{
set CHPL_LAUNCHER to...
T}
_
T{
\&...run jobs interactively on your system
T}	T{
aprun
T}
_
T{
\&...queue jobs using PBS (qsub)
T}	T{
pbs\-aprun
T}
_
T{
\&...queue jobs using SLURM (sbatch)
T}	T{
slurm\-srun
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
You can also set CHPL_LAUNCHER to \fBnone\fP if you prefer to manually
manage all queuing and job launch commands yourself.
.sp
On Cray CS systems, \fBCHPL_LAUNCHER\fP defaults to \fBgasnetrun_ibv\fP\&.
.sp
On Cray X\-Series systems, \fBCHPL_LAUNCHER\fP defaults to \fBaprun\fP if
it is in your path; \fBnone\fP otherwise.
.sp
For more information on Chapel\(aqs launcher capabilities and options,
refer to readme\-launcher\&.
.IP 3. 3
Select the target compiler that Chapel should use when compiling
code for the compute node:
.sp
On a Cray CS series system, set the \fBCHPL_TARGET_COMPILER\fP environment
variable to indicate which compiler to use (and make sure that the compiler
is in your path).
.INDENT 3.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
To request...
T}	T{
set CHPL_TARGET_COMPILER to...
T}
_
T{
\&...the GNU compiler (gcc)
T}	T{
gnu    (default)
T}
_
T{
\&...the Intel compiler (icc)
T}	T{
intel
T}
_
T{
\&...the PGI compiler (pgcc)
T}	T{
pgi
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
On a Cray X\-series system, ensure that you have one of the following
Programming Environment modules loaded to specify your target compiler:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
PrgEnv\-cray
PrgEnv\-gnu
PrgEnv\-intel
PrgEnv\-pgi
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For PrgEnv\-cray we recommend using CCE 8.4 or newer for best performance.
This allows us to build our recommended third\-party packages (i.e. allows
us to default to CHPL_TASKS=qthreads instead of CHPL_TASKS=fifo)
.IP 4. 3
By default, \fBg++\fP will be used to compile code that runs on the login
node, such as the Chapel compiler and launcher code.  Optionally, you can
override this default by setting \fBCHPL_HOST_COMPILER\fP to one of the
following values:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBgnu\fP
the GNU compiler suite \-\- \fBgcc\fP and \fBg++\fP
.TP
.B \fBintel\fP
the Intel compiler suite \-\- \fBicc\fP and \fBicpc\fP
.TP
.B \fBpgi\fP
the PGI compiler suite \-\- \fBpgcc\fP and \fBpgc++\fP
.UNINDENT
.UNINDENT
.UNINDENT
.IP 5. 3
Optionally, set one or more of the following environment variables to
configure the Chapel build.  These are described in greater detail in
readme\-chplenv\&.
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBCHPL_TASKS\fP
tasking implementation, default \fBqthreads\fP
.TP
.B \fBCHPL_COMM\fP
communication implementation, default \fBgasnet\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Other configuration environment variables such as \fBCHPL_MEM\fP can also
be set, but this is more typical when doing internal development.
For production work the configuration scripts should always select an
appropriate default for these.
.sp
Note that the Cray\-specific settings of \fBmuxed\fP tasking and \fBugni\fP
communications cannot be selected when building Chapel from source,
because the corresponding runtime layers are not distributed in
source form.  These settings can only be selected when using the
pre\-built Chapel module.
.IP 6. 3
Make sure you\(aqre in the top\-level chapel/ directory and make/re\-make the
compiler and runtime:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
gmake
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that a single Chapel installation can support multiple
configurations simultaneously and that you can switch between them
simply by changing any of the above settings.  However, each
configuration must be built separately.  Thus, you can change any of
the settings in the steps before this, and then re\-run this step in
order to create additional installations.  Thereafter, you can switch
between any of these configurations without rebuilding.
.UNINDENT
.SS Using Chapel on a Cray System
.INDENT 0.0
.IP 1. 3
If you are working from a Chapel module:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.IP a. 3
Load the module using \fBmodule load chapel\fP
.IP b. 3
Optionally select a launcher, as in step 2 above
.IP c. 3
Select a target compiler, as in step 3 above
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If you are working from a source installation:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.IP a. 3
Set your host platform as in step 1 above
.IP b. 3
Optionally select a launcher, as in step 2 above
.IP c. 3
Select a target compiler, as in step 3 above
.IP d. 3
Set \fBCHPL_HOME\fP and your paths by invoking the appropriate
\fButil/setchplenv\fP script for your shell.  For example:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source util/setchplenv.bash
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.IP 2. 3
Optionally, set one or more of the following environment variables to
select a Chapel configuration.  These are described in greater detail
in readme\-chplenv\&.
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \fBCHPL_TASKS\fP
tasking implementation, default \fBqthreads\fP
.TP
.B \fBCHPL_COMM\fP
communication implementation, default \fBugni\fP on Cray
XC/XE with pre\-built module, else \fBgasnet\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Other configuration environment variables such as \fBCHPL_MEM\fP can also
be set, but this is more typical when doing internal development.
For production work the configuration scripts should always select an
appropriate default for these.
.sp
The configuration selected must be one that is present in the Chapel
installation being used, whether that is a source distribution or the
pre\-built module.  If it is not, the Chapel compiler will produce an
error message saying so when you try to compile anything.  If you get
this error, you will need to build the desired configuration (if you
are working from source) or modify your configuration so that it is
one of those supplied (if you are working with the pre\-built module).
.IP 3. 3
Compile your Chapel program.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-o hello6\-taskpar\-dist $CHPL_HOME/examples/hello6\-taskpar\-dist.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See readme\-compiling or  \fBman chpl\fP for further details.
.IP 4. 3
If \fBCHPL_LAUNCHER\fP is set to anything other than \fBnone\fP, when you
compile a Chapel program for your Cray system, you will see two
binaries (e.g., \fBhello6\-taskpar\-dist\fP and \fBhello6\-taskpar\-dist_real\fP).
The first binary contains code to launch the Chapel program onto
the compute nodes, as specified by your \fBCHPL_LAUNCHER\fP setting.  The
second contains the program code itself; it is not intended to be
executed directly from the shell prompt.
.sp
You can use the \fB\-v\fP flag to see the commands used by the launcher
binary to start your program.
.sp
If \fBCHPL_LAUNCHER\fP is \fBpbs\-aprun\fP or \fBpbs\-gasnetrun_ibv\fP:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.IP a. 3
You can optionally specify a queue name using the environment
variable \fBCHPL_LAUNCHER_QUEUE\fP\&.  For example:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER_QUEUE=batch
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If this variable is left unset, no queue name will be
specified.  Alternatively, you can set the queue name on your
Chapel program command line using the \fB\-\-queue\fP flag.
.IP b. 3
You can also optionally set a wall clock time limit for the
job using \fBCHPL_LAUNCHER_WALLTIME\fP\&.  For example to specify a
10\-minute time limit, use:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER_WALLTIME=00:10:00
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Alternatively, you can set the wall clock time limit on your
Chapel program command line using the \fB\-\-walltime\fP flag.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If \fBCHPL_LAUNCHER\fP is \fBslurm\-gasnetrun_ibv\fP:
.INDENT 3.0
.INDENT 3.5
You must set the amount of time to request from SLURM.
For example, the following requests 15 minutes:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER_WALLTIME=00:15:00
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For further information about launchers, please refer to
readme\-launcher\&.
.IP 5. 3
Execute your Chapel program.  Multi\-locale executions require the
number of locales (compute nodes) to be specified on the command
line.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
\&./hello6\-taskpar\-dist \-nl 2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Requests the program to be executed using two locales.
.IP 6. 3
If your Cray system has compute nodes with varying numbers of
cores, you can request nodes with at least a certain number of
cores using the variable \fBCHPL_LAUNCHER_CORES_PER_LOCALE\fP\&.  For
example, on a Cray system in which some compute nodes have 24 or
more cores per compute node, you could request nodes with at least
24 cores using:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER_CORES_PER_LOCALE=24
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This variable may be needed when you are using the aprun launcher and
running Chapel programs within batch jobs you are managing yourself.
The aprun launcher currently creates aprun commands that request the
maximum number of cores per locale found on any locale in the system,
irrespective of the fact that the batch job may have a lower limit
than that on the number of cores per locale.  If the batch job limit
is less than the maximum number of cores per locale, you will get the
following error message when you try to run a Chapel program:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
apsched: claim exceeds reservation\(aqs CPUs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can work around this by setting \fBCHPL_LAUNCHER_CORES_PER_LOCALE\fP to
the same or lesser value as the number of cores per locale specified
for the batch job (for example, the mppdepth resource for the PBS
qsub command).  In the future we hope to achieve better integration
between Chapel launchers and workload managers.
.IP 7. 3
If your Cray system has compute nodes with varying numbers of CPUs
per compute unit, you can request nodes with a certain number of
CPUs per compute unit using the variable \fBCHPL_LAUNCHER_CPUS_PER_CU\fP\&.
For example, on a Cray XC series system with some nodes having at
least 2 CPUs per compute unit, to request running on those nodes
you would use:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER_CPUS_PER_CU=2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Currently, the only legal values for \fBCHPL_LAUNCHER_CPUS_PER_CU\fP are
0 (the default), 1, and 2.
.UNINDENT
.TS
center;
|l|l|.
_
T{
For more information on...
T}	T{
see...
T}
_
T{
\&...CHPL_* environment settings
T}	T{
readme\-chplenv
T}
_
T{
\&...Compiling Chapel programs
T}	T{
readme\-compiling
T}
_
T{
\&...Launcher options
T}	T{
readme\-launcher
T}
_
T{
\&...Executing Chapel programs
T}	T{
readme\-executing
T}
_
T{
\&...Running multi\-locale Chapel programs
T}	T{
readme\-multilocale
T}
_
.TE
.SS Cray File Systems and Chapel execution
.sp
For best results, it is recommended that you execute your Chapel
program by placing the binaries on a file system shared between the
login node and compute nodes (typically Lustre), as this will provide
the greatest degree of transparency when executing your program.  In
some cases, running a Chapel program from a non\-shared file system
will make it impossible to launch onto the compute nodes.  In other
cases, the launch will succeed, but any files read or written by the
Chapel program will be opened relative to the compute node\(aqs file
system rather than the login node\(aqs.
.SS Special Notes for Cray XC, XE, and XK Series Systems
.SS Controlling the Heap Size
.sp
When running on Cray XC/XE/XK systems using either of the following
configurations, the comm layer needs to know the maximum size the
program heap will grow to during execution:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
CHPL_COMM=gasnet
  CHPL_COMM_SUBSTRATE=gemini or aries
  CHPL_GASNET_SEGMENT=fast or large
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
CHPL_COMM=ugni, with a craype\-hugepages module loaded
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With \fBCHPL_COMM=gasnet\fP, by default the heap will occupy as much of the
free memory on each locale (compute node) as the runtime can acquire,
less some amount to allow for demands from other (system) programs
running there.  With \fBCHPL_COMM=ugni\fP when a craype\-hugepages module is
loaded, by default the heap will occupy 2/3 of the free memory on each
locale.  With the ugni comm layer and slurm job placement, however, this
default is reduced to 16 GiB if that is less.  See \fI\%Communication Layer
Concurrency and Slurm\fP, below, for more information.
.sp
Advanced users may want to make the heap smaller than this.  Programs
start more quickly with a smaller heap, and in the unfortunate event
that you need to produce core files, those will be written more quickly
if the heap is smaller.  However, note that if you reduce the heap size
to less than the amount your program actually needs and then run it, it
will terminate prematurely due to not having enough memory.
.sp
To change the heap size, set the \fBCHPL_RT_MAX_HEAP_SIZE\fP environment
variable.  Set it to just a number to specify the size of the heap in
bytes, or to a number with a \fBk\fP or \fBK\fP, \fBm\fP or \fBM\fP, or \fBg\fP or \fBG\fP
suffix with no intervening spaces to specify the heap size in KiB (2^10
bytes), MiB (2^20 bytes), or GiB (2^30 bytes), respectively.  Any of the
following would set the heap size to 1 GiB, for example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_RT_MAX_HEAP_SIZE=1073741824
export CHPL_RT_MAX_HEAP_SIZE=1048576k
export CHPL_RT_MAX_HEAP_SIZE=1024m
export CHPL_RT_MAX_HEAP_SIZE=1g
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Note that the value you set in \fBCHPL_RT_MAX_HEAP_SIZE\fP may get rounded up
internally to match the page alignment.  How much, if any, this will add
depends on the hugepage size in any craype\-hugepage module you have loaded at
the time you execute the program.
.sp
Note that for \fBCHPL_COMM=gasnet\fP, \fBCHPL_RT_MAX_HEAP_SIZE\fP is synonymous with
\fBGASNET_MAX_SEGSIZE\fP, and the former overrides the latter if both are set.
.SS Native Runtime Layers
.sp
The readme\-multilocale and readme\-tasks pages
describe a variety of
communication and tasking layers that can be used by Chapel programs.
In addition to the standard runtime layers available in any Chapel
release, the pre\-built Chapel module for Cray XC and XE series systems
supports Cray\-specific communication and tasking layers.  These make use
of the Cray systems\(aq hardware and/or software to produce enhanced
performance for Chapel programs.  When using the pre\-built module on
Cray XC or XE systems the allowed combinations are ugni communications
with either qthreads (the default) or muxed tasking.  On other kinds of
Cray systems or when not using the pre\-built module, the default is to
use gasnet communications and qthreads tasking.
.sp
Note that neither the ugni communication layer nor the muxed tasking
layer can be built from sources, as they are not distributed in source
form.
.sp
The ugni communication layer interacts with the system\(aqs network
interface very closely through a lightweight interface called uGNI (user
Generic Network Interface).  The muxed tasking layer switches Chapel
tasks and threads in a lightweight manner in user space, avoiding the
overhead and some of the resource limitations associated with OS thread
switching.  These layers cooperate to overlap communication to remote
locales with task execution, particularly improving the performance of
programs limited by the latency of small remote data references, such as
graph analytic applications.
.SS Using the ugni Communications Layer
.sp
To use ugni communications:
.INDENT 0.0
.IP 1. 3
Make sure that you are using either the GNU, Intel, or Cray target
compiler:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
module load PrgEnv\-gnu
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
module load PrgEnv\-intel
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
module load PrgEnv\-cray
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
(If you have a different PrgEnv module loaded, you will have to
unload it first, or do a swap instead of a load.)
.IP 2. 3
Set your CHPL_COMM environment variable to \fBugni\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_COMM=ugni
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This specifies that you wish to use the Cray\-specific communication
layer.
.IP 3. 3
Set your CHPL_TASKS environment variable to \fBqthreads\fP (the
default), \fBmuxed\fP, or \fBfifo\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_TASKS=qthreads
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_TASKS=muxed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_TASKS=fifo
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All of these tasking layers work with ugni communications.  Other
Chapel environment variables having to do with runtime layers can
be left unset.  Setting \fBCHPL_COMM\fP and \fBCHPL_TASKS\fP like this
will cause the correct combination of other runtime layers that work
with those to be selected automatically.
.IP 4. 3
\fI(Optional)\fP Load an appropriate craype\-hugepages module.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
module load craype\-hugepages16M
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The ugni communication layer can be used with or without so\-called
\fIhugepages\fP\&.  Performance for remote variable references is better
when hugepages are used.  However, using hugepages effectively may
require setting \fBCHPL_RT_MAX_HEAP_SIZE\fP to a value large enough to
encompass the program\(aqs memory needs (see \fI\%Controlling the Heap
Size\fP, above), and that quantity can be hard to know.  Using
hugepages also means that the tasking layer cannot use guard pages to
detect task stack overflows (see below).
.sp
To use hugepages, you must have a \fBcraype\-hugepages\fP module loaded
both when building your program and when running it.
There are several hugepage modules, with suffixes indicating the page
size they support.  For example, \fBcraype\-hugepages16M\fP supports 16 MiB
hugepages.  It does not matter which \fBcraype\-hugepages\fP module you have
loaded when you build your program.  Any of them will do.  However,
which one you have loaded when you run your program does matter.  For
general use, the Chapel group recommends the \fBcraype\-hugepages16M\fP
module.  You can read on for more information about \fBcraype\-hugepage\fP
modules if you would like, but the recommended \fBcraype\-hugepages16M\fP
module will probably give you satisfactory results.
.sp
The architecture of the Cray network interface chips (NICs) limits
them to addressing at most 16k (2**14) pages of memory.  This is
sufficient to cover a 32 GiB Cray XC locale with 2 MiB pages.  But
if you will be running on 64 GiB locales, you will need to use at
least 4 MiB pages to cover all of the memory.  Generally, using
larger hugepage sizes results in modest performance benefits,
mostly in program startup time.  The \fBcraype\-hugepages16M\fP module
will result in slightly faster program startup, and its 16 MiB
hugepages will cover the locale memory on any Cray X\-series system.
.sp
The only downside to larger page sizes is that they can waste more
memory than smaller page sizes do, when the data segments that reside
on them are smaller than the hugepage size (which is often the case).
In practice, however, the effect of this is minor.  Even using the
fairly large 16 MiB hugepages will typically only result in around 1%
of the total locale memory being wasted.
.UNINDENT
.sp
When hugepages are used with the ugni comm layer, tasking layers
cannot use guard pages for stack overflow detection.  Qthreads tasking
can only use guard pages for stack overflow detection, so if ugni
communications is combined with qthreads tasking, overflow detection is
turned off completely.  Muxed tasking can use guard pages for stack
overflow detection, but it can also drop back to synchronous overflow
detection, as described below, with \fBCHPL_COMM=ugni\fP and hugepages.
.sp
There is one special parameter recognized by the ugni communication
layer:
.SS Communication Layer Concurrency
.sp
The \fBCHPL_RT_COMM_CONCURRENCY\fP environment variable tells the ugni
communication layer how much program concurrency it should try to
support.  This basically controls how much of the communication
resources on the NIC will be used by the program.  The default
value is the number of hardware processor cores the program will
use for Chapel tasks (\fBCHPL_RT_NUM_HARDWARE_THREADS\fP in the next
section).  Usually this is enough, but for highly parallel codes
that do a lot of remote references, increasing it may help the
performance.  Useful values for \fBCHPL_RT_COMM_CONCURRENCY\fP are in
the range 1 to 30.  Values specified outside this range are
silently increased or reduced so as to fall within it.
.SS Communication Layer Concurrency and Slurm
.sp
When slurm is used for job placement on Cray systems, it limits the
total NIC memory registration in order to allow for job sharing on
the compute nodes.  In our experience this limit is approximately
240 GiB.  The product of \fBCHPL_RT_MAX_HEAP_SIZE\fP and the communication
layer concurrency discussed above must be less than this.  The ugni
communication layer adjusts its heap size and concurrency defaults
to reflect this limit when slurm is used for job placement.  The
default heap size is reduced to 16 GiB.  The concurrency is computed
such that the product of heap size and concurrency is below 240 GiB.
Thus under slurm, the ugni communication layer can support programs
with very large heaps or programs that need a lot of communication
concurrency, but not programs that need both simultaneously.  Such
programs need to be run on a system that uses ALPS instead of slurm
for job placement.
.SS Using the muxed Tasking Layer
.sp
To use muxed tasking:
.INDENT 0.0
.IP 1. 3
Make sure that you are using either the GNU, Intel, or Cray target
compiler:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
module load PrgEnv\-gnu
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
module load PrgEnv\-intel
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
module load PrgEnv\-cray
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
(If you have a different PrgEnv module loaded, you will have to
unload it first, or do a swap instead of a load.)
.IP 2. 3
Set your \fBCHPL_TASKS\fP environment variable to \fBmuxed\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_TASKS=muxed
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This specifies that you wish to use the Cray\-specific tasking
layer.
.IP 3. 3
Set your CHPL_COMM environment variable to \fBugni\fP (the usual
default), \fBgasnet\fP (an alternative default), or \fBnone\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_COMM=ugni
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_COMM=gasnet
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
or:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_COMM=none
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All three Chapel communication layers are known to work with muxed
tasking.  Other Chapel environment variables having to do with
runtime layers can be left unset.  Setting \fBCHPL_TASKS\fP and
\fBCHPL_COMM\fP like this will cause the correct combination of other
runtime layers that work with those to be selected automatically.
.UNINDENT
.UNINDENT
.sp
There are a few special parameters recognized by the muxed tasking
layer:
.SS Controlling the Call Stack Size
.sp
For muxed tasking, more so than for other tasking implementations,
it may be important to reduce the task call stack size from its
default of 8 MiB.  A side effect of using the ugni communication
layer is that task stacks have to be created at full size.  With
other comm layers (or no comm layer), creating a stack just reserves
the memory for it without actually bringing the pages of memory into
existence.  The memory does not exist until each page of the stack
is actually used.  If the stack limit is 8 MiB (the default) and
2,000 tasks exist at the same time but each one only uses 32 KiB of
its stack space, then the program only requires about 64 MiB (2000 *
32 KiB) of memory for stacks.  But with ugni communications, the
network interactions require that all the space be brought into
existence up front.  So there, our hypothetical program would need
16 GiB (2000 * 8 MiB) of heap space just for stacks.  Thus with ugni
communications, in programs that may have many tasks active at once
but where each one does not need a very large call stack (such as
SSCA#2), it can be useful to make the stack size smaller than its
default of 8 MiB.
.sp
You can set the task stack size using \fBCHPL_RT_CALL_STACK_SIZE\fP, as described
in readme\-executing\&.  The following would make the task stack
size 128 KiB, for example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_RT_CALL_STACK_SIZE=128k
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Stack Overflow Checking
.sp
With muxed tasking, the compiler \fB\-\-stack\-checks\fP setting
specifies the default setting for execution\-time stack overflow
checking.  If this is set and the program heap (from which stacks
are allocated) is not on hugepages then each stack gets an
inaccessible guard page added at the end toward which stack growth
occurs.  If the stack overflows into this guard page, the resulting
SIGSEGV is diagnostic.  This signal\-based solution is crude, but
also trustworthy because it relies on OS services.
.sp
Guard pages cannot be used when the heap is on hugepages, because
the system call that makes memory pages inaccessible cannot be
applied to hugepages.  Currently the heap is on hugepages when
\fBCHPL_COMM=ugni\fP and there is a craype\-hugepages module loaded.
In this case muxed tasking does synchronous
stack overflow detection instead.  Explicit checks against the
task\(aqs stack limit are done on entry to selected functions in the
muxed tasking layer.  If overflow is seen, the runtime prints an
error message and halts the program.  The level of overflow checking
may be controlled using the \fBCHPL_RT_STACK_CHECK_LEVEL\fP
environment variable, which can take the following values:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B 0
no stack overflow checking
.TP
.B 1
limited stack overflow checking (default)
.TP
.B 2
more stack overflow checking
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Successively higher levels of overflow checking are more likely both to
catch overflow and to catch it earlier, but they also have more overhead
and thus a greater impact on performance.
.sp
Note: in some situations the check as to whether or not the task
stacks are in hugepage memory gets the wrong answer, leading to
internal errors when the tasking layer tries to use guard pages and
cannot do so.  This issue and its workarounds are tracked here:
.INDENT 0.0
.INDENT 3.5
\fI\%https://chapel.atlassian.net/browse/CHAPEL\-117\fP
.UNINDENT
.UNINDENT
.SS Number of Threads per Locale
.sp
The muxed tasking layer gets the threads it uses as task execution
vehicles from the soft\-threads threading layer.  The soft\-threads
layer provides lightweight threads that can be switched rapidly.
Chapel configuration constants allow you to control how many
processor cores the soft\-threads threading layer uses and the total
number of lightweight threads it provides to the tasking layer.
.sp
The \fBCHPL_RT_NUM_HARDWARE_THREADS\fP environment variable specifies the
number of cores that should be used to run Chapel tasks on each
locale.  The default is to use all of the cores, but if something
other than the ability to run tasks limits performance, such as
limited parallelism or doing many remote loads, reducing this may
improve performance.  You can set \fBCHPL_RT_NUM_HARDWARE_THREADS\fP to
any value from 1 to the actual number of hardware processor cores.
For applications where the performance is dominated by the latency
of small remote loads, such as the SSCA#2 benchmark and other graph
processing codes, using 8 processor cores often gives better
performance than using all of them.
.sp
The \fBCHPL_RT_NUM_THREADS_PER_LOCALE\fP environment variable specifies
the number of lightweight threads the soft\-threads threading layer
should provide to the muxed tasking layer for hosting tasks.  The
default is the number of processor cores being used, which gives
good performance in most cases.  However, if performance is limited
by something other than on\-node processor or bandwidth limits, and
especially for applications like RA or SSCA#2 where performance is
limited by network latency, it can be worthwhile to set this to as
much as 16*the number of hardware threads (whether default or user
specified).  You can set this to any value >= 0, but note that the
soft\-threads threading layer will silently limit it to >= 1 and <=
32*the number of hardware threads.
.SS Network Atomics
.sp
The Gemini(TM) and Aries(TM) networks support remote atomic memory
operations (AMOs) on XC, XE, and XK series systems.  When the \fBCHPL_COMM\fP
environment variable is set to \fBugni\fP, the following operations on
remote atomics are done using the network:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
32\- and 64\-bit signed and unsigned integer types:
32\- and 64\-bit floating point types:
  read()
  write()
  exchange()
  compareExchange()
  add(), fetchAdd()
  sub(), fetchSub()

32\- and 64\-bit signed and unsigned integer types:
  or(),  fetchOr()
  and(), fetchAnd()
  xor(), fetchXor()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that on XE and XK systems, which have Gemini networks, out of the
above list only the 64\-bit integer operations are done natively by the
network hardware.  32\-bit integer and all floating point operations are
done using implicit \fBon\fP statements inside the ugni communication
layer, accelerated by Gemini hardware capabilities.
.sp
On XC systems, which have Aries networks, all of the operations shown
above are done natively by the network hardware.
.SS Known Constraints and Bugs
.INDENT 0.0
.IP \(bu 2
Our PBS launcher explicitly supports PBS Pro, Moab/Torque, and the
NCCS site versions of PBS.  It may also work with other versions.
If our PBS launcher does not work for you, you can fall back on a
more manual launch of your program.  For example:
.INDENT 2.0
.IP \(bu 2
Launch the \fBa.out_real\fP binary manually using aprun and your own
qsub script or command.
.IP \(bu 2
Use \fB\&./a.out \-\-generate\-qsub\-script\fP to generate a qsub script.
Then edit the generated script and launch the \fBa.out_real\fP binary
manually as above.
.UNINDENT
.IP \(bu 2
Redirecting stdin when executing a Chapel program under PBS/qsub
may not work due to limitations of qsub.
.IP \(bu 2
GASNet targets multiple network \fIconduits\fP as the underlying
communication mechanism.  On certain platforms, the Chapel build
will use the \fBmpi\fP conduit as the default.  As a result of using the
mpi conduit, you may see a GASNet warning message at program start
up.  To squelch this message, you can set the environment variable
\fBGASNET_QUIET=yes\fP\&.
.IP \(bu 2
There is a known GASNet build issue when using the gemini or aries
conduits with hugepage support that results in link errors due to
multiply defined symbols in the hugetlbfs library.  The workaround
is to make sure that you do not have any \fBcraype\-hugepages*\fP module
loaded when you compile and link a Chapel program while using the
GASNet communication layer.  You may load a hugepage module when
running the Chapel program.
.IP \(bu 2
For X\-series systems, there is a known issue with the Cray MPI
release that causes some programs to assert and then hang during
exit.  A workaround is to set the environment variable,
\fBMPICH_GNI_DYNAMIC_CONN\fP to \fBdisabled\fP\&.  Setting this environment
variable affects all MPI programs, so remember to unset it after
running your Chapel program.
.IP \(bu 2
The amount of memory available to a Chapel program running over
GASNet with the gemini and aries conduits is allocated at program
start up.  The default memory segment size may be too high on some
platforms, resulting in an internal Chapel error or a GASNet
initialization error such as:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
node 1 log gasnetc_init_segment() at $CHPL_HOME/third\-party/gasnet/gasnet\-src/gemini\-conduit/gasnet_gemini.c:<line#>: MemRegister segment fault 8 at  0x2aab6ae00000 60000000, code GNI_RC_ERROR_RESOURCE
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If your Chapel program exits with such an error, try setting the
environment variable \fBCHPL_RT_MAX_HEAP_SIZE\fP or \fBGASNET_MAX_SEGSIZE\fP to a
lower value than the default (say 1G) and re\-running your program.
For more information, refer to the discussion of \fBCHPL_RT_MAX_HEAP_SIZE\fP
above and/or the discussion of \fBGASNET_MAX_SEGSIZE\fP here:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
$CHPL_HOME/third\-party/gasnet/gasnet\-src/README
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS NCCS user notes
.INDENT 0.0
.IP \(bu 2
NCCS Cray systems use a different qsub mechanism in order to
enforce their queuing policies.  We have attempted to make our
pbs\-aprun launch code work with this version of qsub, but require a
\fBCHPL_LAUNCHER_ACCOUNT\fP environment variable to be set to specify your
NCCS account name.  For example:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LAUNCHER_ACCOUNT=MYACCOUNTID
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
NCCS users either need to specify \fBdebug\fP as their queue or set an
explicit wall clock time limit using the mechanisms described above.
.UNINDENT
.SS Using Chapel on Cygwin
.sp
Chapel can be used on both 32\-bit and 64\-bit installations of Cygwin.
Chapel can be sensitive to directories with spaces, but otherwise it
will work on Cygwin just like any other platform.
.SS Unpacking Chapel
.sp
For best results, avoid using WinZip to unpack the release, or make
sure that it is running in a mode that will not convert textfiles to
use Windows\-style carriage\-return/linefeed end\-of\-lines \-\- doing so
can change Makefiles such that they break the build process. We
recommend using Cygwin\(aqs gunzip and tar utilities to unpack the
release:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gunzip chapel.tar.gz
tar xvf chapel.tar
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is best to unpack the release in a directory whose path contains no
spaces. For example, unpacking the release in the root directory of your
hard\-drive (\fB/cygdrive/c/\fP) to create \fB/cygdrive/c/chapel\fP tends to
work well. Currently, our compiler\-generated Makefiles break when the
compiler or runtime use an absolute path that contains spaces. If any
Cygwin experts have tips on addressing this issue in a portable way,
please let us know at \fI\%chapel_info@cray.com\fP\&.
.SS Required Packages
.sp
In order to get the required tools listed in readme\-prereqs,
Cygwin users will need to ensure that the following packages are
installed in addition to the standard set of Cygwin packages:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Devel
.INDENT 7.0
.IP \(bu 2
gcc and gcc\-g++
.IP \(bu 2
make
.UNINDENT
.TP
.B Perl
.INDENT 7.0
.IP \(bu 2
perl
.UNINDENT
.TP
.B Python
.INDENT 7.0
.IP \(bu 2
python
.UNINDENT
.TP
.B Utils
.INDENT 7.0
.IP \(bu 2
diffutils
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Additional Information
.sp
For more information on Cygwin, please refer to:
.INDENT 0.0
.INDENT 3.5
\fI\%http://www.cygwin.com\fP
.UNINDENT
.UNINDENT
.SS Using Chapel on IBM Systems
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
We have not used Chapel on IBM Systems in several years.  It is
likely the information presented here is stale or outdated.  If
you are interested in using Chapel on IBM Systems, please let us
know.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you are using Chapel on IBM\(aqs MareNostrum, you should refer to
readme\-marenostrum\&.
.UNINDENT
.UNINDENT
.sp
We only have limited experience using Chapel on IBM systems.  This
file contains notes that reflect our experience, focusing first on
PowerPC\-based systems and then BG systems.  If you are not familiar
with Chapel, it is recommended that you first try the
chapelhome\-quickstart to get started with the language.
.SS PowerPC SMP clusters
.sp
We have run Chapel on clusters of Power5 and Power6 SMP nodes using
the following settings:
.INDENT 0.0
.IP 1. 3
Set \fBCHPL_HOME\fP and \fBMANPATH\fP as indicated in readme\-chplenv\&.
.IP 2. 3
Set \fBCHPL_HOST_PLATFORM\fP to \fBpwr5\fP for a Power5 cluster or
\fBpwr6\fP for a Power6 cluster.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_HOST_PLATFORM=pwr6
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will cause Chapel to use the IBM xlc and xlC compilers by
default.
.IP 3. 3
Set \fBCHPL_COMM\fP to gasnet.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_COMM=gasnet
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See readme\-multilocale for further information about
running using multiple locales and GASNet.
.sp
Note: if you are using an installation in which your xlc/xlC
compilers and \fBar\fP utility do not use 64\-bit object formats by
default, you will need to set the \fBOBJECT_MODE\fP variable to 64
to use GASNet.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export OBJECT_MODE=64
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 3
Make sure you\(aqre in the top\-level chapel/ directory:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Make/re\-make the compiler and runtime:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
gmake
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 5. 3
Set your \fBPATH\fP to include the directory
\fB$CHPL_HOME/bin/$CHPL_HOST_PLATFORM\fP which is created when you
build the compiler.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export PATH="$PATH:$CHPL_HOME/bin/$CHPL_HOST_PLATFORM"
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 6. 3
Compile your Chapel program as usual.  See
readme\-compiling for details.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-o hello6\-taskpar\-dist $CHPL_HOME/examples/hello6\-taskpar\-dist.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 7. 3
When you compile a multi\-locale program for, you will get a
single binary by default (e.g., \fBhello6\-taskpar\-dist\fP).  In
order to run this program properly, you will typically need to
write a loadleveler script that requests a number of compute
nodes equal to the number of locales that you will specify
through the \fB\-nl\fP option, and launches a single copy of the
binary per node (either using poe, or on some systems by simply
invoking the binary directly, at the bottom of the script).  The
parallelism within the node will be generated within the binary
using pthreads in order to utilize all of the cores per node.  In
our experience, the details of required options for loadleveler
scripts vary greatly from one site to another so check with your
site\(aqs documentation for details.
.sp
There is a prototype loadleveler launcher, which can be utilized
by setting the \fBCHPL_LAUNCHER\fP environment variable to
\fBloadleveler\fP\&. See readme\-launcher for a general
description of the role of launchers in Chapel.  This launcher is
not sufficiently portable, robust, configurable, or interactive
to warrant being made the default for Power5 or Power6 machines.
If you are an IBM enthusiast who would like to work with us to
improve the utility of this launcher we would greatly appreciate
the help.
.UNINDENT
.SS Additional Notes for Power5 Clusters
.sp
Our current technique for querying the amount of memory per node is
apparently not portable to the Power5 (which is to say, we get an
insanely large value back).  When running the hpcc benchmarks with
the default configuration constants, this will exhibit itself as a
halt indicating that we can\(aqt take the \fIlog()\fP of a non\-positive
integer.  Set the problem size explicitly using the \fB\-\-m\fP or
\fB\-\-n\fP flags.  If anyone has a chance to debug this problem or
suggest a better way to query the amount of memory before we come up
with a solution, please let us know.
.SS Blue Gene/L
.sp
Our current implementation of Chapel relies heavily on POSIX threads
(pthreads) to implement both intra\- and inter\-locale parallelism.
Since BG/L does not support pthreads, Chapel is not supported on
this platform.  If you are interested in running Chapel on BG/L,
please contact us and let us know.
.SS Blue Gene/P
.sp
We have done some initial experimentation with the GASNet team to
try and run Chapel on BG/P with some limited success, however more
effort is required to make this a stable and supported platform.  If
running Chapel on BG/P would be of interest to you, please contact
us and let us know.
.SS Using Chapel on Intel "Knights Landing"
.sp
The following information is assembled to help Chapel users get up and
running on Intel Xeon Phi, Knights Landing (KNL).
.sp
The initial implementation has only been tested on Cray machines where
the KNL chip is the host processor. While we have not explicitly tested
on other platforms, or with KNL as a Coprocessor, we don\(aqt know of any
reason an advanced user couldn\(aqt run on such a platform.
.SS Getting started
.sp
By and large running on KNL on a Cray XC will be the same as running on
a Xeon based Cray XC. See readme\-cray for more info.
.sp
In order to take better advantage of the AVX\-512 micro\-architecture
you\(aqll want to have a KNL targeting module loaded. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
module load craype\-mic\-knl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You\(aqll also want to ensure you have a new enough target compiler loaded
that is KNL/AVX\-512 ready. We recommend using at least gcc 5.3, cce 8.5,
or intel 16.
.sp
Currently we don\(aqt provide any mechanism to manage the MCDRAM (High
Bandwidth Memory/HBM.) As a result, we recommend running with HBM in
cache\-only mode. We intend to add HBM support (through Locale Models)
in future releases.
.SS Future Directions
.sp
As mentioned above, we plan to add support for targeting the HBM through
our Locale Model interface.
.sp
We also plan to explore which clustering mode(s) tend to work best for a
typical Chapel program.
.SS Using Chapel on Mac OS X
.sp
By and large, Chapel can be used on a Macintosh running OS X just like
any other platform \-\- refer to the chapelhome\-quickstart for more
information on building and using Chapel.
.SS Homebrew
.sp
A minimal installation of Chapel can be obtained through \fI\%Homebrew\fP with the
following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
brew install chapel
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The Homebrew installation provides a minimal installation of Chapel for
users to explore and test the language.
Of the omitted features, multilocale support
is most notable.
Users interested in utilizing all of the
language\(aqs rich features should clone the \fI\%repository\fP or
download a \fI\%release\fP, and build Chapel from source\&.
.UNINDENT
.UNINDENT
.SS Using Chapel on MareNostrum
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
We have not used Chapel on MareNostrum in several years.  It is
likely the information presented here is stale or outdated.  If
you are interested in using Chapel on MareNostrum, please let us
know.
.UNINDENT
.UNINDENT
.sp
The following information describes how to build and use Chapel on
Barcelona Supercomputing Center\(aqs MareNostrum machine for users who
have an account there.  If you are not familiar with Chapel, it is
recommended that you first try the chapelhome\-quickstart
to get started with the language.
.INDENT 0.0
.IP 1. 3
Set \fBCHPL_HOME\fP to point to the directory of your installation as
usual.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_HOME=~/chapel\-x.y.z/chapel
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 2. 3
Set \fBCHPL_HOST_PLATFORM\fP to \fBmarenostrum\fP and \fBCHPL_COMM\fP to
\fBgasnet\fP\&.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_HOST_PLATFORM=marenostrum
export CHPL_COMM=gasnet
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Additional information about running using multiple locales and
GASNet can be found in readme\-multilocale
.IP 3. 3
Make sure you\(aqre in the top\-level chapel/ directory:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Make/re\-make the compiler and runtime:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
gmake
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 4. 3
Set your \fBPATH\fP to include \fB$CHPL_HOME/bin/marenostrum\fP which
is created when you build the compiler.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export PATH="$PATH:$CHPL_HOME/bin/marenostrum"
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 5. 3
Compile your Chapel program as usual.  See
readme\-compiling for details.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-o hello6\-taskpar\-dist $CHPL_HOME/examples/hello6\-taskpar\-dist.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.IP 6. 3
The above settings will result in a multi\-locale compilation.  When
you compile a Chapel program, you should see two binaries (e.g.,
\fBhello6\-taskpar\-dist\fP and \fBhello6\-taskpar\-dist_real\fP).  The
first binary contains code to launch the Chapel program onto the
compute nodes using \fBmnsubmit\fP\&.  The second contains the program
code itself; it is not intended to be executed directly from the
shell prompt.
.IP 7. 3
On MareNostrum, a marenostrum\-specific launcher is used by default
to wrap the \fBmnsubmit\fP and \fBslurm\fP scripts required to launch a
job on the compute nodes.  This launcher accepts the following
flags:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
\-\-walltime <HH:MM:SS> : (required) set the max wallclock time
\-\-queue <name>        : (optional) specify the debug or interactive queue
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These options can also be set using the \fBCHPL_LAUNCHER_WALLTIME\fP
and \fBCHPL_LAUNCHER_QUEUE\fP environment variables, respectively.
.IP 8. 3
Multi\-locale binaries require the number of locales to be specified
on the command line.  Other than this, execute your Chapel program
as usual.  For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
\&./hello6\-taskpar\-dist \-nl 2 \-\-walltime 00:03:00 \-\-queue debug
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can use the \fB\-v\fP flag to see the commands used to launch your
program.  If you set the \fBCHPL_LAUNCHER_DEBUG\fP environment
variable, the script used with the \fBmnsubmit\fP command will be
preserved after your program executes.
.IP 9. 3
On MareNostrum, jobs cannot be run in an interactive mode, so all
program will end up in a \fB\&.out\fP file whose name matches the
executable.  For example, the program above would leave its output
in \fBhello6\-taskpar\-dist.out\fP
.UNINDENT
.SS Using Chapel on SGI Altix
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
We have not used Chapel on SGI Altix in several years.  It is
likely the information presented here is stale or outdated.  If
you are interested in using Chapel on SGI Altix, please let us
know.
.UNINDENT
.UNINDENT
.sp
The Chapel team does not have access to an SGI Altix for the purposes
of testing, so this file describes the experiences that other users
have had in hopes that it will be useful to future Altix users.  This
file assumes a certain amount of familiarity building and using Chapel
in single\- and multi\-locale settings such as desktops or commodity
clusters.
.sp
As an opening note, performance on the Altix was not quite as good as
we\(aqd expected based on what we see on other platforms.  We conjecture
that the cause is that our runtime pthreads are not bound to specific
cores/processors and expect that some overhead creeps in as the OS
tries to schedule them \-\- that perhaps it ends up moving them around
more than is ideal.  The Altix represents a larger core count per node
(not to mention a different OS) than the platforms that we\(aqve focused
on to date, so it may be more sensitive to this.  As a result, a
possible area of future work would be to look into how our runtime
might be modified to do this binding and/or to utilize a user\-level
tasking library that multiplexes logical tasks onto a fixed set of
pthreads equal to (and bound to) the number of cores.
.INDENT 0.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This performance characterization was written when \fBfifo\fP
was the default tasking layer. It is likely that \fBqthreads\fP
performs substantially better on Altix as it provides all of
the desired runtime capabilities listed above.  Additionally,
previous studies done by the qthreads team have shown strong
performance on Altix. See readme\-tasks for more
information on Chapel\(aqs tasking layers.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Due to its support for shared memory, an Altix machine can either be
viewed as a large single locale, or as a multi\-locale machine.  Our
experience is that better performance is obtained when treating it as
a single\-locale machine.  However, since most Altix installations are
organized as multi\-partition machines, you will need to treat it as a
multi\-locale machine if you want to span multiple partitions.
.sp
For the single\-locale version, you should be able to build Chapel in
the standard way as described in the chapelhome\-quickstart,
making sure that the \fBCHPL_COMM\fP environment variable is unset or set to
\fBnone\fP\&.
.sp
For multi\-locale executions, Chapel uses GASNet as our means of
specifying inter\-locale communication.  Left to its own devices,
GASNet prefers to use its SHMEM conduit on the SGI Altix because it\(aqs
considered the lowest overhead communication layer with which to
implement GASNet.  Unfortunately, GASNet\(aqs SHMEM conduit is not
thread\-safe (because SHMEM itself is apparently not thread\-safe); or,
to use GASNet terminology, it does not support PAR mode.  Chapel\(aqs
execution model requires PAR mode, and therefore the suboptimal MPI
conduit needs to be used for GASNet executions.
.sp
This can be done using the following settings:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# cd to chapel source directory
export CHPL_HOME=$(pwd)
export CHPL_COMM=gasnet
export CHPL_COMM_SUBSTRATE=mpi
# edit make/Makefile.base to include
CHPL_GASNET_CFG_OPTIONS += \-\-disable\-aligned\-segments
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In our experience, different Altix installations support MPI in
different ways.  If your Altix machine supports MPI via an \fBmpicc\fP
compiler command and launches using an \fBmpiexec\fP command, then make the
following settings:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export MPI_CC=mpicc
export MPI_LDFLAGS=\-mt
export MPI_RUNCMD="mpiexec \-n %N %C"
export MPI_LIBS=
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If on the other hand, your Altix machine supports MPI via a normal
compiler invocation and by linking in the mpi libraries, make the
following settings:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export MPI_CC=cc   # or whatever compiler you wish to use
export MPI_LIBS=\-lmpi
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then build the Chapel compiler/runtime again using \fBmake\fP or \fBgmake\fP\&.
.SH TECHNICAL NOTES
.sp
Contents:
.SS Chapel\(aqs Use of Allocators
.sp
The Chapel runtime will select an allocator according to the \fBCHPL_MEM\fP
environment variable. See readme\-chplenv for details on how that
works.  The default is usually the system allocator (ie malloc/free as
supported by the C compiler and runtime) but some configurations use a
different allocator in order to get all of memory allocated by Chapel on
to a network registered heap.  Using the registered heap can improve
communication performance, but having two allocators can create
interoperability challenges:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
memory allocated by one allocator cannot be freed by another
.IP \(bu 2
the Chapel heap might pre\-allocate a significant amount of memory. In this
situation, programs might run out of memory if there are too many
allocations in the system heap.
.IP \(bu 2
memory allocated by the Chapel allocator will generally have better
performance when communication occurs
.UNINDENT
.UNINDENT
.UNINDENT
.sp
This file describes two strategies for overcoming these challenges.
.sp
Note that both of these strategies will only allow C code to use the allocator
that the Chapel runtime is providing. In particular, while a Chapel program
might be able to allocate memory on a hardware provided memory region, these
methods will only work with system memory.
.SS Calling Chapel Allocation Functions Directly
.sp
You can call Chapel allocation functions directly from an extern block or from
C code that is built with the proper \-I paths for the Chapel runtime.
.sp
The command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$CHPL_HOME/util/config/compileline \-\-includes\-and\-defines
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
should produce the necessary \fB\-I\fP and \fB\-D\fP options so that you can
compile a \fB\&.c\fP file to a \fB\&.o\fP file for linking with the Chapel
runtime. Note that these include paths are already handled for extern
blocks.
.sp
For example, here is a Chapel program that uses the Chapel allocator from C:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern {
  #include "chpl\-mem.h"
  static int64_t* mymalloc(void) {
    int64_t *ret = (int64_t*) chpl_malloc(1024);
    ret[0] = 5;
    return ret;
  }
  static void myfree(int64_t *x) {
    chpl_free(x);
  }
}


var x = mymalloc();

writeln(x.deref());

myfree(x);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Chapel runtime includes \fBchpl_calloc\fP, \fBchpl_malloc\fP,
\fBchpl_memalign\fP, \fBchpl_realloc\fP, \fBchpl_free\fP,
\fBchpl_posix_memalign\fP, \fBchpl_valloc\fP, and \fBchpl_pvalloc\fP\&.  These
routines take in exactly the same arguments as the C library versions.
.SS Replacing the System Allocator
.sp
In some cases, it may not be possible to modify C code that you would like to
allocate. At the same time, some C libraries allow their allocation functions
to be replaced. The manner in which the allocation functions can be replaced is
very platform specific. Because the GNU C library is common in the environments
that Chapel targets, we have provided a library which replaces the C library
functions with the Chapel allocator. It works by defining malloc, free, etc
because these are normally defined as weak symbols in the GNU C library.  This
feature should be considered a demonstration. It is highly platform\-specific
and will not work on all platforms! For this reason, we recommend instead
calling the Chapel versions of the allocation routines (such as chpl_malloc) if
allocation interoperability is required.
.sp
The following command will compile a Chapel program while replacing the C
allocation functions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl myprogram.chpl \-lchplmalloc
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern {
  #include <stdlib.h>
  static int64_t* mymalloc(void) {
    // If this pointer is to be freed by the Chapel free function,
    // it\(aqs much better to use chpl_malloc instead!
    int64_t *ret = (int64_t*) malloc(1024);
    ret[0] = 5;
    return ret;
  }
}

// SysBasic provides c_calloc and c_free to call the Chapel allocator
// directly for C interoperability purposes
use SysBasic;

// Allocate using the system allocator (malloc)
var x = mymalloc();

writeln(x.deref());

// Free using the Chapel allocator \- c_free calls the Chapel free function
// directly. It\(aqs named c_free because it\(aqs meant to be used for C
// interoperability purposes.
// This will generally cause a core dump unless:
//   * you have configured Chapel to use the system allocator, or
//   * you link this program with \-lchplmalloc
c_free(x);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Runtime Support for Atomics
.sp
The following information is meant to describe the underlying
runtime support for Chapel\(aqs Atomic Variables.
.sp
For more information on Atomic Variables refer to the Chapel
Language Specification, or for a list of available functions on
Atomics see \fBAtomics\fP
.sp
For code examples using atomics, see the
\fB$CHPL_HOME/examples/primers/atomics.chpl\fP primer.
.SS Overview
.sp
Atomic variables are a built\-in type that support predefined atomic
operations.  Currently, Chapel supports processor\-provided atomic
operations on \fBbool\fP, as well as all sizes of \fBint\fP,  \fBuint\fP,
and \fBreal\fP for most backend compilers (see readme\-chplenv
for the current list of supported compilers.) Initial support for
network\-provided atomic operations is also available. See the
platform\-specific documentation to check if
network\-based atomics are available for your platform
.sp
The choice of supported atomic variable types as well as the atomic
operations were strongly influenced by the C11 standard. A notable
exception is that Chapel supports atomics for \fBreal\fP types as
well.
.sp
The specific implementation of atomics can be selected via the
environment variable \fBCHPL_ATOMICS\fP\&.  Similar to the other Chapel
environment variables, an appropriate default is chosen when not
specified, and not all implementations are available for all
settings.  Chapel currently supports two atomics implementations:
\fBintrinsics\fP and \fBlocks\fP\&. This environment variable also
specifies the atomic implementation used by the Chapel runtime.
.sp
If compiler support for atomics is available, the atomic operations
will be mapped down the appropriate compiler intrinsics which often
map directly to processor atomics.  If intrinsics are not available,
the atomic implementation defaults to using locks in the form of
Chapel\(aqs sync vars. As a result the locks implementation will be
slower than the intrinsic implementation. Since Chapel\(aqs atomics
were modeled after the C11 standard, as C11 support becomes more
prevalent, we will support an implementation that maps to the C11
atomics.
.sp
Currently, unless using network atomics, all remote atomic
operations will result in the calling task effectively migrating to
the locale on which the atomic variable was allocated and performing
the atomic operations locally.
.sp
If supported, the network atomics implementation can be selected via
the environment variable \fBCHPL_NETWORK_ATOMICS\fP\&. If set, all
variables declared to be atomic will use the specified network\(aqs
atomic operations. It is possible to override this default by using
the undocumented internal function \fBchpl__processorAtomicType()\fP
defined in \fB$CHPL_HOME/modules/internal/Atomics.chpl\fP\&. Over time
we will add a more principled way for explicitly requesting
processor atomics, and this function may disappear.
.sp
For more information about the runtime implementation see
\fB$CHPL_HOME/runtime/include/atomics/README\fP\&.
.SS Memory Order Notes
.sp
As mentioned in the spec, most atomic operations optionally take a
memory order. However for all current implementations, this argument
is ignored. The resulting effect is that all atomic operations are
performed with memory_order_seq_cst (sequentially consistent)
regardless of the actual order specified. The reason for this is
because the compiler intrinsics used in the runtime have no way to
specify memory order.
.sp
We expect to begin using the specified memory order with a C11
implementation of the atomics.
.SS Variances from the C11 standard
.sp
While Chapel atomics are modeled after the C11 standard there are some
notable differences. The primary one is that Chapel supports atomics for
\fBreal\fP types. It should be noted that since there is virtually no
hardware support for floating point atomics, our implementation is
not very efficient.
.sp
As noted in the spec there a few additional methods in Chapel that
are not in C11. They are \fBpeek\fP, \fBpoke\fP, and \fBwaitFor\fP\&.
\fBpeek\fP and \fBpoke\fP are supposed to be relaxed versions of read
and write that allow users to perform reads and writes with more
relaxed memory constraints.  Currently they are implemented as reads
and writes with memory_order_relaxed but current implementations
ignore memory_order. \fBwaitFor\fP is method that waits until an
atomic value has a specific value.  It can yield to other tasks
while waiting.
.sp
Chapel currently does not support the memory fences or the
\fBisLockFree\fP method from the C11 spec. They are defined in the
runtime but not in the modules. The primary reason that
\fBisLockFree\fP is not available is that it may not be accurate for
the intrinsics. Without examining each intrinsic operation for each
compiler it is hard to know if they actually map down to lock free
operations. \fBthreadFence\fP and \fBsignalFence\fP are also in the
runtime but not in the modules. The primary reason for this is that
there is no need for them with the current implementation.  All our
operations use memory_order_seq_cst. The fences are used with other
memory_orders to allow you to create safe programs when atomic
operations are using non sequential memory orders.
.SS Open issues
.INDENT 0.0
.IP \(bu 2
Atomic bools are only supported for the default size and not
implemented for all sizes of bools.
.IP \(bu 2
The memory_order is currently ignored by all implementations.
.UNINDENT
.SS Additional References
.INDENT 0.0
.IP \(bu 2
See the section titled "Memory Consistency Model" in the Chapel
Language Specification for more information on memory orders and
Chapel\(aqs memory consistency model.
.UNINDENT
.SS Auxiliary I/O Systems
.sp
This README describes Chapel support for Auxiliary I/O(AIO) systems. It also
provides instructions on how to set Chapel up to support multiple Auxiliary I/O
systems simultaneously.
.SS Dependencies
.sp
Each AIO system is typically described in the support module for it.
See:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBHDFS\fP
.IP \(bu 2
\fBCurl\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
for specific instructions on how to install and use those features.
.sp
The AIO system depends upon three environment variables:
.INDENT 0.0
.INDENT 3.5
\fBCHPL_AUX_FILESYS\fP
\fBCHPL_AUXIO_INCLUDE\fP
\fBCHPL_AUXIO_LIBS\fP
.UNINDENT
.UNINDENT
.sp
In the following sections, we will explain what they should be set to, and give
the general idea of what they do.
.SS CHPL_AUXIO_INCLUDE & CHPL_AUXIO_LIBS
.sp
These paths are for the extra libraries that will be linked in with the runtime
when it is compiled. For instance, if I installed libcurl, and had it install in
\fB~/include\fP and \fB~/lib\fP you would set them to be:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_AUXIO_LIBS="\-L~/include"
export CHPL_AUXIO_INCLUDE="\-I~/lib"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In general, you want it so that if you had a .c file that used the libraries
that you wish to compile Chapel with, all you would need to do to compile this
file would be:
.sp
\fBcc $CHPL_AUXIO_LIBS $CHPL_AUXIO_INCLUDE <any libraries> <the .c file>\fP
.sp
where <any libraries> might be \fB\-lcurl\fP, \fB\-lhdfs\fP, \fB\-lhdfs3\fP, \fB\-ljvm\fP etc.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
It is not necessary to pass these library flags, or library/include paths
to the Chapel compiler invocations (chpl) as the values in \fBCHPL_AUXIO_LIBS\fP
and \fBCHPL_AUXIO_INCLUDE\fP will be used there as well as in building the
Chapel runtime
.UNINDENT
.UNINDENT
.SS CHPL_AUX_FILESYS
.sp
This is a space delimited string detailing what AIO systems we wish to compile
Chapel with (and use). For example if we wanted to enable Curl and HDFS support
simultaneously we would set:
.INDENT 0.0
.INDENT 3.5
\fBCHPL_AUX_FILESYS="hdfs curl"\fP
.UNINDENT
.UNINDENT
.sp
Assuming that you have correctly defined \fBCHPL_AUXIO_INCLUDES\fP and \fBCHPL_AUXIO_LIBS\fP
as detailed above, and have the correct libraries installed.
.sp
If you only have one AIO system that you wish to use, you may simply set
\fBCHPL_AUX_FILESYS=<system>\fP\&. For example, if we only wanted Apache Hadoop HDFS support,
we would set:
.INDENT 0.0
.INDENT 3.5
\fBCHPL_AUX_FILESYS=hdfs\fP
.UNINDENT
.UNINDENT
.SS I/O Systems Supported
.sp
Currently, the I/O systems supported are:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Lustre
.IP \(bu 2
\fBHDFS\fP
.IP \(bu 2
\fBCurl\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Parallel and Distributed I/O Features
.sp
We support two functions for Parallel and Distributed file systems (these also
work on "standard" file systems as well).
.sp
\fBfile.getchunk(start:int(64), end:int(64)):(int(64), int(64))\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
This returns the first logical \fIchunk\fP of the file that is inside this
section. If no \fIchunk\fP can be found inside this region, (0,0) is returned. If
no arguments are provided, we return the start and end of the first logical
chunk for this file.
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
On Lustre, this returns the first stripe for the file that is inside this region.
.IP \(bu 2
On HDFS, this returns the first block for the file that is inside this
region.
.IP \(bu 2
On local file systems, it returns the first \fIoptimal transfer block\fP
(from fstatfs) inside this section of the file.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBfile.localesForRegion(start:int(64), end:int(64)):domain(locale)\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
This returns the \fIbest locales\fP for a given chunk of the file. If no
individual or set of locales are \fIbest\fP (i.e., there is some sort of data
affinity that we can exploit), we return all locales.
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
On Lustre, no locale are \fIbest\fP, so we return all locales
.IP \(bu 2
On HDFS, we return the block owners for that specific block
.IP \(bu 2
On local file systems, we return all locales, since no individual
locale is best.
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
Apache Hadoop provides a libhdfs implementation that uses the Java virtual
machine (jvm) and the Apache Hadoop HDFS jar files. When using Apache Hadoop
libhdfs, make sure the jvm installation includes a static version of libjvm.
Since, Apache Hadoop\(aqs libhdfs spins up a jvm, each compute node will need
access to the Apache Hadoop HDFS jar files and correct Java classpath
configurations.
.IP \(bu 2
Pivotal libhdfs3 is a pure C/C++ alternative implementation of the libhdfs.
To use libhdfs3: install the libhdfs3 using source code from the PivotalHD
github repository, follow the instructions for installing the Chapel support
for Apache Hadoop libhdfs, and set \fBCHPL_AUX_FILESYS=hdfs3\fP
.IP \(bu 2
When building Chapel HDFS support, select \fIone\fP libhdfs implementation!
.IP \(bu 2
To use Chapel\(aqs third\-party build support (in the event you do not have or
would like avoid performing a system build of libhdfs) review the \fBREADME\fP
file in \fB$CHPL_HOME/third\-party/libhdfs3\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Interactive Chapel
.sp
The Chapel team has initiated an effort to develop an Interactive
Programming Environment (IPE) for Chapel.  This system will allow
Chapel developers to write applications in an incremental and
interactive fashion e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
IPE 0.1

1 > var x = 20;
2 > proc double(x : int) : int return x + x;
3 > writeln(\(aq2 * x is \(aq, double(x));
    2 * x is    40
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
without the traditional edit\-compile\-run cycle.
.sp
Release 1.11 includes a proof\-of\-concept implementation of this
effort.  The current functionality is extremely limited, and somewhat
fragile, but we believe that there is enough behavior to provide a
sense of the direction we are pursuing.
.sp
It is expected that the IPE will mature reasonably quickly over the
coming months.  If the IPE is of interest to you then you may wish
to track our progress on Github.
.sp
\fBContents\fP:
.INDENT 0.0
.IP 1. 3
\fI\%No Additional Installation\fP
.IP 2. 3
\fI\%Overview\fP
.IP 3. 3
\fI\%The IPE subset of Chapel\fP
.IP 4. 3
\fI\%chpl\-ipe Future directions\fP
.UNINDENT
.SS No Additional Installation
.sp
For this release there are no additional installation instructions.
If you have a working version of the Chapel compiler then the IPE
should also be in your path!  Just run \fBchpl\-ipe\fP\&.
.SS Overview
.sp
To use the interpreter on a unix\-like system do:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
prompt> chpl\-ipe
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You will be greeted with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
IPE 0.1

1 >
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
i.e. an indication that you have started version 0.1 of the IPE and then an
interactive prompt.  At this point you can type simple Chapel statements e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
IPE 0.1

1 > var x = 20;
2 > writeln(\(aqX  is \(aq, x);
    X  is    20
3 > proc double(x : int) : int return x + x;
4 > writeln(\(aq2X is \(aq, double(x));
    2X is    40
5 >
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For convenience you can specify the name of a file that contains Chapel definitions
on the command line.  This file will be processed by the interpreter and then the
interactive prompt will appear.  This saves typing the same code each time you
start the IPE. Suppose the file \fISquare.chpl\fP contains the definition of a procedure
that computes the square of an integer value.  You could then do:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
> chpl\-ipe Square.chpl

IPE 0.1

1 > writeln(\(aqsquare(5) => \(aq, square(5));
    square(5) =>    25
2 >
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The IPE subset of Chapel
.sp
The version of the IPE that is included in the 1.11 release implements a
very small subset of Chapel.  Once again, this is expected to change
quickly during the coming months and so you may wish to track the github
version of the code base.
.SS Variables
.sp
The IPE supports variables with types bool, int, real, and c_string.
These are declared in the natural way with local type inference e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1 > var x : int = 20;
2 > var y = 30.3;             // Equivalent to var y : real = 30.3;
3 > var z : int;              // Equivalent to var z : int  =  0;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Assignment
.sp
The assignment operator is defined for bool, int, and real e.g:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1 > var x : int;              // x is  0
2 > var y = 42;               // y is 42
3 > x = y;                    // x is now 42
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The types of the LHS and RHS must match.  There is currently no
support for Chapel\(aqs implicit coercion from int to real during
assignment.
.SS Arithmetic operators
.sp
The IPE implements the unary +, \- operators on int and real and the
binary operators +, \-, *, / on int and real.  Once again the IPE
does not currently implement implicit coercion from int to real.
.SS Equality operators
.sp
The IPE implements == and != on pairs of bool, int, and real.
.SS Comparison operators
.sp
The IPE implements <, >, <=, >= on pairs of int and real.
.SS If statement
.sp
The IPE implements the IF statement e.g. the code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var value : int = 0;

writeln(\(aqvalue (expect  0) \(aq, value);

if true then
  value =  6;

writeln(\(aqvalue (expect  6) \(aq, value);

if false then
  value =  2;

writeln(\(aqvalue (expect  6) \(aq, value);

if value > 9 then
  value =  2;
else
  value = 10;

writeln(\(aqvalue (expect 10) \(aq, value);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will produce:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
value (expect  0)     0
value (expect  6)     6
value (expect  6)     6
value (expect 10)    10
.ft P
.fi
.UNINDENT
.UNINDENT
.SS While statement
.sp
The IPE implements a restricted form of the while statement; it does
not support the break or continue statement e.g. entering the following
in to the IPE:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var i   : int =  0;
var n   : int = 10;

var res : int =  1;

while (i < n)
{
  res = res * 2;
  i   = i   + 1;
}

writeln(\(aqi:   \(aq, i);
writeln(\(aqn:   \(aq, n);
writeln(\(aqres: \(aq, res);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will produce:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
i:      10
n:      10
res:  1024
.ft P
.fi
.UNINDENT
.UNINDENT
.SS User defined procedures
.sp
The IPE supports user defined procedures with the limitation that
any formals must be explicitly typed and cannot be named or take a
default value.  Additionally the type of the return value, if any,
must be specified.  If there is no return value, then void must be
specified.  For example the following implements square() for an
integer:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1> proc square(x : int) : int return x * x;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Return statement
.sp
The IPE implements the return statement within a procedure
with the limitation that if it appears, then it must be the
final statement of the procedure.  This implies that there can
be only one return statement in a procedure and that a return
cannot appear within an if statement or a while statement.
.SS Output functions
.sp
There is a small set of output functions.  There is a procedure
print() which takes one argument of type bool, int, real, or c_string
and prints the type and the value e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1 > var x = 30;
2 > print(x);
    int      30
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There is a restricted form of writeln().  The first version takes a
single c_string and prints the string and then a newline e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1> writeln(\(aqHello world\(aq);
   Hello world
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The remaining versions take two arguments.  The first argument must be
a c_string, and the second argument must be a bool, int, or real.  This
prints the c_string followed by a representation of the second argument e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1 > var x = 42;
2 > writeln(\(aqThe Answer to the Ultimate Question of Life, the Universe, and Everything is \(aq, x);
    The Answer to the Ultimate Question of Life, the Universe, and Everything is    42
.ft P
.fi
.UNINDENT
.UNINDENT
.SS chpl\-ipe Future directions
.sp
We expect the IPE to mature rapidly during the development for release 1.12.  In the
immediate term we plan to
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Stabilize the implementation so that a small variety of simple sequential
programs can be executed
.IP \(bu 2
Support applications with multiple tasks by implementing the \fBbegin\fP statement
.IP \(bu 2
Support multi\-locale applications by implementing the \fBon\fP statement.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
i.e. to go deep before we go wide.  Once we have developed this core functionality we can
turn our attention to, in no well\-defined order,
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Generic functions
.IP \(bu 2
Arrays and domains
.IP \(bu 2
Iterators
.IP \(bu 2
Classes and Records
.IP \(bu 2
Generic types
.IP \(bu 2
For loops, forall loops, and so on
.UNINDENT
.UNINDENT
.UNINDENT
.sp
It is not currently clear how much of this will be present in the 1.12 release but
we hope you share our excitement about the possibilities!
.SS Domain Map Standard Interface
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Domain Map Standard Interface\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Introduction\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Status of this document\fP
.IP \(bu 2
\fI\%Additional Resources\fP
.UNINDENT
.IP \(bu 2
\fI\%Overview\fP
.IP \(bu 2
\fI\%Phase 1: The Essentials\fP
.INDENT 2.0
.IP \(bu 2
\fI\%class GlobalDistribution\fP
.IP \(bu 2
\fI\%class GlobalDomain\fP
.INDENT 2.0
.IP \(bu 2
\fI\%A. Subdomain Description\fP
.IP \(bu 2
\fI\%B. Follower Yield Order\fP
.UNINDENT
.IP \(bu 2
\fI\%class GlobalArray\fP
.IP \(bu 2
\fI\%Naming\fP
.UNINDENT
.IP \(bu 2
\fI\%Phase 2: Additional Operations\fP
.IP \(bu 2
\fI\%Phase 3: Privatization\fP
.INDENT 2.0
.IP \(bu 2
\fI\%What is privatization?\fP
.IP \(bu 2
\fI\%How does privatization work with DSI?\fP
.IP \(bu 2
\fI\%What is reprivatization?\fP
.IP \(bu 2
\fI\%DSI privatization requirements\fP
.IP \(bu 2
\fI\%Tip: testing privatization\fP
.IP \(bu 2
\fI\%Tip: privatized copies should reference privatized copies\fP
.IP \(bu 2
\fI\%Tip: "privatize" the domains and arrays used in the implementation\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Introduction
.sp
This document defines \fBDSI\fP \-\- the Domain map Standard Interface.
It is the interface that a domain map must implement.
This interface is currently in place and is implemented by the standard
domain maps provided with this Chapel distribution.
.sp
The specification is split into "phases". The intention is to suggest
an implementation order. The requirements of first phase are relied
upon by the more essential operations on domains and arrays. Later
phases support additional functionality and/or improved performance.
The phasing is approximate and is not required.
.SS Status of this document
.sp
This document, as well as the DSI interface itself, are work in progress.
We solicit feedback on both.
.sp
The following aspects are not documented yet:
.INDENT 0.0
.IP \(bu 2
a summary of the six descriptor classes
.IP \(bu 2
the requirements for a domain map to support
associative, opaque, or sparse domains;
.IP \(bu 2
the significance of dsiClone();
.IP \(bu 2
the "local descriptor" classes;
.IP \(bu 2
some required methods.
.UNINDENT
.SS Additional Resources
.sp
Implementations of the standard domain maps may be consulted as
examples.  They are available in:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$CHPL_HOME/modules/dists
$CHPL_HOME/modules/layouts
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
In addition, the following publication provide more background
information on domain maps in general.
.INDENT 0.0
.IP \(bu 2
"User\-Defined Distributions and Layouts in Chapel: Philosophy and
Framework." Bradford L. Chamberlain, Steven J. Deitz, David
Iten, Sung\-Eun Choi. 2nd USENIX Workshop on Hot Topics in
Parallelism, June 2010.
.INDENT 2.0
.INDENT 3.5
The high level motivation and overview of DSI.
.sp
\fI\%http://chapel.cray.com/publications/hotpar10\-final.pdf\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
"Authoring User\-Defined Domain Maps in Chapel."  Bradford
L. Chamberlain, Sung\-Eun Choi, Steven J. Deitz, David Iten, Vassily
Litvinov. CUG 2011, May 2011.
.INDENT 2.0
.INDENT 3.5
A follow\-on paper that outlines how to write a domain map.
.sp
\fI\%http://chapel.cray.com/publications/cug11\-final.pdf\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Overview
.sp
A domain map must provide three (or more) "global descriptor" classes.
Here they are called \fBGlobalDistribution\fP, \fBGlobalDomain\fP,
and \fBGlobalArray\fP\&.
Their required fields and methods, as well as suggested naming,
are specified below.
.sp
A domain map is allowed to contain/provide features, data structures
and functionality (internally to facilitate implementation and/or
externally for users\(aq benefit) beyond the DSI requirements.
For example, a distribution (i.e. a domain map that distributes data across
multiple locales) will typically define "local descriptor" classes as well.
.SS Phase 1: The Essentials
.SS class \fBGlobalDistribution\fP
.INDENT 0.0
.INDENT 3.5
This class is visible to the users of the domain map: the \fBdmap\fP wrapper
in Chapel\(aqs \fIdmapped\fP clauses wraps instances of this class.
This class must be a subclass of \fBBaseDist\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDistribution.GlobalDistribution() // or with arguments
Constructor(s)  These are not regulated by DSI \- their specifics are
at the domain map implementor\(aqs discretion.
.sp
We suggest providing constructor(s) that accept, as an argument,
an array of locales over which to distribute, with \fBLocales\fP
as the default value.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDistribution.dsiClone(): GlobalDistribution
Returns a duplicate of \fIthis\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDistribution.dsiDisplayRepresentation(): void
A debugging method. It implements displayRepresentation()
on the dmap wrapper.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDistribution.dsiEqualDMaps(that: /*some other GlobalDistribution*/): bool
Return whether or not the two domain maps are "equal" (specify the
same distribution).  This is invoked when \fB==\fP is applied to two
domain maps.
.UNINDENT
.SS class \fBGlobalDomain\fP
.INDENT 0.0
.INDENT 3.5
An instance of this class is created whenever a \fBGlobalDistribution\fP\-mapped
Chapel domain is created (e.g. when a domain variable is declared).
There is a one\-to\-one correspondence at run time between a
(conceptual) Chapel domain value and an instance of \fBGlobalDomain\fP\&.
For presentation simplicity, \fBGlobalDomain\fP\(aqs properties refer to
the properties of the corresponding Chapel domain value, when
clear from the context.
.sp
Depending on the domain kind, this class is returned by the following
method on \fBGlobalDistribution\fP
and must be a subclass of the following class:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|l|.
_
T{
domain kind
T}	T{
creating method
T}	T{
required superclass
T}
_
T{
rectangular
T}	T{
\fBdsiNewRectangularDom\fP
T}	T{
\fBBaseRectangularDom\fP
T}
_
T{
associative
T}	T{
\fBdsiNewAssociativeDom\fP
T}	T{
\fBBaseAssociativeDom\fP
T}
_
T{
opaque
T}	T{
\fBdsiNewOpaqueDom\fP
T}	T{
\fBBaseOpaqueDom\fP
T}
_
T{
sparse
T}	T{
\fBdsiNewSparseDom\fP
T}	T{
\fBBaseSparseDom\fP
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
It is legal for these methods to return instances of different classes
in different circumstances. (For example, due to the absence of multiple
inheritance, different domain kinds require different classes.)
.sp
The DSI requirements apply to each of those classes.
\fBGlobalDomain\fP is used in this document to refer to each such class.
.sp
The DSI requirements depend on the domain kind that is supported.
The following requirements apply when supporting rectangular domains.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class GlobalDomain
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
class GlobalDomain ... {
  param rank: int;
  type idxType;
  param stridable: bool;
  var dist;
  ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The fields \fBrank\fP, \fBidxType\fP, \fBstridable\fP are the attributes
of the corresponding Chapel domain. (They could be replaced with
parenthesesless functions of the same names and param/type intents.)
.sp
The field \fBdist\fP must contain a reference
to the \fBGlobalDistribution\fP object
that created this \fBGlobalDomain\fP\&. It is used when creating the (runtime)
type for this domain, which contains the domain\(aqs domain map.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiMyDist() return dist;
Returns this domain\(aqs domain map. This procedure should be provided as shown.
(Exception: see \fBdsiLinksDistribution()\fP\&.)
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDistribution.dsiNewRectangularDom(param rank: int, type idxType, param stridable: bool) : GlobalDomain(rank, idxType, stridable)
This method is invoked when the Chapel program is creating an uninitialized
domain value of the type domain(rank, idxType, stridable)
mapped using the domain map \fIthis\fP\&.
.sp
This method returns a new \fBGlobalDomain\fP instance that will correspond to
that Chapel domain value, i.e., be that value\(aqs runtime representation.
The field \fBdist\fP of the returned \fBGlobalDomain\fP must point to \fIthis\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiGetIndices(): rank * range(idxType, BoundedRangeType.bounded, stridable)
Returns a tuple of ranges describing the dimensions of this domain.
.sp
\fBdsiDims()\fP and \fBdsiGetIndices()\fP have the same specification
and so may be implemented in terms of one another.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiSetIndices(dom: domain(rank, idxType, stridable)): void
Updates the internal representation of \fIthis\fP
to match the index set of \fBdom\fP\&.
.sp
\fBdsiSetIndices\fP and \fBdsiGetIndices\fP are used to assign a domain value to
a domain variable (or any domain l\-value).
Note: the arrays associated with this domain will be updated
outside these method.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiSetIndices(ranges: rank * range(idxType)): void
The same as the other \fBdsiSetIndices\fP\&. Could be implemented like this:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{ dsiSetIndices([(...rangesArg)]); }
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
It is used to initialize the index set of the object returned by
\fBdsiNewRectangularDom()\fP to the index set of the corresponding Chapel
domain value.
.UNINDENT
.INDENT 0.0
.TP
.B iter GlobalDomain.these()
The serial iterator over the indices of this domain.
Yields values of the type \fBidxType\fP if \fBrank==1\fP,
otherwise \fBrank*idxType\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B iter GlobalDomain.these(param tag) where tag == iterKind.leader
.UNINDENT
.INDENT 0.0
.TP
.B iter GlobalDomain.these(param tag, followThis) where tag == iterKind.follower
The "leader" and "follower" iterators (defined below). They are
invoked implicitly to implement parallel ("forall") loops over this domain.
Currently the serial iterator must also be defined for "forall" loops to work.
.sp
The presentation below is tailored to the use of leader/follower iterators
in domain maps. For a more general discussion, see:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$CHPL_HOME/examples/primers/leaderfollower.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The job of the leader iterator is to:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
subdivide the given domain into subdomains,
.IP \(bu 2
introduce parallelism between these subdomains, and
.IP \(bu 2
place computations for each subdomain on the desired locale,
as appropriate for this domain map.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The leader iterator must yield, for each subdomain it chooses,
a description of that subdomain, created as defined below.
Parallelism and placement are achieved, for example, by placing the
yield statements within parallel loops and \fIon\fP statements.
The leader is invoked (implicitly) once per parallel loop or expression
over the corresponding domain.
.sp
The job of the follower iterator is simply to iterate sequentially
over a subdomain whose description is yielded by the leader iterator,
yielding all indices in that subdomain.
Each time the leader yields a description, the follower is invoked
(implicitly) with that description passed to its \fBfollowThis\fP argument.
(The argument name must be exactly "followThis".)
.sp
For a zippered loop, only the leader for the first of the zippered
items is invoked. Each time that leader yields a description,
all followers are invoked in a zippered manner, with that description
passed to their \fBfollowThis\fP arguments.
.sp
In general, it is up to the implementer of the leaders/followers
whether and how to support their interoperability in this situation.
That is, whether and how the description from the leader of one
zippered item is handled by the follower of another item.
For example, one could support zippering of similar items
and generate a compile\-time or run\-time error when the items
are not "similar".
.sp
DSI requires interoperability between domain maps only
for \fIrectangular\fP domains, by prescribing:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP A. 3
how the leader builds the description of a subdomain, and
.IP B. 3
in what order the follower yields the indices of that subdomain.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS A. Subdomain Description
.INDENT 0.0
.INDENT 3.5
Let \fBDwhole\fP be the Chapel domain corresponding to this \fBGlobalDomain\fP\&.
.sp
Let \fBDsub\fP be a subdomain chosen by the leader iterator.
.sp
Let \fBDD\fP be the number of dimensions in Dwhole and Dsub.
.sp
The description of \fBDsub\fP is its "densification" w.r.t. \fBDwhole\fP:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// densification of a domain is a tuple of densifications
// of ranges for each dimension
densify(Dsub, Dwhole) =
  ( densify(Dsub.dim(1), Dwhole.dim(1)),
    ...,
    densify(Dsub.dim(DD), Dwhole.dim(DD)) )

// densification of a range is the sequence of densifications
// of its elements, preserving their order
if Rsub describes the sequence
  i_1, ..., i_N
then densify(Rsub, Rwhole) describes the sequence
  densify(i_1, Rwhole), ..., densify(i_N, Rwhole)

For example, densify(Rwhole, Rwhole) == 0.. #(Rwhole.length)

// densification of an index is its indexOrder
densify(i, Rwhole) = Rwhole.indexOrder(i)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The optional module DSIUtil provides the following implementations
of densifications and the reverse transformation:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
densify(Dsub, Dwhole)
densify(RSsub, RSwhole)  // on tuples of ranges
densify(Rsub, Rwhole)
unDensify(Dsub, Dwhole)
unDensify(RSsub, RSwhole)  // on tuples of ranges
unDensify(Rsub, Rwhole)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Hint: when developing a new domain map, skip densification and
de\-densification, but ensure it is used in zippering only
with domains/arrays of the same domain map.
.UNINDENT
.UNINDENT
.SS B. Follower Yield Order
.INDENT 0.0
.INDENT 3.5
The follower iterator must traverse the subdomain for which the above
description is created in the order given by the default domain map.
(That order can be observed, e.g., by assigning \fBRsub\fP to a domain
variable whose type does not specify a domain map explicitly,
then invoking \fBwrite()\fP on that variable.)
.sp
(Interoperability of domain maps implies that the follower must
accept a densification of any subdomain of \fBDwhole\fP, not just the
ones that can be generated by its leader.)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B iter GlobalDomain.these(param tag) where tag == iterKind.standalone
A "standalone" parallel iterator. It is optional. If it is provided,
it is used in non\-zippered "forall" loops
instead of a combination of leader+follower iterators.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiSerialWrite(f: Writer): void
Writes out the domain to the given Writer (e.g. a file or stdout) serially.
Is used to implement write() on the corresponding domain.
.sp
This method will typically invoke f.write() on \fBGlobalDomain\fP\(aqs components
(e.g. bounds) and strings (e.g. "[" and "]"). Such invocations, whether
direct or indirect, must occur within the same task that \fBdsiSerialWrite()\fP
is invoked in, and not within any \fIon\fP statements, direct or indirect.
Otherwise a deadlock may occur.
(Invoking \fBwrite()\fP on \fBWriters\fP other than \fBf\fP
is not affected by this.)
.sp
\fBdsiSerialWrite()\fP will always be invoked on \fBLocales(0)\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiDisplayRepresentation(): void
A debugging method. It implements \fBdisplayRepresentation()\fP
on the corresponding Chapel domain value.
.UNINDENT
.SS class \fBGlobalArray\fP
.INDENT 0.0
.INDENT 3.5
An instance of this class is created whenever a Chapel array is created
over a domain represented by a \fBGlobalDomain\fP\&.
There is a one\-to\-one correspondence at run time between a
(conceptual) Chapel array value and an instance of \fBGlobalArray\fP\&.
.sp
This class is returned by \fBGlobalDomain.dsiBuildArray\fP\&.
It must be a subclass of \fBBaseArr\fP\&.
.sp
It is legal for \fBGlobalDomain.dsiBuildArray\fP to return instances of
different classes in different circumstances.
The DSI requirements apply to each of those classes.
Here \fBGlobalArray\fP refers to each such class.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class GlobalArray ... {
  type eltType;
  var dom;
  ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The field \fBeltType\fP gives the type of the array elements.
.sp
The field \fBdom\fP must contain a reference to the \fBGlobalDomain\fP object
that created this \fBGlobalArray\fP\&. This is used when creating the (runtime)
type for this array, which contains the array\(aqs domain.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.GlobalArray() // or with arguments
Constructor(s). These are not regulated by DSI \-\- their specifics are
at the domain map implementor\(aqs discretion.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiBuildArray(type eltType) : GlobalArray(eltType, this.type)
This method is invoked when the Chapel program is creating
an array value over the domain \fIthis\fP with the element type \fBeltType\fP\&.
This method returns a new \fBGlobalArray\fP instance that will correspond to
that Chapel array value, i.e., be that value\(aqs runtime representation.
The field \fBdom\fP of the returned \fBGlobalDomain\fP must point to \fIthis\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.dsiGetBaseDom() return dom;
Returns this array\(aqs \fBGlobalDomain\fP\&.
This procedure should be provided as shown.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.dsiAccess(indexx) var: eltType
Given an index, returns the corresponding array element (as an l\-value).
.sp
The domain map implementer is allowed to restrict the type of indexx
that this method accepts.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.dsiSerialWrite(f: Writer): void
Writes out the array to the given \fBWriter\fP
(e.g. a \fBfile\fP or \fBstdout\fP) serially.
Is used to implement \fBwrite()\fP on the corresponding array.
.sp
The restrictions on this method are the same as on
\fBGlobalDomain.dsiSerialWrite()\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B iter GlobalArray.these() var: eltType
The serial iterator over the elements of this array.
.UNINDENT
.INDENT 0.0
.TP
.B iter GlobalArray.these(param tag) where tag == iterKind.leader
.UNINDENT
.INDENT 0.0
.TP
.B iter GlobalArray.these(param tag, followThis) var  where tag == iterKind.follower
.UNINDENT
.INDENT 0.0
.TP
.B iter GlobalArray.these(param tag) where tag == iterKind.standalone
The leader, follower, and standalone iterators.
.sp
These are defined in the same way as the leader and follower for
\fBGlobalDomain\fP, except the follower must yield array locations.
.sp
Given a subdomain description passed to the \fBfollowThis\fP argument,
the \fBGlobalArray\fP follower iterator must yield array locations
corresponding to the indices yielded by the \fBGlobalDomain\fP follower,
in the same order.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.dsiReallocate(d: domain): void
When this array\(aqs domain is assigned a new value, say \fBnewDom\fP,
first \fBdsiReallocate(newDom)\fP is invoked on this array.
Then, \fBdsiSetIndices(newDom)\fP is invoked on this array\(aqs \fBdom\fP\&.
.sp
Correspondingly, \fBdsiReallocate\fP needs to adjust everything
that won\(aqt be taken care of in \fBdsiSetIndices\fP\&.
.sp
NOTE: the formal\(aqs name must be exactly \fBd\fP
at present (due to compiler specifics).
.sp
NOTE: this method can/should be a no\-op if:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBGlobalArray\fP stores its array elements in Chapel array(s), and
.IP \(bu 2
the domain(s) of those array(s) are updated by \fBdsiSetIndices\fP,
.UNINDENT
.UNINDENT
.UNINDENT
.sp
as in the following simplified example:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class GlobalDomain : BaseRectangularDom {
  // required
  param rank: int;
  type idxType;
  param stridable: bool;
  const dist;
  // for example, store indices as a single Chapel domain
  var myIndices: domain(rank, idxType, stridable);
}

proc GlobalDomain.dsiSetIndices(dom: domain(rank,idxType,stridable)): void
{ myIndices = dom; }

class GlobalArray : BaseArr {
  // required
  type eltType;
  const dom;
  // for example, store elements as a single Chapel array
  var myElements: [dom.myIndices] eltType;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Given one instance of each class, say \fBgd\fP and \fBga\fP,
where \fBga.dom == gd\fP
the domain of \fBga.myElements\fP is \fBgd.myIndices\fP\&.
A call \fBgd.dsiSetIndices(newDom)\fP updates \fBgd.myIndices\fP, which, in turn,
resizes \fBga.myElements\fP, according to Chapel\(aqs array semantics.
Nothing remains to do in \fBdsiReallocate()\fP\&.
.sp
(Behind the scene, resizing of \fBga.myElements\fP is implemented by
\fBdsiReallocate\fP of the default domain map. That\(aqs the domain map
that \fBmyIndices\fP is distributed with, since \fBmyIndices\fP\(aqs type
provides no explicit domain map.)
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.dsiDisplayRepresentation(): void
A debugging method. It implements \fBdisplayRepresentation()\fP
on the corresponding Chapel array value.
.UNINDENT
.SS Naming
.sp
Once you have chosen the name for your domain map, say, MyMap,
we suggest naming the descriptor classes as follows:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
in this document
T}	T{
in your code
T}
_
T{
\fBGlobalDistribution\fP
T}	T{
\fBMyMapDist\fP
T}
_
T{
\fBGlobalDomain\fP
T}	T{
\fBMyMapDom\fP
T}
_
T{
\fBGlobalArray\fP
T}	T{
\fBMyMapArr\fP
T}
_
T{
\fBLocalDistribution\fP
T}	T{
\fBLocMyMapDist\fP
T}
_
T{
\fBLocalDomain\fP
T}	T{
\fBLocMyMapDom\fP
T}
_
T{
\fBLocalArray\fP
T}	T{
\fBLocMyMapArr\fP
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
Some domain maps in this Chapel distribution use just the domain map
name for their \fBGlobalDistribution\fP classes, e.g. Block and Cyclic.
.SS Phase 2: Additional Operations
.sp
The operations in this phase are required by DSI.
However, if a domain map is in use by a limited set of applications,
these operations do not need to be implemented up front. Instead,
each of them could be implemented later, when the need arises.
The "unresolved call" compilation errors could be used
as an indication of what procedure(s) need to be defined.
.INDENT 0.0
.TP
.B proc GlobalDistribution.dsiIndexToLocale(indexx): locale
Given an index \fBindexx\fP, returns the locale that "owns" that index,
i.e. on which the corresponding data is located.
This is used to implement \fBidxToLocale()\fP on the \fBdmap\fP wrapper.
.sp
The domain map implementer is allowed to restrict the type of \fBindexx\fP
that this method accepts.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiDim(dim: int): range(idxType, BoundedRangeType.bounded, stridable)
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiDims(): rank * range(idxType, BoundedRangeType.bounded, stridable)
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiLow
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiHigh
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiStride
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiNumIndices
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiMember(indexx)
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiIndexOrder(indexx)
These methods implement the corresponding queries
(\fBdim\fP, \fBdims\fP, \fBlow\fP, etc.)
of the domain value for which this \fBGlobalDomain\fP instance was created.
For example, \fBdsiDim(d)\fP returns the range describing the domain\(aqs
\fBd\fP\-th dimension.
.sp
\fBdsiDims()\fP and \fBdsiGetIndices()\fP have the same specification
and so may be implemented in terms of one another.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiBuildRectangularDom(param rank: int, type idxType, param stridable: bool, ranges: rank * range(idxType, BoundedRangeType.bounded, stridable))
This method is similar to \fBdsiNewRectangularDom()\fP, except it is used
in the cases where a new Chapel domain is created from an existing
Chapel domain (represented by \fIthis\fP) and the index set of the desired
domain is known (it is defined by the \fBranges\fP argument). For example,
it is invoked upon domain slicing and when applying domain operations
such as expand, exterior, interior, translate.
The \fBGlobalDistribution\fP of the result is the same as that of \fIthis\fP\&.
.sp
This method returns a new instance of
\fBGlobalDomain(rank, idxType, stridable)\fP
that will be the runtime representation of a Chapel domain whose index set
is initialized as defined by \fBranges\fP\&. Other than that, this instance must
satisfy the same constraints as the result of \fBdsiNewRectangularDom()\fP\&.
.sp
This method can be implemented as follows,
unless a more efficient implementation is desired:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
const result = dist.dsiNewRectangularDom(rank, idxType, stridable);
result.dsiSetIndices(ranges);
return result;
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.dsiSlice(sliceDef: GlobalDomain)
Returns a \fBGlobalArray\fP object representing a slice of the array
corresponding to \fIthis\fP\&. Like generally in Chapel, the array elements
in the slice must be aliases of the corresponding elements of \fIthis\fP\&.
The argument \fBsliceDef\fP defines the slice, i.e., which of the elements
of \fIthis\fP are to be included in the result.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.dsiReindex(reindexDef: GlobalDomain)
Similar to \fBdsiSlice\fP, except: The array alias represented by the
returned object is a reindexing, rather than a slice, of the array
represented by \fIthis\fP\&. The argument \fBreindexDef\fP represents the
reindexing expression. The callers of dsiReindex must ensure that
the domain of this array and \fBreindexDef\fP have the same number of
dimensions and the same number of indices along each dimension.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalArray.dsiRankChange(reindexDef: GlobalDomain, param newRank: int, param newStridable: bool, args)
Similar to \fBdsiReindex\fP, except reindexing changes the rank.
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.linksDistribution() param
.UNINDENT
.INDENT 0.0
.TP
.B proc GlobalDomain.dsiLinksDistribution()
Typically these should not be defined.
.sp
If the domains mapped using \fBGlobalDistribution\fP do NOT need to be tracked
and the \fBGlobalDistribution\fP itself does NOT need to be reference counted,
these two methods should be defined to return \fIfalse\fP;
Also in this case \fBdsiMyDist()\fP does not need to be defined.
.UNINDENT
.SS Phase 3: Privatization
.SS What is privatization?
.sp
Privatization of an object \fBX\fP means providing a local copy of \fBX\fP on
each locale. Such a copy is called the "privatized copy".
On \fBX.locale\fP, \fBX\fP itself serves as the privatized copy.
We refer to \fBX\fP as the "original object".
.sp
Privatization aims at reducing communication between locales.
When \fBX\fP needs to be accessed (by reading its fields or invoking
its methods) from another locale, its privatized copy
on the current locale is used instead.
Therefore, communication to \fBX.locale\fP is eliminated.
.SS How does privatization work with DSI?
.sp
Privatization is optional in DSI. Each of the global descriptor classes
can support privatization independently of the others. A class indicates
to the Chapel implementation whether it supports privatization via
its method \fBdsiSupportsPrivatization()\fP (see below).
.sp
Layouts (i.e. the domain maps that do not distribute domains across locales)
can potentially benefit from privatization. However, the standard
layouts do not support it.
.sp
The remainder of DSI privatization requirements must be implemented
by each global descriptor class that chooses to support privatization.
.sp
The domain map implementation must provide methods to:
.INDENT 0.0
.IP \(bu 2
create a privatized copy given the original object, and
.IP \(bu 2
update a privatized copy when some other privatized copy changes
(see "reprivatization" below).
.UNINDENT
.sp
The Chapel implementation:
.INDENT 0.0
.IP \(bu 2
invokes DSI privatization methods to create or update privatized copies, and
.IP \(bu 2
redirects original object accesses to its privatized copies.
.UNINDENT
.sp
The Chapel implementation creates privatized copies (over \fIall\fP locales)
greedily as follows (if that class supports privatization):
.INDENT 0.0
.IP \(bu 2
of a \fBGlobalDistribution\fP \- when it is wrapped in \fBnew dmap()\fP
and when that wrapper is copied;
.IP \(bu 2
of a \fBGlobalDomain\fP or \fBGlobalArray\fP \- when the corresponding
Chapel domain or array is created.
.UNINDENT
.SS What is reprivatization?
.sp
Should any privatized copy be modified, the changes need to be
propagated to all the other privatized copies.
This propagation is called reprivatization.
.sp
The domain map implementation provides methods to update a privatized copy.
The Chapel implementation invokes these methods when necessary.
.SS DSI privatization requirements
.sp
The following requirements apply individually to each global descriptor
class that chooses to support privatization.
\fBGlobal\fP denotes such a class.
.INDENT 0.0
.TP
.B proc Global.dsiSupportsPrivatization() param return true;
Returns \fItrue\fP to indicate that privatization is supported.
NOTE: do not specify the return type (due to a bug in the compiler).
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class Global ... {
  ...
  var pid = \-1;
  ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The field \fBpid\fP should be provided as shown.
It should not be accessed by the DSI implementation except
in conjunction with \fBchpl_getPrivatizedCopy()\fP as discussed later.
.INDENT 0.0
.TP
.B proc Global.dsiGetPrivatizeData()
Returns the data to be used as the argument to \fBdsiPrivatize()\fP\&.
It can be a tuple of values or any other type, at the implementor\(aqs
discretion. See \fBdsiPrivatize()\fP for explanation.
.UNINDENT
.INDENT 0.0
.TP
.B proc Global.dsiPrivatize(privatizeData): Global
Returns a privatized copy of \fIthis\fP\&. The Chapel implementation
invokes this method as follows:
.INDENT 7.0
.IP \(bu 2
on the locale where the privatized copy is to be located,
.IP \(bu 2
\fIthis\fP is either the original object or its privatized copy
created by \fBdsiPrivatize\fP on some other locale,
.IP \(bu 2
\fBprivatizeData\fP is the result of invoking dsiGetPrivatizeData()
on the original object.
.UNINDENT
.sp
Typically \fBdsiPrivatize()\fP will need to copy and/or privatize
some information from the original object into the privatized copy
being created. This information could be obtained by querying \fIthis\fP
directly. Alternatively, it could be passed from the original object
via \fBprivatizeData\fP\&. This approach could allow the needed information
to be bundled into the original active message, rather than requiring
additional communications when accessing \fIthis\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc Global.dsiGetReprivatizeData()
Similar do \fBdsiGetPrivatizeData()\fP, except the result is used
as the argument to \fBdsiReprivatize()\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc Global.dsiReprivatize(other: Global, reprivatizeData): void
Updates a privatized copy.
.sp
\fIthis\fP is the object to be updated as part of reprivatization.
.sp
\fBother\fP is either the object whose modification originally
necessitated reprivatization or one of the privatized copies
that have already been updated for that modification
by \fBdsiReprivatize()\fP\&.
.sp
\fBreprivatizeData\fP is the result of invoking dsiGetReprivatizeData()
on the originally\-modified object.
.sp
Q: What modifications must \fBdsiReprivatize()\fP reflect?
.sp
A: Any changes that the domain map implementation may perform on
an instance of \fBGlobal\fP (or its privatized copy) after that instance
has been created and privatized.
.sp
For example, \fBGlobalDomain.dsiReprivatize()\fP must reflect any changes
that \fBGlobalDomain.dsiSetIndices()\fP may perform.
.UNINDENT
.SS Tip: testing privatization
.sp
In addition to the usual correctness testing, it may be useful to check
whether array access is purely local, i.e., results in no communication.
This can be done using \fIlocal\fP statements.
.sp
(A \fIlocal\fP statement performs runtime checks that report an error
whenever any communication occurs within the its body.)
.sp
Here is a simple example:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// declare an array that uses the domain map to be tested
var A: ...;

// initialize it
A = value1;

forall loc in (locales that A is distributed over) do
  // run the check on each locale
  on loc {
    // value2 to be different from value1
    var valTemp = value2;
    const idxTemp = (an index (tuple) that is mapped to the locale \(aqloc\(aq);
    local {
      // Access the array.
      // This statement succeeds if there is no communication.
      valTemp = A[idxTemp];
    }
    // reference the read value
    assert(valTemp == value1);
  }
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Tip: privatized copies should reference privatized copies
.sp
The global descriptor classes are required to reference each other
(e.g. \fBGlobalArray.dom\fP references \fBGlobalDomain\fP; \fBGlobalDomain.dist\fP
references \fBGlobalDistribution\fP). Therefore, if it is desired to
eliminate communication completely upon array references,
all the three global descriptor classes may have to be privatized.
When one descriptor object references another, a privatized copy of
the former needs to reference a privatized copy of the latter.
.sp
To obtain a privatized copy of an object, e.g. for use within
\fBdsiPrivatize()\fP, use the following procedure:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc chpl_getPrivatizedCopy(type objectType, objectPid:int): objectType
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Notes:
.INDENT 0.0
.IP \(bu 2
The first argument is type of the object being privatized.
.IP \(bu 2
The second argument is the original object\(aqs \fBpid\fP field.
.IP \(bu 2
The procedure returns a privatized copy of the original object.
.IP \(bu 2
The procedure can be applied only to objects that have already
been privatized.
.INDENT 2.0
.IP \(bu 2
A \fBGlobalArray\fP is privatized after its \fBGlobalDomain\fP, which is
privatized after its \fBGlobalDistribution\fP\&.
.IP \(bu 2
The \fBpid\fP field is set to a different value than \fB\-1\fP
when an object is privatized.
.UNINDENT
.UNINDENT
.sp
Here is an example of using it for privatizing \fBGlobalDomain\fP,
assuming that \fBGlobalDistribution\fP also supports privatization:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc GlobalDomain.dsiGetPrivatizeData() {
  // include the desired \(aqpid\(aq
  return (this.dist.pid, ... other data as needed ...);
}

proc GlobalDomain.dsiPrivatize(privatizeData) {
  // extract the \(aqpid\(aq provided above
  const distPid = privatizeData(1);
  // obtain the privatized copy of the GlobalDistribution object
  const privatizedDMap = chpl_getPrivatizedCopy(this.dist.type, distPid);

  return new GlobalDomain(dist = privatizedDMap,
                          ... other fields as needed ...)
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Tip: "privatize" the domains and arrays used in the implementation
.sp
If a global descriptor class to be privatized uses domains and arrays,
those need to be "privatized", too, to reduce communication. In the
case of domains and arrays mapped using the default layout,
their "privatization" is achieved by copying.
.sp
Careful consideration is needed to eliminate all communication.
For example:
.INDENT 0.0
.IP \(bu 2
Copying an array preserves the source\(aqs domain \- unless
the destination\(aqs domain is declared explicitly.
.IP \(bu 2
Copying a domain preserves the source\(aqs domain map \- unless
the destination\(aqs type is declared explicitly.
.IP \(bu 2
If an array\(aqs domain or a domain\(aqs domain map is declared explicitly,
ensure that privatized copies of those are used.
.IP \(bu 2
There is no need to privatize the default layout.
Specifically, copying a domain declared without an explicit domain map
is sufficient to privatize that domain.
.IP \(bu 2
The same considerations are valid for reprivatization.
.UNINDENT
.sp
Here is an example of "privatizing" domains/arrays within \fBGlobalDomain\fP\&.
The key insight here is that \fBauxArrayG\fP\(aqs domain needs to be "privatized".
Cf. the domains of \fBauxArrayED1\fP and \fBauxArrayED2\fP are created
implicitly for each \fBGlobalDomain\fP object and so will be local in any case.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class GlobalDomain ... {
  ...

  // this field is generic
  var auxArrayG;

  // domain is specified explicitly
  var auxArrayED1: [1..10] int;

  // similar
  var auxDomain: domain(1);
  var auxArrayED2: [auxDomain] int;
}

proc GlobalDomain.dsiGetPrivatizeData() {
  return (this.dist.pid, auxArrayG,
          auxArrayED1, auxDomain, auxArrayED2, ...);
}

proc GlobalDomain.dsiPrivatize(privatizeData) {

  // To privatize auxArrayG, we must "privatize" its domain first.
  // No need to declare privDom\(aqs type if auxArrayG uses the default layout.
  var privDom = privatizeData(2).domain;
  var privArr: [privDom] privatizeData(2).eltType = privatizeData(2);

  // If the following were used, privArr.domain would be the same
  // as privatizeData(2).domain, i.e., it would not be privatized.
  //var privArr = privatizeData(2);

  return new GlobalDomain(..., auxArrayG = privArr,
    // the other fields can be simply copied
    auxArrayED1 = privatizeData(3),
    auxDomain   = privatizeData(4),
    auxArrayED2 = privatizeData(5));

}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS C Interoperability
.sp
This README describes support in the Chapel compiler for referring to C
code within Chapel using a keyword named \(aqextern\(aq. These features are
still in the process of being improved.
.sp
External C functions, variables, and types can be referred to within a
Chapel program. The section \fI\%Working with C\fP below describes the
basic ideas of how Chapel and C interoperate. There are two supported
strategies for providing the Chapel compiler with information about the
C declarations that should be usable from Chapel code.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
The explicit strategy is to use extern declarations, as described in
the section \fI\%Support for Extern Declarations\fP below.  When using the
explicit strategy, one creates a Chapel declarations for each C
function, variable, or type that one wants to use from Chapel code.
This explicit strategy allows for a great deal of manual control over
how the Chapel compiler views a C function or type. This strategy is
typically used within the Chapel standard modules for portability
reasons.
.IP 2. 3
The extern block feature provides an implicit strategy, as described in
the section \fI\%Support for Extern Blocks\fP below. This strategy makes
use of the \fIclang\fP parser and so requires a Chapel compiler built with
LLVM support. The main advantage of the extern block strategy is that
it is not necessary to provide Chapel declarations for every desired C
function or type. Instead, such declarations are added automatically.
In addition, the extern block can contain C function definitions in
addition to declarations and so provides a way in which programs that
need to be written in both C and Chapel can be implemented in a single
source file.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Working with C
.sp
Whether using extern declarations or extern blocks, it is important
to understand the basic interoperability support provided by the
Chapel compiler.
.sp
The general approach is as follows:
.INDENT 0.0
.IP 1. 3
Programmers inform the Chapel compiler about C concepts that they want
to refer to in their Chapel code with \fI\%explicit extern
declarations\fP or by \fI\%creating
extern declarations with extern blocks\fP\&.
.IP 2. 3
Programmers use the extern C concepts that have been described. That
might include declaring variables, calling functions, or operating on
already declared global variables. See \fI\%Using Extern Declarations\fP\&.
.IP 3. 3
Library and header dependencies are described on the Chapel compiler\(aqs
command line or with \fBrequire\fP statements as described in the section
\fI\%Expressing Dependencies\fP\&.
.UNINDENT
.sp
The next section describes the basic information about how the Chapel
compiler views common C types.
.SS Standard C Types
.sp
In declaring extern C procedures and variables, one of the
requirements is to accurately describe their types within the Chapel
\(aqextern\(aq declarations.  Because the C specification allows compilers
to determine how many bits are used in the representation of various
types, one must be careful to avoid false assumptions, such as that a
C \(aqint\(aq can always be represented via a Chapel \(aqint\(aq or \(aqint(32)\(aq.
.sp
To help with mapping types between C and Chapel, Chapel installations
contain a standard module named \fBSysCTypes\fP (located under
\fB$CHPL_HOME/modules/standard/gen/...\fP).  This module defines a number of
type aliases that accurately describe C types using their Chapel
equivalents.  Most of these are prefixed by \fBc_\fP to distinguish them
from Chapel type names that may have different meanings.
.sp
The Chapel names for C types are:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
c_int
c_uint
c_long
c_ulong
c_longlong
c_ulonglong
c_char
c_schar
c_uchar
c_short
c_ushort
ssize_t
size_t
c_void_ptr
c_ptr(T)
c_string
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For consistency, the following type aliases are also provided even
though their sizes can\(aqt vary in C (thereby permitting the equivalent
Chapel types to always be usable):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
c_float  // (a real(32) in Chapel)
c_double // (a real(64) in Chapel)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
c_void_ptr, c_string, and c_ptr(T) are described in the next section.
.SS Pointer and String Types
.sp
Chapel supports 3 C pointer types: c_void_ptr, c_string, and c_ptr(T).
These types are the same as C types:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
c_void_ptr is void*
c_ptr(T) is T*
c_string is const char*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that in some cases, a ref argument intent may be used in place of
c_void_ptr or c_ptr(T).
.sp
All three of these pointer types may only point to local memory. The intent is
that they will be used to interoperate with C libraries that run within a
single locale. In addition, these pointer types must be treated carefully as it
is possible to create the same kinds of problems as in C \- in particular, it is
necessary know that one of these types points to valid memory before it is
used.  As in C, these pointers could point to a stack variable that is no
longer valid, or to memory that has been freed. The Chapel language makes no
effort to extend a variable\(aqs lifetime if it is converted in some manner to a C
pointer.
.SS c_void_ptr
.sp
The c_void_ptr type is provided as an opaque C pointer. Since the type is
unknown, there is no way to dereference this pointer. In addition, it is not
possible to construct a c_void_ptr directly in Chapel. Normally, a C function
will return the void pointer, which will be passed to other C functions.
.SS c_ptr(T)
.sp
The c_ptr(T) type is a generic type representing a C pointer to an arbitrary
type T. This pointer should normally only point to local memory \- since no
communication will be generated when it is dereferenced.  Of course, the
pointed\-to type T should be one that is supported in C interoperability if the
c_ptr(T) is used for C interoperability.
.SS ref intents
.sp
Note that when declaring extern procedures that use function arguments that are
passed by pointer in C, it is recommended to use the ref argument intent
instead of c_ptr(T). Using the ref intent allows the arguments to the extern
proc to be passed directly instead of needing to be converted to a C pointer
first. For example, both the functions byRef and byPtr below have the same C
prototype, but they must be used differently in Chapel:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// both of these correspond to void fn(int* x)
extern proc byRef(ref x:c_int);
extern proc byPtr(x:c_ptr(c_int));

var x:c_int = 7;
byRef(x); // ref argument intent allows the variable to be passed directly
byPtr(c_ptrTo(x)); // c_ptr argument must be constructed explicitly
.ft P
.fi
.UNINDENT
.UNINDENT
.SS c_string
.sp
The c_string type maps to a constant C string (that is, const char*)
that is intended for use locally. A c_string can be obtained from a
Chapel string using the method \fBc_str\fP\&. A Chapel string can be
constructed from a C string using the cast operator. Note however that
because c_string is a local\-only type, the .c_str() method can only be
called on Chapel strings that are stored on the same locale; calling
.c_str() on a non\-local string will result in a runtime error.
.SS Support for Extern Declarations
.SS Declaring External C Types
.sp
You can refer to other external C types using \(aqextern\(aq plus the normal
type alias keyword.  By leaving off any sort of type definition, you
are telling the Chapel compiler that it can\(aqt assume it knows anything
about how the type is represented or how to operate on it (though the
compiler may make copies of values of the type using assignment and/or
memcpy()).
.sp
Effectively, such a declaration defines a new primitive type in
Chapel.  For example, the following declaration says that there is an
external type named \(aqfoo\(aq:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern type foo;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This permits you to declare variables of type \(aqfoo\(aq and to declare
external functions that accept or return arguments of type \(aqfoo\(aq.
Because Chapel knows nothing about the type \(aqfoo\(aq such variables
cannot be manipulated within Chapel apart from passing them between
routines.  The type symbol \(aqfoo\(aq must be declared in a C header file
provided on Chapel\(aqs compiler command\-line.
.sp
If an external C type can be described in Chapel, that definition can
be given in Chapel, which permits the compiler to deal with the type
directly, as it would any other Chapel type alias.  For example, if
the external type \(aqfoo\(aq was a 64\-bit integer, you could describe it in
Chapel using:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern type foo = int(64);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Static, fixed\-size C array types can be described within Chapel using
its homogeneous tuple type.  For example, the following C typedef:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
typedef double vec[3];
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
could be described in Chapel using:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern type vec = 3*real(64);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To refer to more complex C types like external structs or pointers to
structs, see the section on \fI\%Declaring External C Structs\fP below.
.SS Declaring External C Variables and Constants
.sp
A C variable or constant can be referred to within Chapel by prefixing
its declaration with the extern keyword.  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern var bar: foo;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
would tell the Chapel compiler about an external C variable named
\(aqbar\(aq of type \(aqfoo\(aq.  Similarly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern const baz: int(32);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
would refer to an external 32\-bit integer constant named \(aqbaz\(aq in the
C code.  In practice, external consts can be used to provide Chapel
definitions for #defines and enum symbols in addition to traditional C
constants.
.sp
Note that it is not currently possible to explicitly declare an \fIextern param\fP\&.
In the future, it might be possible to use an \fI\%extern block\fP to import #define constants that are known at
compile time as param constants within Chapel.
.SS Declaring External C Functions
.sp
To make a call to an external C function, you will need to prototype
the routine in your Chapel code using the \fBextern\fP keyword.  For
example, for a C function foo() that takes no arguments and returns
nothing, the prototype would appear as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc foo();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
C functions that return values which you wish to refer to within your
Chapel program must have those return types declared. Note that the Chapel
compiler will not infer the return type as it does for Chapel functions.
To make the function above return a C "double", it would be declared:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc foo(): real;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Similarly, external functions that expect arguments must declare those
arguments in Chapel.
.sp
Types of function arguments may be omitted, in which case the types
will be inferred based on the Chapel callsite.  For example, the
following Chapel code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc foo(x: int, y): real;

var a, b: int;

foo(a, b);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Would imply that external function foo() is able to take two 32\-bit
integer values and that it returns a 64\-bit real (\(aqdouble\(aq in C).
External function declarations with omitted type arguments can be used
to support calls to external C macros or varargs functions that accept
multiple argument signatures.
.sp
Default arguments can be declared for external function arguments, in
which case the Chapel compiler will supply the default argument value
if it is omitted at the callsite.  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc foo(x: int, y = 1.2): real;

foo(0);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Would cause external function foo() to be called with the arguments 0
and 1.2.
.sp
C varargs functions can be declared using Chapel\(aqs varargs ("...")
syntax.  For example, the following declaration prototypes C\(aqs printf
function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc printf(fmt: c_string, vals...?numvals): int;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that it can also be prototyped more trivially/less accurately
as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc printf(args...): int;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which relies on the callsite to pass in reasonable arguments
(otherwise, the C compilation step will likely fail).
.sp
External C functions or macros that accept type arguments can also be
prototyped in Chapel by declaring the argument as a type.  For
example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern foo(type t);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Calling such a routine with a Chapel type will cause the type
identifier (e.g., \(aqint\(aq) to be passed to the routine.  In practice,
this will typically only be useful if the external function is a macro
or built\-in (like sizeof()) that can handle type identifiers.
.sp
Extern functions with array arguments are handled as a special case within the
compiler. As an example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc foo(x: [] int, n: int);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This procedure definition will match up to a C function with the prototype of
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
void foo(int64_t* x, int64_t n);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Chapel compiler will then rewrite any calls to \fIfoo\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
foo(x, 10); // \-> foo(c_ptrTo(x), 10);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that this same technique won\(aqt work for distributed rectangular arrays,
nor for associative, sparse, or opaque arrays because their data isn\(aqt
necessarily stored using a representation that translates trivially to a C
array.
.sp
It is possible to provide the Chapel compiler with a different
name for the function than the name available to other Chapel code.
For example, if there is a C function called \fBfoo_in_c\fP returning an int,
we might use the following declaration to provide that function to
other Chapel code with the name \fBfoo_in_chapel\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern "foo_in_c" proc foo_in_chapel(): c_int;
writeln(foo_in_chapel()); // will generate a call to foo_in_c
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Frequently Asked Questions About Declaring External Routines
.sp
How do I pass a Chapel variable to an external routine that expects
a pointer?
.sp
Today, the preferred way to do this is to declare the argument as
having \(aqref\(aq intent.  This should cause the Chapel compiler to pass
a pointer to the argument.  For example, given a C function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
void foo(double* x);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This could be called in Chapel using:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc foo(ref x: real);

var myVal: real = 1.2;

foo(myVal);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Declaring External C Structs
.sp
External C struct types can be referred to within Chapel by prefixing
a Chapel record definition with the extern keyword.  For example,
given an external C structure defined in foo.h called fltdbl:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct _fltdbl {
  float x;
  double y;
} fltdbl;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This type could be referred to within a Chapel program using:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern record fltdbl {
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Within the Chapel declaration, some or all of the fields from the C
structure may be specified.  Any fields that are not specified (or
that cannot be specified because there is no equivalent Chapel type)
cannot be referenced within the Chapel code.  The order of these
fields need not match the order they were specified within the C code.
As an example, the following declaration would permit access to both
fields x and y within variables of type fltdbl:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern record fltdbl {
  var x: real(32);
  var y: real(64);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
as would the following declaration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern record fltdbl {
  var y: real(64);
  var x: real(32);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, the external declaration could only mention one of the
fields.  For example, the following declaration would permit field y
to be accessed by a Chapel program, but not field x (though both would
still be stored in any variable of type \(aqfltdbl\(aq).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern record fltdbl {
  var y: real(64);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, the external declaration can avoid mentioning any
fields, which would permit a variable of that struct type to be passed
between Chapel and C routines, but without permitting its fields to be
accessed within the Chapel program:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern record fltdbl {
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A C header file containing the struct\(aqs definition in C must be
specified on the chpl compiler command line or in a \fBrequire\fP statement
as described in \fI\%Expressing Dependencies\fP\&.
.sp
To work with a C structure that is not typedef\(aqd, just name the
C type name after the \fBextern\fP keyword. In the example below,
the \fBstruct stat\fP type does not have a corresponding typedef
in C. Therefore, we inform the Chapel compiler that the C name
for the type is \fBstruct stat\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern "struct stat" record chpl_stat_type {
  var st_size: off_t;
}

proc getFileSize(path:c_string) : int {
  extern proc stat(x: c_string, ref buf:chpl_stat_type): c_int;
  var buf: chpl_stat_type;

  if (chpl_stat_function(path, buf) == 0) {
    return buf.st_size;
  }
  return \-1;
}

writeln(getFileSize("stat\-example.chpl"));
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that external record types only support assignment from records
of matching type.  In particular, Chapel\(aqs normal mechanisms that
perform record assignment by field name are not used for external
records.  This restriction could be lifted in the future if considered
useful to users.
.SS Referring to External C Pointer\-to\-Structs ("extern classes")
.sp
You can also refer to an external C pointer\-to\-struct types by
considering it to be an \(aqextern class\(aq in Chapel.  The declaration
style is similar to that described above, it simply has different
implications on the underlying C types.
.sp
As an example, given the declaration:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern class D {
  var x: real;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The requirements on the corresponding C code are:
.INDENT 0.0
.IP 1. 3
There must be a struct type that is typedef\(aqd to have the name _D.
.IP 2. 3
A pointer\-to\-_D type must be typedef\(aqd to have the name D.
.IP 3. 3
The _D struct type must contain a field named \(aqx\(aq of type double.
Like external records/structs, it may also contain other fields
that will simply be ignored by the Chapel compiler.
.UNINDENT
.sp
Thus, the following C typedef would fulfill the external Chapel class
declaration shown above:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct __D {
  double x;
  int y;
} _D, *D;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where the Chapel compiler would not know about the \(aqy\(aq field and
therefore could not refer to it or manipulate it.
.SS Opaque Types
.sp
NOTE: This support may eventually be deprecated as other \(aqextern\(aq
features become increasingly flexible and robust.
.sp
You can refer to other external pointer\-based C types that cannot be
described in Chapel using the "opaque" keyword.  As the name implies,
these types are opaque as far as Chapel is concerned and cannot be
used for operations other than argument passing and assignment
(to/from other similarly opaque types).
.sp
For example, Chapel could be used to call an external C function that
returns a pointer to a structure (that we can\(aqt or won\(aqt describe as
an external class using the previous mechanism) as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc returnStructPtr(): opaque;

var structPtr: opaque = returnStructPtr();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However, because structPtr\(aqs type is opaque, it cannot be used for
much apart from assigning it to other opaque variables of matching
underlying type, or passing it back to an external C routine that
expects a pointer\-to\-struct of that type:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc operateOnStructPtr(ptr: opaque);

var copyOfStructPtr = structPtr;

operateOnStructPtr(structPtr);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Support for Extern Blocks
.sp
[Note: The features in this section rely on Chapel to being built with
llvm/clang enabled.  To do so, set environment variable CHPL_LLVM to
\(aqllvm\(aq and rebuild your Chapel installation. See readme\-llvm\&.].
.sp
C code and header files can be included directly within Chapel source
code using an \fBextern block\fP as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern {
  #include "my_C_API.h"
  static int myCInt = 7;
  ....
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Such \(aqextern { }\(aq block statements add the top\-level C statements to
the enclosing Chapel module.  This is similar to what one might do
manually using the extern declarations (as described above), but can
save a lot of labor for a large API.  Moreover, using an inline extern
block permits you to write C declarations directly within Chapel
without having to create distinct C files.
.sp
If you don\(aqt want to have a lot of C symbols cluttering up a module\(aqs
namespace, it\(aqs easy to put the C code into its own Chapel module:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
module C {
  extern {
    static int foo(int x) { return x + 1; }
    ... c code here...
  }
}

writeln(C.foo(3));
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This feature strives to support C global variables, functions, structures,
typedefs, enums, and some #defines. Structures always generate a Chapel record,
and pointers to a structure are represented with c_ptr(struct type). Also,
pointer arguments to functions are always represented with c_ptr or c_string
instead of the ref intent.
.sp
Note that functions or variables declared within an extern block should either
be declared in a .h file that is #included or they should be be declared
\fBstatic\fP (otherwise you might get a warning during C compilation).
.sp
Also note that a \fBstatic inline\fP function can be inlined into Chapel
code that calls it. Thus, by using \fBstatic inline\fP in an \fBextern block\fP,
it is possible to hand\-tune a computational kernel by writing some of
it in inline assembly.
.SS #defines
.sp
The extern block functionality allows simple #defines to be used from Chapel
code. Simple defines take no arguments and define an integer value or use
another #define. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern {
 #define NEG_ONE (\-1)
 #define MY_NUMBER (NEG_ONE)
}
writeln(MY_NUMBER);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
However, it is easy to create #defines that are not supported because the
Chapel compiler is unable to determine their expression type. In particular,
any #define taking arguments is not currently supported. For example, the
ADD definition below has a resulting expression type that cannot be determined
by the Chapel compiler:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern {
  #define ADD(x,y) ((x)+(y)) // NOT SUPPORTED
}
var x = ADD(1,2); // ERROR \- ADD not defined in Chapel.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the library you are using depends on these types, the current solution
is to create inline functions to call the define with the appropriate argument
types; for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern {
  #define ADD(x,y) ((x)+(y))
  static inline int ADD_int_int(int x, int y) { return ADD(x,y); }
}
var sum = ADD_int_int(1,2);
writeln(sum);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Pointer Types
.sp
See the section \fI\%Pointer and String Types\fP above for background on
how the Chapel programs can work with C pointer types. Any pointer type used in
an extern block will be made visible to the Chapel program as c_ptr(T) or
c_string (for const char* types).
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern {
  static void setItToOne(int* x) { *x = 1; }
  // will translate automatically into
  //  extern proc setItToOne(x:c_ptr(c_int));

  // The Chapel compiler can\(aqt know if X is used as an array,
  // if the argument will come from a Chapel variable, and in more general
  // cases, the best way to handle multiple levels of pointers. For example:
  static void setSpace(int** x) {
    static int space[10];
    *x = space;
  }
  // translates automatically into
  //  extern proc returnSpace( x:c_ptr(c_ptr(c_int)) );

  static void setString(const char** x) { *x = "My String"; }
}
var x:c_int;
setItToOne(c_ptrTo(x));

var space:c_ptr(c_int);
setSpace(c_ptrTo(space));

var str:c_string;
setString(c_ptrTo(str));
writeln(toString(str));
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As you can see in this example, using the extern block might result in
more calls to c_ptrTo() when using the generated extern declarations,
because the compiler cannot automatically distinguish between several
common cases (passing an array vs. passing in an argument by reference).
.SS Example
.sp
Here\(aqs a more complete example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
module MyCModule {
  extern {
    static int foo(int b) { return b + 1; }
  }
}

writeln("Hello");
writeln(MyCModule.foo(7));
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This prints out
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Hello
8
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which demonstrates full integration between Chapel and the C function
it calls.
.SS Using Extern Declarations
.sp
Extern declarations can be used just like normal Chapel types, variables,
or functions. Using these extern declarations from Chapel code requires
some care.
.SS Parallel Safety
.sp
If external routines are to be called from Chapel within parallel
execution contexts, they should be parallel\-safe.  As with internal Chapel
routines, it is also the responsibility of the Chapel programmer to call
external routines in a manner that preserves the integrity of objects
accessible to those routines.  Simply put, objects shared across Chapel
tasks must be kept parallel\-safe within Chapel.
.SS Multiple Locales
.sp
Since the extern C code does not generally have any support for multiple
locales, it is important to take care when using this code from multiple
locales. Here are some things to be aware of:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
extern global variables will refer to a local version of that variable
on each locale. These variables might become different if they
are changed differently on different locales.
.IP \(bu 2
c_ptr is always generated as a narrow pointer type (in other words, it
does not encode the locale storing the pointed\-to value \- just an
address). That means that passing a c_ptr from one locale to another
and then using it on the second locale will probably result in a core
dump.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Initialization
.sp
Chapel variables of extern type are not generally initialized
automatically. Be sure to manually initialize Chapel variables of extern
type.
.sp
In the future, we would like to support automatic zero initialization
of such variables and a way to provide their default initializer.
.SS Working with c_ptr
.sp
A c_ptr type can be constructed from a Chapel variable using the c_ptrTo()
function; for example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var i:c_int;
var i_ptr = c_ptrTo(i); // now i_ptr has type c_ptr(c_int) == int* in C
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since a C pointer might refer to a single variable or an array, the c_ptr type
supports 0\-based array indexing and dereferencing. In addition, it is possible
to allocate and free space for one or more elements and return the result as a
c_ptr. See the following example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var cArray = c_calloc(c_int, 10);
for i in 0..#10 {
 cArray[i] = i:c_int;
}
// c_ptr.deref() always refers to the first element.
cArray.deref() = 17;
for i in 0..#10 {
 writeln(cArray[i]);
}
c_free(cArray);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Variables of type c_ptr can be compared against or set to nil.
.SS Working with strings
.sp
If you need to call a C function and provide a Chapel string, you may need to
convert the Chapel string to a C string first.  Chapel string literals will
automatically convert to C strings.  A Chapel string variable can be converted
using the \fBc_str\fP method.
.sp
myprint.h:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
void myprint(const char* str);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
myprint.c:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
void myprint(const char* str) {
  printf("%s\en", str);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
myprint.chpl:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extern proc myprint(str:c_string);

// string literal is automatically converted to a c_string
myprint("hello");

// a string variable must be converted with .c_str()
var s = "goodbye";
myprint(s.c_str());
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Expressing Dependencies
.sp
Any required C header files, source code files, object files, or
library files must be provided to the Chapel compiler by one of
two mechanisms.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
They can be listed at compile\-time on the Chapel command line For
example, if an external function foo() was defined in foo.h and foo.c,
it could be added to the compilation using any of these commands:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
chpl foo.h foo.c myProgram.chpl
chpl foo.h foo.o myProgram.chpl #if foo.c had already been compiled)
chpl foo.h \-lfoo myProgram.chpl #if foo.c had been archived in libfoo.a)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that you can use \-I and \-L arguments for the Chapel compiler
to specify include or library paths as with a C compiler.
.IP 2. 3
Alternatively, the required C resources can be listed within the
Chapel file using the \fIrequire\fP statement. For example:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
require "foo.h", "foo.c";
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This has an effect similar to adding foo.h and foo.c to the
command line. You might need to specify \-I and \-L arguments
to indicate to the directories storing any headers or library
files.
.sp
Similarly, the version below uses the require statement to indicate
that this module depends on libfoo.a (and has a similar effect as if
\fB\-lfoo\fP were added to the command line).
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
require "foo.h", "\-lfoo";
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Either approach has the following results:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
During Chapel\(aqs C code generation stage, any header files listed on the
compiler\(aqs command line or in a require statement will be #include\(aqd by
the generated code in order to ensure that the appropriate prototypes
are found before making any references to the external symbols.
.IP \(bu 2
During Chapel\(aqs C compilation stage, any C files on the command line or
in a require statement will be compiled using the same flags as the
Chapel\-generated C files (use \-\-print\-commands to see these compile
commands).
.IP \(bu 2
During Chapel\(aqs link step, any .o and .a files listed on the compiler\(aqs
command\-line or in require statements will be included in the final
executable.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Future Directions
.sp
We intend to continue improving these capabilities to provide richer
and richer support for external types and functions over time.  If you
have specific requests for improvement, please let us know at:
\fI\%chapel_info@cray.com\fP\&.
.SS First\-class Functions in Chapel
.sp
This README describes some initial support that we have added to the
compiler for first\-class functions in Chapel.  This mechanism should
be considered a stopgap technology until we have developed and
implemented a more robust story, which is why it\(aqs being described in
this README rather than the language specification.
.SS Manipulating first\-class functions
.sp
Functions defined with parentheses may be captured as values by
referring to them by name without parentheses.  Once captured, these
values may be passed around as other value types.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc myfunc(x:int) { return x + 1; }
var f = myfunc;
writeln(f(3));  // outputs: 4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To be captured, a function must not be any of the following:
.INDENT 0.0
.IP \(bu 2
A generic function (all captured functions must be fully\-qualified
with no generic arguments)
.IP \(bu 2
A function with special return types (type, param)
.IP \(bu 2
An iterator
.IP \(bu 2
The method of an object
.IP \(bu 2
An operator
.IP \(bu 2
An overloaded function
.UNINDENT
.sp
Rationale. Generic functions would require manipulating generic,
uninstantiated types, which is currently not available in Chapel.
Functions with compile\-time return types like type and param would
require the ability to have param classes, to fit with the current
implementation. Param classes are not currently part of Chapel.
Iterators would require a new type of capture, one that works
similarly to the current implementation but respects the yielding that
occurs inside an iterator. Method capture requires the currying of
the object as the first argument to the first\-class function.
Operators and overloaded functions require a type\-based multiple
dispatch mechanism.
.SS Lambda functions
.sp
Lambda functions are anonymous first\-class function objects. In other
words, they are expressions rather than formally\-defined named
functions. They are available with the following syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
lambda\-declaration\-expression:
  lambda argument\-list return\-type_opt function\-body
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where \fBlambda\fP is a Chapel keyword and \fBreturn\-type_opt\fP is an optional
return\-type.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var f = lambda(x:int, y:int) { return x + y; };
writeln(f(1,2));  // outputs: 3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lambdas can also "capture" variables that are defined outside of the
lambda by referring to them in the body of the lambda. These form a
"closure", a combination of a function and an associated execution
environment.  This closure captures the variables in such a way that
modifying them modifies the original variables (this is sometimes
called "capturing the variables by reference").  Currently a lambda
that captures variables can be used only while the activation records
of the functions that define these variables, if any, still exist
on the stack, i.e. while these functions are still executing.
.sp
Example. For example the following is acceptable:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc myfunc() {
  var x = 3;
  var f = lambda() { x = 4; };
  f();
  return x;
}

writeln(myfunc());  // outputs: 4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
whereas having \fBmyfunc()\fP return its \fBf\fP variable is not supported.
.SS Function type signatures
.sp
The types of first\-class functions can be obtained by using
the \(aqfunc\(aq type functions that are provided as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// no arguments, void return type (returns no value)
proc func() type

// no arguments, the return type is \(aqrettype\(aq
proc func(type rettype) type

// argument types are \(aqargtypes\(aq
proc func(type argtypes...?n, type rettype) type
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var f : func(void);  // A function with no arguments, no return value
var f1: func();      // A shortcut for the above
var g : func(int);   // A function with no arguments, returning int
var h : func(bool, int); // A function with one bool argument, returning int
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Future Directions
.sp
Over time, we will be improving the support for first\-class functions
and their syntax.  If you have specific feature requests or
suggestions, please let us know at: \fI\%chapel_info@cray.com\fP\&.
.SS Exporting Chapel as a Library
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This page discusses the implementation of libraries, which are still
under development.  The idea is to allow components to be developed in
Chapel and linked with other programs and languages.  It is currently fragile
and difficult to work with.
.UNINDENT
.UNINDENT
.sp
Normally, Chapel assumes that you are building a main program and produces a
main routine whether one is explicitly coded or not.  When the \fB\-\-library\fP
flag is provided on the command line, it tells the Chapel compiler to produce a
library instead.  The user can further specify (through the \fB\-\-static\fP
and \fB\-\-dynamic\fP flags) which type of library to produce.  If
neither \fB\-\-static\fP nor \fB\-\-dynamic\fP is specified, a platform\-dependent
default library type is produced.
.sp
Some platforms support linking against both static and dynamic versions of
the same library.  On those platforms, the \fB\-\-static\fP or \fB\-\-dynamic\fP
flag can be used to select which type of library (and thus which kind of
linking) is performed by default.  Library files which are named explicitly on
the \fBchpl\fP command line take precedence over any found through object
library paths (\fB\-L\fP).  Where there is a conflict, the last library
specified takes precedence.
.sp
When creating a library file from Chapel code, only those symbols with
\fBexport\fP attached to them will be available from outside the library.  For
example, if one defines a Chapel file \fBfoo.chpl\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// This function will be available to the library user
export proc bar(): int {
  // Does something
  ...
}

// As will this one
export proc baz(int x) {
  // Does something different
  ...
}

// but this function will not be
proc gloop() {
  // Does something else
  ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When using a Chapel library file in C code, a fairly exact incantation is
required.  First, a header file must be created for the library.  This does not
happen through use of the Chapel \fB\-\-library\fP flag during compilation!  If
during compilation of the library the \fB\-\-savec <dir>\fP flag is also used, the C
definitions for the exported functions should be visible in a C file under
\fIdir\fP of the same name as the library Chapel file.  A declaration version of
these definitions should go into a \fB\&.h\fP file.  For instance, if one compiled
\fBfoo.chpl\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-\-library \-\-savec cDir \-\-static \-o libfoo foo.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
then under \fBcDir/foo.c\fP one might see something resembling:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
int64_t bar(void) {
  ...
}

void baz(int64_t x) {
  ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
from which one would create a \fB\&.h\fP file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
int64_t bar(void);
void baz(int64_t x);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It may be necessary to \fB#include\fP some Chapel headers, such as
\fBchpl\-string.h\fP, depending on the types used in your Chapel library.
.sp
Next, if compiling dynamically, update the \fB$LD_LIBRARY_PATH\fP environment
variable to include the directory where the new library file lives and the
directory where the Chapel build lives.  The latter can be found by looking at
the output of a \fB$CHPL_HOME/util/printchplenv\fP call and finding the
appropriate directory under \fB$CHPL_HOME/lib\fP; the directory name can be found
by running \fB$CHPL_HOME/util/printchplenv \-\-runtime\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Replace $PWD with the appropriate path to your library file if it isn\(aqt
# in the current directory
# Replace libDir with the directory we just found.
export LD_LIBRARY_PATH=$PWD:$CHPL_HOME/lib/\(ga$CHPL_HOME/util/printchplenv \-\-runtime\(ga:$LD_LIBRARY_PATH
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When using a Chapel library from C, one must first initialize the Chapel runtime
and standard modules.  This is done by the addition of a couple of extern
declarations, calling the function \fBchpl_library_init()\fP before the Chapel
library function calls and by calling \fBchpl_library_finalize()\fP after all the
Chapel library function calls are finished.  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include "foo.h"

extern void chpl_library_init(int argc, char* argv[]);
extern void chpl_library_finalize(void);

int main(int argc, char* argv[]) {
    chpl_library_init(argc, argv);

    baz(7); // Call into a library function

    chpl_library_finalize();

    return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, compilation of the C program involves some additional command line
includes and links.  The easiest way to get the right combination is by using
the \fBcompileline \-\-compile\fP and \fBcompileline \-\-libraries\fP tools we provide.
The compilation command would then look like this (replacing myprog.c with the
name of your C program):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\(ga$CHPL_HOME/util/config/compileline \-\-compile\(ga myprog.c \-L. \-lfoo \(ga$CHPL_HOME/util/config/compileline \-\-libraries\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Chapel library files cannot be used from Chapel code.  The library files must
include the chapel runtime and standard modules for use in a non\-Chapel program
and when the library is linked to a Chapel program this leads to multiple
definitions of these functions.
.sp
As mentioned above, this feature is not very sturdy.  Please refer to
readme\-bugs if any problems are encountered.
.SS LLVM Support
.sp
The Chapel compiler can be built with LLVM support in able to enable
the following features:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
extern block support (see readme\-extern). This feature uses the clang
parser. Note that it is \fInot\fP necessary to use the LLVM code generator in
order to use extern block support.
.IP 2. 3
Experimental LLVM code generator. The \fB\-\-llvm\fP flag activates the LLVM
code generator. Note that by default, a Chapel compiler built with LLVM
support still uses the C backend.
.IP 3. 3
Experimental LLVM communication optimizations. You can activate these
communication optimizations with \fB\-\-llvm \-\-llvm\-wide\-opt\fP\&. Some
benchmark programs run faster with these LLVM communication optimizations.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Building the LLVM support
.sp
To build the compiler with LLVM support for extern blocks, \fB\-\-llvm\fP code
generation, but no support for \fB\-\-llvm\-wide\-opt\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source ./util/setchplenv.bash
export CHPL_LLVM=llvm

make # you might want to do e.g. make \-j 16 for a parallel build
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To build the compiler with LLVM support for extern blocks, \fB\-\-llvm code\fP
generation, and also support \fB\-\-llvm\-wide\-opt\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source ./util/setchplenv.bash
export CHPL_LLVM=llvm
export CHPL_WIDE_POINTERS=node16 # optional but useful with \-\-llvm\-wide\-opt
                                 # see discussion below

make # you might want to do e.g. make \-j 16 for a parallel build
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note:
.INDENT 0.0
.IP \(bu 2
If you have a built llvm in \fBthird\-party/llvm/install\fP, even if you forget
to \fBexport CHPL_LLVM=llvm\fP, the default will be to use the built llvm.  You
can override this default by setting \fBCHPL_LLVM=none\fP\&.
.IP \(bu 2
the Makefile in third\-party/llvm will unpack LLVM and Clang source releases
and build them
.IP \(bu 2
LLVM code generation has not been tested on all supported configurations,
and some features (such as building a library instead of an executable)
are not yet supported.
.IP \(bu 2
You can set the environment variable \fBCHPL_LLVM_DEVELOPER\fP
to request a debug build of LLVM.
.UNINDENT
.SS Activating the LLVM support
.sp
To compile a program using the LLVM backend, add \fB\-\-llvm\fP to the chpl command
line.
.sp
If you pass a \fB\-\-savec\fP directory, the LLVM backend will emit two .bc files
in that directory:
.INDENT 0.0
.IP \(bu 2
\fBchpl__module.bc\fP is the version that will be linked
.IP \(bu 2
\fBchpl__module\-nopt.bc\fP is the generated code without optimizations applied.
.UNINDENT
.sp
Passing \fB\-\-fast\fP will cause LLVM optimizations to run.
.sp
The \fB\-\-ccflags\fP option can control which LLVM optimizations are run, using the
same syntax as flags to clang.
.sp
Additionally, if you build your compiler with \fBCHPL_WIDE_POINTERS=node16\fP and
then compile a program with \fB\-\-llvm \-\-llvm\-wide\-opt \-\-fast\fP, you will allow
LLVM optimizations to work with global memory. For example, the Loop Invariant
Code Motion (LICM) optimization might be able to hoist an access of a remote
variable \- ie, a \(aqget\(aq \- out of a loop.  This optimization has produced better
performance with some benchmarks.
.sp
CHPL_WIDE_POINTERS=node16 is necessary to use \fB\-\-llvm\-wide\-opt\fP because of
historical limitations in LLVM support for pointers in different address spaces
having different sizes.  The default \fBCHPL_WIDE_POINTERS=struct\fP uses a
128\-bit wide pointer, but \fBCHPL_WIDE_POINTERS=node16\fP packs wide pointers
into a pointer\-sized value (normally 64 bits) which includes 16 bits of node
number in order to avoid these problems.  We plan to remove this requirement in
the future to enable \fB\-\-llvm\-wide\-opt\fP to work with
\fBCHPL_WIDE_POINTERS=struct\fP\&.
.sp
Caveats:
.INDENT 0.0
.IP \(bu 2
\fB\-\-llvm\-wide\-opt\fP currently requires \fBCHPL_WIDE_POINTERS=node16\fP, which
means that it will not work with the numa locale model since packed pointers
will not have a sublocale.
.IP \(bu 2
\fB\-\-llvm\-wide\-opt\fP may add communication to or from a task\(aqs stack, so it
may not function correctly for combinations of tasking and communication
layers in which some task has a stack outside of an acceptable region for
communication (e.g. operations on the initial \(aqmain\(aq thread may fail with
\fBCHPL_COMM=gasnet\fP, \fBCHPL_GASNET_SEGMENT=fast\fP).
.UNINDENT
.SS How \fB\-\-llvm\-wide\-opt works\fP
.sp
Communication optimization within LLVM uses the address space feature of LLVM
in order to create a conceptual global address space. In particular, instead of
generating a call to the runtime functions to \(aqput\(aq or \(aqget\(aq, when
\fB\-\-llvm\-wide\-opt\fP is enabled, the Chapel compiler will generate a load,
store, or memcpy using an address space 100 pointer. Address space 100 pointers
represent global memory \- and address space 0 pointers continue to represent
local memory. The existing LLVM optimization passes will operate normally on
these address space 100 operations. The LLVM documentation describes these
optimizations and which are normally run.
.sp
Because it may be necessary to build a global pointer or to gather information
from it \- for example when constructing a global pointer from a node number and
a local address, or extracting the node number or the address \- the LLVM code
generated with \fB\-\-llvm\-wide\-opt\fP includes calls to nonexistent functions to
mark these operations:
.INDENT 0.0
.IP \(bu 2
\&.gf.addr extracts an address from a global pointer
.IP \(bu 2
\&.gf.loc extracts a locale from a global pointer
.IP \(bu 2
\&.gf.node extracts a node number from a global pointer
.IP \(bu 2
\&.gf.make constructs a global pointer from a locale and an address
.IP \(bu 2
\&.gf.g2w converts a global pointer to a wide pointer
.IP \(bu 2
\&.gf.w2g converts a wide pointer to a global pointer
.UNINDENT
.sp
These functions will be replaced with the usual runtime functions once all
global pointers are lowered into wide pointers by the global\-to\-wide pass.
.sp
After the usual LLVM optimization passes run, two Chapel LLVM passes run:
.INDENT 0.0
.IP \(bu 2
aggregate\-global\-ops bundles together sequences of loads or sequences of
stores on adjacent global memory locations into a single memcpy. That way,
adjacent loads will generate a single \(aqget\(aq instead of several \(aqget\(aq calls.
.IP \(bu 2
global\-to\-wide converts operations on address space 100 pointers, notably
including load, store, memcpy, and memset operations, into calls to the
Chapel runtime. It converts address space 100 pointers into packed pointers
and any of the special function calls (e.g. .gf.addr to extract the local
address portion of a global pointer) into the usual operations on a packed
pointer. In the future, we would like to support converting address space 100
pointers into the usual Chapel wide pointer format.
.UNINDENT
.SS The \(aqlocal\(aq keyword
.SS The \(aqlocal\(aq Statement
.sp
This README describes the \fBlocal\fP statement in the Chapel language.
Its definition and implementation is an area of ongoing work and it
should be used with caution.
.SS Overview
.sp
The \fBlocal\fP construct in Chapel performs runtime checks for any
communication within the construct. If communication occurs, an error
is reported. The checks are performed in the code within the lexical
scope of the construct, as well as in all function calls performed by
that code, directly or indirectly, explicitly or implicitly. The
checks can be disabled with the \fB\-\-no\-local\-checks\fP flag, which is implied
by the \fB\-\-no\-checks\fP and \fB\-\-fast\fP flags.
.sp
Communication occurs in the following cases:
.INDENT 0.0
.IP \(bu 2
remote memory (i.e. data not located on the current locale)
is referenced (read from or assigned to), or
.IP \(bu 2
an \fBon\fP statement attempts to execute on a remote locale.
.UNINDENT
.sp
The \fBlocal\fP construct is useful to establish that certain code is
communication free. This may be desired, for example, when tuning
the performance of a program, as communication usually slows down
execution.
.sp
The \fBlocal\fP construct does not necessarily indicate the cause of
communication when present. See the \fI\%Module: CommDiagnostics\fP for ways to
diagnose communication.
.SS Syntax
.sp
The \fBlocal\fP construct is a statement. It consists of the \fBlocal\fP keyword
followed by a statement:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local\-statement:
    "local" statement
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Examples
.sp
Here is an example of a \fBlocal\fP statement:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local
  x = A(5);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The inner statement is often a block, commonly referred to as a
"local block":
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local {
  initializeMyData();
  compute();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the above examples, the Chapel implementation checks whether \fBx\fP,
as well as all memory referenced during the calls of \fBA.this(5)\fP
(an implicit call for \fBA(5)\fP), initializeMyData(), and compute(),
are located on the current locale. Otherwise an error is reported.
Analogously, if \fBon\fP statement(s) are executed during these calls
that attempt to execute on a different locale, an error is reported.
.SS The \(aqlocal on\(aq Statement
.sp
The \fBlocal on\fP construct in Chapel performs an on\-statement on a sublocale
within the current node. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
for i in 0..#here.getChildCount() {
  local on here.getChild(i) {
    writeln("On sublocale ", here);
  }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When the \fB\-\-local\-checks\fP flag is enabled, a runtime check will be inserted
to confirm that the on\-statement is performed within the same node.
\fB\-\-local\-checks\fP is enabled by default and can be disabled with
\fB\-\-no\-local\-checks\fP, \fB\-\-no\-checks\fP, or \fB\-\-fast\fP\&.
.sp
For example this complete program would produce a runtime error if the number
of locales is greater than one:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var LastLocale = Locales[numLocales\-1];
local on LastLocale {
  writeln("On remote locale ", LastLocale);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
> ./a.out \-nl 2
local\-on\-err.chpl:2: error: Local\-on is not local
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This program begins executing on Locale 0, so when the \fBlocal on\fP attempts to
execute on a different node (the last Locale) we see a runtime error.
.sp
The \fBlocal on\fP construct functions similarly to a normal on\-statement in all
other ways. Note that it is unrelated to \fBlocal\fP statements or \fBlocal\fP
blocks, and that it has no impact on what communication is or is not allowed
(other than where the on\-statement can execute).
.sp
With this information the compiler can reduce overhead associated with wide
pointers and hopefully improve performance.
.SS Locale Models
.SS Introduction
.sp
Chapel\(aqs original computer system architecture model was a collection of
simple locales connected by a communication network.  The locales had
one or more homogeneous processor cores and one kind of memory, with all
the memory equidistant from all the processor cores.  But while this
model was conceptually easy to deal with, it couldn\(aqt support users who
wanted to take advantage of modern node architectures.  To support
these, we are extending architectural descriptions.  In the new model
the top level may still be a network of locales, but the locales are
more complicated.  They may be internally heterogeneous, containing
multiple instances of memories and/or processors with differing
characteristics.  They may also be hierarchical, with parent locales
containing one or more child sublocales within them.
.sp
There are currently two locale models available, flat and NUMA.  The
flat model is the default and maps closely to the view of locales
implemented in the 1.7 release.  The NUMA locale model maps sublocales
to NUMA domains.  The NUMA model is currently implemented at a prototype
level. Performance has not yet been a focus in the NUMA locale model and
will require additional effort in future releases.  We expect to add
more locale models in future releases.
.SS Architecture support in the modules
.sp
The code emitted by the compiler contains calls to support routines that
manage memory, communication, and tasking, among other things.  Before
hierarchical locale support was added, these calls were all satisfied
directly by the runtime.  With hierarchical locales, now they are
satisfied by the Chapel module code that defines the architecture of a
locale.  The required interface for this is defined by ChapelLocale and
implemented by \fBLocaleModel.chpl\fP\&.  The required interface is still a work
in progress and will continue to evolve.
.SS Flat Locale Model
.sp
The current default locale model is the flat locale model. In the flat model,
locales have homogeneous processor cores and all cores are equidistant from
memory.
.SS NUMA Locale Model
.sp
In the NUMA locale model, the processor is split into NUMA domains
and cores within a domain have faster access to local memory.
.sp
The NUMA locale model is supported most fully when qthreads tasking is
used.  While other tasking layers are also functionally correct using
the NUMA locale model, they are not NUMA aware.  In addition, the
Portable Hardware Locality library (hwloc) is used with qthreads to map
sublocales to NUMA domains. For more information about qthreads and
about tuning parameters such as the number of qthread shepherds per
locale, please see readme\-tasks\&.
.sp
To use the NUMA locale model:
.INDENT 0.0
.IP 1. 3
Set the \fBCHPL_LOCALE_MODEL\fP environment variable to \fBnuma\fP\&.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_LOCALE_MODEL=numa
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 2. 3
Re\-make the compiler and runtime from \fBCHPL_HOME\fP
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME
make
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 3. 3
Compile your Chapel program as usual.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-o jacobi $CHPL_HOME/examples/programs/jacobi.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Qthreads thread scheduling
.sp
When qthreads tasking is used, different Qthreads thread schedulers are
selected depending upon the \fBCHPL_LOCALE_MODEL\fP setting.  For the flat
locale model the "nemesis" thread scheduler is used, and for the NUMA
locale model the "sherwood" thread scheduler is used.  This selection is
done at the time the Qthreads third\-party package is built, and cannot
be adjusted later, either at user compile time or at execution time.
.SS Caveats for using the NUMA locale model
.INDENT 0.0
.IP \(bu 2
Explicit memory allocation for NUMA domains is not yet implemented.
.IP \(bu 2
Distributed arrays other than Block do not yet map iterations to NUMA
domains.
.IP \(bu 2
Performance for NUMA has not been optimized.
.UNINDENT
.SS Support for main() Functions
.sp
After running module initialization code (top\-level statements in
modules), a Chapel program will start executing from the entry point,
a function named main().  Chapel\(aqs main() function has typically taken
no arguments and had no return type.  This README describes initial
support for returning a status value and making main() take arbitrary
command\-line arguments.
.SS Returning a status value
.sp
Traditionally, the only way to return a nonzero exit value from a
Chapel program has been to call exit().  Optionally, main() can be
declared to return an integer in which case the value returned serves
as the status value.
.SS Having main() accept command\-line arguments
.SS Overview
.sp
Because Chapel programs have traditionally accepted a number of
"built\-in" flags and configuration variables, there has been no way to
create a Chapel program that accepts arguments like an arbitrary list
of filenames or flags that might conflict with built\-in capabilities.
For most uses, Chapel\(aqs existing config variable support is useful and
easy; occasionally, however, one wants to fully control argument
processing.
.sp
If a program\(aqs main() function is declared to take no arguments, Chapel
will behave as it traditionally has \-\- built\-in flags and config
settings will be handled and unrecognized flags will trigger an error.
.sp
Alternatively, a main() function can be declared to take an array of
strings as an argument.  By doing so, the program opts\-in to explicit
argument handling, described in the remainder of this README.
.SS Usage
.sp
To use this feature, declare main as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc main(args: [] string) {
  // ...body...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When main is so declared, Chapel\(aqs default command line argument
processing changes. Rather than generate an error message when an
unknown argument is encountered, that argument will instead be passed
on to this main(args) function. Arguments corresponding to config
variables or Chapel\(aqs predefined flags (like \fB\-nl\fP, \fB\-b\fP, etc) will still
be processed and will not be passed on to the main(args) function.
.sp
To be clear, the arguments that would be handled without using this
feature will continue to behave as usual. The difference is that other
arguments will be passed to main(args) rather than generating an error
message. The only exception to this, is \fB\-\-help\fP and \fB\-h\fP\&.
.sp
Prior to this feature, a Chapel program would always exit immediately
after printing the help message. A programmer might want to print
other information explaining what non\-config\-var command line
arguments are available and what they might do. For this reason, when
a Chapel program includes a main declared to take arguments, \fB\-\-help\fP
and \fB\-h\fP will be passed on to the main(args) function.  The function
Help.printUsage() will print out the familiar config var table.
.sp
To gain access to this new function requires a module:
.sp
\fBuse Help;\fP
.sp
From that module, the function printDefaultUsage() is available. For
example, consider the following program:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Help;

proc main(args: [] string) {
  for a in args {
    if a=="\-\-help" {
      printUsage();
      writeln("\enEXTRA ARGUMENTS:");
      writeln(  "================");
      writeln("You can provide an arbitrary list of filenames.");
      exit(0);
    }
  }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This program scans its argument list for \fB\-\-help\fP, and if found, it
prints the standard usage message as well as some additional text
explaining the purpose of the extra arguments. Note that this could be
used by a program which simply wants to add explanatory text to the
\fB\-\-help\fP output without actually handling any additional arguments.
.sp
Finally, as is common in GNU programs, there is a way to suspend
argument processing when main is declared to take arguments. Suppose
you are writing \fBrm\fP in Chapel and need to delete a file named
\fB\-\-memTrack=true\fP\&. Your program will consume this flag during startup,
rather than passing it on to the declared main function. However,
placing the argument \fB\-\-\fP in the argument list will cause all
following arguments to be passed to the declared main function and
will suspend handling of any builtin command line
arguments. Specifically, if a.out is a Chapel program which has
declared main to take arguments:
.sp
\fB\&./a.out \-\- \-\-memTrack=true\fP
.sp
will result in the program receiving \fB\-\-memTrack=true\fP as the first
argument after the executable name.
.SS Module Search Paths
.sp
This README describes how modules are located by the current Cray implementation
of Chapel.
.sp
Internal modules are always loaded by a chapel program \fIas if\fP the
statement \fBuse ChapelStandard;\fP has been inserted ahead of the first
statement in the main module.  Unlike standard modules, internal modules cannot
be overridden.
.sp
The compiler uses three module search paths: one for internal modules, one for
standard modules and one for user modules.  The user path first includes all the
paths used to specify module files directly on the \fBchpl\fP command line and
then includes the paths specified via \fB\-M\fP commands or through
the \fBCHPL_MODULE_PATH\fP environment variable.
.sp
The module search paths are initialized as follows:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B Internal
.INDENT 7.0
.IP \(bu 2
\fB$CHPL_HOME/modules/internal/localeModels/$CHPL_LOCALE_MODEL\fP
.IP \(bu 2
\fB$CHPL_HOME/modules/internal/tasks/$CHPL_TASKS\fP
.IP \(bu 2
\fB$CHPL_HOME/modules/internal/comm/$CHPL_COMM\fP
.IP \(bu 2
\fB$CHPL_HOME/modules/internal\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B Standard
.INDENT 7.0
.IP \(bu 2
\fB$CHPL_HOME/modules/standard/gen/$CHPL_TARGET_PLATFORM\-$CHPL_TARGET_COMPILER\fP
.IP \(bu 2
\fB$CHPL_HOME/modules/standard\fP
.IP \(bu 2
\fB$CHPL_HOME/modules/layouts\fP
.IP \(bu 2
\fB$CHPL_HOME/modules/dists\fP
.IP \(bu 2
\fB$CHPL_HOME/modules/dists/dims\fP
.UNINDENT
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B User
.INDENT 7.0
.IP \(bu 2
\fB$CHPL_MODULE_PATH\fP
.IP \(bu 2
\fB(User paths)\fP
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
When the root internal module \fIChapelStandard\fP and its dependencies are
loaded, the internal module path is searched first.  If a module is found there,
it is marked as internal.  Otherwise, it is skipped.
.sp
The user\(aqs modules are parsed next.  If a module named in a use statement is not
found, the standard version is loaded instead if it exists.  Otherwise, a
file\-not\-found error will be issued.  If both user and standard versions of a
module exist, the user is warned that the standard version is being overridden.
.SS Reduce Intents
.sp
Note: this is work in progress and is subject to change.
.SS Overview
.sp
Reduce intents are a kind of forall intent \- see Section 25.3
"Forall Intents" of the Chapel Language Specification.
.sp
As with any forall intent, a reduce intent can be specified on any
\fIouter variable\fP \- that is, a variable used within the body of a
forall loop and declared outside that loop.  References to such a
variable within the loop implicitly refer to the corresponding formal
argument of the task function or the leader iterator.
.sp
Reduce intents are distinct:
.INDENT 0.0
.IP \(bu 2
Each task formal that corresponds to an outer variable with a reduce
intent is initialized, at the beginning of its task, to the identity
value for the corresponding reduction.
.IP \(bu 2
The value of the outer variable immediately after the forall loop is a
reduction of the values of the corresponding formals at the end of
their tasks.
.UNINDENT
.sp
Note that the value of the outer variable immediately before the forall loop
is discarded.
.sp
Reduce intents are also available with coforall statements.
.SS Syntax
.sp
The syntax of \fBtask\-intent\-list\fP is extended to allow \fBreduce\-intent\fP:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
task\-intent\-list:
  // no change with these
  formal\-intent identifier
  formal\-intent identifier, task\-intent\-list
  // added for reduce intents:
  reduce\-intent
  reduce\-intent, task\-intent\-list

reduce\-intent:
  reduce\-operator \(aqreduce\(aq identifier
  reduce\-class    \(aqreduce\(aq identifier

reduce\-operator: one of
   // these have the same meaning as in a reduction expression
   +  *  &&  ||  &  |  ^  min  max

reduce\-class:
   // the name of the class that implements a user\-defined reduction
   identifier
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Examples
.sp
Increment \fBx\fP in the loop \-\- counts the number of iterations:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var x = 5;
forall myIterator() with (+ reduce x) {
  x += 1;
}
writeln("The number of loop iterations is: ", x);
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Set \fBx\fP in the loop \-\- counts the number of tasks:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var x = 5;
forall myIterator() with (+ reduce x) {
  x = 1;
}
writeln("The number of tasks is: ", x);
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For a user\-defined reduction, there is a task\-private instance
of the reduction class for each task created for the forall
or coforall loop. Here is an example of such a class:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/* Implements + reduction over numeric data. */
class PlusReduceOp: ReduceScanOp {

  /* the type of the elements to be reduced */
  type eltType;

  /* task\-private accumulator state */
  var value: eltType;

  /* identity w.r.t. the reduction operation */
  proc identity         return 0: eltType;

  /* accumulate a single element onto the accumulator */
  proc accumulate(elm)  { value = value + elm; }

  // Note: \(aqthis\(aq can be accessed by multiple calls to combine()
  // concurrently. The Chapel implementation serializes such calls
  // with a lock on \(aqthis\(aq.
  // \(aqother\(aq will not be accessed concurrently.
  /* combine the accumulations in \(aqthis\(aq and \(aqother\(aq */
  proc combine(other)   { value = value + other.value; }

  /* Convert the accumulation into the value of the reduction
     that is reported to the user. This is trivial in our case. */
  proc generate()       return value;

  /* produce a new instance of this class */
  proc clone()          return new PlusReduceOp(eltType=eltType);
}

// Use the above class.
var A = [1000, 200, 30, 4];
var sum: int;
forall elm in A with (PlusReduceOp reduce sum) {
  sum += elm;
}
writeln(sum);
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Open Issues
.INDENT 0.0
.IP \(bu 2
Should reduce\-intent variables within the loop body
be task\-private or iteration\-private?
I.e. should the variable\(aqs value that is reduced into the final result
be taken at the end of each task or at the end of each loop iteration?
.sp
The current implementation and the above examples provide the former.
Both above examples would report the number of iterations if the latter.
.IP \(bu 2
How to support reductions where the type of the result is different
from the type of the values being reduced, e.g. for a \fBmin\-k\fP reduction?
.IP \(bu 2
Should the initial value of the reduction variable participate
in the reduction as well?
.IP \(bu 2
How would we support reductions over nested forall loops, e.g.:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
var global = 0;

forall i in iterX() with (+ reduce global) do
  forall j in iterY() with (+ reduce global) do
     global += kernel(i,j);

writeln("result = ", global);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The current implementation would exclude, from the final result,
the values of \fBkernel(i,j)\fP for most \fBi\fP\&. Indeed, assume that each task
of the outer forall executes several inner forall loops.
The reduction result of the inner loop will be stored into
the outer task\(aqs \fBglobal\fP formal. Since the value of that formal
is discarded when entering the inner loop, only the result
from the last inner loop within the outer task will be retained
and reduced into the outer \fBglobal\fP\&.
.UNINDENT
.SS Future Work
.INDENT 0.0
.IP \(bu 2
Provide reduce intents as task intents for cobegin statements.
.IP \(bu 2
Provide the other predefined reduction operators as reduce intents:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
minloc maxloc
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Associative Set Operations
.sp
This README describes some initial support for set operations on associative
arrays and domains. It is expected that the features described here will be
included in a future version of the language specification.
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Associative Set Operations\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Associative Domain Set Operations\fP
.INDENT 2.0
.IP \(bu 2
\fI\%isSubset\fP
.IP \(bu 2
\fI\%isSuper\fP
.IP \(bu 2
\fI\%Union\fP
.IP \(bu 2
\fI\%Difference\fP
.IP \(bu 2
\fI\%Intersection\fP
.IP \(bu 2
\fI\%Symmetric Difference\fP
.UNINDENT
.IP \(bu 2
\fI\%Associative Array Set Operations\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Value Precedence for the Union Operator\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Associative Domain Set Operations
.sp
The following set functions/operations are supported by associative domains.
In the following code examples, \fBA\fP, \fBB\fP, and \fBC\fP are associative domains.
For every operator, an op= variant exists. For these op= functions, LHS op= RHS,
the LHS argument is modified in\-place using the same rules as the normal
operator function.
.SS isSubset
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc isSubset(super : domain) : bool;

A.isSubset(B);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This statement will return true if \fBA\fP is a subset of \fBB\fP\&. \fBA\fP is a subset of
\fBB\fP if every index in \fBA\fP is also present in \fBB\fP\&.
.SS isSuper
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc isSuper(sub : domain) : bool;

A.isSuper(B);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This statement will return true if \fBB\fP is a subset of \fBA\fP\&.
.SS Union
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C = A + B;
C = A | B;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBC\fP will be a new associative domain which contains every index in \fBA\fP and
every index in \fBB\fP\&.
.sp
The op= variants are:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A |= B;
A += B;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Difference
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C = A \- B;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBC\fP will contain the indices in \fBA\fP that are not also in \fBB\fP\&.
.sp
The op= variant is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A \-= B;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Any indices in both \fBA\fP and \fBB\fP will be removed from \fBA\fP\&.
.SS Intersection
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C = A & B;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBC\fP will contain the indices in \fBA\fP that are also in \fBB\fP\&.
.sp
The op= variant is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A &= B;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Symmetric Difference
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C = A ^ B;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBC\fP will contain the indices that are unique to \fBA\fP and unique to \fBB\fP\&. Another
way of writing this statement is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C = (A + B) \- (A & B)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The op= variant is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A ^= B;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Associative Array Set Operations
.sp
The Union, Difference, Intersection, and Symmetric Difference operators
(and their op= variants) are available for associative arrays that don\(aqt share
their domains. This restriction exists because it may be surprising to appear
to be modifying one array, and in turn modify another due to a shared domain.
.sp
When performing a set operation between two associative arrays, the resulting
array\(aqs domain is the result of the rules described in the previous section.
Unless otherwise stated, the values from the LHS of the operation are used as
the new array\(aqs values.
.SS Value Precedence for the Union Operator
.sp
In the following code snippet, let \fBA\fP and \fBB\fP be associative arrays whose
domains contain some of the same indices:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C = A + B;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the resulting array \fBC\fP, the values from \fBB\fP will take precedence when
indices overlap.
.SS Querying a Local Subdomain
.sp
While writing a distributed program, one might need to know the index set that
a certain locale owns in a given distributed array. This README describes the
initial support for this functionality.
.sp
For code examples using these features, see the
\fB$CHPL_HOME/examples/primers/distributions.chpl\fP primer.
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Querying a Local Subdomain\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Functions Supported on All Array Types\fP
.INDENT 2.0
.IP \(bu 2
\fI\%hasSingleLocalSubdomain\fP
.IP \(bu 2
\fI\%localSubdomain\fP
.IP \(bu 2
\fI\%localSubdomains\fP
.UNINDENT
.IP \(bu 2
\fI\%Functions Supported on Distributed Arrays\fP
.INDENT 2.0
.IP \(bu 2
\fI\%targetLocales\fP
.UNINDENT
.IP \(bu 2
\fI\%Future Work\fP
.UNINDENT
.UNINDENT
.SS Functions Supported on All Array Types
.SS hasSingleLocalSubdomain
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc array.hasSingleLocalSubdomain() : bool;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is a param function which returns a boolean. If true, then the index set
owned by a locale can be represented by a single domain.
.TS
center;
|l|l|.
_
T{
Distribution
T}	T{
hasSingleLocalSubdomain
T}
_
T{
Block
T}	T{
true
T}
_
T{
Cyclic
T}	T{
true
T}
_
T{
BlockCyclic
T}	T{
false
T}
_
T{
Replicated
T}	T{
true
T}
_
.TE
.sp
This function always returns \fBtrue\fP for non\-distributed arrays.
.sp
To support this function on a custom distributed array type, write a param
function named \(aqdsiHasSingleLocalSubdomain\(aq.
.SS localSubdomain
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc array.localSubdomain() : domain;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function only operates on arrays whose \(aqhasSingleLocalSubdomain()\(aq result
is true. Otherwise, a compiler error is thrown.
.sp
This function returns a single domain that represents the index set owned
by the current locale. This returned domain cannot be used to modify the index
set owned by the locale.
.sp
For non\-distributed arrays, this function returns a copy of that array\(aqs
domain.
.sp
To support this function on a custom distributed array type, write a function
named \(aqdsiLocalSubdomain\(aq.
.SS localSubdomains
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
iter array.localSubdomains() : domain;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This iterator yields the subdomain(s) that represent the index set owned by the
current locale.
.sp
If the locale\(aqs index set can be represented by a single domain, then the
result of \fBlocalSubdomain\fP is yielded.
.sp
Currently, this is a serial iterator.
.sp
To support this iterator on a custom distributed array type, write an iterator
named \(aqdsiLocalSubdomains\(aq.
.SS Functions Supported on Distributed Arrays
.sp
Any functions in this section are only supported on distributed array types.
Calling them on a non\-distributed array will result in a compiler error.
.SS targetLocales
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc array.targetLocales() : [] locale;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function returns an array of locales that the distribution uses as the
locale grid.
.SS Future Work
.sp
While these functions are currently supported on arrays, future work involves
support for domains and domain maps.
.SH TOOLS
.sp
Contents:
.SS chpldoc
.SS chpldoc
.SS SYNOPSIS
.nf
\fBchpldoc\fP [\fB\-o\fP \fIdirectory\fP]
.in +2
[\fB\-\-author\fP \fIauthortext\fP]
[\fB\-\-save\-sphinx\fP \fIdirectory\fP]
[options] source\-files...

.in -2
.fi
.sp
.SS DESCRIPTION
.sp
\fBchpldoc\fP is a tool for generating HTML based documentation from
Chapel source code and its comments. It does this by parsing Chapel
source files and associating comments with symbols, then generating
reStructuredText, and finally building the output documentation with
Sphinx. Most users will not need to be aware of the use of
reStructuredText as an intermediate format.
.sp
\fIDocumentation Options\fP
.sp
\fB\-o, \-\-output\-dir <dirname>\fP
.INDENT 0.0
.INDENT 3.5
Specify the \fIdirectory\fP name into which documentation should be saved
(defaults to \(aqdocs\(aq if unspecified).
.UNINDENT
.UNINDENT
.sp
\fB\-\-author <\fP\fIauthortext\fP\fB>\fP
.INDENT 0.0
.INDENT 3.5
Documentation author string. \fIauthortext\fP becomes the copyright and
author in the output documentation.
.UNINDENT
.UNINDENT
.sp
\fB\-\-comment\-style <string>\fP
.INDENT 0.0
.INDENT 3.5
Specify the opening comment character sequence used to distinguish a
documentation comment from a normal one (defaults to \(aq/*\(aq if
unspecified).
.UNINDENT
.UNINDENT
.sp
\fB\-\-process\-used\-modules\fP
.INDENT 0.0
.INDENT 3.5
By default, \fBchpldoc\fP only generates documentation for the source
\fBfile\fP(s) named on the command\-line. When this flag is thrown,
modules that it \(aquse\(aqs are also parsed and processed.
.UNINDENT
.UNINDENT
.sp
\fB\-\-save\-sphinx <\fP\fIdirectory\fP\fB>\fP
.INDENT 0.0
.INDENT 3.5
Save generated Sphinx project in \fIdirectory\fP\&.
.UNINDENT
.UNINDENT
.sp
\fB\-\-text\-only\fP
.INDENT 0.0
.INDENT 3.5
Generate text\-based documentation instead of HTML. Takes precedence over
\-\-[no\-]html
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]html\fP
.INDENT 0.0
.INDENT 3.5
[Don\(aqt] generate HTML\-based documentation (on by default)
.UNINDENT
.UNINDENT
.sp
\fB\-\-[no\-]print\-commands\fP
.INDENT 0.0
.INDENT 3.5
Prints the system commands that \fBchpldoc\fP executes in order to create
the documentation.
.UNINDENT
.UNINDENT
.sp
\fIInformation Options\fP
.sp
\fB\-h, \-\-help\fP
.INDENT 0.0
.INDENT 3.5
Print a list of the command line options, indicating the arguments that
they expect and a brief summary of their purpose.
.UNINDENT
.UNINDENT
.sp
\fB\-\-help\-env\fP
.INDENT 0.0
.INDENT 3.5
Print the command line option help message, listing the environment
variable equivalent for each flag, if applicable (see ENVIRONMENT), and
its current value.
.UNINDENT
.UNINDENT
.sp
\fB\-\-help\-settings\fP
.INDENT 0.0
.INDENT 3.5
Print the command line option help message, listing the current setting
of each option as specified by environment variables and other flags on
the command line.
.UNINDENT
.UNINDENT
.sp
\fB\-\-version\fP
.INDENT 0.0
.INDENT 3.5
Print \fBchpldoc\fP\(aqs version number.
.UNINDENT
.UNINDENT
.sp
\fB\-\-copyright\fP
.INDENT 0.0
.INDENT 3.5
Print \fBchpldoc\fP\(aqs copyright information.
.UNINDENT
.UNINDENT
.sp
\fB\-\-license\fP
.INDENT 0.0
.INDENT 3.5
Print \fBchpldoc\fP\(aqs license information.
.UNINDENT
.UNINDENT
.SS ENVIRONMENT
.sp
Some command\-line options have an environment variable that can be used
to specify a default value. Use the \fB\-\-help\-env\fP option to list the
environment variable equivalent for each option. Command\-line options
will always override environment variable settings in the event of a
conflict.
.sp
If the environment variable equivalent is set to empty, it is considered
unset. This does not apply to options expecting a string or a path.
.sp
For options that can be used with or without the leading \fB\-\-no\fP (they
are shown with "[no\-]" in the help text), the environment variable
equivalent, when set to a non\-empty string, has the following effect.
When the first character of the string is one of:
.nf
Y y T t 1 \- same as passing the option without \-\-no,
.fi
.sp
.INDENT 0.0
.INDENT 3.5
N n F f 0 \- same as passing the option with \-\-no,
.sp
anything else \- generates an error.
.UNINDENT
.UNINDENT
.sp
For the other options that enable, disable or toggle some feature, any
non\-empty value of the environment variable equivalent has the same
effect as passing that option once.
.SS BUGS
.sp
See $CHPL_HOME/STATUS for a list of known bugs and
$CHPL_HOME/doc/bugs.rst for instructions on reporting bugs.
.SS SEE ALSO
.sp
$CHPL_HOME/QUICKSTART.rst for more information on how to get started with
Chapel.
.SS AUTHORS
.sp
See $CHPL_HOME/CONTRIBUTORS.md for a list of contributors to Chapel.
.SS COPYRIGHT
.sp
Copyright (c) 2004\-2016 Cray Inc. (See $CHPL_HOME/LICENSE for more
details.)
.sp
\fBchpldoc\fP is a tool for generating HTML based documentation from Chapel
source code and embedded comments. It is similar in spirit to Godoc, Javadoc,
and Pydoc. \fBchpldoc\fP is used to produce Chapel\(aqs web documentation for the
Standard Library and
Built\-in\-Types and Functions\&.
.sp
See the online \fBman page\fP for all available flags.
.SS Building chpldoc
.sp
To build \fBchpldoc\fP, use:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[g]make chpldoc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This downloads the required Python package dependencies and creates the
\fBchpldoc\fP program in the same directory as the \fBchpl\fP compiler.
.sp
To ensure chpldoc is installed properly, optionally run the automatic sanity
check:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
[g]make check\-chpldoc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Prerequisites
.sp
\fBchpldoc\fP depends on several Python packages. The full list is available in
\fI\%$CHPL_HOME/third\-party/chpl\-venv/README.md\fP including details on each
package.
.SS Documenting Chapel code
.sp
To document Chapel code, place a multi\-line comment just prior to the
definition of the symbol \-\-\- module, class, function, method, global variable,
etc. \-\-\- that you wish to comment. All multi\-line comments are considered
potential documentation. Documentation is output in the same order that it
exists in the source. Documentation text within comments is parsed as
ReStructured Text.
.SS Documenting Modules
.sp
To document individual modules, inside the Chapel standard library or
elsewhere, use the chpldoc command directory. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpldoc modules/standard/Random.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By default, documentation created by chpldoc will end up in a subdirectory of
the current working directory named \(aqdocs/\(aq. You can specify a different
directory name using the \-\-docs\-dir option.
.sp
As an example, there is a primer on the chpldoc capability in
\fB$CHPL_HOME/examples/primers/\fP that can be turned into documentation using:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd $CHPL_HOME/examples/primers
chpldoc chpldoc.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The output documentation will be located in:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$CHPL_HOME/examples/primers/docs/chpldoc.html
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Comment style
.sp
For the Chapel standard modules, it is recommended to use multiline comments
without any per\-line prefixes. This results in the most consistent, best
looking output. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/* Support for buffers \- ...

   Provides bytes and buffer types, which can be used to...
 */
module Buffers {
  ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Argument and return/yield types
.sp
Arguments and their types can optionally be documented using the \fB:arg:\fP and
\fB:type:\fP fields. For the Chapel standard modules, \fB:arg:\fP should be a
concise description of the argument using a sentence, or two. This should
include any constraints and default information. \fB:type:\fP should be the
literal type for the parameter. A link will be created to the type, if
possible. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/* Fill and array with pseudorandom values ...

   :arg arr: Array to be filled, where T is real(64), imag(64), or complex(128).
   :type arr: [] T

   :arg seed: Integer seed to use for the PRNG. Defaults to :proc:\(gaSeedGenerator.currentTime\(ga.
   :type seed: int(64)
 */
proc fillRandom(arr: [], seed: int(64) = SeedGenerator.currentTime) {
  ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Return or yield types can optionally be documented using the \fB:returns:\fP and
\fB:yields:\fP fields, and the \fB:rtype:\fP and \fB:ytype:\fP fields. \fB:returns:\fP
and \fB:rtype:\fP are for procedures and methods, while \fB:yields:\fP and
\fB:ytype:\fP are for iterators.
.sp
Similar to arguments, the \fB:returns:\fP and \fB:yields:\fP should be a concise
description of the return value or yield value, including any constraints,
using a sentence, or two. \fB:rtype:\fP and \fB:ytype:\fP should be the literal
types. A link to the type will be created, if possible. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/* Returns the next value in the random stream.

   :returns: Next value in the random integer stream.
   :rtype: int
 */
proc RandomStream.getNext(): int {
  ...

/* Simple find\-like utility for iterating over files.

   :arg startdir: Directory to start looking for files.
   :arg recursive: Whether or not to descend recursively into directories.
   :arg hidden: Whether or not to yield hidden files.

   :yields: Filenames found in \(gastartdir\(ga based on input arguments.
   :ytype: string
 */
iter findfiles(startdir=".", recursive=false, hidden=false): string {
  ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Leave an empty line above and below all these fields for best results.
.IP \(bu 2
All of these fields must be left\-aligned with the outer most paragraph(s).
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For more information see the \fI\%Documenting argument, return, and yield values
and types\fP section.
.SS Stifling documentation
.sp
To mark a particular symbol to not be output as part of the documentation,
preface the symbol with the pragma "no doc". For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pragma "no doc"
proc foo() { ... }
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Private symbols are not documented by default.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
private proc foo() { ... }
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Private cannot be applied to all symbols at this time.  It is currently
limited to functions, iterators, globals, and modules.  Not supported are
type aliases, enum declarations, classes/records/unions, methods, and fields.
.UNINDENT
.UNINDENT
.SS Creating links to other symbols
.sp
See the \fI\%hyperlinks\fP section for details on creating links, also
known as cross\-references, in the documentation to other symbols.
.SS reStructuredText primer
.sp
This section is a brief introduction to reStructuredText (aka reST). It is
intended to provide Chapel developers with enough information to write
documentation in comments in the source code.
.sp
The Python and Sphinx projects have thorough primers of reST. Please see those
for more detail.
.INDENT 0.0
.IP \(bu 2
\fI\%Sphinx reST Primer\fP
.IP \(bu 2
\fI\%Python reST Primer\fP
.UNINDENT
.sp
This primer is based on the information and text in the Sphinx and Python reST
primers (some of the text is copied verbatim).
.sp
The authoritative \fI\%reStructuredText User Guide\fP is also helpful.
.SS Paragraphs
.sp
Simple chunks of text. Paragraphs can have line breaks to improve source
readability. Separate paragraphs with an empty line. Indentation is significant
in reST. All lines of paragraph must be left\-aligned.
.SS Inline markup
.INDENT 0.0
.IP \(bu 2
one asterisk: \fB*text*\fP for emphasis (italics),
.IP \(bu 2
two asterisks: \fB**text**\fP for strong emphasis (boldface), and
.IP \(bu 2
backquotes: \fB\(ga\(gatext\(ga\(ga\fP for code samples.
.UNINDENT
.sp
If asterisks or backquotes appear in running text and could be confused with
inline markup delimiters, they have to be escaped with a backslash.
.SS Lists and Quotes
.sp
To create a list, put an asterisk at the start of a paragraph and indent
accordingly. Create numbered lists by using the literal numbers, e.g. \fB1.\fP,
\fB2.\fP\&. Automatically numbered lists begin with \fB#.\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Nested lists are possible, but be aware that they must be separated from the
parent list items by blank lines:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
* a
* b

  * nested
  * blah

* my final item, in the parent list
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Source Code
.sp
Literal code blocks are introduced by ending a paragraph with the special marker
\fB::\fP\&.  The literal block must be indented:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The handling of the \fB::\fP marker is smart:
.INDENT 0.0
.IP \(bu 2
If it occurs as a paragraph of its own, that paragraph is completely left
out of the document.
.IP \(bu 2
If it is preceded by whitespace, the marker is removed.
.IP \(bu 2
If it is preceded by non\-whitespace, the marker is replaced by a single
colon.
.UNINDENT
.sp
That way, the second sentence in the above example\(aqs first paragraph would be
rendered as "The next paragraph is a code sample:".
.sp
The highlight language is configured with the \fBhighlight\fP directive. The
configured language is used for all literal blocks until the next highlight
directive. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. highlight:: chapel

Chapel code::

   writeln("Hello from Chapel!");

More chapel::

   x <=> y;

\&.. highlight:: c

::

   printf("Hello from C!\en");
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Showing code examples
.sp
The \fBcode\-block\fP directive can be used to specify the highlight language of a
single code block. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. code\-block:: chapel

   use Foo;

   proc bar() {
     writeln("Fooy!");
   }
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If highlighting with the specified language fails, e.g. if the syntax is not
parsable, the block is not highlighted in anyway. Note that there should be a
blank line between the \fBcode\-block\fP directive and the indented code snippet.
.SS Hyperlinks
.SS External links
.sp
Use \fB\(gaLink text <http://target>\(ga_\fP for inline web links.  If the link text
should be the web address, you don\(aqt need special markup at all, the parser
finds links and mail addresses in ordinary text.
.SS Internal links
.sp
Internal linking is done via a special reST role, see the section on specific
markup \fI\%cross\-references\fP\&.
.SS Sections
.sp
Section headers are created by underlining (and optionally overlining) the
section title with a punctuation character, at least as long as the text:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
This is a heading
=================
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There are no heading levels assigned to certain characters. The structure is
determined from the succession of headings.
.SS Comments
.sp
Every explicit markup block which is not a valid markup construct is regarded
as a comment. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
This is a normal paragraph.
It is interesting.

\&.. TODO: Make it more interesting.

Another paragraph goes here.

\&.. add another paragraph below
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can indent text after a comment start to form multiline comments:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&..
   This whole indented block
   is a comment.

   Still in the comment.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Inline markup
.sp
As said before, Sphinx uses interpreted text roles to insert semantic markup in
documents.
.sp
Names of builtins, like \fItrue\fP, \fIfalse\fP, types like \fIint(64)\fP, and local
variables, such as function/method arguments, are an exception, they should be
marked simply with \fB\(gamyVar\(ga\fP\&.
.sp
For all other roles, you have to write \fB:rolename:\(gacontent\(ga\fP\&.
.sp
There are some additional facilities that make cross\-referencing roles more
versatile:
.INDENT 0.0
.IP \(bu 2
You may supply an explicit title and reference target, like in reST direct
hyperlinks: \fB:role:\(gatitle <target>\(ga\fP will refer to \fItarget\fP, but the link
text will be \fItitle\fP\&.
.IP \(bu 2
If you prefix the content with \fB!\fP, no reference/hyperlink will be created.
.IP \(bu 2
For the Chapel roles, if you prefix the content with \fB~\fP, the link text
will only be the last component of the target.  For example,
\fB:proc:\(ga~Random.RandomStream.fillRandom\(ga\fP will refer to
\fBRandom.RandomStream.fillRandom\fP but only display \fBfillRandom\fP as the
link text.
.sp
In HTML output, the link\(aqs \fBtitle\fP attribute (that is e.g. shown as a
tool\-tip on mouse\-hover) will always be the full target name.
.UNINDENT
.sp
The following roles refer to objects in modules and are possibly hyperlinked if
a matching identifier is found:
.sp
\fB:mod:\fP
.INDENT 0.0
.INDENT 3.5
Reference a module; a dotted name may be used. See \fI\%cross\-references\fP for
details on dotted and non\-dotted names.
.UNINDENT
.UNINDENT
.sp
\fB:proc:\fP
\fB:iter:\fP
.INDENT 0.0
.INDENT 3.5
Reference a Chapel function or iterator. The role text needs not include
trailing parentheses to enhance readability.
.sp
These can also be used to reference a method or iterator on an object
(class or record instance). The role text can include the type name and the
method, in those cases. If it occurs within the description of a type, the
type name can be omitted.
.sp
Dotted names may be used for any form.
.UNINDENT
.UNINDENT
.sp
\fB:data:\fP
\fB:const:\fP
\fB:var:\fP
\fB:param:\fP
\fB:type:\fP
.INDENT 0.0
.INDENT 3.5
Reference a module\-level variable, constant, compiler param, or type.
.UNINDENT
.UNINDENT
.sp
\fB:class:\fP
\fB:record:\fP
.INDENT 0.0
.INDENT 3.5
Reference a class or record; a dotted name may be used.
.UNINDENT
.UNINDENT
.sp
\fB:attr:\fP
.INDENT 0.0
.INDENT 3.5
Reference a data attribute (const, var, param, generic type) of an object.
.UNINDENT
.UNINDENT
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Uses :proc:\(gaRandom.RandomStream.fillRandom\(ga and real\->int casts to
generate a vector of random integers. See :attr:\(gaRandomStream.seed\(ga
and description of :mod:\(gaRandom\(ga for details on PRNG.

Relies on :iter:\(gaMyModule.Set.these\(ga to iterate over all values in the
given :record:\(gaMyModule.Set\(ga.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Documenting argument, return, and yield values and types
.sp
Inside Chapel description directives, reST field lists with these fields are
recognized and formatted nicely:
.INDENT 0.0
.IP \(bu 2
\fBarg\fP, \fBargument\fP: Description of a parameter.
.IP \(bu 2
\fBtype\fP: Type of a parameter. Creates a link if possible.
.IP \(bu 2
\fBreturns\fP, \fBreturn\fP: Description of the return value.
.IP \(bu 2
\fBrtype\fP: Return type. Creates a link if possible.
.IP \(bu 2
\fByields\fP, \fByield\fP: Description of the yield value, often used for
iterators.
.IP \(bu 2
\fBytype\fP: Yield type. Creates a link if possible.
.UNINDENT
.sp
\fBtype\fP, \fBrtype\fP, and \fBytype\fP should be concise and literal type
definitions, like \fBint\fP, \fBint(64)\fP, \fBbool\fP, \fB[] int\fP, \fBRandomStream\fP,
etc. More verbose descriptions, qualifications, and limitations of those types
should go in the corresponding \fBarg\fP, \fBreturns\fP, or \fByields\fP field.
.sp
For example, when documenting a Chapel proc:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/*
 * Calculates number of pipes and returns fooy.
 *
 * :arg bars: Number of bars. Must be more than 1 and less than 1000.
 * :type bars: int
 *
 * :arg hours: Hours available. Default is 1.0.
 * :type hours: real
 *
 * :returns: Amount of fooy available.
 * :rtype: Foo
 */
proc foo(bars, hours=1.0): Foo
{
  ...
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Leave an empty line above and below all these fields for best results.
.IP \(bu 2
All of these fields must be left\-aligned with the outer most paragraph(s).
.UNINDENT
.UNINDENT
.UNINDENT
.SS Paragraph level markup
.sp
These directives create short paragraphs and can be used inside information
units as well as normal text:
.sp
\fBnote\fP
.INDENT 0.0
.INDENT 3.5
An especially important bit of information about an API that a user should be
aware of when using whatever bit of API the note pertains to.  The content of
the directive should be written in complete sentences and include all
appropriate punctuation.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. note::

   This function is not suitable for high precision calculations.
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBwarning\fP
.INDENT 0.0
.INDENT 3.5
An important bit of information about an API that a user should be aware of
when using whatever bit of API the warning pertains to.  The content of the
directive should be written in complete sentences and include all appropriate
punctuation.  In the interest of not scaring users away from pages filled
with warnings, this directive should only be chosen over \fBnote\fP for
information regarding the possibility of crashes, data loss, or security
implications.
.UNINDENT
.UNINDENT
.sp
\fBversionadded\fP
.INDENT 0.0
.INDENT 3.5
This directive documents the version of Chapel which added the described
feature, or a part of it, to the library or API. When this applies to an
entire module, it should be placed at the top of the module section before
any prose.
.sp
The first argument must be given and is the version in question; if the
addition is only part of the described API element, you should add a second
argument consisting of a \fIbrief\fP explanation of the change.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. versionadded:: 2.1
   Multi\-precision integer support added.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that there must be no blank line between the directive head and the
explanation; this is to make these blocks visually continuous in the markup.
.UNINDENT
.UNINDENT
.sp
\fBversionchanged\fP
.INDENT 0.0
.INDENT 3.5
Similar to \fBversionadded\fP, but describes when and what changed in the named
feature in some way (changed side effects, platform support, etc.).  This one
\fImust\fP have the second argument (explanation of the change).
.UNINDENT
.UNINDENT
.sp
\fBseealso\fP
.INDENT 0.0
.INDENT 3.5
Many sections include a list of references to module documentation or
external documents.  These lists are created using the \fBseealso\fP directive.
.sp
The \fBseealso\fP directive is typically placed in a section just before any
sub\-sections.  For the HTML output, it is shown boxed off from the main flow
of the text.
.sp
The content of the \fBseealso\fP directive should be a reST definition list.
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. seealso::

   Module :mod:\(gaRandom\(ga
      Documentation of the :mod:\(gaRandom\(ga standard module.

   \(gaMersenne Twister pseudo random number generator <http://link>\(ga_
      Documentation for the PRNG.
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Advanced chpldoc options
.sp
If you would like to restrict documentation to multi\-line comments starting
only with a special character sequence (say, \fB/***\fP) use the
\fB\-\-docs\-comment\-style\fP flag to indicate the desired prefix (e.g.,
\fB\-\-docs\-comment\-style=\(aq/***\(aq\fP). Setting a comment style in this way also
establishes that the closing comment style should have the same number of
characters (though they can be different ones).
.SS How chpldoc works
.sp
The Chapel standard library documentation is generated by running chpldoc over
all Chapel source files in \fB$CHPL_HOME/modules/standard/\fP\&.
.sp
The markup used in the comments is \fI\%reStructuredText\fP\&. reStructuredText is
developed by the \fI\%docutils\fP projects and is amended by custom directives to
support documenting Chapel code. \fI\%Sphinx\fP is used by \fBchpldoc\fP to render
reStructuredText as HTML.
.SS Future directions
.sp
If there are other features you would like, please let us know. These are
currently on our backlog:
.INDENT 0.0
.IP \(bu 2
Expand visibility control (public/private) to remaining Chapel symbols
(with options for including private elements in output if desired).
.IP \(bu 2
Ability to include doctests, which would be code snippets in documentation
that can be tested. This is similar to Python\(aqs doctest feature.
.UNINDENT
.SS chplvis
.SS A Task and Communication Debug Tool for Chapel
.sp
\fBchplvis\fP is a tool to help the Chapel programmer visualize their
Chapel program\(aqs tasks and communication between locales.  Using the
standard module \fBVisualDebug\fP, the programmer controls what part
of their program generates information for chplvis.  During the run of
a program using the \fBVisualDebug\fP module, data files are
created that are used as input for \fBchplvis\fP\&.  This document
will help you understand the \fBVisualDebug\fP module and the
\fBchplvis\fP tool.
.SS Setup
.sp
\fBchplvis\fP is built by giving the command \fBmake chplvis\fP at the top level of
the chapel tree.  This also builds the GUI tool, \fIFLTK\fP, required to build and
run \fBchplvis\fP\&.  (Note: Some versions of Linux may require the standard
package \fBlibx11\-dev\fP to be installed before \fIFLTK\fP will compile properly.)
To get the most out of this primer, you should compile and run the example
programs and examine the \fBVisualDebug\fP results with \fBchplvis\fP\&.  The
example programs are found on the path \fBexamples/primers/chplvis\fP\&.  The
graphics in this primer were produced on a system using the \fBfifo\fP threads
instead of the default, \fBqthreads\fP, for the tasking layer.   If you use
\fBqthreads\fP, your task count may differ from the examples.
.SS Chapel Source Code
.sp
To use \fBchplvis\fP, the programmer adds code to their program.  In many
cases, the programmer may want to investigate only part of the program.  This
is accomplished by having functions \fBstartVdebug\fP and
\fBstopVdebug\fP to control where to start and stop the
instrumentation of their program.  Compilation and execution of these programs
remain the same.  When the \fBstartVdebug\fP is executed, a
collection of files, one per locale, are created in a directory with the
\fBname\fP given in \fBstartVdebug\fP\&.
.SS Example 1
.sp
Consider the chapel program \fBprog1.chpl\fP: (The example programs in this
primer are found in the directory \fBexamples/primers/chplvis\fP in your
distribution tree.  The files have more comments than are shown here.)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
//  Example 1 using visual debug

use VisualDebug;

startVdebug("E1");

coforall loc in Locales do
  on loc do writeln("Hello from locale " + here.id + ".");

stopVdebug();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Compiling the program and running it with the options \fB\-nl 6\fP will then
produce a directory called \fBE1\fP containing 6 data files, one
for each of the locales and named \fBE1\-n\fP where \fBn\fP is
replaced with the locale number, a number from 0 to 5.  Once this
directory is created, one can run chplvis as \fBchplvis E1\fP or
simply \fBchplvis\fP and then opening the file \fBE1/E1\-0\fP
from the \fBfile/open\fP menu.  The resulting display is:
[image]
.sp
(Note: This image is from an X11 display.  On OS\-X, the menu bar
will be on the normal menu bar at the top of the screen and will
not show in the main window.)
.SS chplvis Elements
.INDENT 0.0
.IP \(bu 2
The \fIinformation\fP box shows the file set opened, which tag (see
\fI\%Example 2\fP ) is displayed, and provides a color bar to help visually
see what values are displayed for locales and communication.
.IP \(bu 2
A \fILocale\fP is represented by a colored box in the main display.  The
initial display draws the color of the locale to represent the
number of tasks run at that locale.  For example 1, we can see that
locale 0 has the most tasks and we expect that to be 12 since that
is the maximum number of tasks as shown by the color reference in
the information box at the top of the window.  Hover your mouse over
a locale and it will display a "tooltip" that is the value for
that locale.
.IP \(bu 2
\fICommunication links\fP are shown by lines between two
locale boxes.  The color of the line adjacent to a locale box
represents the data being sent to that locale from the locale on
the other end.   For example 1, the line between locale 0 and
locale 1 is colored red next to locale 0.  This means that there
is a lot of communications \fIinto locale 0\fP from locale 1.
The blue line next to locale 1 means that there is little
communication \fIinto locale 1\fP from locale 0.
.sp
\fBNOTE:\fP
.INDENT 2.0
.INDENT 3.5
If two locales do not communicate, no line is drawn between them.  If
communication is only one way, the communication color for \fIno
communication\fP is gray.
.UNINDENT
.UNINDENT
.IP \(bu 2
The \fIData menu\fP controls what data is used for the display colors
and available tooltip values.  This initial data is number of tasks
for locales and number of communications calls for the communication
links.  For locales, one can select number of tasks, CPU time, clock
time or concurrency.  Clock time is normally very close to equal
across all locales.  For the communication links, one can select
number of communications or size of data sent.
.UNINDENT
.SS Display Interaction
.sp
Clicking on elements of the display will bring up more information.
Clicking on a locale will open a new window for that locale showing
information for that locale.  In example 1, clicking on locale 0 when
the locale data is \(aqnumber of tasks\(aq, \(aqCPU time\(aq or \(aqclock time\(aq will
produce a window that looks like:
[image]
.sp
(Note: There is overhead generated in tasks, CPU time, clock time and
communication for the Visual Debug function calls.  \fBchplvis\fP removes
the overhead tasks and communication from displayed values, but it can
not remove the CPU and clock time overhead.)
.sp
When the locale data selected is \(aqconcurrency\(aq, clicking on a locale
will bring up a window that shows a task time line for the locale.
This display shows the order the tasks are executed and the color of
each task shows the clock time for that task.  The black vertical vertical
lines show the life time of the task.  There are two kinds of tasks
shown: tasks forked to this locale indicated by an \fIF\fP and tasks
started locally indicated by an \fIL\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The task order may change from run to run.  The following shows one possible
execution order of the tasks:
.UNINDENT
.UNINDENT
[image]
.sp
Note the special \fIMain\fP task.  It is shown as a square gray box because
it was already running at the start of the displayed data.
.sp
In this concurrency display, hovering the mouse over a task will bring
up a "tooltip" that shows the clock time taken by that task, the
number of \fIgets\fP, \fIputs\fP and \fIforks\fP performed by that task and if
available, the source file name and line number of the code that
started that task.  If the task has communication, clicking on the
task will cause the task\(aqs communications to be listed in the window
similar to the following:
[image]
.sp
The number in brackets is the clock time since the task started
execution.   This list gives details about the \fIgets\fP, \fIputs\fP and
\fIforks\fP initiated by this task.
.sp
In the main window, clicking on a communication line will create a
window with communication information for that link.  Clicking red
part of the line between locale 0 and locale 1 will produce a window
that looks like:
[image]
.sp
It is important to notice the direction of the \fIarrow\fP in the header
for the windows.  This is for communication from locale 1 to locale 0.
The total number of communication calls was 12.  It is further broken
out into three components:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fIGets:\fP This is a communication call initiated by locale 0 to
get a data located on locale 1.
.IP \(bu 2
\fIPuts:\fP This is a communication call initiated by \fIlocale 1\fP
to put data from locale 1 onto locale 0.
.IP \(bu 2
\fIForks:\fP This where \fIlocale 1\fP starts a task running
on locale 0.  As part of the task start, a block of data is sent to
locale 0 as an argument to the task.  This data is considered a
communication call  by \fIchplvis\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Example 2
.sp
In many programs, one will want to look at a number of small parts of
their program in addition to seeing the total statistics.  \fBprog2.chpl\fP
gives an example of using the \fBVisualDebug\fP functions
\fBtagVdebug\fP and \fBpauseVdebug\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Example 2 of use of VisualDebug module and chplvis tool.

use BlockDist;
use VisualDebug;

config var ncells = 10;

proc main() {

   // Create a couple of domains and a block mapped data array.
   const Domain = { 1 .. ncells };
   const mapDomain = Domain dmapped Block(Domain);

   var  data : [mapDomain] int = 1;

   // Start VisualDebug here
   startVdebug ("E2");

   // First computation step ... a simple forall
   forall i in Domain do data[i] += here.id + 1;

   // Write the result, we want to see the results of the above
   // so we tag before we continue.
   tagVdebug("writeln 1");
   writeln("data= ", data);

   // Second computation step ... using the distributed domain
   tagVdebug("step 2");
   forall i in mapDomain do data[i] += here.id+1;

   // Don\(aqt capture the writeln
   pauseVdebug();
   writeln("data2= ", data);

   // Reduction step
   tagVdebug("reduce");
   var i = + reduce data;

   // done with visual debug
   stopVdebug();

   writeln ("sum is " + i + ".");
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the \fBstartVdebug("E2")\fP is placed after the declarations
so that tasks and communication for the declarations are not included.
The initial display of \fBchplvis\fP shows data for the entire run. (This
program was run on five locales.)
[image]
.sp
There is now a new menu called \fITags\fP that reflects the
\fBtagVdebug()\fP calls in the program.  Selecting the tags menu
gives the following display:
[image]
.sp
There are two special tags in this menu, \fIAll\fP and \fIStart\fP\&.  \fIAll\fP
shows the initial display for the entire run and \fIStart\fP shows the
tasks and communication only between the \fBstartVdebug("E2")\fP call and
the first call to \fBtagVdebug()\fP, in this case, \fBtagVdebug("writeln
1")\fP\&.  The display for the \fIStart\fP tag looks like:
[image]
.sp
You should be able to immediately see that
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Locale 0 has 3 tasks and all other locales do not have any tasks.
(Task boxes colored white mean no tasks.)
This means that locale 0 is doing all the computation.
.IP \(bu 2
The majority of communication is happening from other locales to
locale 0.  By clicking on the communication links you should be
to easily see that locale 0 is doing gets and puts for all the
communication.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Compare the results of this first \fBforall\fP loop with the loop in the second
computation step, tagged \fIstep 2\fP\&.  Notice, \fIstep 2\fP does not include the
second \fBwriteln\fP because of the call to \fBpauseVdebug()\fP\&.
That suspends collecting task and communication data until the next
\fBtagVdebug()\fP call.
[image]
.sp
The difference between the two loops is the domain used.   \fIDomain\fP
is not a distributed domain, so the computation remains on locale 0.
The \fBmapDomain\fP is a distributed domain, so the computation is
distributed.  One needs to be careful in specifying these kind of loops
to make sure you use a distributed domain if you are operating on
distributed data and you want distributed computation.  This is
where \fBchplvis\fP can quickly let you know if you used the wrong
domain in your \fBforall\fP loop.
.sp
Now, consider the \fIwriteln 1\fP tag display.
[image]
.sp
Notice the gray communication links.  This means there was no data
flow from locale 0 to the other locales.   The gray links are provided
to make it easy to visually see the corresponding locale.
.sp
Finally, for completeness, look at the display for the last tag
used, \fIreduce\fP\&.  It is very similar to the \fIstep 2\fP
tag.
[image]
.SS Example 3
.sp
The program prog3.chpl is similar to the program
\fBexamples/programs/jacobi.chpl\fP\&.  This version uses dmapped domains
and VisualDebug.  Only parts of the code are shown to illustrate
other \fBchplvis\fP features.  First, config variables are handy here so one
can create different directories of chplvis data on different runs.
Although not shown here, config params are useful to allow your
program to use VisualDebug and generate data only if you need it.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Allow different runs to create different data directories so it is
// easier to compare runs with chplvis.
config var dirname = "E3";

// Start VisualDebug here to see that distributed domain and variable
// declarations generate tasks and communication.
startVdebug(dirname);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Next, if \fBtagVdebug()\fP calls are made inside a loop, it
produces a unique tag for each call.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Main computation loop \-\- we want to see the two parts of this
// loop, the computation and the reduction part.

while (delta > epsilon) {

  // Tag the computation part of this loop
  tagVdebug("computation");

  for t in 1 .. compLoop do {
    forall (i,j) in R do
      A(i,j) = Temp(i,j);
    forall (i,j) in R do
      Temp(i,j) = (A(i\-1,j) + A(i+1,j) + A(i,j\-1) + A(i,j+1)) / 4.0;
  }

  // tag the reduction part of this loop.
  tagVdebug("max");
  forall (i,j) in R {
    Diff(i,j) = abs(Temp(i,j)\-A(i,j));
  }
  delta = max reduce Diff;

  pauseVdebug();
  iteration += compLoop;
  if (verbose) {
    writeln("iteration: ", iteration);
    writeln("delta:     ", delta);
    writeln(Temp);
  }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
We use \fBpauseVdebug()\fP here to make sure chplvis data is generated for
the parts of the loop of interest.
.sp
This example was run with the command line arguments \fB\-\-n=8 \-nl 8\fP\&.
The following shows the default \fItags\fP menu for this run:
[image]
.sp
Notice that the tags are now numbered and the tags menu extends past
the end of the window. (This screenshot does not show the entire tags
menu that was displayed on the screen.)  \fIAll\fP and \fIStart\fP remain the
same, but since two or more tags have the same name, \fBchplvis\fP shows a
unique tag for each \fBtagVdebug()\fP call.  Notice the new menu
item above \fIAll\fP which is highlighted in this example.  \fIMerge Tags\fP allows you
to see data for tags with the same name to be merged together.  For this
example, with merged tags, the tags menu now looks like:
[image]
.sp
Now, selecting the tag \fIcomputation\fP will show the accumulated tasks and
communication for the entire \fIwhile\fP loop for just the computation
part of the loop.  This is all code between the \fBtagVdebug("computation")\fP
call and the \fBtagVdebug("max")\fP call.   Selecting the tag \fImax\fP will
then show accumulated tasks and communication for the code between
the \fBtagVdebug("max")\fP call and the \fBpauseVdebug()\fP call.
The following shows the display for the \fIcomputation\fP tags and displaying \fICPU\fP
data.
[image]
.sp
The concurrency display is not available for tags in the "merge tag mode"
except the \fIAll\fP tag, which is the same for both tags mode.
.sp
This example has some extra config variables that can be used to help
understand the usefulness of \fBchplvis\fP\&.  For example, one can compare
the CPU time used between the \fIcomputation\fP and \fImax\fP phases of this
Jacobi computation.  The config variable \fIcompLoop\fP allows one to run
the computation loop more than once before then checking for convergence
in the \fImax\fP tagged code.  It is known that the Jacobi code will not
diverge and thus extra computation steps will not produce a "wrong"
answer.  By doing extra computation, the result will be a bit more
accurate.  The reader should use the \fIcompLoop\fP and the \fIdirname\fP
config variables to run several versions of this program yielding
a \fBchplvis\fP directory for each run.  Then one can compare the different
results by running \fBchplvis\fP multiple times.  By a good choice of
the \fIcompLoop\fP variable, one can dramatically reduce the CPU time for
computing the \fImax\fP while not increasing the \fIcomputation\fP time by much.
.SS Example 4
.sp
To help show another feature of the "\fI\%Concurrency View\fP", prog4.chpl was
written to create a \fIbegin\fP task on all locales and have those tasks
live across calls to the \fBVisualDebug\fP module.  The code is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Example 4, begin tasks as shown in chplvis
// This is a contrived example to have tasks live
// across a tagVdebug() call.

use VisualDebug;
use BlockDist;

const space =  { 0 .. #numLocales };
const Dspace = space dmapped Block (boundingBox=space);

startVdebug("E4");

var go$: [Dspace] single bool;
var done$: [Dspace] single bool;

// Start a begin task on all locales.  The task will start and then block.
coforall loc in Locales do
  on loc do begin { // start a async task

           go$[here.id]; // Block until ready!
           writeln ("Finishing running the \(aqbegin\(aq statement on locale "
                     + here.id + ".");
           done$[here.id] = true;
        }

tagVdebug("loc");

coforall loc in Locales do
    on loc do writeln("Hello from " + here.id);

tagVdebug("finish");

// Let all tasks go
go$ = true;

// Wait until all tasks are finished
done$;

stopVdebug();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
First we will look at the results of running this code on a single
locale.  Even though there is no communication, \fBchplvis\fP can help
you see how tasks are run, especially how much concurrency you have.
[image]
.sp
This view shows the tasks for locale 0, the only locale in this run.
Things to notice from this view are
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Main represents the main program.  It is shown as a gray rectangular
box to show that it was running at the time of
\fBstartVdebug()\fP was called.
.IP \(bu 2
In the \fItag ALL\fP view, tags are shown in the sequence of tasks.
.IP \(bu 2
Task \fIF 28\fP is started before the \fIloc\fP tag, but it finishes
in the \fIfinish\fP tag.
.UNINDENT
.UNINDENT
.UNINDENT
[image]
.sp
This view shows the tasks for locale 1 on a 3 locale run for the tag
\fIloc\fP\&.  In this view, the task started before the \fIloc\fP tag appears
as a gray rectangular box at the top of the view.  This indicates
that is was running at the start of the tag.  The lack of a task
termination horizontal line on the task line indicates that the task
continued running past the end of the tag.  Tasks that are running
at the beginning of a tag and terminate during a tag can be seen
by the horizontal termination line, such as for task \fIC50\fP, a
\fIcontinued\fP task for locale 0 on the same 3 locale run as seen next.
[image]
.sp
\fIMain\fP will always show as a continued task with no termination.
\fIMain\fP is shown only for locale 0.  \fIMain\fP is included in the
calculation of concurrency as seen above.
.SS Config Parameters and Variables
.sp
Because \fBVisualDebug\fP support requires added procedure calls in source to
use it, there is a boolean config const, \fBVisualDebugOn\fP
that controls generation of \fBVisualDebug\fP data.
This may be set on the execution command line like any config const.
The standard default value is \fItrue\fP\&.
This default value may be changed at compile time
by setting the config param \fBDefaultVisualDebugOn\fP\&.
If this is set to \fIfalse\fP at compile time
then \fBVisualDebugOn\fP must be set to \fItrue\fP
on the execution command line to generate \fBVisualDebug\fP data.
.SS Final Comments
.sp
The following items are not covered above:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
By clicking on the locale box or a communication link, a window
with more detailed information is presented.  To make it easier
to close those windows, a second click on the same location will
close the window.   The \fIWindows\fP menu allows one to close
or show all previously created locale and communication windows.
.IP \(bu 2
The command line for \fBchplvis\fP is:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
chplvis [name]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where \fIname\fP may be the name of the directory or a file in the
directory generated by a run of a program using \fBVisualDebug\fP\&.
If \fIname\fP is not given, it looks for the directory named
\fB\&.Vdebug\fP which is generated if the \fBstartVdebug\fP
function is given a string of zero length.  ("")
.IP \(bu 2
In all the examples given, all calls to \fBxVdebug()\fP routines were
essentially in the \fBmain\fP program.   While this will not be the case
in all programs, a couple of things should be noted.
.INDENT 2.0
.IP \(bu 2
All calls run code on all locales.
.IP \(bu 2
All calls should be made from locale 0.
.IP \(bu 2
Calls should not be made in \fBon\fP statements.  While such programs
should run, the \fBchplvis\fP data will mostly likely not make much
sense.
.IP \(bu 2
Calls should not be made in \fBbegin\fP statements for similar reasons.
.IP \(bu 2
Calls should not be made in forall or coforall statements.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBchplvis\fP was created in 2015 and first released with Chapel\-1.12.0.
The Chapel team hopes this tool will be of use to Chapel programmers
and would like feedback on this tool.
.INDENT 0.0
.TP
.B Author
Philip A. Nelson
.UNINDENT
.SH CHAPEL QUICK REFERENCE
.sp
\fBView Quick Reference [pdf]\fP
.SH CHAPEL LANGUAGE SPECIFICATION
.sp
\fBView Language Specification [pdf]\fP
.sp
To see language specifications of previous versions, see Archived Languages Specifications\&.
.SH BUILT-IN TYPES AND FUNCTIONS
.sp
The following sections describe built\-in language features which are
amenable to being documented using \fBchpldoc\fP:
.SS Atomics
.sp
Atomic variables are variables that support atomic operations. Chapel
currently supports atomic operations for bools, all supported sizes of
signed and unsigned integers, as well as all supported sizes of reals.
.sp
Most atomic methods accept an optional argument named \fBorder\fP of type
\fBmemory_order\fP\&. The \fBorder\fP argument is used to specify the ordering
constraints of atomic operations. The supported values are:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
memory_order_relaxed
.IP \(bu 2
memory_order_acquire
.IP \(bu 2
memory_order_release
.IP \(bu 2
memory_order_acq_rel
.IP \(bu 2
memory_order_seq_cst
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B atomic (bool)
The boolean atomic type.
.INDENT 7.0
.TP
.B proc read(order: memory_order = memory_order_seq_cst): bool
.INDENT 7.0
.TP
.B Returns
The stored value.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc write(value: bool, order: memory_order = memory_order_seq_cst)
Stores \fIvalue\fP as the new value.
.UNINDENT
.INDENT 7.0
.TP
.B proc exchange(value: bool, order: memory_order = memory_order_seq_cst): bool
Stores \fIvalue\fP as the new value and returns the original value.
.UNINDENT
.INDENT 7.0
.TP
.B proc compareExchange(expected: bool, desired: bool, order: memory_order = memory_order_seq_cst): bool
Equivalent to \fI\%compareExchangeStrong\fP
.UNINDENT
.INDENT 7.0
.TP
.B proc compareExchangeWeak(expected: bool, desired: bool, order: memory_order = memory_order_seq_cst): bool
Similar to \fI\%compareExchangeStrong\fP, except that this function may
return \fIfalse\fP even if the original value was equal to \fIexpected\fP\&. This
may happen if the value could not be updated atomically.
.UNINDENT
.INDENT 7.0
.TP
.B proc compareExchangeStrong(expected: bool, desired: bool, order: memory_order = memory_order_seq_cst): bool
Stores \fIdesired\fP as the new value, if and only if the original value is
equal to \fIexpected\fP\&. Returns \fItrue\fP if \fIdesired\fP was stored.
.UNINDENT
.INDENT 7.0
.TP
.B proc testAndSet(order: memory_order = memory_order_seq_cst)
Stores \fItrue\fP as the new value and returns the old value.
.UNINDENT
.INDENT 7.0
.TP
.B proc clear(order: memory_order = memory_order_seq_cst)
Stores \fIfalse\fP as the new value.
.UNINDENT
.INDENT 7.0
.TP
.B proc waitFor(val: bool, order: memory_order = memory_order_seq_cst)
.INDENT 7.0
.TP
.B Arguments
\fBval\fP \-\- Value to compare against.
.UNINDENT
.sp
Waits until the stored value is equal to \fIval\fP\&. The implementation may
yield the running task while waiting.
.UNINDENT
.INDENT 7.0
.TP
.B proc peek()
.INDENT 7.0
.TP
.B Returns
Stored value using memory_order_relaxed.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc poke(value: bool)
Stores \fIvalue\fP as the new value using memory_order_relaxed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B atomic (T)
.INDENT 7.0
.TP
.B proc read(order: memory_order = memory_order_seq_cst): T
.INDENT 7.0
.TP
.B Returns
The stored value.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc write(value: T, order: memory_order = memory_order_seq_cst)
Stores \fIvalue\fP as the new value.
.UNINDENT
.INDENT 7.0
.TP
.B proc exchange(value: T, order: memory_order = memory_order_seq_cst): T
Stores \fIvalue\fP as the new value and returns the original value.
.UNINDENT
.INDENT 7.0
.TP
.B proc compareExchange(expected: T, desired: T, order: memory_order = memory_order_seq_cst): bool
Equivalent to \fI\%compareExchangeStrong\fP
.UNINDENT
.INDENT 7.0
.TP
.B proc compareExchangeWeak(expected: T, desired: T, order: memory_order = memory_order_seq_cst): bool
Similar to \fI\%compareExchangeStrong\fP, except that this function may
return \fIfalse\fP even if the original value was equal to \fIexpected\fP\&. This
may happen if the value could not be updated atomically.
.UNINDENT
.INDENT 7.0
.TP
.B proc compareExchangeStrong(expected: T, desired: T, order: memory_order = memory_order_seq_cst): bool
Stores \fIdesired\fP as the new value, if and only if the original value is
equal to \fIexpected\fP\&. Returns \fItrue\fP if \fIdesired\fP was stored.
.UNINDENT
.INDENT 7.0
.TP
.B proc fetchAdd(value: T, order: memory_order = memory_order_seq_cst): T
.INDENT 7.0
.TP
.B Returns
The original value.
.UNINDENT
.sp
Adds \fIvalue\fP to the original value and stores the result. Defined for
integer and real atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc add(value: T, order: memory_order = memory_order_seq_cst): void
Adds \fIvalue\fP to the original value and stores the result. Defined for
integer and real atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc fetchSub(value: T, order: memory_order = memory_order_seq_cst): T
.INDENT 7.0
.TP
.B Returns
The original value.
.UNINDENT
.sp
Subtracts \fIvalue\fP from the original value and stores the result. Defined
for integer and real atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc sub(value: T, order: memory_order = memory_order_seq_cst): void
Subtracts \fIvalue\fP from the original value and stores the result. Defined
for integer and real atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc fetchOr(value: T, order: memory_order = memory_order_seq_cst): T
.INDENT 7.0
.TP
.B Returns
The original value.
.UNINDENT
.sp
Applies the \fB|\fP operator to \fIvalue\fP and the original value, then stores
the result.
.sp
Only defined for integer atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc or(value: T, order: memory_order = memory_order_seq_cst): void
Applies the \fB|\fP operator to \fIvalue\fP and the original value, then stores
the result.
.sp
Only defined for integer atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc fetchAnd(value: T, order: memory_order = memory_order_seq_cst): T
.INDENT 7.0
.TP
.B Returns
The original value.
.UNINDENT
.sp
Applies the \fB&\fP operator to \fIvalue\fP and the original value, then stores
the result.
.sp
Only defined for integer atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc and(value: T, order: memory_order = memory_order_seq_cst): void
Applies the \fB&\fP operator to \fIvalue\fP and the original value, then stores
the result.
.sp
Only defined for integer atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc fetchXor(value: T, order: memory_order = memory_order_seq_cst): T
.INDENT 7.0
.TP
.B Returns
The original value.
.UNINDENT
.sp
Applies the \fB^\fP operator to \fIvalue\fP and the original value, then stores
the result.
.sp
Only defined for integer atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc xor(value: T, order: memory_order = memory_order_seq_cst): void
Applies the \fB^\fP operator to \fIvalue\fP and the original value, then stores
the result.
.sp
Only defined for integer atomic types.
.UNINDENT
.INDENT 7.0
.TP
.B proc waitFor(val: T, order: memory_order = memory_order_seq_cst)
Waits until the stored value is equal to \fIval\fP\&. The implementation may
yield the running task while waiting.
.UNINDENT
.INDENT 7.0
.TP
.B proc peek()
.INDENT 7.0
.TP
.B Returns
Stored value using memory_order_relaxed.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc poke(value: T)
Stores \fIvalue\fP as the new value using memory_order_relaxed.
.UNINDENT
.UNINDENT
.SS Domain and Array Operations
.SS Distribution, Domain and Array Equality operators
.sp
Equality operators are defined to test if two distributions
are equivalent or not:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dist1 == dist2
dist1 != dist2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or to test if two domains are equivalent or not:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dom1 == dom2
dom1 != dom2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Arrays are promoted, so the result of the equality operators is
an array of booleans.  To get a single result use the \fBequals\fP
method instead.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
arr1 == arr2 // compare each element resulting in an array of booleans
arr1 != arr2 // compare each element resulting in an array of booleans
arr1.equals(arr2) // compare entire arrays resulting in a single boolean
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Miscellaneous Domain and Array Operators
.SS The domain count operator \fB#\fP
.sp
The \fB#\fP operator can be applied to dense rectangular domains
with a tuple argument whose size matches the rank of the domain
(or optionally an integer in the case of a 1D domain). The operator
is equivalent to applying the \fB#\fP operator to the component
ranges of the domain and then using them to slice the domain.
.SS The array count operator \fB#\fP
.sp
The \fB#\fP operator can be applied to dense rectangular arrays
with a tuple argument whose size matches the rank of the array
(or optionally an integer in the case of a 1D array). The operator
is equivalent to applying the \fB#\fP operator to the array\(aqs domain
and using the result to slice the array.
.SS The array swap operator \fB<=>\fP
.sp
The \fB<=>\fP operator can be used to swap the contents of two arrays
with the same shape.
.SS The array alias operator \fB=>\fP
.sp
The \fB=>\fP operator can be used in a variable declaration to create
a new alias of an array. The new variable will refer to the same
array elements as the aliased array.  In the following example,
the variable \fBInner\fP refers to the inner 9 elements of \fBA\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var A: [0..10] int;
var Inner => A[1..9];
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Set Operations on Associative Domains and Arrays
.sp
Associative domains and arrays support a number of operators for
set manipulations.  The supported set operators are:
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
+ |
T}	T{
Union
T}
_
T{
&
T}	T{
Intersection
T}
_
T{
\-
T}	T{
Difference
T}
_
T{
^
T}	T{
Symmetric Difference
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
Consider the following code where \fBA\fP and \fBB\fP are associative arrays:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var C = A op B;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The result \fBC\fP is a new associative array backed by a new associative
domain. The domains of \fBA\fP and \fBB\fP are not modified by \fBop\fP\&.
.sp
There are also op= variants that store the result into the first operand.
.sp
Consider the following code where \fBA\fP and \fBB\fP are associative arrays:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
A op= B;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBA\fP must not share its domain with another array, otherwise the program
will halt with an error message.
.sp
For the \fB+=\fP and \fB|=\fP operators, the value from \fBB\fP will overwrite
the existing value in \fBA\fP when indices overlap.
.SS Functions and Methods on Arrays and Domains
.INDENT 0.0
.TP
.B proc isRectangularDom(d: domain) param
Return true if the argument \fBd\fP is a rectangular domain.
Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isRectangularArr(a: []) param
Return true if the argument \fBa\fP is an array with a rectangular
domain.  Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isIrregularDom(d: domain) param
Return true if \fBd\fP is an irregular domain; e.g. is not rectangular.
Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isIrregularArr(a: []) param
Return true if \fBa\fP is an array with an irregular domain; e.g. not
rectangular. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isAssociativeDom(d: domain) param
Return true if \fBd\fP is an associative domain. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isAssociativeArr(a: []) param
Return true if \fBa\fP is an array with an associative domain. Otherwise
return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isEnumDom(d: domain) param
Return true if \fBd\fP is an associative domain defined over an enumerated
type. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isEnumArr(a: []) param
Return true if \fBa\fP is an array with an enumerated domain. Otherwise
return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isOpaqueDom(d: domain) param
Return true if \fBd\fP is an opaque domain. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isSparseDom(d: domain) param
Return true if \fBd\fP is a sparse domain. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isSparseArr(a: []) param
Return true if \fBa\fP is an array with a sparse domain. Otherwise
return false.
.UNINDENT
.INDENT 0.0
.TP
.B type domain
.INDENT 7.0
.TP
.B proc dist
Return the domain map that implements this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc rank param
Return the number of dimensions in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc idxType type
Return the type of the indices of this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc stridable param
Return true if this is a stridable domain
.UNINDENT
.INDENT 7.0
.TP
.B proc clear()
Remove all indices from this domain, leaving it empty
.UNINDENT
.INDENT 7.0
.TP
.B proc add(i)
Add index \fBi\fP to this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc bulkAdd(inds: [] _value.idxType, isSorted = false, isUnique = false, preserveInds = true)
.UNINDENT
.INDENT 7.0
.TP
.B proc bulkAdd(inds: [] _value.rank*(_value.idxType), isSorted = false, isUnique = false, preserveInds = true)
.UNINDENT
.INDENT 7.0
.TP
.B proc remove(i)
Remove index \fBi\fP from this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc requestCapacity(i)
Request space for a particular number of values in an
domain.
.sp
Currently only applies to associative domains.
.UNINDENT
.INDENT 7.0
.TP
.B proc size
Return the number of indices in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc numIndices
Return the number of indices in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc low
Return the lowest index in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc high
Return the highest index in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc stride
Return the stride of the indices in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc alignment
Return the alignment of the indices in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc first
Return the first index in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc last
Return the last index in this domain
.UNINDENT
.INDENT 7.0
.TP
.B proc alignedLow
Return the low index in this domain factoring in alignment
.UNINDENT
.INDENT 7.0
.TP
.B proc alignedHigh
Return the high index in this domain factoring in alignment
.UNINDENT
.INDENT 7.0
.TP
.B proc member(i: _value.idxType ...rank)
Return true if \fBi\fP is a member of this domain. Otherwise
return false.
.UNINDENT
.INDENT 7.0
.TP
.B proc isSubset(super: domain)
Returns true if this domain is a subset of \fBsuper\fP\&. Otherwise
returns false.
.UNINDENT
.INDENT 7.0
.TP
.B proc isSuper(sub: domain)
Returns true if this domain is a superset of \fBsub\fP\&. Otherwise
returns false.
.UNINDENT
.INDENT 7.0
.TP
.B proc expand(off: rank*(_value.idxType))
Returns a new domain that is the current domain expanded by
\fBoff(d)\fP in dimension \fBd\fP if \fBoff(d)\fP is positive or
contracted by \fBoff(d)\fP in dimension \fBd\fP if \fBoff(d)\fP
is negative.
.UNINDENT
.INDENT 7.0
.TP
.B proc expand(off: _value.idxType)
Returns a new domain that is the current domain expanded by
\fBoff\fP in all dimensions if \fBoff\fP is positive or contracted
by \fBoff\fP in all dimensions if \fBoff\fP is negative.
.UNINDENT
.INDENT 7.0
.TP
.B proc exterior(off: rank*(_value.idxType))
Returns a new domain that is the exterior portion of the
current domain with \fBoff(d)\fP indices for each dimension \fBd\fP\&.
If \fBoff(d)\fP is negative, compute the exterior from the low
bound of the dimension; if positive, compute the exterior
from the high bound.
.UNINDENT
.INDENT 7.0
.TP
.B proc exterior(off: _value.idxType)
Returns a new domain that is the exterior portion of the
current domain with \fBoff\fP indices for each dimension.
If \fBoff\fP is negative, compute the exterior from the low
bound of the dimension; if positive, compute the exterior
from the high bound.
.UNINDENT
.INDENT 7.0
.TP
.B proc interior(off: rank*(_value.idxType))
Returns a new domain that is the interior portion of the
current domain with \fBoff(d)\fP indices for each dimension
\fBd\fP\&. If \fBoff(d)\fP is negative, compute the interior from
the low bound of the dimension; if positive, compute the
interior from the high bound.
.UNINDENT
.INDENT 7.0
.TP
.B proc interior(off: _value.idxType)
Returns a new domain that is the interior portion of the
current domain with \fBoff\fP indices for each dimension.
If \fBoff\fP is negative, compute the interior from the low
bound of the dimension; if positive, compute the interior
from the high bound.
.UNINDENT
.INDENT 7.0
.TP
.B proc translate(off)
Returns a new domain that is the current domain translated by
\fBoff(d)\fP in each dimension \fBd\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B proc translate(off)
Returns a new domain that is the current domain translated by
\fBoff\fP in each dimension.
.UNINDENT
.INDENT 7.0
.TP
.B iter sorted()
Yield the domain indices in sorted order
.UNINDENT
.INDENT 7.0
.TP
.B proc safeCast(type t)
Cast a rectangular domain to another rectangular domain type.
If the old type is stridable and the new type is not stridable,
ensure that the stride was 1.
.UNINDENT
.INDENT 7.0
.TP
.B proc targetLocales()
.UNINDENT
.INDENT 7.0
.TP
.B proc hasSingleLocalSubdomain() param
Return true if the local subdomain can be represented as a single
domain. Otherwise return false.
.UNINDENT
.INDENT 7.0
.TP
.B proc localSubdomain()
Return the subdomain that is local to the current locale
.UNINDENT
.INDENT 7.0
.TP
.B iter localSubdomains()
Yield the subdomains that are local to the current locale
.UNINDENT
.sp
Currently this is not optimized for addition of a sparse
.UNINDENT
.INDENT 0.0
.TP
.B type array
.INDENT 7.0
.TP
.B proc eltType type
The type of elements contained in the array
.UNINDENT
.INDENT 7.0
.TP
.B proc idxType type
The type of indices used in the array\(aqs domain
.UNINDENT
.INDENT 7.0
.TP
.B proc rank param
The number of dimensions in the array
.UNINDENT
.INDENT 7.0
.TP
.B proc numElements
Return the number of elements in the array
.UNINDENT
.INDENT 7.0
.TP
.B proc size
Return the number of elements in the array
.UNINDENT
.INDENT 7.0
.TP
.B proc IRV ref
Return the Implicitly Represented Value for sparse arrays
.UNINDENT
.INDENT 7.0
.TP
.B iter sorted()
Yield the array elements in sorted order.
.UNINDENT
.INDENT 7.0
.TP
.B proc targetLocales()
.UNINDENT
.INDENT 7.0
.TP
.B proc hasSingleLocalSubdomain() param
Return true if the local subdomain can be represented as a single
domain. Otherwise return false.
.UNINDENT
.INDENT 7.0
.TP
.B proc localSubdomain()
Return the subdomain that is local to the current locale
.UNINDENT
.INDENT 7.0
.TP
.B iter localSubdomains()
Yield the subdomains that are local to the current locale
.UNINDENT
.INDENT 7.0
.TP
.B proc isEmpty(): bool
Return true if the array has no elements
.UNINDENT
.INDENT 7.0
.TP
.B proc push_back(val: this.eltType)
Add element \fBval\fP to the back of the array, extending the array\(aqs
domain by one. If the domain was \fB{1..5}\fP it will become \fB{1..6}\fP\&.
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc pop_back()
Remove the last element from the array, reducing the size of the
domain by one. If the domain was \fB{1..5}\fP it will become \fB{1..4}\fP
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc push_front(val: this.eltType)
Add element \fBval\fP to the front of the array, extending the array\(aqs
domain by one. If the domain was \fB{1..5}\fP it will become \fB{0..5}\fP\&.
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc pop_front()
Remove the first element of the array reducing the size of the
domain by one.  If the domain was \fB{1..5}\fP it will become \fB{2..5}\fP\&.
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc insert(pos: this.idxType, val: this.eltType)
Insert element \fBval\fP into the array at index \fBpos\fP\&. Shift the array
elements above \fBpos\fP up one index. If the domain was \fB{1..5}\fP it will
become \fB{1..6}\fP\&.
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc remove(pos: this.idxType)
Remove the element at index \fBpos\fP from the array and shift the array
elements above \fBpos\fP down one index. If the domain was \fB{1..5}\fP
it will become \fB{1..4}\fP\&.
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc remove(pos: this.idxType, count: this.idxType)
Remove \fBcount\fP elements from the array starting at index \fBpos\fP and
shift elements above \fBpos+count\fP down by \fBcount\fP indices.
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc remove(pos: range(this.idxType, stridable = false))
Remove the elements at the indices in the \fBpos\fP range and shift the
array elements down by \fBpos.size\fP elements. If the domain was
\fB{1..5}\fP and this is called with \fB2..3\fP as an argument, the new
domain would be \fB{1..3}\fP and the array would contain the elements
formerly at positions 1, 4, and 5.
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc reverse()
Reverse the order of the values in the array.
.UNINDENT
.INDENT 7.0
.TP
.B proc clear()
Remove all elements from the array leaving the domain empty. If the
domain was \fB{5..10}\fP it will become \fB{5..4}\fP\&.
.sp
The array must be a rectangular 1\-D array; its domain must be
non\-stridable and not shared with other arrays.
.UNINDENT
.INDENT 7.0
.TP
.B proc find(val: this.eltType): (bool, .(this, "idxType"))
Return a tuple containing \fBtrue\fP and the index of the first
instance of \fBval\fP in the array, or if \fBval\fP is not found, a
tuple containing \fBfalse\fP and an unspecified value is returned.
.UNINDENT
.INDENT 7.0
.TP
.B proc count(val: this.eltType): int
Return the number of times \fBval\fP occurs in the array.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc array.equals(that: [])
Return true if all this array is the same size and shape
as argument \fBthat\fP and all elements of this array are
equal to the corresponding element in \fBthat\fP\&. Otherwise
return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isDmapType(type t) param
Return true if \fBt\fP is a domain map type. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isDmapValue(e) param
Return true if \fBe\fP is a domain map. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isDomainType(type t) param
Return true if \fBt\fP is a domain type. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isDomainValue(e) param
Return true if \fBe\fP is a domain. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isArrayType(type t) param
Return true if \fBt\fP is an array type. Otherwise return false.
.UNINDENT
.INDENT 0.0
.TP
.B proc isArrayValue(e) param
Return true if \fBe\fP is an array. Otherwise return false.
.sp
We remove elements in the RHS domain from those in the LHS domain only if
they exist. If an element in the RHS is not present in the LHS, no error
occurs.
.sp
We remove elements in the RHS domain from those in the LHS domain only if
they exist. If an element in the RHS is not present in the LHS, no error
occurs.
.sp
We remove elements in the RHS domain from those in the LHS domain only if
they exist. If an element in the RHS is not present in the LHS, it is
added to the LHS.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
The following procedure is effectively equivalent to:
.IP \(bu 2
.IP \(bu 2
because the parser renames the routine since \(aqby\(aq is a keyword.
.IP \(bu 2
The following procedure is effectively equivalent to:
.IP \(bu 2
.IP \(bu 2
because the parser renames the routine since \(aqalign\(aq is a keyword.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc reshape(A: [], D: domain)
Returns a copy of the array containing the same values but
in the shape of the new domain. The number of indices in the
domain must equal the number of elements in the array. The
elements of the array are copied into the new array using the
default iteration orders over both arrays.
.UNINDENT
.SS Complex
.sp
Complex is a predefined structured type in Chapel. It is specified
in the Types chapter of the Chapel Language Specification.
.INDENT 0.0
.TP
.B record complex
It is defined as if it were a record with two fields.
Note that both of these fields are of type \fIreal\fP\&.
Specifically the imaginary component is not of type \fIimag\fP\&.
This is important when using the getter/setter for the
field \fIim\fP\&.
.INDENT 7.0
.TP
.B var re: real
.UNINDENT
.INDENT 7.0
.TP
.B var im: real
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc complex.re ref
When used as a value, this returns the real component of
the complex number as a \fIreal\fP\&.
.sp
When used as an lvalue, this is a setter that assigns the
real component.
.UNINDENT
.INDENT 0.0
.TP
.B proc complex.im ref
When used as a value, this returns the imaginary component of
the complex number as a \fIreal\fP\&.
.sp
When used as an lvalue, this is a setter that assigns the
imaginary component.
.UNINDENT
.SS Chapel Environment Variables
.sp
The values of Chapel\(aqs environment variables upon compile time are
accessible through the built\-in parameters shown below. This information
can also be displayed from the command line by executing the compiled
program with the \fB\-\-about\fP flag.
.INDENT 0.0
.TP
.B param CHPL_HOME: string
See readme\-chplenv.CHPL_HOME for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_AUX_FILESYS: string
See readme\-chplenv.CHPL_AUX_FILESYS for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_TARGET_PLATFORM: string
See readme\-chplenv.CHPL_TARGET_PLATFORM for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_HOST_PLATFORM: string
See readme\-chplenv.CHPL_HOST_PLATFORM for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_HOST_COMPILER: string
See readme\-chplenv.CHPL_COMPILER for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_TARGET_COMPILER: string
See readme\-chplenv.CHPL_COMPILER for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_TARGET_ARCH: string
See readme\-chplenv.CHPL_TARGET_ARCH for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_LOCALE_MODEL: string
See readme\-chplenv.CHPL_LOCALE_MODEL for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_COMM: string
See readme\-chplenv.CHPL_COMM for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_COMM_SUBSTRATE: string
See readme\-launcher for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_GASNET_SEGMENT: string
See readme\-multilocale for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_TASKS: string
See readme\-chplenv.CHPL_TASKS for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_LAUNCHER: string
See readme\-chplenv.CHPL_LAUNCHER for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_TIMERS: string
See readme\-chplenv.CHPL_TIMERS for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_UNWIND: string
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_MEM: string
See readme\-chplenv.CHPL_MEM for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_MAKE: string
See readme\-chplenv.CHPL_MAKE for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_ATOMICS: string
See readme\-chplenv.CHPL_ATOMICS for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_NETWORK_ATOMICS: string
See readme\-atomics for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_GMP: string
See readme\-chplenv.CHPL_GMP for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_HWLOC: string
See readme\-chplenv.CHPL_HWLOC for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_REGEXP: string
See readme\-chplenv.CHPL_REGEXP for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_WIDE_POINTERS: string
See readme\-chplenv.CHPL_WIDE_POINTERS for more information.
.UNINDENT
.INDENT 0.0
.TP
.B param CHPL_LLVM: string
See readme\-chplenv.CHPL_LLVM for more information.
.UNINDENT
.SS IO Support
.sp
Basic types and utilities in support of I/O operation.
.sp
Most of Chapel\(aqs I/O support is within the \fBIO\fP module.  This section
describes automatically included basic types and routines that support the
\fBIO\fP module.
.SS Writing and Reading
.sp
The \fBwriteln\fP function allows for a simple implementation
of a Hello World program:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
writeln("Hello, World!");
// outputs
// Hello, World!
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBread\fP functions allow one to read values into variables as
the following example demonstrates. It shows three ways to read values into
a pair of variables \fBx\fP and \fBy\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var x: int;
var y: real;

/* reading into variable expressions, returning
   true if the values were read, false on EOF */
var ok:bool = read(x, y);

/* reading via a single type argument */
x = read(int);
y = read(real);

/* reading via multiple type arguments */
(x, y) = read(int, real);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The readThis(), writeThis(), and readWriteThis() Methods
.sp
When programming the input and output method for a custom data type, it is
often useful to define both the read and write routines at the same time. That
is possible to do in a Chapel program by defining a \fBreadWriteThis\fP method,
which is a generic method expecting a single \fBchannel\fP argument.
.sp
In cases when the reading routine and the writing routine are more naturally
separate, or in which only one should be defined, a Chapel program can define
\fBreadThis\fP (taking in a single argument \- a readable channel) and/or
\fBwriteThis\fP (taking in a single argument \- a writeable channel).
.sp
If none of these routines are provided, a default version of \fBreadThis\fP and
\fBwriteThis\fP will be generated by the compiler. If \fBreadWriteThis\fP is
defined, the compiler will generate \fBreadThis\fP or \fBwriteThis\fP methods \- if
they do not already exist \- which call \fBreadWriteThis\fP\&.
.sp
Note that arguments to \fBreadThis\fP and \fBwriteThis\fP may represent a locked
channel; as a result, calling methods on the channel in parallel from within a
\fBreadThis\fP, \fBwriteThis\fP, or \fBreadWriteThis\fP may cause undefined behavior.
.sp
Because it is often more convenient to use an operator for I/O, instead of
writing
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
f.readwrite(x);
f.readwrite(y);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
one can write
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
f <~> x <~> y;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the types \fBIO.ioLiteral\fP and \fBIO.ioNewline\fP may be useful
when using the \fB<~>\fP operator. \fBIO.ioLiteral\fP represents some string
that must be read or written as\-is (e.g. \fB","\fP when working with a tuple),
and \fBIO.ioNewline\fP will emit a newline when writing but skip to and
consume a newline when reading.
.sp
This example defines a readWriteThis method and demonstrates how \fB<~>\fP will
call the read or write routine, depending on the situation.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class IntPair {
  var x: int;
  var y: int;
  proc readWriteThis(f) {
    f <~> x <~> new ioLiteral(",") <~> y <~> new ioNewline();
  }
}
var ip = new IntPair(17,2);
write(ip);
// prints out
// 17,2

delete ip;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example defines a only a writeThis method \- so that there will be a
function resolution error if the class NoRead is read.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
class NoRead {
  var x: int;
  var y: int;
  proc writeThis(f) {
    f.writeln("hello");
  }
  // Note that no readThis function will be generated.
}
var nr = new NoRead();
write(nr);
// prints out
// hello

// Note that read(nr) will generate a compiler error.

delete nr;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Default write and read Methods
.sp
Default \fBwrite\fP methods are created for all types for which a user\-defined
\fBwrite\fP method is not provided.  They have the following semantics:
.INDENT 0.0
.IP \(bu 2
for an array argument: outputs the elements of the array in row\-major order
where rows are separated by line\-feeds and blank lines are used to separate
other dimensions.
.IP \(bu 2
for a \fIdomain\fP argument: outputs the dimensions of the domain enclosed by
\fB[\fP and \fB]\fP\&.
.IP \(bu 2
for a \fIrange\fP argument: output the lower bound of the range, output \fB\&..\fP,
then output the upper bound of the range.  If the stride of the range
is not \fB1\fP, output the word \fBby\fP and then the stride of the range.
.IP \(bu 2
for a tuples, outputs the components of the tuple in order delimited by \fB(\fP
and \fB)\fP, and separated by commas.
.IP \(bu 2
for a class: outputs the values within the fields of the class prefixed by
the name of the field and the character \fB=\fP\&.  Each field is separated by a
comma.  The output is delimited by \fB{\fP and \fB}\fP\&.
.IP \(bu 2
for a record: outputs the values within the fields of the class prefixed by
the name of the field and the character \fB=\fP\&.  Each field is separated by a
comma.  The output is delimited by \fB(\fP and \fB)\fP\&.
.UNINDENT
.sp
Default \fBread\fP methods are created for all types for which a user\-defined
\fBread\fP method is not provided.  The default \fBread\fP methods are defined to
read in the output of the default \fBwrite\fP method.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Note that it is not currently possible to read and write circular
data structures with these mechanisms.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc halt()
Prints an error message to stderr giving the location of the call to
\fBhalt\fP in the Chapel source, followed by the arguments to the call,
if any, then exits the program.
.UNINDENT
.INDENT 0.0
.TP
.B proc halt(s: string)
Prints an error message to stderr giving the location of the call to
\fBhalt\fP in the Chapel source, followed by the arguments to the call,
if any, then exits the program.
.UNINDENT
.INDENT 0.0
.TP
.B proc halt(args ...?numArgs)
Prints an error message to stderr giving the location of the call to
\fBhalt\fP in the Chapel source, followed by the arguments to the call,
if any, then exits the program.
.UNINDENT
.INDENT 0.0
.TP
.B proc warning(s: string)
Prints a warning to stderr giving the location of the call to \fBwarning\fP
in the Chapel source, followed by the argument(s) to the call.
.UNINDENT
.INDENT 0.0
.TP
.B proc warning(args ...?numArgs)
Prints a warning to stderr giving the location of the call to \fBwarning\fP
in the Chapel source, followed by the argument(s) to the call.
.UNINDENT
.SS Vectorizing Iterator
.sp
Data parallel constructs (such as \fBforall\fP loops) are implicitly
vectorizable. If the \fB\-\-vectorize\fP compiler flag is thrown (implied by
\fB\-\-fast\fP), the Chapel compiler will emit vectorization hints to the backend
compiler, though the effects will vary based on the target compiler.
.sp
In order to allow users to explicitly request vectorization, this prototype
vectorizing iterator is being provided. Loops that invoke this iterator will
be marked with vectorization hints, provided the \fB\-\-vectorize\fP flag is
thrown.
.sp
This iterator is currently available for all Chapel programs and does not
require a \fBuse\fP statement to make it available. In future releases it will
be moved to a standard module and will likely require a \fBuse\fP statement to
make it available.
.INDENT 0.0
.TP
.B iter vectorizeOnly(iterables ...)
Vectorize only "wrapper" iterator:
.sp
This iterator wraps and vectorizes other iterators. It takes one or more
iterables (an iterator or class/record with a these() iterator) and yields
the same elements as the wrapped iterables.
.sp
This iterator exists to provide a way to vectorize data parallel loops
without invoking a parallel iterator with the goal of avoiding task
creation for loops with small trip counts or where task creation isn\(aqt
desirable.
.sp
Data parallel operations in Chapel such as forall loops are
order\-independent. However, a forall is implemented in terms of either
leader/follower or standalone iterators which typically create tasks.
This iterator exists to allow vectorization of order\-independent loops
without requiring task creation. By using this wrapper iterator you are
asserting that the loop is order\-independent (and thus a candidate for
vectorization) just as you are when using a forall loop.
.sp
When invoked from a serial for loop, this iterator will simply mark your
iterator(s) as order\-independent. When invoked from a parallel forall loop
this iterator will implicitly be order\-independent because of the
semantics of a forall, and additionally it will invoke the serial
iterator instead of the parallel iterators. For instance:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
forall i in vectorizeOnly(1..10) do;
for    i in vectorizeOnly(1..10) do;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will both effectively generate:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
CHPL_PRAGMA_IVDEP
for (i=0; i<=10; i+=1) {}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBvectorizeOnly\fP iterator  automatically handles zippering, so the
\fBzip\fP keyword is not needed. For instance, to vectorize:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
for (i, j) in zip(1..10, 1..10) do;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
simply write:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
for (i, j) in vectorizeOnly(1..10, 1..10) do;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the use of \fBzip\fP is not explicitly prevented, but all
iterators being zipped must be wrapped by a \fBvectorizeOnly\fP iterator.
Future releases may explicitly prevent the use \fBzip\fP with this iterator.
.UNINDENT
.SS Locales
.sp
A \fIlocale\fP is a Chapel abstraction for a piece of a target
architecture that has processing and storage capabilities.
Generally speaking, the tasks running within a locale have
roughly uniform access to values stored in the locale\(aqs local
memory and longer latencies for accessing the memories of other
locales.  As examples, a single shared memory machine would be
defined as a single locale, while in a system consisting of a
group of network\-connected multicore nodes or SMPs each node
would be defined as a locale.
.sp
Chapel provides several predefined methods on locales, as well as
a few variables that describe the locales upon which a program is
running.
.sp
In addition to what is documented below, \fBnumLocales\fP, \fBLocaleSpace\fP,
and \fBLocales\fP are available as global variables.
.sp
\fBnumLocales\fP is the number of top\-level (network connected) locales.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
config const numLocales: int;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBLocaleSpace\fP is the domain over which the global \fBLocales\fP array is
defined.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
const LocaleSpace = {0..numLocales\-1};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The global \fBLocales\fP array contains an entry for each top\-level locale.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
const Locales: [LocaleSpace] locale;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
One common code idiom in Chapel is the following, which spreads parallel
tasks across the network\-connected locales upon which the program is running:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
coforall loc in Locales { on loc { ... } }
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class locale
\fBlocale\fP is the abstract class from which the various
implementations inherit.  It specifies the required interface
and implements part of it, but requires the rest to be provided
by the corresponding concrete classes.
.INDENT 7.0
.TP
.B proc numPUs(logical: bool = false, accessible: bool = true)
A \fIprocessing unit\fP or \fIPU\fP is an instance of the processor
architecture, basically the thing that executes instructions.
\fI\%numPUs\fP tells how many of these are present on this
locale.  It can count either physical PUs (commonly known as
\fIcores\fP) or hardware threads such as hyperthreads and the like.
It can also either take into account any OS limits on which PUs
the program has access to or do its best to ignore such limits.
By default it returns the number of accessible physical cores.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBlogical\fP : \fIbool\fP \-\- Count logical PUs (hyperthreads and the like),
or physical ones (cores)?  Defaults to \fIfalse\fP,
for cores.
.IP \(bu 2
\fBaccessible\fP : \fIbool\fP \-\- Count only PUs that can be reached, or all of
them?  Defaults to \fItrue\fP, for accessible PUs.
.UNINDENT
.TP
.B Returns
number of PUs
.TP
.B Return type
\fIint\fP
.UNINDENT
.sp
There are several things that can cause the OS to limit the
processor resources available to a Chapel program.  On plain
Linux systems using the \fBtaskset(1)\fP command will do it.  On
Cray systems the \fBCHPL_LAUNCHER_CORES_PER_LOCALE\fP environment
variable may do it, indirectly via the system job launcher.
Also on Cray systems, using a system job launcher (\fBaprun\fP or
\fBslurm\fP) to run a Chapel program manually may do it, as can
running programs within Cray batch jobs that have been set up
with limited processor resources.
.UNINDENT
.INDENT 7.0
.TP
.B proc numCores: int
\fI\%numCores\fP is a deprecated predecessor to \fI\%numPUs\fP,
equivalent to \fInumPUs(logical=true, accessible=true)\fP\&.  It will
be removed after Chapel 1.13 is released.
.UNINDENT
.INDENT 7.0
.TP
.B var maxTaskPar: int
This is the maximum task concurrency that one can expect to
achieve on this locale.  The value is an estimate by the
runtime tasking layer.  Typically it is the number of physical
processor cores available to the program.  Creating more tasks
than this will probably increase walltime rather than decrease
it.
.UNINDENT
.INDENT 7.0
.TP
.B const callStackSize: size_t
\fBcallStackSize\fP holds the size of a task stack on a given
locale.  Thus, \fBhere.callStackSize\fP is the size of the call
stack for any task on the current locale, including the
caller.
.UNINDENT
.INDENT 7.0
.TP
.B proc id: int
Get the integer identifier for the top\-level locale the
current task is running on.
.INDENT 7.0
.TP
.B Returns
locale number, in the range \fB0..numLocales\-1\fP
.TP
.B Return type
int
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc name
Get the name of the top\-level locale the current task is
running on.
.INDENT 7.0
.TP
.B Returns
locale name
.TP
.B Return type
string
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc here
This returns the locale from which the call is made.
.INDENT 7.0
.TP
.B Returns
current locale
.TP
.B Return type
locale
.UNINDENT
.UNINDENT
.SS Ranges
.sp
A \fBrange\fP is a first\-class, constant\-space representation of a
regular sequence of integer indices. Ranges support iteration over the
sequences they represent as well as operations such as slicing, shifting,
comparisons, striding, counting and aligning.
.sp
Range Construction Operations:
New ranges can be constructed using the striding, counting, and alignment
operators, \fBby\fP, \fB#\fP and \fBalign\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0..#10 // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
0..10 by 2 // 0, 2, 4, 6, 8, 10
0..10 by 2 align 1 // 1, 3, 5, 7, 9
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Range Slicing:
A range can be sliced with another range to form a new range that is the intersection of the two ranges.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(1..10)(3..8) // 3..8
(0..20)(1..20 by 2) // 1..20 by 2
(1..10)(5..) // 5..10
(1..10)(..5) // 1..5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Range Shifting:
A range can be shifted by an integer using the \fB+\fP and \fB\-\fP operators.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(1..10) + 5 // 6..15
(1..10) \- 3 // \-2..7
(1..) + 1 // 2..
(..10) + 1 // ..11
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Range Comparisons:
Ranges can be compared for equality using the \fB==\fP and \fB!=\fP operators
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1..10 == 1..10 // true
1.. == 1.. // true
1..10 != (1..10 by 2) // true
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Iteration over ranges:
Ranges can be used as the iterable expression in for, forall, and coforall
loops.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
for i in 1..10 { ... f(i) ... }
forall i in 1..1000 { ... f(i) ... }
coforall i in 0..#numTasks { ... f(i) ... }
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When ranges that are not fully bounded are zipped with another iterator,
the other iterator is used to determine an ending point.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// (i, j) will take the values: (1, 7), (2, 8), (3, 9), (4, 10)
for (i, j) in zip(1..4, 7..) { ... }

// (i, j) will take the values: (1, 10), (2, 9), (3, 8), (4, 7)
for (i,j) in zip(1..4, ..10 by \-1) { ... }
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B enum BoundedRangeType { bounded, boundedLow, boundedHigh, boundedNone }
The BoundedRangeType enum is used to specify the types of bounds a range
is required to have.
.INDENT 7.0
.IP \(bu 2
bounded \- The range has finite low and high bounds.
.IP \(bu 2
boundedLow \- The range starts at a given low bound, but conceptually goes up to infinity.
.IP \(bu 2
boundedHigh \- The range conceptually starts at negative infinity and ends at a given high bound.
.IP \(bu 2
boundedNone \- The range conceptually runs from negative infinity to infinity.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc isRangeType(type t) param
Return true if argument \fBt\fP is a range type, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc isBoundedRange(r: range(?)) param
Return true if argument \fBr\fP is a fully bounded range, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.hasLowBound() param
Return true if this range has a low bound, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.hasHighBound() param
Returns true if this range has a high bound, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.first
Return the first element in the sequence the range represents
.UNINDENT
.INDENT 0.0
.TP
.B proc range.last
Return the last element in the sequence the range represents
.UNINDENT
.INDENT 0.0
.TP
.B proc range.alignedLow: idxType
Returns the range\(aqs aligned low bound. If the aligned low bound is
undefined (does not exist), the behavior is undefined.
.UNINDENT
.INDENT 0.0
.TP
.B proc range.alignedHigh: idxType
Returns the range\(aqs aligned high bound. If the aligned high bound is
undefined, the behavior is undefined.
.UNINDENT
.INDENT 0.0
.TP
.B proc range.isEmpty()
If the sequence represented by the range is empty, return true.  An
error is reported if the range is ambiguous.
.UNINDENT
.INDENT 0.0
.TP
.B proc range.length: idxType
Returns the number of elements in this range, cast to the index type.
.sp
Note: The result is undefined if the index is signed
and the low and high bounds differ by more than max(idxType).
.UNINDENT
.INDENT 0.0
.TP
.B proc range.hasFirst() param
Return true if the range has a first index, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.hasLast() param
Return true if the range has a last index, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.isNaturallyAligned()
Returns true if this range is naturally aligned, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.isAmbiguous() param
Returns true if the range is ambiguously aligned, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.member(i: idxType)
Returns true if \fBi\fP is in this range, false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.member(other: range(?))
Returns true if the range \fBother\fP is contained within this one,
false otherwise
.sp
private
.UNINDENT
.INDENT 0.0
.TP
.B proc ident(r1: range(?), r2: range(?))
Returns true if the two ranges are the same in every respect: i.e. the
two ranges have the same idxType, boundedType, stridable, low, high,
stride and alignment values.
.UNINDENT
.INDENT 0.0
.TP
.B proc range.boundsCheck(other: range(?e, ?b, ?s))
Returns true if \fBother\fP lies entirely within this range and false
otherwise.  Returns false if either range is ambiguously aligned.
.UNINDENT
.INDENT 0.0
.TP
.B proc range.boundsCheck(other: idxType)
Return true if \fBother\fP is a member of this range and false otherwise
.UNINDENT
.INDENT 0.0
.TP
.B proc range.indexOrder(i: idxType)
.INDENT 7.0
.INDENT 3.5
If \fBi\fP is a member of the range\(aqs represented sequence, returns an
integer giving the ordinal index of i within the sequence using
zero\-based indexing. Otherwise, returns \fB(\-1):idxType\fP\&. It is an error
to invoke \fBindexOrder\fP if the represented sequence is not defined or
the range does not have a first index.
.sp
The following calls show the order of index 4 in each of the given ranges:
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
(0..10).indexOrder(4) == 4
(1..10).indexOrder(4) == 3
(3..5).indexOrder(4) == 1
(0..10 by 2).indexOrder(4) == 2
(3..5 by 2).indexOrder(4) == \-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc range.orderToIndex(ord: integral): idxType
Returns the zero\-based \fBord\fP\-th element of this range\(aqs represented
sequence. It is an error to invoke \fBorderToIndex\fP if the range is not
defined, or if \fBord\fP is negative or greater than the range\(aqs length.
The \fBorderToIndex\fP procedure is the reverse of \fBindexOrder\fP\&.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
0..10.orderToIndex(4) == 4
1..10.orderToIndex(3) == 4
3..5.orderToIndex(1)  == 4
0..10 by 2.orderToIndex(2) == 4
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc range.translate(i: integral)
Return a range with elements shifted from this range by \fBi\fP\&.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
0..9.translate(1) == 1..10
0..9.translate(2) == 2..11
0..9.translate(\-1) == \-1..8
0..9.translate(\-2) == \-2..7
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc range.interior(i: idxType)
Return a range with \fBi\fP elements from the interior portion of this
range. If \fBi\fP is positive, take elements from the high end, and if
\fBi\fP is negative, take elements from the low end.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
0..9.interior(1)  == 9..9
0..9.interior(2)  == 8..9
0..9.interior(\-1) == 0..0
0..9.interior(\-2) == 0..1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc range.exterior(i: idxType)
Return a range with \fBi\fP elements from the exterior portion of this
range. If \fBi\fP is positive, take elements from the high end, and if
\fBi\fP is negative, take elements from the low end.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
0..9.exterior(1)  = 10..10
0..9.exterior(2)  = 10..11
0..9.exterior(\-1) = \-1..\-1
0..9.exterior(\-2) = \-2..\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc range.expand(i: idxType)
Return a range expanded by \fBi\fP elements from each end.  If \fBi\fP is
negative, the range will be contracted.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
 0..9.expand(1)  == \-1..10
 0..9.expand(2)  == \-2..11
 0..9.expand(\-1) == 1..8
 0..9.expand(\-2) == 2..7



* The following procedure is effectively equivalent to:
*
* because the parser renames the routine since \(aqby\(aq is a keyword.



* The following procedure is effectively equivalent to:
*
* because the parser renames the routine since \(aqby\(aq is a keyword.
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc range.offset(offs: idxType)
Returns a range whose alignment is this range\(aqs first index plus \fBn\fP\&.
If the range has no first index, a runtime error is generated.
.UNINDENT
.SS Synchronization Variables
.sp
Synchronization variables have a logical state associated with the value. The
state of the variable is either full or empty. Normal reads of a
synchronization variable cannot proceed until the variable\(aqs state is full.
Normal writes of a synchronization variable cannot proceed until the variable\(aqs
state is empty.
.sp
Chapel supports two types of synchronization variables: sync and single. Both
types behave similarly, except that a single variable may only be written once.
Consequently, when a sync variable is read, its state transitions to empty,
whereas when a single variable is read, its state does not change. When either
type of synchronization variable is written, its state transitions to full.
.sp
If a task attempts to read or write a synchronization variable that is not in
the correct state, the task is suspended. When the variable transitions to the
correct state, the task is resumed. If there are multiple tasks blocked waiting
for the state transition, one is non\-deterministically selected to proceed and
the others continue to wait if it is a sync variable; all tasks are selected to
proceed if it is a single variable.
.INDENT 0.0
.TP
.B proc isSyncType(type t) param
Returns true if \fIt\fP is a sync type, false otherwise.
.UNINDENT
.INDENT 0.0
.TP
.B proc sync.readFE(): base_type
This method blocks until the sync variable is full. The state of the sync
variable is set to empty when this method completes. This method
implements the default read of a sync variable.
.INDENT 7.0
.TP
.B Returns
The value of the sync variable.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc sync.readFF()
This method blocks until the sync variable is full. The state of the sync
variable remains full when this method completes.
.INDENT 7.0
.TP
.B Returns
The value of the sync variable.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc sync.readXX()
This method is non\-blocking and the state of the sync variable is
unchanged when this method completes.
.INDENT 7.0
.TP
.B Returns
The value of the sync variable.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc sync.writeEF(val: base_type)
.INDENT 7.0
.TP
.B Arguments
\fBval\fP \-\- New value of the sync variable.
.UNINDENT
.sp
This method blocks until the sync variable is empty. The state of the sync
variable is set to full when this method completes. This method implements
the default write of a sync variable.
.UNINDENT
.INDENT 0.0
.TP
.B proc sync.writeFF(val: base_type)
.INDENT 7.0
.TP
.B Arguments
\fBval\fP \-\- New value of the sync variable.
.UNINDENT
.sp
This method blocks until the sync variable is full. The state
of the sync variable remains full when this method completes.
.UNINDENT
.INDENT 0.0
.TP
.B proc sync.writeXF(val: base_type)
.INDENT 7.0
.TP
.B Arguments
\fBval\fP \-\- New value of the sync variable.
.UNINDENT
.sp
This method is non\-blocking and the state of the sync
variable is set to full when this method completes.
.UNINDENT
.INDENT 0.0
.TP
.B proc sync.reset()
Resets the value of this sync variable to the default value of
its type. This method is non\-blocking and the state of the sync
variable is set to empty when this method completes.
.UNINDENT
.INDENT 0.0
.TP
.B proc sync.isFull
.INDENT 7.0
.TP
.B Returns
true if the state of the sync variable is full.
.UNINDENT
.sp
This method is non\-blocking and the state of the sync variable is
unchanged when this method completes.
.UNINDENT
.INDENT 0.0
.TP
.B proc isSingleType(type t) param
Returns true if \fIt\fP is a single type, false otherwise.
.UNINDENT
.INDENT 0.0
.TP
.B proc single.readFF()
This method blocks until the single variable is full. The state of the single
variable remains full when this method completes. This method implements
the default read of a single variable.
.INDENT 7.0
.TP
.B Returns
The value of the single variable.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc single.readXX()
This method is non\-blocking and the state of the single variable is
unchanged when this method completes.
.INDENT 7.0
.TP
.B Returns
The value of the single variable.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc single.writeEF(val: base_type)
.INDENT 7.0
.TP
.B Arguments
\fBval\fP \-\- New value of the single variable.
.UNINDENT
.sp
This method blocks until the single variable is empty. The state of the single
variable is set to full when this method completes. This method implements
the default write of a single variable.
.UNINDENT
.INDENT 0.0
.TP
.B proc single.isFull
.INDENT 7.0
.TP
.B Returns
true if the state of the single variable is full.
.UNINDENT
.sp
This method is non\-blocking and the state of the single variable is
unchanged when this method completes.
.UNINDENT
.SS Tuples
.sp
Predefined Functions on Tuples.
.sp
Tuples are a predefined structured type in Chapel. They are specified
in the Tuples chapter of the Chapel Language Specification.
This page lists the predefined functions on tuples.
They are always available to all Chapel programs.
.sp
Besides the functions defined here, the Chapel Language specification
defines other operations available on tuples: indexing, iteration,
assignment, and unary, binary, and relational operators.
.sp
The following method is also available:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc tuple.size param
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
It returns the number of components of the tuple.
.INDENT 0.0
.TP
.B proc isTupleType(type t) param
Returns \fItrue\fP if its argument is a tuple type.
The argument must be a type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isHomogeneousTupleType(type t) param
Returns \fItrue\fP if its argument is a homogeneous tuple type.
The argument must be a type.
.UNINDENT
.INDENT 0.0
.TP
.B proc max(type t): t
Returns a tuple of type t with each component set to \fBmax\fP
of the type in the corresponding component of the argument.
.UNINDENT
.INDENT 0.0
.TP
.B proc min(type t): t
Returns a tuple of type t with each component set to \fBmin\fP
of the type in the corresponding component of the argument.
.UNINDENT
.SS Strings
.sp
The following documentation shows functions and methods used to
manipulate and process Chapel strings.
.sp
Besides the functions below, some other modules proved routines that are
useful for working with strings. The \fBIO\fP module provides
\fBIO.string.format\fP which creates a string that is the result of
formatting. It also includes functions for reading and writing strings.
The \fBRegexp\fP module also provides some routines for searching
within strings.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
While \fI\%string\fP is intended to be a Unicode string, there is much
left to do. As of Chapel 1.13, only ASCII strings can be expected to work
correctly with all functions.
.sp
Future work involves support for both ASCII and unicode strings, and
allowing users to specify the encoding for individual strings.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record string
.INDENT 7.0
.TP
.B proc string(s: string, owned: bool = true)
Construct a new string from \fBs\fP\&. If \fBowned\fP is set to \fBtrue\fP then
\fBs\fP will be fully copied into the new instance. If it is \fBfalse\fP a
shallow copy will be made such that any in\-place modifications to the new
string may appear in \fBs\fP\&. It is the responsibility of the user to
ensure that the underlying buffer is not freed while being used as part
of a shallow copy.
.UNINDENT
.INDENT 7.0
.TP
.B proc string(cs: c_string, owned: bool = true, needToCopy: bool = true)
Construct a new string from the \fIc_string\fP \fIcs\fP\&. If \fIowned\fP is set to
true, the backing buffer will be freed when the new record is destroyed.
If \fIneedToCopy\fP is set to true, the \fIc_string\fP will be copied into the
record, otherwise it will be used directly. It is the responsibility of
the user to ensure that the underlying buffer is not freed if the
\fIc_string\fP is not copied in.
.UNINDENT
.INDENT 7.0
.TP
.B proc string(buff: bufferType, length: int, size: int, owned: bool = true, needToCopy: bool = true)
Construct a new string from \fIbuff\fP ( \fIc_ptr(uint(8))\fP ). \fIsize\fP indicates
the total size of the buffer available, while \fIlen\fP indicates the current
length of the string in the buffer (the common case would be \fIsize\-1\fP for
a C\-style string). If \fIowned\fP is set to true, the backing buffer will be
freed when the new record is destroyed. If \fIneedToCopy\fP is set to true,
the \fIc_string\fP will be copied into the record, otherwise it will be used
directly. It is the responsibility of the user to ensure that the
underlying buffer is not freed if the \fIc_string\fP is not copied in.
.UNINDENT
.INDENT 7.0
.TP
.B proc length
.INDENT 7.0
.TP
.B Returns
The number of characters in the string.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc localize(): string
Gets a version of the \fI\%string\fP that is on the currently
executing locale.
.INDENT 7.0
.TP
.B Returns
A shallow copy if the \fI\%string\fP is already on the
current locale, otherwise a deep copy is performed.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc c_str(): c_string
Get a \fIc_string\fP from a \fI\%string\fP\&.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
This can only be called safely on a \fI\%string\fP whose home is
the current locale.  This property can be enforced by calling
\fI\%string.localize()\fP before \fI\%c_str()\fP\&. If the
string is remote, the program will halt.
.UNINDENT
.UNINDENT
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var my_string = "Hello!";
on different_locale {
  printf("%s", my_string.localize().c_str());
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Returns
A \fIc_string\fP that points to the underlying buffer used by this
\fI\%string\fP\&. The returned \fIc_string\fP is only valid when used
on the same locale as the string.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B iter these(): string
Iterates over the string character by character.
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var str = "abcd";
for c in str {
  writeln(c);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Output:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
a
b
c
d
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc string(i: int): string
Index into a string
.INDENT 7.0
.TP
.B Returns
A string with the character at the specified index from
\fI1..string.length\fP
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc string(r: range(?)): string
Slice a string. Halts if r is not completely inside the range
\fI1..string.length\fP\&.
.INDENT 7.0
.TP
.B Arguments
\fBr\fP \-\- range of the indices the new string should be made from
.TP
.B Returns
a new string that is a substring within \fI1..string.length\fP\&. If
the length of \fIr\fP is zero, an empty string is returned.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc isEmptyString(): bool
.INDENT 7.0
.TP
.B Returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when the string is empty
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT

.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc startsWith(needles: string ...): bool
.INDENT 7.0
.TP
.B Arguments
\fBneedles\fP \-\- A varargs list of strings to match against.
.TP
.B Returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when the string begins with one or more of the \fIneedles\fP
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT

.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc endsWith(needles: string ...): bool
.INDENT 7.0
.TP
.B Arguments
\fBneedles\fP \-\- A varargs list of strings to match against.
.TP
.B Returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when the string ends with one or more of the \fIneedles\fP
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT

.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc find(needle: string, region: range(?) = 1..): int
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBneedle\fP \-\- the string to search for
.IP \(bu 2
\fBregion\fP \-\- an optional range defining the substring to search within,
default is the whole string. Halts if the range is not
within \fI1..string.length\fP
.UNINDENT
.TP
.B Returns
the index of the first occurrence of \fIneedle\fP within a
string, or 0 if the \fIneedle\fP is not in the string.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc rfind(needle: string, region: range(?) = 1..): int
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBneedle\fP \-\- the string to search for
.IP \(bu 2
\fBregion\fP \-\- an optional range defining the substring to search within,
default is the whole string. Halts if the range is not
within \fI1..string.length\fP
.UNINDENT
.TP
.B Returns
the index of the first occurrence from the right of \fIneedle\fP
within a string, or 0 if the \fIneedle\fP is not in the string.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc count(needle: string, region: range(?) = 1..): int
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBneedle\fP \-\- the string to search for
.IP \(bu 2
\fBregion\fP \-\- an optional range defining the substring to search within,
default is the whole string. Halts if the range is not
within \fI1..string.length\fP
.UNINDENT
.TP
.B Returns
the number of times \fIneedle\fP occurs in the string
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc replace(needle: string, replacement: string, count: int = \-1): string
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBneedle\fP \-\- the string to search for
.IP \(bu 2
\fBreplacement\fP \-\- the string to replace \fIneedle\fP with
.IP \(bu 2
\fBcount\fP \-\- an optional integer specifying the number of replacements to
make, values less than zero will replace all occurrences
.UNINDENT
.TP
.B Returns
a copy of the string where \fIneedle\fP replaces \fIreplacement\fP up
to \fIcount\fP times
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B iter split(sep: string, maxsplit: int = \-1, ignoreEmpty: bool = false)
Splits the string on \fIsep\fP yielding the substring between each
occurrence, up to \fImaxsplit\fP times.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBsep\fP \-\- The delimiter used to break the string into chunks.
.IP \(bu 2
\fBmaxsplit\fP \-\- The number of times to split the string, negative values
indicate no limit.
.IP \(bu 2
\fBignoreEmpty\fP \-\- .INDENT 2.0
.IP \(bu 2
.INDENT 2.0
.TP
.B When \fItrue\fP  \-\- Empty strings will not be yielded,
and will not count towards \fImaxsplit\fP
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
.B When \fIfalse\fP \-\- Empty strings will be yielded when
\fIsep\fP occurs multiple times in a row.
.UNINDENT
.UNINDENT

.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B iter split(maxsplit: int = \-1)
Works as above, but uses runs of whitespace as the delimiter.
.INDENT 7.0
.TP
.B Arguments
\fBmaxsplit\fP \-\- The number of times to split the string, negative values
indicate no limit.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc join(const ref S: string ...): string
Returns a new string, which is the concatenation of all of the strings
passed in with the receiving string inserted between them.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var x = "|".join("a","10","d");
writeln(x); // prints: "a|10|d"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc join(const ref S): string
Same as the varargs version, but with a homogeneous tuple of strings.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var x = "|".join("a","10","d");
writeln(x); // prints: "a|10|d"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc join(const ref S: [] string): string
Same as the varargs version, but with all the strings in an array.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var x = "|".join(["a","10","d"]);
writeln(x); // prints: "a|10|d"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc _join(const ref S): string
.UNINDENT
.INDENT 7.0
.TP
.B proc strip(chars: string = " trn", leading = true, trailing = true): string
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBchars\fP \-\- A string containing each character to remove.
Defaults to \fI" trn"\fP\&.
.IP \(bu 2
\fBleading\fP \-\- Indicates if leading occurrences should be removed.
Defaults to \fItrue\fP\&.
.IP \(bu 2
\fBtrailing\fP \-\- Indicates if trailing occurrences should be removed.
Defaults to \fItrue\fP\&.
.UNINDENT
.TP
.B Returns
A new string with all occurrences of characters in \fIchars\fP
removed, including \fIleading\fP and \fItrailing\fP occurrences as
appropriate.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc partition(sep: string): 3*(string)
Splits the string on \fIsep\fP into a \fI3*string\fP consisting of the section
before \fIsep\fP, \fIsep\fP, and the section after \fIsep\fP\&. If \fIsep\fP is not found,
the tuple will contain the whole string, and then two empty strings.
.UNINDENT
.INDENT 7.0
.TP
.B proc isUpper(): bool
Checks if all the characters in the string are either uppercase (A\-Z) or
uncased (not a letter).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B returns
.INDENT 7.0
.IP \(bu 2
.INDENT 2.0
.TP
.B \fItrue\fP  \-\- if the string contains at least one uppercase
character and no lowercase characters, ignoring
uncased characters.
.UNINDENT
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc isLower(): bool
Checks if all the characters in the string are either lowercase (a\-z) or
uncased (not a letter).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when there are no uppercase characters in the string.
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc isSpace(): bool
Checks if all the characters in the string are whitespace (\(aq \(aq, \(aqt\(aq,
\(aqn\(aq, \(aqv\(aq, \(aqf\(aq, \(aqr\(aq).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when all the characters are whitespace.
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc isAlpha(): bool
Checks if all the characters in the string are alphabetic (a\-zA\-Z).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when the characters are alphabetic.
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc isDigit(): bool
Checks if all the characters in the string are digits (0\-9).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when the characters are digits.
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc isAlnum(): bool
Checks if all the characters in the string are alphanumeric (a\-zA\-Z0\-9).
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when the characters are alphanumeric.
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc isPrintable(): bool
Checks if all the characters in the string are printable. Characters are
defined as being printable if they are not within the range of \fI0x00\-0x1f\fP
or are \fI0x7f\fP\&.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when the characters are alphanumeric.
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc isTitle(): bool
Checks if all uppercase characters are preceded by uncased characters,
and if all lowercase characters are preceded by cased characters.
.INDENT 7.0
.TP
.B Returns
.INDENT 7.0
.IP \(bu 2
\fItrue\fP  \-\- when the condition described above is met.
.IP \(bu 2
\fIfalse\fP \-\- otherwise
.UNINDENT

.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc toLower(): string
.INDENT 7.0
.TP
.B Returns
A new string with all uppercase characters replaced with their
lowercase counterpart.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc toUpper(): string
.INDENT 7.0
.TP
.B Returns
A new string with all lowercase characters replaced with their
uppercase counterpart.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc toTitle(): string
.INDENT 7.0
.TP
.B Returns
A new string with all cased characters following an uncased
character converted to uppercase, and all cased characters
following another cased character converted to lowercase.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc =(ref lhs: string, rhs: string)
Copies the string \fIrhs\fP into the string \fIlhs\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc =(ref lhs: string, rhs_c: c_string)
Copies the c_string \fIrhs_c\fP into the string \fIlhs\fP\&.
.sp
Halts if \fIlhs\fP is a remote string.
.UNINDENT
.INDENT 0.0
.TP
.B proc +(s0: string, s1: string)
.INDENT 7.0
.TP
.B Returns
A new string which is the result of concatenating \fIs0\fP and \fIs1\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc *(s: string, n: integral)
.INDENT 7.0
.TP
.B Returns
A new string which is the result of repeating \fIs\fP \fIn\fP times.
If \fIn\fP is less than or equal to 0, an empty string is returned.
.UNINDENT
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
writeln("Hello! " * 3);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Results in:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
Hello! Hello! Hello!
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc +(s: string, x: numeric)
The following concatenation functions return a new string which is the
result of casting the non\-string argument to a string, and concatenating
that result with \fIs\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc +(x: numeric, s: string)
.UNINDENT
.INDENT 0.0
.TP
.B proc +(s: string, x: enumerated)
.UNINDENT
.INDENT 0.0
.TP
.B proc +(x: enumerated, s: string)
.UNINDENT
.INDENT 0.0
.TP
.B proc +(s: string, x: bool)
.UNINDENT
.INDENT 0.0
.TP
.B proc +(x: bool, s: string)
.UNINDENT
.INDENT 0.0
.TP
.B proc +=(ref lhs: string, const ref rhs: string): void
Appends the string \fIrhs\fP to the string \fIlhs\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc ascii(a: string): int(32)
.INDENT 7.0
.TP
.B Returns
The byte value of the first character in \fIa\fP as an integer.
.UNINDENT
.UNINDENT
.SS Misc Functions
.sp
Additional utilities
.INDENT 0.0
.TP
.B proc compilerError(param x: c_string ...?n)
Generate a compile\-time error.
The error text is a concatenation of the arguments.
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerError(param x: c_string ...?n, param errorDepth: int)
Generate a compile\-time error.
The error text is a concatenation of the string arguments.
.INDENT 7.0
.TP
.B Arguments
\fBerrorDepth\fP \-\- controls the depth of the error stack trace
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerWarning(param x: c_string ...?n)
Generate a compile\-time warning.
The warning text is a concatenation of the arguments.
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerWarning(param x: c_string ...?n, param errorDepth: int)
Generate a compile\-time warning.
The warning text is a concatenation of the string arguments.
.INDENT 7.0
.TP
.B Arguments
\fBerrorDepth\fP \-\- controls the depth of the error stack trace
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool)
This function is used primarily within system modules to test a compile
time property. An error message is generated if the property is false
.INDENT 7.0
.TP
.B Arguments
\fBtest\fP \-\- the param value to be tested
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1: integral)
This function is used primarily within system modules to test a compile
time property. An error message is generated if the property is false.
The second parameter, which must be integral, is used to control the
depth of the error stack traceback.
.INDENT 7.0
.TP
.B Arguments
\fBtest\fP \-\- the param value to be tested
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1)
This function of two arguments will be used if the second parameter is not
integral.  If the first parameter is false, then the second parameter is
included in the error message that is generated
.INDENT 7.0
.TP
.B Arguments
\fBtest\fP \-\- the param value to be tested
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1, param arg2)
Generate a compile\-time error if \fItest\fP is false.
The error message includes \fIarg1\fP and \fIarg2\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1, param arg2, param arg3)
Generate a compile\-time error if \fItest\fP is false.
The error message includes \fIarg1\fP, \fIarg2\fP, \fIarg3\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1, param arg2, param arg3, param arg4)
Generate a compile\-time error if \fItest\fP is false.
The error message includes \fIarg1\fP through \fIarg4\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1, param arg2, param arg3, param arg4, param arg5)
Generate a compile\-time error if \fItest\fP is false.
The error message includes \fIarg1\fP through \fIarg5\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1, param arg2, param arg3, param arg4, param arg5, argrest ...)
This variation accepts any number of arguments.  The first five additional parameters are
included if an error message is generated and then there is an indication that there are
additional parameters.
.INDENT 7.0
.TP
.B Arguments
\fBtest\fP \-\- the param value to be tested
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1, param arg2, param arg3, param arg4, param arg5, param arg6: integral)
This variation accepts the value to be tested, precisely 5 values to be included in the
error message, and finally an integral value that controls the depth of the error stack.
.INDENT 7.0
.TP
.B Arguments
\fBtest\fP \-\- the param value to be tested
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc compilerAssert(param test: bool, param arg1, param arg2, param arg3, param arg4, param arg5, argrest ..., param arglast: integral)
This variation accepts any number of arguments but detects that the final argument is integral.
In this version the final argument is treated as an errorDepth as for compilerWarning() and
compilerError()
.INDENT 7.0
.TP
.B Arguments
\fBtest\fP \-\- the param value to be tested
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc min(x, y ...)
Compute the minimum value of 2 or more arguments
using the \fB<\fP operator for comparison.
.UNINDENT
.INDENT 0.0
.TP
.B proc max(x, y ...)
Compute the maximum value of 2 or more arguments
using the \fB>\fP operator for comparison.
.UNINDENT
.INDENT 0.0
.TP
.B proc exit(status: int)
Exit the program
.INDENT 7.0
.TP
.B Arguments
\fBstatus\fP \-\- The exit code for the program
.UNINDENT
.UNINDENT
.SS Index
.INDENT 0.0
.IP \(bu 2
Chapel Online Documentation Index
.UNINDENT
.SH STANDARD MODULES
.sp
Standard modules are those which describe features that are considered
part of the Chapel Standard Library.
.sp
All Chapel programs automatically \fBuse\fP the modules \fBAssert\fP ,
\fBMath\fP , and \fBTypes\fP by default.
.SS Assert
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Assert;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for simple assert() routines.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
All Chapel programs automatically \fBuse\fP this module by default.
An explicit \fBuse\fP statement is not necessary.
.UNINDENT
.UNINDENT
.sp
In the current implementation, these asserts never become no\-ops.  That is,
using them will always incur execution\-time checks.
.INDENT 0.0
.TP
.B proc assert(test: bool)
Assert that a boolean condition is true.  If it is false, prints
\(aqassert failed\(aq and halts the program.
.INDENT 7.0
.TP
.B Arguments
\fBtest\fP : \fIbool\fP \-\- the boolean condition
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc assert(test: bool, args ...?numArgs)
Assert that a boolean condition is true.  If it is false, prints
\(aqassert failed \- \(aq followed by all subsequent arguments, as though
printed using \fBwrite()\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBtest\fP : \fIbool\fP \-\- the boolean condition
.IP \(bu 2
\fBargs\fP \-\- other arguments to print
.UNINDENT
.UNINDENT
.UNINDENT
.SS Barrier
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Barrier;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for task barriers.
.sp
The Barrier type provided in this module can be used to prevent tasks
from proceeding until all other related tasks have also reached the
barrier.
.sp
In the following example, all of the tasks created by the coforall loop
will print their "entering the barrier" messages in an unspecified order,
then all of the tasks will print their "past the barrier" messages, also
in an unspecified order.  Because of the barrier, all of the
"entering the barrier" messages will be printed before any of the
"past the barrier" messages.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Barrier;

config const numTasks = here.maxTaskPar;
var b = new Barrier(numTasks);

coforall tid in 1..numTasks {
  writeln("Task ", tid, " is entering the barrier");
  b.barrier();
  writeln("Task ", tid, " is past the barrier");
}

delete b;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Future direction
.sp
In the future, we expect to add more language\-level support for a
"task\-team" concept.  A task\-team will more directly support collective
operations such as barriers between the tasks within a team.
.sp
The Barrier type is currently implemented as a class, requiring it to be
explicitly deleted before it goes out of scope.  It is expected that this
type will be changed into a record allowing it to be automatically
reclaimed.  When this change happens, code that uses this Barrier will need
to have the explicit deletes removed, but should require no other changes.
.sp
The current implementation is designed for correctness, but is not expected
to perform well at scale.  We expect performance at scale to improve as
this barrier implementation is optimized and as the task\-team concept is
implemented and optimized.
.INDENT 0.0
.TP
.B enum BarrierType { Atomic, Sync }
An enumeration of the different barrier implementations.  Used to choose
the implementation to use when constructing a new barrier object.
.INDENT 7.0
.IP \(bu 2
\fIBarrierType.Atomic\fP uses Chapel atomic variables to control the barrier.
.IP \(bu 2
\fIBarrierType.Sync\fP uses Chapel sync variables to control the barrier.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class Barrier
A barrier that will cause \fInumTasks\fP to wait before proceeding.
.INDENT 7.0
.TP
.B proc Barrier(numTasks: int, barrierType: BarrierType = BarrierType.Atomic, reusable: bool = barrierType==BarrierType.Atomic)
Construct a new barrier object.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBnumTasks\fP \-\- The number of tasks that will use this barrier
.IP \(bu 2
\fBbarrierType\fP \-\- The barrier implementation to use
.IP \(bu 2
\fBreusable\fP \-\- Incur some extra overhead to allow reuse of this barrier?
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc barrier()
Block until all related tasks have called this method.  If \fIreusable\fP
is true, reset the barrier to be used again.
.UNINDENT
.INDENT 7.0
.TP
.B proc notify()
Notify the barrier that this task has reached this point.
.UNINDENT
.INDENT 7.0
.TP
.B proc wait()
Wait until \fIn\fP tasks have called \fI\%notify\fP\&.  If \fIreusable\fP is true,
reset the barrier to be used again.  Note: if \fIreusable\fP is true
\fI\%wait\fP will block until \fIn\fP tasks have called it after calling
\fI\%notify\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B proc try(): bool
return \fItrue\fP if \fIn\fP tasks have called \fI\%notify\fP
.UNINDENT
.UNINDENT
.SS BitOps
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use BitOps;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Bitwise operations implemented using C intrinsics when possible.
.INDENT 0.0
.TP
.B proc clz(x: integral)
Count leading zeros in \fIx\fP\&.
.INDENT 7.0
.TP
.B Returns
the number of 0 bits before the most significant 1 bit in \fIx\fP
.TP
.B Return type
\fIx.type\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc ctz(x: integral)
Count trailing zeros in \fIx\fP\&.
.INDENT 7.0
.TP
.B Returns
the number of 0 bits after the least significant 1 bit in \fIx\fP
.TP
.B Return type
\fIx.type\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc popcount(x: integral)
Find the population count of \fIx\fP\&.
.INDENT 7.0
.TP
.B Returns
the number of 1 bits set in \fIx\fP as \fIx.type\fP
.TP
.B Return type
\fIx.type\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc parity(x: integral)
Find the parity of \fIx\fP\&.
.INDENT 7.0
.TP
.B Returns
.INDENT 7.0
.IP \(bu 2
0 \-\- when an even number of bits are set in \fIx\fP
.IP \(bu 2
1 \-\- when an odd number of bits are set in \fIx\fP
.UNINDENT

.TP
.B Return type
\fIx.type\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc rotl(x: integral, n: integral)
Rotate \fIx\fP left.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBx\fP \-\- integral of size \fIbits\fP
.IP \(bu 2
\fBn\fP \-\- rotation amount, must be less than \fIbits\fP
.UNINDENT
.TP
.B Returns
\fIx\fP rotated left by \fIn\fP bits
.TP
.B Return type
\fIx.type\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc rotr(x: integral, n: integral)
Rotate \fIx\fP right.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBx\fP \-\- integral of size \fIbits\fP
.IP \(bu 2
\fBn\fP \-\- rotation amount, must be less than \fIbits\fP
.UNINDENT
.TP
.B Returns
\fIx\fP rotated right by \fIn\fP bits
.TP
.B Return type
\fIx.type\fP
.UNINDENT
.UNINDENT
.SS Buffers
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Buffers;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for buffers \- regions of memory without a particular interpretation.
.sp
This module provides \fI\%bytes\fP and \fI\%buffer\fP types which
can be used to manage memory regions.
.sp
A \fI\%bytes\fP is a contiguous memory region \- really a data structure
containing a pointer, length, and also the information necessary to free the
memory region when it is no longer used.
.sp
A \fI\%buffer\fP consists of a sequence views into \fI\%bytes\fP
objects. A \fI\%bytes\fP object might be shared by several
\fI\%buffer\fP objects.
.sp
These types should be safe to use in a multi\-locale context. These types
should free their memory after the last user of that memory goes out of
scope. They are currently reference counted but that may not always be the
case.
.INDENT 0.0
.TP
.B record bytes
This type represents a contiguous sequence of bytes.
This sequence of bytes is represented with a C pointer and length and is
currently reference counted.  Note that this record contains private
fields in addition to the home field.
.INDENT 7.0
.TP
.B var home: locale
The home locale storing the data
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc bytes.bytes()
Construct an empty bytes object
.UNINDENT
.INDENT 0.0
.TP
.B proc bytes.bytes(len: int(64), out error: syserr)
Construct a bytes object by allocating zero\-filled memory.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBlen\fP \-\- the number of bytes to allocate
.IP \(bu 2
\fBerror\fP \-\- (optional) capture an error that was encountered instead of
halting on error
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc bytes.len: int(64)
.INDENT 7.0
.TP
.B Returns
the number of bytes stored in a \fI\%bytes\fP object
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record buffer_iterator
This type represents a particular location with a buffer.
Use buffer methods like \fI\%buffer.start\fP and \fI\%buffer.advance\fP to
create and manipulate \fI\%buffer_iterator\fP s.  Note that this record
contains private fields in addition to the home field.
.INDENT 7.0
.TP
.B var home: locale
The home locale storing the data
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record buffer_range
A region within a buffer (indicated by two \fI\%buffer_iterator\fP s )
.INDENT 7.0
.TP
.B var start: buffer_iterator
.UNINDENT
.INDENT 7.0
.TP
.B var end: buffer_iterator
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer_range.len: int(64)
.INDENT 7.0
.TP
.B Returns
the number of bytes stored in a \fI\%buffer_range\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record buffer
A buffer which can contain multiple memory regions
(that is, multiple regions of \fI\%bytes\fP objects).  Note that this
record contains private fields in addition to the home field.
.INDENT 7.0
.TP
.B var home: locale
The home locale storing the data
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.buffer(out error: syserr)
Create an empty buffer.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- (optional) capture an error that was encountered instead of
halting on error
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.flatten(range: buffer_range, out error: syserr)
Flatten a buffer. Create a new \fI\%bytes\fP object and copy
the buffer into it. This function should work even if buffer is
remote.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBrange\fP \-\- the region of the buffer to copy, for example buffer.all()
.IP \(bu 2
\fBerror\fP \-\- (optional) capture an error that was encountered instead of
halting on error
.UNINDENT
.TP
.B Returns
a newly constructed bytes object on the current locale
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.len
.INDENT 7.0
.TP
.B Returns
the number of bytes stored in a \fI\%buffer\fP object
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.append(b: bytes, skip_bytes: int(64) = 0, len_bytes: int(64) = b.len, out error: syserr)
Append a \fI\%bytes\fP object to a \fI\%buffer\fP\&.
This function might store the passed bytes object by reference instead of
copying it. The current implementation will always do so and will always
increase the reference count of the bytes object.  The version of this
function called without the error argument will halt if an error is
encountered.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBb\fP \-\- the \fI\%bytes\fP object to append
.IP \(bu 2
\fBskip_bytes\fP \-\- how many bytes at the front of b to skip
.IP \(bu 2
\fBlen_bytes\fP \-\- how many bytes to append to the buffer
.IP \(bu 2
\fBerror\fP \-\- (optional) capture an error that was encountered instead of
halting on error
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.append(buf: buffer, part: buffer_range = AppendExpr.Call08, out error: syserr)
Append a \fI\%buffer\fP object to a \fI\%buffer\fP\&.
This function might store a pointers to the bytes objects contained in
\fIbuf\fP instead of copying them. If that happens, the current implementation
will increase their reference counts.  The version of this function called
without the error argument will halt if an error is encountered.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBbuf\fP \-\- the \fI\%buffer\fP object to append
.IP \(bu 2
\fBpart\fP \-\- a \fI\%buffer_range\fP indicating which section of the
buffer to copy. Defaults to all of the buffer.
.IP \(bu 2
\fBerror\fP \-\- (optional) capture an error that was encountered instead of
halting on error
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.prepend(b: bytes, skip_bytes: int(64) = 0, len_bytes: int(64) = b.len, out error: syserr)
Prepend a \fI\%bytes\fP object to a \fI\%buffer\fP\&.
This function might store the passed bytes object by reference instead of
copying it. The current implementation will always do so and will always
increase the reference count of the bytes object.  The version of this
function called without the error argument will halt if an error is
encountered.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBb\fP \-\- the \fI\%bytes\fP object to prepend
.IP \(bu 2
\fBskip_bytes\fP \-\- how many bytes at the front of b to skip
.IP \(bu 2
\fBlen_bytes\fP \-\- how many bytes to append to the buffer
.IP \(bu 2
\fBerror\fP \-\- (optional) capture an error that was encountered instead of
halting on error
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.start(): buffer_iterator
.INDENT 7.0
.TP
.B Returns
a \fI\%buffer_iterator\fP to the start of a buffer
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.end(): buffer_iterator
.INDENT 7.0
.TP
.B Returns
a \fI\%buffer_iterator\fP to the end of a buffer
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.all(): buffer_range
.INDENT 7.0
.TP
.B Returns
a \fI\%buffer_range\fP for the entirety of a buffer
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.next_part(ref it: buffer_iterator)
Advance a \fI\%buffer_iterator\fP to the next contiguous
memory region stored therein
.INDENT 7.0
.TP
.B Arguments
\fBit\fP \-\- the buffer iterator to advance
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.prev_part(ref it: buffer_iterator)
Advance a \fI\%buffer_iterator\fP to the previous contiguous
memory region stored therein
.INDENT 7.0
.TP
.B Arguments
\fBit\fP \-\- the buffer iterator to advance
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.advance(ref it: buffer_iterator, amount: int(64))
Advance a \fI\%buffer_iterator\fP by a particular number
of bytes.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBit\fP \-\- the buffer iterator to advance
.IP \(bu 2
\fBamount\fP \-\- the number of bytes to advance
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.copyout(it: buffer_iterator, out value, out error: syserr): buffer_iterator
Read a basic type from a buffer. This method reads the value
by copying from memory \- so it reads a binary value in native endianness.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBit\fP \-\- a \fI\%buffer_iterator\fP where reading will start
.IP \(bu 2
\fBvalue\fP \-\- a basic type (integral or floating point value)
.IP \(bu 2
\fBerror\fP \-\- (optional) capture an error that was encountered instead of
halting on error
.UNINDENT
.TP
.B Returns
a buffer iterator storing the position immediately after
the read value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc buffer.copyin(it: buffer_iterator, value, out error: syserr): buffer_iterator
Write a basic type to a buffer. This method writes the value
by copying to memory \- so it reads a binary value in native endianness.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBit\fP \-\- a \fI\%buffer_iterator\fP where reading will start
.IP \(bu 2
\fBvalue\fP \-\- a basic type (integral or floating point value)
.IP \(bu 2
\fBerror\fP \-\- (optional) capture an error that was encountered instead of
halting on error
.UNINDENT
.TP
.B Returns
a buffer iterator storing the position immediately after
the written value.
.UNINDENT
.UNINDENT
.SS CommDiagnostics
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use CommDiagnostics;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This module provides support for reporting and counting
communication operations between network\-connected locales.  The
operations include various kinds of remote reads (GETs), remote
writes (PUTs), and remote executions.
Callers can request on\-the\-fly output each time a remote operation
occurs, or count such operations as they occur and retrieve the
counts later.  The former gives more detailed information but has
much more overhead.  The latter has much less overhead but only
provides aggregate information.
.sp
\fBOn\-the\-fly Reporting\fP
.sp
All forms of communication reporting and counting are done between
pairs of function calls that turn it on and off.  On\-the\-fly
reporting across all locales is done like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
startVerboseComm();
// between start/stop calls, report comm ops initiated on any locale
stopVerboseComm();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On\-the\-fly reporting for just the calling locale is similar.  Only
the procedure names change:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
startVerboseCommHere();
// between start/stop calls, report comm ops initiated on this locale
stopVerboseCommHere();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In either case, the output produced consists of a line written to
\fBstdout\fP for each communication operation.  (Here \fBstdout\fP means
the file associated with the process, not the Chapel channel with the
same name.)
.sp
Consider this little example program:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use CommDiagnostics;
proc main() {
  startVerboseComm();
  var x: int = 1;
  on Locales(1) {     // should execute_on a blocking task onto locale 1
    x = x + 1;        // should invoke a remote put and a remote get
  }
  stopVerboseComm();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Executing this on two locales with the \fB\-nl 2\fP command line
option results in the following output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0: remote task created on 1
1: t.chpl:6: remote get from 0
1: t.chpl:6: remote put to 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The initial number refers to the locale reporting the communication
event.  The file name and line number point to the place in the
code that triggered the communication event.  (For remote execute_ons,
file name and line number information is not yet reported.)
.sp
\fBCounting Communication Operations\fP
.sp
Counting communication operations requires a few more calls then just
reporting them does.  In particular, the counts have to be retrieved
after they are collected and, if they have been used previously, the
internal counters have to be reset before counting is turned on.
Counting across all locales is done like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// (optional) if we counted previously, reset the counters to zero
resetCommDiagnostics();
startCommDiagnostics();
// between start/stop calls, count comm ops initiated on any locale
stopCommDiagnostics();
// retrieve the counts and report the results
writeln(getCommDiagnostics());
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Counting on just the calling locale is similar.  Just as for
on\-the\-fly reporting, only the procedure names change:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// (optional) if we counted previously, reset the counters to zero
resetCommDiagnosticsHere();
startCommDiagnosticsHere();
// between start/stop calls, count comm ops initiated on this locale
stopCommDiagnosticsHere();
// retrieve the counts and report the results
writeln(getCommDiagnosticsHere());
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The optional call to reset the counters is only needed when a program
collects counts more than once.  In this case, the counters have to
be set back to zero before starting the second and succeeding
counting periods.  By far the most common situation is that programs
only collect communication counts once per run, in which case this
step is not needed.
.sp
Note that the same internal mechanisms and counters are used for
counting on all locales and counting on just the calling locale, so
trying to do both at once may lead to surprising turn\-on/turn\-off
behavior and/or incorrect results.
.sp
Consider this little example program:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use CommDiagnostics;
proc main() {
  startCommDiagnostics();
  var x: int = 1;
  on Locales(1) {     // should execute_on a blocking task onto locale 1
    x = x + 1;        // should invoke a remote put and a remote get
  }
  stopCommDiagnostics();
  writeln(getCommDiagnostics());
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Executing this on two locales with the \fB\-nl 2\fP command line
option results in the following output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
(get = 0, get_nb = 0, put = 0, put_nb = 0, test_nb = 0, wait_nb = 0, try_nb = 0, execute_on = 1, execute_on_fast = 0, execute_on_nb = 0) (get = 1, get_nb = 0, put = 1, put_nb = 0, test_nb = 0, wait_nb = 0, try_nb = 0, execute_on = 0, execute_on_fast = 0, execute_on_nb = 0)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The first parenthesized group contains the counts for locale 0, and
the second contains the counts for locale 1.  So, for the
instrumented section of this program we can say that a remote execute_on
was executed on locale 0, and a remote get and a remote put were
executed on locale 1.
.sp
\fBStudying Communication During Module Initialization\fP
.sp
It is hard for a programmer to determine exactly what happens during
initialization or teardown of a module, because the code that runs
then does so only implicitly, as a result of the declarations
present.  And even if that code can be identified, doing debug
output or logging data for later reporting might not work because
the Chapel capabilities needed to do so could be unavailable due to
being implemented by built\-in modules which themselves are not yet
initialized, or have already been torn down.
.sp
To help with that problem, this module provides built\-in support for
studying communication operations during module initialization and
teardown.  To use it, set either or both of the config params
\fI\%printInitVerboseComm\fP and \fI\%printInitCommCounts\fP,
described below.  You can do this by using appropriate
\fB\-sconfigParamName=value\fP command line options when you compile
your program.
.sp
The reporting and/or counting enabled by these covers all of program
execution, from just before the first module is initialized until
just after the last one is torn down.  This is almost always a
superset of the part of the program that is of interest, which is
often just a single module.  To learn what communication is being
done by a single module during its initialization and teardown it is
often necessary to run a small test program twice, once with that
module present and once without it.
.INDENT 0.0
.TP
.B record chpl_commDiagnostics
Aggregated communication operation counts.  This record type is
defined in the same way by both the underlying comm layer(s) and
this module, because we don\(aqt have a good way to inherit types back
and forth between the two.  This first definition duplicates the
one in the comm layer(s).
.INDENT 7.0
.TP
.B var get: uint(64)
blocking GETs, in which initiator waits for completion
.UNINDENT
.INDENT 7.0
.TP
.B var get_nb: uint(64)
non\-blocking GETs
.UNINDENT
.INDENT 7.0
.TP
.B var put: uint(64)
blocking PUTs, in which initiator waits for completion
.UNINDENT
.INDENT 7.0
.TP
.B var put_nb: uint(64)
non\-blocking PUTs
.UNINDENT
.INDENT 7.0
.TP
.B var test_nb: uint(64)
tests for non\-blocking GET/PUT completions
.UNINDENT
.INDENT 7.0
.TP
.B var wait_nb: uint(64)
blocking waits for non\-blocking GET/PUT completions
.UNINDENT
.INDENT 7.0
.TP
.B var try_nb: uint(64)
non\-blocking waits for non\-blocking GET/PUT completions
.UNINDENT
.INDENT 7.0
.TP
.B var execute_on: uint(64)
blocking remote executions, in which initiator waits for completion
.UNINDENT
.INDENT 7.0
.TP
.B var execute_on_fast: uint(64)
blocking remote executions performed by the target locale\(aqs
Active Message handler
.UNINDENT
.INDENT 7.0
.TP
.B var execute_on_nb: uint(64)
non\-blocking remote executions
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B type commDiagnostics = chpl_commDiagnostics
The Chapel record type inherits the comm layer definition of it.
.UNINDENT
.INDENT 0.0
.TP
.B proc startVerboseComm()
Start on\-the\-fly reporting of communication initiated on any locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc stopVerboseComm()
Stop on\-the\-fly reporting of communication initiated on any locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc startVerboseCommHere()
Start on\-the\-fly reporting of communication initiated on this locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc stopVerboseCommHere()
Stop on\-the\-fly reporting of communication initiated on this locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc startCommDiagnostics()
Start counting communication operations across the whole program.
.UNINDENT
.INDENT 0.0
.TP
.B proc stopCommDiagnostics()
Stop counting communication operations across the whole program.
.UNINDENT
.INDENT 0.0
.TP
.B proc startCommDiagnosticsHere()
Start counting communication operations initiated on this locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc stopCommDiagnosticsHere()
Stop counting communication operations initiated on this locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc resetCommDiagnostics()
Reset aggregate communication counts across the whole program.
.UNINDENT
.INDENT 0.0
.TP
.B proc resetCommDiagnosticsHere()
Reset aggregate communication counts on the calling locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc getCommDiagnostics()
Retrieve aggregate communication counts for the whole program.
.INDENT 7.0
.TP
.B Returns
array of counts of comm ops initiated on each locale
.TP
.B Return type
\fI[LocaleSpace] commDiagnostics\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getCommDiagnosticsHere()
Retrieve aggregate communication counts for this locale.
.INDENT 7.0
.TP
.B Returns
counts of comm ops initiated on this locale
.TP
.B Return type
\fIcommDiagnostics\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B config param printInitVerboseComm = false
If this is set, on\-the\-fly reporting of communication operations
will be turned on before any module initialization begins and
turned off after all module teardown ends.  See procedures
\fI\%startVerboseComm\fP and \fI\%stopVerboseComm\fP for more
information.
.UNINDENT
.INDENT 0.0
.TP
.B config param printInitCommCounts = false
If this is set, communication operations are counted from before
any module initialization begins until after all module teardown
ends, and then the aggregate counts are printed.  See procedures
\fI\%startCommDiagnostics\fP, \fI\%stopCommDiagnostics\fP, and
\fI\%getCommDiagnostics\fP for more information.
.UNINDENT
.SS DynamicIters
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use DynamicIters;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This module contains several iterators that can be used to drive a \fIforall\fP
loop by performing dynamic and adaptive splitting of a range\(aqs iterations.
.sp
For more information, see \fIUser\-Defined Parallel Zippered Iterators
in Chapel\fP\&. Bradford L. Chamberlain, Sung\-Eun Choi, Steven J. Deitz,
Angeles Navarro. \fIPGAS 2011: Fifth Conference on Partitioned Global
Address Space Programming Models\fP, October 2011.
.INDENT 0.0
.TP
.B config param debugDynamicIters: bool = false
Toggle debugging output.
.UNINDENT
.INDENT 0.0
.TP
.B iter dynamic(c: range(?), chunkSize: int, numTasks: int = 0)
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBc\fP : \fIrange(?)\fP \-\- The range to iterate over. The length of the range must be greater
than zero.
.IP \(bu 2
\fBchunkSize\fP : \fIint\fP \-\- The size of chunks to be yielded to each thread. Must be
greater than zero.
.IP \(bu 2
\fBnumTasks\fP : \fIint\fP \-\- The number of tasks to use. Must be >= zero. If this argument
has the value 0, it will use the value indicated by
\fBdataParTasksPerLocale\fP\&.
.UNINDENT
.TP
.B Yields
Indices in the range \fBc\fP\&.
.UNINDENT
.sp
This iterator is equivalent to the dynamic scheduling approach of OpenMP.
.sp
Given an input range \fBc\fP, each task is assigned chunks of size
\fBchunkSize\fP from \fBc\fP (or the remaining iterations if there are fewer
than \fBchunkSize\fP). This continues until there are no remaining iterations
in \fBc\fP\&.
.sp
This iterator can be called in serial and zippered contexts.
.UNINDENT
.INDENT 0.0
.TP
.B iter dynamic(c: domain, chunkSize: int, numTasks: int = 0, parDim: int = 1)
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBc\fP : \fIdomain\fP \-\- The domain to iterate over. The rank of the domain must be greater
than zero.
.IP \(bu 2
\fBchunkSize\fP : \fIint\fP \-\- The size of chunks to be yielded to each thread. Must be
greater than zero
.IP \(bu 2
\fBnumTasks\fP : \fIint\fP \-\- The number of tasks to use. Must be >= zero. If this argument
has the value 0, it will use the value indicated by
\fBdataParTasksPerLocale\fP\&.
.IP \(bu 2
\fBparDim\fP : \fIint\fP \-\- The index of the dimension to parallelize across. Must be > 0.
Must be <= the rank of the domain \fBc\fP\&. Defaults to 1.
.UNINDENT
.TP
.B Yields
Indices of the domain \fBc\fP
.UNINDENT
.sp
Given an input domain \fBc\fP, each task is assigned slices of \fBc\fP\&. The
chunks each have \fBchunkSize\fP slices in them (or the remaining iterations
if there are fewer than \fBchunkSize\fP). This continues until there are no
remaining iterations in the dimension of \fBc\fP indicated by \fBparDim\fP\&.
.sp
This iterator can be called in serial and zippered contexts.
.UNINDENT
.INDENT 0.0
.TP
.B iter guided(c: range(?), numTasks: int = 0)
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBc\fP : \fIrange(?)\fP \-\- The range to iterate over. Must have a length greater than zero.
.IP \(bu 2
\fBnumTasks\fP : \fIint\fP \-\- The number of tasks to use. Must be >= zero. If this argument
has the value 0, it will use the value indicated by
\fBdataParTasksPerLocale\fP\&.
.UNINDENT
.TP
.B Yields
Indices in the range \fBc\fP\&.
.UNINDENT
.sp
This iterator is equivalent to the guided policy of OpenMP: Given an input
range \fBc\fP, each task is assigned chunks of variable size, until there are
no remaining iterations in \fBc\fP\&. The size of each chunk is the number of
unassigned iterations divided by the number of tasks, \fBnumTasks\fP\&. The size
decreases approximately exponentially to 1. The splitting strategy is
therefore adaptive.
.sp
This iterator can be called in serial and zippered contexts.
.UNINDENT
.INDENT 0.0
.TP
.B iter adaptive(c: range(?), numTasks: int = 0)
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBc\fP : \fIrange(?)\fP \-\- The range to iterate over. Must have a length greater than zero.
.IP \(bu 2
\fBnumTasks\fP : \fIint\fP \-\- The number of tasks to use. Must be >= zero. If this argument
has the value 0, it will use the value indicated by
\fBdataParTasksPerLocale\fP\&.
.UNINDENT
.TP
.B Yields
Indices in the range \fBc\fP\&.
.UNINDENT
.sp
This iterator implements a naive adaptive binary splitting work\-stealing
strategy: Initially the leader iterator distributes the range to split, \fBc\fP,
evenly among the \fBnumTasks\fP tasks.
.sp
Then, each task performs adaptive splitting on its local sub\-range\(aqs iterations.
When a task exhausts its local iterations, it steals and splits from the
range of another task (the victim). The splitting method on the local range
and on the victim range is binary: i.e. the size of each chunk is computed as
the number of unassigned iterations divided by 2. There are three stealing
strategies that can be selected at compile time using the config param
\fI\%methodStealing\fP\&.
.sp
This iterator can be called in serial and zippered contexts.
.UNINDENT
.INDENT 0.0
.TP
.B enum Method { Whole = 0, RoundRobin = 1, WholeTail = 2 }
The enum used to represent adaptive methods.
.INDENT 7.0
.IP \(bu 2
\fBWhole\fP
Each task without work tries to steal from its neighbor range
until it exhausts that range. Then the task continues with the next
neighbor range, and so on until there is no more work. This is the default
policy.
.IP \(bu 2
\fBRoundRobin\fP
Each task without work tries to steal once from its neighbor range, next
from the following neighbor range and so on in a round\-robin way until
there is no more work.
.IP \(bu 2
\fBWholeTail\fP
Similar to the \fBWhole\fP method, but now the splitting in the victim
range is performed from its tail.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B config param methodStealing = Method.Whole
Used to select the adaptive stealing method. Defaults to \fBWhole\fP\&.
See \fI\%Method\fP for more information.
.UNINDENT
.SS Error
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Error;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for error handling.
.sp
This module helps to handle errors. In particular, it enables routines
to return a syserr \- encoding an error state \- and then contains routines
that can be provided a syserr in order to print out a useful error message.
.sp
This module defines the type syserr, which can encode an error code or an
error message. This type can be returned from routines generating an error.
.sp
The IO module uses these routines in a way that supports error inspection
and also rapid prototyping. Most routines in the IO module have two forms.
In one form, an error (of type syserr) is returned in an out error argument.
In the second form, no error is returned, and instead the task will halt
with a fatal error if an error is encountered.
.INDENT 0.0
.TP
.B proc ioerror(error: syserr, msg: string)
Halt with a useful message if there was an error. Do nothing if the error
argument does not indicate an error occurred. The error message printed
when halting will describe the error passed and msg will be appended to it.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- the error object
.IP \(bu 2
\fBmsg\fP \-\- extra information to print after the error description
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc ioerror(error: syserr, msg: string, path: string)
Halt with a useful message if there was an error. Do nothing if the error
argument does not indicate an error occurred. The error message printed
when halting will describe the error passed and msg will be appended to it,
along with the path related to the error (for example, the path to a file
which could not be opened).
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- the error object
.IP \(bu 2
\fBmsg\fP \-\- extra information to print after the error description
.IP \(bu 2
\fBpath\fP \-\- a path to print out that is related to the error
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc ioerror(error: syserr, msg: string, path: string, offset: int(64))
Halt with a useful message if there was an error. Do nothing if the error
argument does not indicate an error occurred. The error message printed
when halting will describe the error passed and msg will be appended to it,
along with the path and file offset related to the error. For example, this
routine might indicate a file format error at a particular location.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- the error object
.IP \(bu 2
\fBmsg\fP \-\- extra information to print after the error description
.IP \(bu 2
\fBpath\fP \-\- a path to print out that is related to the error
.IP \(bu 2
\fBoffset\fP \-\- an offset to print out that is related to the error
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc ioerror(errstr: string, msg: string, path: string, offset: int(64))
Halt with a useful message. Instead of an error argument, this routine takes
in an error string to report.
The error message printed when halting will describe the error passed and
msg will be appended to it, along with the path and file offset related to
the error. For example, this routine might indicate a file format error at a
particular location.
.sp
This routine .
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerrstr\fP \-\- the error string
.IP \(bu 2
\fBmsg\fP \-\- extra information to print after the error description
.IP \(bu 2
\fBpath\fP \-\- a path to print out that is related to the error
.IP \(bu 2
\fBoffset\fP \-\- an offset to print out that is related to the error
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc errorToString(error: syserr): string
Convert a syserr error code to a human\-readable string describing that
error.
.INDENT 7.0
.TP
.B Arguments
\fBerrstr\fP \-\- the error string
.TP
.B Returns
a string describing the error
.UNINDENT
.UNINDENT
.SS FileSystem
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use FileSystem;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A file utilities library
.sp
The FileSystem module focuses on file and directory properties and
operations.  It does not cover every interaction involving a file\-\-\- for
instance, path\-specific operations live in the \fBPath\fP module, while
routines for opening, writing to, or reading from a file live in the
\fBIO\fP module.  Rather, it covers cases where the user would prefer a file
or directory to be handled wholesale and/or with minimal interaction.  For
example, this module contains \fI\%File/Directory Manipulations\fP and functions for determining
the \fI\%File/Directory Properties\fP\&.  Also included are operations relating to the current
process\(aqs file system state, which are performed on a specified locale
(\fI\%Locale State Functionality\fP).  The module also contains iterators for traversing the
file system (\fI\%File System Traversal Iterators\fP).
.SS File/Directory Manipulations
.sp
\fI\%copy\fP
\fI\%copyFile\fP
\fI\%copyTree\fP
\fI\%mkdir\fP
\fI\%moveDir\fP
\fI\%remove\fP
\fI\%rmTree\fP
\fI\%symlink\fP
\fI\%chmod\fP
\fI\%chown\fP
\fI\%copyMode\fP
\fI\%rename\fP
.SS File/Directory Properties
.sp
\fI\%getGID\fP
\fI\%getMode\fP
\fI\%getFileSize\fP
\fI\%getUID\fP
\fI\%exists\fP
\fI\%isDir\fP
\fI\%isFile\fP
\fI\%isLink\fP
\fI\%isMount\fP
\fI\%sameFile\fP
.SS Locale State Functionality
.sp
\fI\%locale.chdir\fP
\fI\%locale.cwd\fP
\fI\%locale.umask\fP
.SS File System Traversal Iterators
.sp
\fI\%glob\fP
\fI\%listdir\fP
\fI\%walkdirs\fP
\fI\%findfiles\fP
.SS Constant and Function Definitions
.INDENT 0.0
.TP
.B const S_IRUSR: int
S_IRUSR and the following constants are values of the form
S_I[R | W | X][USR | GRP | OTH], S_IRWX[U | G | O], S_ISUID, S_ISGID, or
S_ISVTX, where R corresponds to readable, W corresponds to writable, X
corresponds to executable, USR and U correspond to user, GRP and G
correspond to group, OTH and O correspond to other, directly tied to the C
idea of these constants as visible at \fI\%GNU Permissions\fP\&.
They are intended for use when dealing with the permissions of files or
directories, such as with \fI\%chmod\fP, \fI\%getMode\fP, \fI\%mkdir\fP,
or \fI\%umask\fP
.sp
S_IRUSR refers to the user\(aqs read permission
.UNINDENT
.INDENT 0.0
.TP
.B const S_IWUSR: int
Refers to the user\(aqs write permission, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IXUSR: int
Refers to the user\(aqs executable permission, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IRWXU: int
Refers to all the user\(aqs permissions \- read, write, and execute.  See
\fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IRGRP: int
Refers to the group\(aqs read permission, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IWGRP: int
Refers to the group\(aqs write permission, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IXGRP: int
Refers to the group\(aqs executable permission, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IRWXG: int
Refers to all the permissions \- read, write, and execute \- of those in this
group, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IROTH: int
Refers to everyone else\(aqs read permission, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IWOTH: int
Refers to everyone else\(aqs write permission, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IXOTH: int
Refers to everyone else\(aqs executable permission, see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_IRWXO: int
Refers to all the permissions \- read, write, and execute \- of everyone else,
see \fI\%S_IRUSR\fP
.UNINDENT
.INDENT 0.0
.TP
.B const S_ISUID: int
Use of this would cause the user id to be set on execution.  See
\fI\%GNU Permissions\fP
for what that generally means, and \fI\%S_IRUSR\fP for intended uses, etc.
.UNINDENT
.INDENT 0.0
.TP
.B const S_ISGID: int
Use of this would cause the group id to be set on execution.  See
\fI\%GNU Permissions\fP
for what that generally means, and \fI\%S_IRUSR\fP for intended uses, etc.
.UNINDENT
.INDENT 0.0
.TP
.B const S_ISVTX: int
This is the sticky bit. See \fI\%GNU Permissions\fP
for what that generally means, and \fI\%S_IRUSR\fP for intended uses, etc.
.UNINDENT
.INDENT 0.0
.TP
.B proc locale.chdir(name: string)
Change the current working directory of the locale in question to the
specified path \fIname\fP\&.
.sp
Will halt with an error message if one is detected.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
This is not safe within a parallel context.  A chdir call in one task
will affect the current working directory of all tasks for that locale.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- The intended current working directory
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc chmod(name: string, mode: int)
Set the permissions of the file or directory specified by the argument
\fIname\fP to that indicated by the argument \fImode\fP\&.
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBname\fP : \fIstring\fP \-\- The name of the file or directory whose permissions should be
altered.
.IP \(bu 2
\fBmode\fP : \fIint\fP \-\- The permissions desired for the file or directory in question.
See description of \fI\%S_IRUSR\fP, for instance, for potential
values.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc chown(name: string, uid: int, gid: int)
Change one or both of the owner and group id of the named file or directory
to the specified values.  If \fIuid\fP or \fIgid\fP are \-1, the value in question
will remain unchanged.
.sp
Halts with an error message if one occurred.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBname\fP : \fIstring\fP \-\- The name of the file to be changed.
.IP \(bu 2
\fBuid\fP : \fIint\fP \-\- The intended new owner(user) id, or \-1 if it should remain the
same.
.IP \(bu 2
\fBgid\fP : \fIint\fP \-\- The intended new group owner(id), or \-1 if it should remain the
same.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc copy(src: string, dest: string, metadata: bool = false)
Copies the contents and permissions of the file indicated by \fIsrc\fP into
the file or directory \fIdest\fP\&.  If \fIdest\fP is a directory, will halt with
an error message.  If \fImetadata\fP is set to \fItrue\fP, will also copy the
metadata (uid, gid, time of last access and time of modification) of the
file to be copied.
.sp
May halt with other error messages.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
In the future, when the \fBPath\fP module has been expanded further,
this function will be able to support directories for the dest argument.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBsrc\fP : \fIstring\fP \-\- The source file whose contents and permissions are to be copied
.IP \(bu 2
\fBdest\fP : \fIstring\fP \-\- The name of the destination file for the contents and permissions.
May or may not exist previously, but will be overwritten if it did
exist
.IP \(bu 2
\fBmetadata\fP : \fIbool\fP \-\- This argument indicates whether to copy metadata associated
with the source file.  It is set to \fIfalse\fP by default.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc copyFile(src: string, dest: string)
Copies the contents of the file indicated by \fIsrc\fP into the file indicated
by \fIdest\fP, replacing \fIdest\fP\(aqs contents if it already exists (and is a
different file than \fIsrc\fP, i.e. not a symbolic link to \fIsrc\fP).
.sp
If \fIdest\fP is not writable, or \fIsrc\fP and \fIdest\fP refer to the same file,
this function will halt with an error message.  Does not copy metadata.  May
halt with other error messages.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBsrc\fP : \fIstring\fP \-\- The source file whose contents are to be copied.
.IP \(bu 2
\fBdest\fP : \fIstring\fP \-\- The intended destination of the contents.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc copyMode(src: string, dest: string)
Copies the permissions of the file indicated by \fIsrc\fP to the file indicated
by \fIdest\fP, leaving contents, owner and group unaffected.
.sp
Will halt with an error message if one is detected.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBsrc\fP : \fIstring\fP \-\- The source file whose permissions are to be copied.
.IP \(bu 2
\fBdest\fP : \fIstring\fP \-\- The intended destination of the permissions.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc copyTree(src: string, dest: string, copySymbolically: bool = false)
Will recursively copy the tree which lives under \fIsrc\fP into \fIdst\fP,
including all contents, permissions, and metadata.  \fIdst\fP must not
previously exist, this function assumes it can create it and any missing
parent directories. If \fIcopySymbolically\fP is \fItrue\fP, symlinks will be
copied as symlinks, otherwise their contents and metadata will be copied
instead.
.sp
Will halt with an error message if one is detected.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBsrc\fP : \fIstring\fP \-\- The root of the source tree to be copied.
.IP \(bu 2
\fBdest\fP : \fIstring\fP \-\- The root of the destination directory under which the contents of
\fIsrc\fP are to be copied (must not exist prior to this function
call).
.IP \(bu 2
\fBcopySymbolically\fP : \fIbool\fP \-\- This argument is used to indicate how to handle
symlinks in the source directory.  It is set to
\fIfalse\fP by default
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc locale.cwd(): string
Obtains and returns the current working directory for this locale.
.sp
Will halt with an error message if one was detected.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
Another task on this locale can change the current working directory from
underneath this task, so use caution when making use of this method in
a parallel environment.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Returns
The current working directory for the locale in question.
.TP
.B Return type
\fIstring\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc exists(name: string): bool
Determines if the file or directory indicated by \fIname\fP exists and returns
the result of this check.
.sp
Will halt with an error message if one was detected.
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- The file or directory whose existence is in question.
.TP
.B Returns
\fItrue\fP if the provided argument corresponds to an existing file or
directory, \fIfalse\fP otherwise.  Also returns \fIfalse\fP for broken
symbolic links.
.TP
.B Return type
\fIbool\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B iter findfiles(startdir: string = ".", recursive: bool = false, hidden: bool = false): string
Finds files from a given start directory and yields their names,
similar to simple invocations of the command\-line \fIfind\fP utility.
May be invoked in serial or non\-zippered parallel contexts.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBstartdir\fP : \fIstring\fP \-\- The root directory from which to start the search
(defaults to \fB"."\fP)
.IP \(bu 2
\fBrecursive\fP : \fIbool\fP \-\- Indicates whether or not to descend recursively into
subdirectories (defaults to \fIfalse\fP)
.IP \(bu 2
\fBhidden\fP : \fIbool\fP \-\- Indicates whether or not to descend into hidden subdirectories and yield hidden files (defaults to \fIfalse\fP)
.UNINDENT
.TP
.B Yields
The paths to any files found, relative to \fIstartdir\fP, as strings
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getGID(name: string): int
Obtains and returns the group id associated with the file or directory
specified by \fIname\fP\&.
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- The file or directory whose group id is desired
.TP
.B Returns
The group id of the file or directory in question
.TP
.B Return type
\fIint\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getMode(name: string): int
Obtains and returns the current permissions of the file or directory
specified by \fIname\fP\&.
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- The file or directory whose permissions are desired.
.TP
.B Returns
The permissions of the specified file or directory
See description of \fI\%S_IRUSR\fP, for instance, for potential
values.
.TP
.B Return type
\fIint\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getFileSize(name: string): int
Obtains and returns the size (in bytes) of the file specified by \fIname\fP\&.
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- The file whose size is desired
.TP
.B Returns
The size in bytes of the file in question
.TP
.B Return type
\fIint\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getUID(name: string): int
Obtains and returns the user id associated with the file or directory
specified by \fIname\fP\&.
.sp
Will halt with an error message if one is detected.
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- The file or directory whose user id is desired
.TP
.B Returns
The user id of the specified file or directory
.TP
.B Return type
\fIint\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B iter glob(pattern: string = "*"): string
Yields filenames that match a given \fIglob\fP pattern.  May be invoked
in serial or parallel contexts (zippered or non\-).
.INDENT 7.0
.TP
.B Arguments
\fBpattern\fP : \fIstring\fP \-\- The glob pattern to match against (defaults to \fB"*"\fP)
.TP
.B Yields
The matching filenames as strings
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc isDir(name: string): bool
Determine if the provided path \fIname\fP corresponds to a directory and return
the result
.sp
Will halt with an error message if one is detected, including if the path
does not refer to a valid file or directory
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- A path that could refer to a directory.
.TP
.B Returns
\fItrue\fP if the path is a directory, \fIfalse\fP if it is not
.TP
.B Return type
\fIbool\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc isFile(name: string): bool
Determine if the provided path \fIname\fP corresponds to a file and return
the result
.sp
Will halt with an error message if one is detected, including if the path
does not refer to a valid file or directory
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- A path that could refer to a file.
.TP
.B Returns
\fItrue\fP if the path is a file, \fIfalse\fP if it is not
.TP
.B Return type
\fIbool\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc isLink(name: string): bool
Determine if the provided path \fIname\fP corresponds to a link and return the
result.  If symbolic links are not supported, will return \fIfalse\fP\&.
.sp
Will halt with an error message if one is detected, including if the path
does not refer to a valid file or directory
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- A path that could refer to a symbolic link.
.TP
.B Returns
\fItrue\fP if the path is a symbolic link, \fIfalse\fP if it is not or
if symbolic links are not supported.
.TP
.B Return type
\fIbool\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc isMount(name: string): bool
Determine if the provided path \fIname\fP corresponds to a mount point and
return the result.
.sp
Will halt with an error message if one is detected, including if the path
does not refer to a valid file or directory.
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- A path that could refer to a mount point.
.TP
.B Returns
\fItrue\fP if the path is a mount point, \fIfalse\fP if it is not.
.TP
.B Return type
\fIbool\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B iter listdir(path: string = ".", hidden: bool = false, dirs: bool = true, files: bool = true, listlinks: bool = true): string
Lists the contents of a directory.  May be invoked in serial
contexts only.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBpath\fP : \fIstring\fP \-\- The directory whose contents should be listed
(defaults to \fB"."\fP)
.IP \(bu 2
\fBhidden\fP : \fIbool\fP \-\- Indicates whether hidden files/directory should be listed
(defaults to \fIfalse\fP)
.IP \(bu 2
\fBdirs\fP : \fIbool\fP \-\- Indicates whether directories should be listed
(defaults to \fItrue\fP)
.IP \(bu 2
\fBfiles\fP : \fIbool\fP \-\- Indicates whether files should be listed (defaults to \fItrue\fP)
.IP \(bu 2
\fBlistlinks\fP : \fIbool\fP \-\- Indicates whether symbolic links should be listed
(defaults to \fItrue\fP)
.UNINDENT
.TP
.B Yields
The names of the specified directory\(aqs contents, as strings
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc mkdir(name: string, mode: int = 511, parents: bool = false)
Attempt to create a directory with the given path, \fIname\fP\&.  If \fIparents\fP
is \fItrue\fP, will attempt to create any directory in the path that did not
previously exist.
.sp
Will halt with an error message if one is detected
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
In the case where \fIparents\fP is \fItrue\fP, there is a potential security
vulnerability.  Checking whether parent directories exist and creating
them are separate events.  This is called a Time of Check, Time of Use
vulnerability (TOCTOU), and in the case of files or directories that did
not previously exist, there is no known guard against it.  So even if
\fIparents == true\fP and a parent directory didn\(aqt exist before this
function was called but does exist afterward, it\(aqs not necessarily true
that this function created that parent. Some other concurrent operation
could have done so, either intentionally or unintentionally, maliciously
or ignorantly.  This option is provided as a convenience only, and any
attempt to perform the same functionality will run a similar risk.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBname\fP : \fIstring\fP \-\- The name of the directory to be created, fully specified.
.IP \(bu 2
\fBmode\fP : \fIint\fP \-\- The permissions desired for the directory to create.  Takes the
current \fI\%umask\fP into account.  See description of
\fI\%S_IRUSR\fP, for instance, for potential values.
.IP \(bu 2
\fBparents\fP : \fIbool\fP \-\- Indicates whether parent directories should be created.  If
set to \fIfalse\fP, any nonexistent parent will cause an error
to occur.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc moveDir(src: string, dest: string)
Recursively moves the directory indicated by \fIsrc\fP and its contents to the
destination denoted by \fIdest\fP\&.  If \fIdest\fP is a directory, \fIsrc\fP is moved
inside of it.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
We do not currently support the case where the dest argument already
exists and is a directory.  When the \fBPath\fP module has been
expanded further, this support can be enabled.
.UNINDENT
.UNINDENT
.sp
Will halt with an error message if one is detected.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBsrc\fP : \fIstring\fP \-\- the location of the directory to be moved
.IP \(bu 2
\fBdest\fP : \fIstring\fP \-\- the location to move it to.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc rename(oldname: string, newname: string)
Renames the file specified by \fIoldname\fP to \fInewname\fP\&.  The file is not
opened during this operation.
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBoldname\fP : \fIstring\fP \-\- Current name of the file
.IP \(bu 2
\fBnewname\fP : \fIstring\fP \-\- Name which should be used to refer to the file in the future.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc remove(name: string)
Removes the file or directory specified by \fIname\fP
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- The file/directory to remove
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc rmTree(root: string)
Delete the entire directory tree specified by root.
.sp
Will halt with an error message if one is detected.
.INDENT 7.0
.TP
.B Arguments
\fBroot\fP : \fIstring\fP \-\- path name representing a directory that should be deleted along
with its entire contents.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc sameFile(file1: string, file2: string): bool
Determines if both pathnames refer to the same file or directory (utilizing
operating system operations rather than string ones, due to the possibility
of symbolic links, \fBcurDir\fP, or \fBparentDir\fP appearing
in the path) and returns the result of that check
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBfile1\fP : \fIstring\fP \-\- The first path to be compared.
.IP \(bu 2
\fBfile2\fP : \fIstring\fP \-\- The second path to be compared.
.UNINDENT
.TP
.B Returns
\fItrue\fP if the two paths refer to the same file or directory,
\fIfalse\fP otherwise.
.TP
.B Return type
\fIbool\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc sameFile(file1: file, file2: file): bool
Determines if both \fBfile\fP records refer to the same file
(utilizing operating system operations rather than string ones, due to the
possibility of symbolic links, \fBcurDir\fP, or
\fBparentDir\fP appearing in the path) and returns the result of that
check
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBfile1\fP : \fIfile\fP \-\- The first file to be compared.
.IP \(bu 2
\fBfile2\fP : \fIfile\fP \-\- The second file to be compared.
.UNINDENT
.TP
.B Returns
\fItrue\fP if the two records refer to the same file, \fIfalse\fP
otherwise.
.TP
.B Return type
\fIbool\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc symlink(oldName: string, newName: string)
Create a symbolic link pointing to \fIoldName\fP with the path \fInewName\fP\&.
.sp
Will halt with an error message if one is detected
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBoldName\fP : \fIstring\fP \-\- The source file to be linked
.IP \(bu 2
\fBnewName\fP : \fIstring\fP \-\- The location where the symbolic link should live
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc locale.umask(mask: int): int
Sets the file creation mask of the current locale to \fImask\fP, and returns
the previous value of the file creation mask for that locale.  See
description of \fI\%S_IRUSR\fP, for instance, for potential values.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
This is not safe within a parallel context.  A umask call in one task
will affect the umask of all tasks for that locale.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
\fBmask\fP : \fIint\fP \-\- The file creation mask to use now.
.TP
.B Returns
The previous file creation mask
.TP
.B Return type
\fIint\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B iter walkdirs(path: string = ".", topdown: bool = true, depth: int = max(int), hidden: bool = false, followlinks: bool = false, sort: bool = false): string
Recursively walk a directory structure, yielding directory names.
May be invoked in serial or non\-zippered parallel contexts.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The current parallel version is not very adaptive/dynamic
in its application of parallelism to the list of
subdirectories at any given level of the traversal, and
could be improved in this regard.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBpath\fP : \fIstring\fP \-\- The directory from which to start the walk (defaults to \fB"."\fP)
.IP \(bu 2
\fBtopdown\fP : \fIbool\fP \-\- Indicates whether to yield a directory before or after descending into its children (defaults to \fItrue\fP)
.IP \(bu 2
\fBdepth\fP : \fIint\fP \-\- Indicates the maximum recursion depth to use (defaults to \fImax(int)\fP)
.IP \(bu 2
\fBhidden\fP : \fIbool\fP \-\- Indicates whether to descend into hidden directories (defaults to \fIfalse\fP)
.IP \(bu 2
\fBfollowlinks\fP : \fIbool\fP \-\- Indicates whether to follow symbolic links (defaults to \fIfalse\fP)
.IP \(bu 2
\fBsort\fP : \fIbool\fP \-\- Indicates whether or not to consider subdirectories in sorted order (defaults to \fIfalse\fP).  Note that requesting sorting has no effect in parallel invocations.
.UNINDENT
.TP
.B Yields
The directory names encountered, relative to \fIpath\fP, as strings
.UNINDENT
.UNINDENT
.SS GMP
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use GMP;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for GNU Multiple Precision Arithmetic
.sp
This module supports integration with the GMP library (the GNU Multiple
Precision Arithmetic Library. See the \fI\%GMP homepage\fP
for more information on this library.
.sp
This module is a prototype implementation of a standard GMP (GNU
Multiple Precision Arithmetic Library) module in Chapel.  It should be
considered incomplete in that (a) only a subset of the full GMP interface is
supported, and (b) the performance is currently lacking due to extraneous
copies in the Chapel code that have not yet been optimized away.  If there is
sufficient interest, this prototype can be expanded to support the full GMP
interface and performance.
.sp
This prototype GMP module has been used to implement a port of the standard GMP
Chudnovsky algorithm for computing pi to arbitrary digits.  If you are
interested in receiving a copy of this Chapel program, or simply in expressing
your support for GMP within Chapel, please contact us at \fI\%chapel_info@cray.com\fP\&.
.SS Using the GMP Module
.INDENT 0.0
.TP
.B Step 1:
Build Chapel with GMP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
# To use the already\-installed GMP
export CHPL_GMP=system
# To use the distributed GMP
export CHPL_GMP=gmp
# From $CHPL_HOME
make clean; make
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B Step 2:
Have your Chapel program \fBuse\fP the standard GMP module
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
use GMP;   // put this statement in your Chapel program
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B Step 3:
Start using the supported subset of GMP types and routines
or the BigInt class (see below for a complete listing).
.UNINDENT
.SS Using the BigInt class
.sp
The GMP Chapel module provides a \fI\%BigInt\fP class wrapping GMP integers.
At the present time, only the functions for \fBmpz\fP (ie signed integer)
GMP types are supported with \fI\%BigInt\fP; future work will be to
extend this support to floating\-point types. Also, in the future,
we hope to provide these GMP functions as records that support
operators like \fB+\fP, \fB*\fP, \fB\-\fP, etc.
.sp
\fI\%BigInt\fP methods all wrap GMP functions with obviously similar names.
The \fI\%BigInt\fP methods are locale aware \- so Chapel programs can create a
distributed array of GMP numbers. The method of \fI\%BigInt\fP objects are
setting the receiver, so e.g. myBigInt.add(x,y) sets myBigInt to \fBx + y\fP\&.
.sp
A code example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use GMP;

var a = new BigInt(); // initialize a GMP value, set it to zero

a.fac_ui(100); // set a to 100!

writeln(a); // output 100!

delete a; // free memory used by the GMP value

var b = new BigInt("48473822929893829847"); // initialize from a decimal string
b.add_ui(b, 1); // add one to b

delete b; // free memory used by b
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Calling GMP functions directly
.sp
The second option for Chapel programs using this module is to call the GMP
functions directly. For a full reference to GMP capabilities, please refer to
the \fI\%GMP website\fP and the
\fI\%GMP documentation\fP\&.
.sp
At present, Chapel\(aqs GMP module supports the following GMP types:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%mp_bitcnt_t\fP
.IP \(bu 2
\fI\%mpf_t\fP
.IP \(bu 2
\fI\%mpz_t\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
And all \fI\%mpz_t\fP GMP routines, as well as the following routines:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%gmp_fprintf()\fP
.IP \(bu 2
\fI\%gmp_printf()\fP
.IP \(bu 2
\fI\%mpf_add()\fP
.IP \(bu 2
\fI\%mpf_clear()\fP
.IP \(bu 2
\fI\%mpf_div_2exp()\fP
.IP \(bu 2
\fI\%mpf_get_d()\fP
.IP \(bu 2
\fI\%mpf_get_prec()\fP
.IP \(bu 2
\fI\%mpf_init()\fP
.IP \(bu 2
\fI\%mpf_mul()\fP
.IP \(bu 2
\fI\%mpf_mul_ui()\fP
.IP \(bu 2
\fI\%mpf_out_str()\fP
.IP \(bu 2
\fI\%mpf_set_d()\fP
.IP \(bu 2
\fI\%mpf_set_default_prec()\fP
.IP \(bu 2
\fI\%mpf_set_prec_raw()\fP
.IP \(bu 2
\fI\%mpf_set_z()\fP
.IP \(bu 2
\fI\%mpf_sub()\fP
.IP \(bu 2
\fI\%mpf_ui_div()\fP
.IP \(bu 2
\fI\%mpf_ui_sub()\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B type mpf_t = 1*__mpf_struct
The GMP \fBmpf_t\fP type
.UNINDENT
.INDENT 0.0
.TP
.B type mpz_t = 1*__mpz_struct
The GMP \fBmpz_t\fP type
.UNINDENT
.INDENT 0.0
.TP
.B type gmp_randstate_t = 1*__gmp_randstate_struct
The GMP \fBgmp_randstate_t\fP type
.UNINDENT
.INDENT 0.0
.TP
.B type mp_bitcnt_t = c_ulong
The GMP \fBmp_bitcnt_t\fP type
.UNINDENT
.INDENT 0.0
.TP
.B type mp_size_t = size_t
The GMP \fBmp_size_t\fP type
.UNINDENT
.INDENT 0.0
.TP
.B type mp_limb_t = uint(64)
The GMP \fBmp_limb_t\fP type
.UNINDENT
.INDENT 0.0
.TP
.B type mp_ptr
The GMP \fBmp_ptr\fP type
.UNINDENT
.INDENT 0.0
.TP
.B const mp_bits_per_limb: c_int
The GMP \fImp_bits_per_limb\(ga\fP constant
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_randinit_default(ref STATE: gmp_randstate_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_randinit_mt(ref STATE: gmp_randstate_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_randinit_lc_2exp(ref STATE: gmp_randstate_t, ref A: mpz_t, C: c_ulong, M2EXP: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_randinit_lc_2exp_size(ref STATE: gmp_randstate_t, SIZE: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_randinit_set(ref ROP: gmp_randstate_t, ref OP: gmp_randstate_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_randclear(ref STATE: gmp_randstate_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_init2(ref X: mpz_t, N: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_init(ref X: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_clear(ref X: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_realloc2(ref X: mpz_t, NBITS: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_set(ref ROP: mpz_t, OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_set_ui(ref ROP: mpz_t, OP: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_set_si(ref ROP: mpz_t, OP: c_long)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_set_d(ref ROP: mpz_t, OP: c_double)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_set_str(ref ROP: mpz_t, STR: c_string, BASE: c_int)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_swap(ref ROP1: mpz_t, ref ROP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_init_set(ref ROP: mpz_t, ref OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_init_set_ui(ref ROP: mpz_t, OP: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_init_set_si(ref ROP: mpz_t, OP: c_long)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_init_set_d(ref ROP: mpz_t, OP: c_double)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_init_set_str(ref ROP: mpz_t, STR: c_string, BASE: c_int): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_get_ui(ref OP: mpz_t): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_get_si(ref OP: mpz_t): c_long
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_get_d(ref OP: mpz_t): c_double
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_get_d_2exp(ref exp: c_long, ref OP: mpz_t): c_double
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_get_str(STR: c_string, BASE: c_int, ref OP: mpz_t): c_string
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_add(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_add_ui(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_sub(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_sub_ui(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_ui_sub(ref ROP: mpz_t, OP1: c_ulong, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_mul(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_mul_si(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_long)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_mul_ui(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_addmul(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_addmul_ui(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_submul(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_submul_ui(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_mul_2exp(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_neg(ref ROP: mpz_t, ref OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_abs(ref ROP: mpz_t, ref OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_q(ref Q: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_q(ref Q: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_q(ref Q: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_r(ref R: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_r(ref R: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_r(ref R: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_qr(ref Q: mpz_t, ref R: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_qr(ref Q: mpz_t, ref R: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_qr(ref Q: mpz_t, ref R: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_q_ui(ref Q: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_q_ui(ref Q: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_q_ui(ref Q: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_r_ui(ref R: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_r_ui(ref R: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_r_ui(ref R: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_qr_ui(ref Q: mpz_t, ref R: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_qr_ui(ref Q: mpz_t, ref R: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_qr_ui(ref Q: mpz_t, ref R: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_ui(ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_ui(ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_ui(ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_q_2exp(ref Q: mpz_t, ref N: mpz_t, B: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_q_2exp(ref Q: mpz_t, ref N: mpz_t, B: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_q_2exp(ref Q: mpz_t, ref N: mpz_t, B: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cdiv_r_2exp(ref R: mpz_t, ref N: mpz_t, B: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fdiv_r_2exp(ref R: mpz_t, ref N: mpz_t, B: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tdiv_r_2exp(ref R: mpz_t, ref N: mpz_t, B: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_mod(ref R: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_mod_ui(ref R: mpz_t, ref N: mpz_t, D: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_divexact(ref Q: mpz_t, ref N: mpz_t, ref D: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_divexact_ui(ref Q: mpz_t, ref N: mpz_t, D: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_divisible_p(ref N: mpz_t, ref D: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_divisible_ui_p(ref N: mpz_t, D: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_divisible_2exp_p(ref N: mpz_t, B: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_congruent_p(ref N: mpz_t, ref C: mpz_t, ref D: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_congruent_ui_p(ref N: mpz_t, C: c_ulong, D: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_congruent_2exp_p(ref N: mpz_t, ref C: mpz_t, B: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_powm(ref ROP: mpz_t, ref BASE: mpz_t, ref EXP: mpz_t, ref MOD: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_powm_ui(ref ROP: mpz_t, ref BASE: mpz_t, EXP: c_ulong, ref MOD: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_pow_ui(ref ROP: mpz_t, ref BASE: mpz_t, EXP: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_ui_pow_ui(ref ROP: mpz_t, BASE: c_ulong, EXP: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_root(ref ROP: mpz_t, ref OP: mpz_t, N: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_rootrem(ref ROOT: mpz_t, ref REM: mpz_t, ref U: mpz_t, N: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_sqrt(ref ROP: mpz_t, ref OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_sqrtrem(ref ROP1: mpz_t, ref ROP2: mpz_t, ref OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_perfect_power_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_perfect_square_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_probab_prime_p(ref N: mpz_t, REPS: c_int): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_nextprime(ref ROP: mpz_t, ref OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_gcd(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_gcd_ui(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_gcdext(ref G: mpz_t, ref S: mpz_t, ref T: mpz_t, ref A: mpz_t, ref B: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_lcm(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_lcm_ui(ref ROP: mpz_t, ref OP1: mpz_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_invert(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_jacobi(ref A: mpz_t, ref B: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_legendre(ref A: mpz_t, ref P: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_kronecker(ref A: mpz_t, ref B: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_kronecker_si(ref A: mpz_t, B: c_long): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_kronecker_ui(ref A: mpz_t, B: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_si_kronecker(A: c_long, ref B: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_ui_kronecker(A: c_ulong, ref B: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_remove(ref ROP: mpz_t, ref OP: mpz_t, ref F: mpz_t): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fac_ui(ref ROP: mpz_t, OP: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_bin_ui(ref ROP: mpz_t, N: mpz_t, K: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_bin_uiui(ref ROP: mpz_t, N: c_ulong, K: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fib_ui(ref FN: mpz_t, N: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fib2_ui(ref FN: mpz_t, FNSUB1: mpz_t, N: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_lucnum_ui(ref LN: mpz_t, N: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_lucnum2_ui(ref LN: mpz_t, LNSUB1: mpz_t, N: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cmp(ref OP1: mpz_t, ref OP2: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cmp_d(ref OP1: mpz_t, OP2: c_double): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cmp_si(ref OP1: mpz_t, OP2: c_long): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cmp_ui(ref OP1: mpz_t, OP2: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cmpabs(ref OP1: mpz_t, ref OP2: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cmpabs_d(ref OP1: mpz_t, OP2: c_double): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_cmpabs_ui(ref OP1: mpz_t, OP2: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_sgn(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_and(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_ior(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_xor(ref ROP: mpz_t, ref OP1: mpz_t, ref OP2: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_com(ref ROP: mpz_t, ref OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_popcount(ref OP: mpz_t): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_hamdist(ref OP1: mpz_t, ref OP2: mpz_t): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_scan0(ref OP: mpz_t, STARTING_BIT: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_scan1(ref OP: mpz_t, STARTING_BIT: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_setbit(ref ROP: mpz_t, BIT_INDEX: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_clrbit(ref ROP: mpz_t, BIT_INDEX: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_combit(ref ROP: mpz_t, BIT_INDEX: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_tstbit(ref OP: mpz_t, BIT_INDEX: c_ulong): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_urandomb(ref ROP: mpz_t, STATE: gmp_randstate_t, N: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_urandomm(ref ROP: mpz_t, STATE: gmp_randstate_t, N: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_rrandomb(ref ROP: mpz_t, STATE: gmp_randstate_t, N: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_randseed(ref STATE: gmp_randstate_t, SEED: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_randseed_ui(ref STATE: gmp_randstate_t, SEED: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_urandomb_ui(ref STATE: gmp_randstate_t, N: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_urandomm_ui(ref STATE: gmp_randstate_t, N: c_ulong): c_ulong
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fits_ulong_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fits_slong_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fits_uint_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fits_sint_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fits_ushort_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_fits_sshort_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_odd_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_even_p(ref OP: mpz_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc mpz_sizeinbase(ref OP: mpz_t, BASE: c_int): size_t
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_set_default_prec(PREC: mp_bitcnt_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_init(ref X: mpf_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_set_z(ref ROP: mpf_t, ref OP: mpz_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_get_prec(ref OP: mpf_t): mp_bitcnt_t
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_get_d(ref OP: mpf_t): c_double
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_set_d(ref ROP: mpf_t, OP: c_double)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_set_prec_raw(ref ROP: mpf_t, PREC: mp_bitcnt_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_ui_div(ref ROP: mpf_t, OP1: c_ulong, ref OP2: mpf_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_mul(ref ROP: mpf_t, ref OP1: mpf_t, ref OP2: mpf_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_ui_sub(ref ROP: mpf_t, OP1: c_ulong, ref OP2: mpf_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_add(ref ROP: mpf_t, ref OP1: mpf_t, ref OP2: mpf_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_sub(ref ROP: mpf_t, ref OP1: mpf_t, ref OP2: mpf_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_mul_ui(ref ROP: mpf_t, ref OP1: mpf_t, OP2: c_ulong)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_div_2exp(ref ROP: mpf_t, ref OP1: mpf_t, OP2: mp_bitcnt_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_out_str(STREAM: _file, BASE: c_int, N_DIGITS: size_t, ref OP: mpf_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc mpf_clear(ref X: mpf_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_printf(fmt: c_string, arg ...)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_fprintf(fp: _file, fmt: c_string, arg ...)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_fprintf(fp: _file, fmt: c_string, arg ...)
.UNINDENT
.INDENT 0.0
.TP
.B proc gmp_asprintf(ref ret: c_string, fmt: c_string, arg ...)
.UNINDENT
.INDENT 0.0
.TP
.B proc chpl_gmp_mpz_print(x: mpz_t)
Print out an mpz_t (for debugging)
.UNINDENT
.INDENT 0.0
.TP
.B proc chpl_gmp_mpz_get_str(base: c_int, x: mpz_t): c_string_copy
Get an mpz_t as a string
.UNINDENT
.INDENT 0.0
.TP
.B enum Round { UP = 1, DOWN = \-1, ZERO = 0 }
.UNINDENT
.INDENT 0.0
.TP
.B class BigInt
The BigInt class provides a more Chapel\-friendly interface to the
GMP integer functions. In particular, this class supports GMP
numbers that are stored in distributed arrays.
.sp
All methods on BigInt work with Chapel types. Many of them use the gmp
functions directly, which use C types. Runtime checks are used to ensure the
Chapel types can safely be cast to the C types (e.g. when casting a Chapel
uint it checks that it fits in the C ulong which could be a 32bit type if
running on linux32 platform).
.sp
The checks are controlled by the compiler options \fB\-\-[no\-]cast\-checks\fP,
\fB\-\-fast\fP, etc.
.sp
TODO: When a Chapel type will not safely cast to a C type, it would be
better to promote the Chapel value to a BigInt, then run the operation on
that BigInt. This would make the BigInt interface consistent across all
platforms (already true today) _and_ always work regardless of platform
(not true today).
.INDENT 7.0
.TP
.B var mpz: mpz_t
.UNINDENT
.INDENT 7.0
.TP
.B proc BigInt(init2: bool, nbits: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc BigInt(num: int)
.UNINDENT
.INDENT 7.0
.TP
.B proc BigInt(str: string, base: int = 0)
.UNINDENT
.INDENT 7.0
.TP
.B proc BigInt(str: string, base: int = 0, out error: syserr)
.UNINDENT
.INDENT 7.0
.TP
.B proc BigInt(num: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc BigInt()
.UNINDENT
.INDENT 7.0
.TP
.B proc BigInt.~BigInt()
.UNINDENT
.INDENT 7.0
.TP
.B proc numLimbs: uint(64)
.UNINDENT
.INDENT 7.0
.TP
.B proc mpzStruct(): __mpz_struct
.UNINDENT
.INDENT 7.0
.TP
.B proc maybeCopy(): (bool, BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc set(a: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc set_ui(num: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc set_si(num: int)
.UNINDENT
.INDENT 7.0
.TP
.B proc set(num: int)
.UNINDENT
.INDENT 7.0
.TP
.B proc set_d(num: real)
.UNINDENT
.INDENT 7.0
.TP
.B proc set_str(str: string, base: int = 0)
.UNINDENT
.INDENT 7.0
.TP
.B proc swap(a: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc get_ui(): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc get_si(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc get_d(): real
.UNINDENT
.INDENT 7.0
.TP
.B proc get_d_2exp(): (int, real)
.UNINDENT
.INDENT 7.0
.TP
.B proc get_str(base: int = 10): string
.UNINDENT
.INDENT 7.0
.TP
.B proc add(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc add_ui(a: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc sub(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc sub_ui(a: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc ui_sub(a: uint, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc mul(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc mul_si(a: BigInt, b: int)
.UNINDENT
.INDENT 7.0
.TP
.B proc mul_ui(a: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc addmul(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc addmul_ui(a: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc submul(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc submul_ui(a: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc mul_2exp(a: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc neg(a: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc abs(a: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc div_q(param rounding: Round, n: BigInt, d: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc div_r(param rounding: Round, n: BigInt, d: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc div_qr(param rounding: Round, r: BigInt, n: BigInt, d: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc div_q_ui(param rounding: Round, n: BigInt, d: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc div_r_ui(param rounding: Round, n: BigInt, d: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc div_qr_ui(param rounding: Round, r: BigInt, n: BigInt, d: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc div_ui(param rounding: Round, n: BigInt, d: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc div_q_2exp(param rounding: Round, n: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc div_r_2exp(param rounding: Round, n: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc mod(n: BigInt, d: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc mod_ui(n: BigInt, d: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc divexact(n: BigInt, d: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc divexact_ui(n: BigInt, d: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc divisible_p(d: BigInt): int
.UNINDENT
.INDENT 7.0
.TP
.B proc divisible_ui_p(d: uint): int
.UNINDENT
.INDENT 7.0
.TP
.B proc divisible_2exp_p(b: uint): int
.UNINDENT
.INDENT 7.0
.TP
.B proc congruent_p(c: BigInt, d: BigInt): int
.UNINDENT
.INDENT 7.0
.TP
.B proc congruent_ui_p(c: uint, d: uint): int
.UNINDENT
.INDENT 7.0
.TP
.B proc congruent_2exp_p(c: BigInt, b: uint): int
.UNINDENT
.INDENT 7.0
.TP
.B proc powm(base: BigInt, exp: BigInt, mod: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc powm_ui(base: BigInt, exp: uint, mod: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc pow_ui(base: BigInt, exp: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc ui_pow_ui(base: uint, exp: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc root(a: BigInt, n: uint): int
.UNINDENT
.INDENT 7.0
.TP
.B proc mpz_rootrem(rem: BigInt, u: BigInt, n: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc sqrt(a: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc sqrtrem(rem: BigInt, a: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc perfect_power_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc perfect_square(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc probab_prime_p(reps: int): int
.UNINDENT
.INDENT 7.0
.TP
.B proc nextprime(a: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc gcd(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc gcd_ui(a: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc gcdext(s: BigInt, t: BigInt, a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc lcm(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc lcm_ui(a: BigInt, b: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc invert(a: BigInt, b: BigInt): int
.UNINDENT
.INDENT 7.0
.TP
.B proc remove(a: BigInt, f: BigInt): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc fac_ui(a: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc bin_ui(n: BigInt, k: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc bin_uiui(n: uint, k: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc fib_ui(n: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc fib2_ui(fnsub1: BigInt, n: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc lucnum_ui(n: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc lucnum2_ui(lnsub1: BigInt, n: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc cmp(b: BigInt): int
.UNINDENT
.INDENT 7.0
.TP
.B proc cmp_d(b: real): int
.UNINDENT
.INDENT 7.0
.TP
.B proc cmp_si(b: int): int
.UNINDENT
.INDENT 7.0
.TP
.B proc cmp_ui(b: uint): int
.UNINDENT
.INDENT 7.0
.TP
.B proc cmpabs(b: BigInt): int
.UNINDENT
.INDENT 7.0
.TP
.B proc cmpabs_d(b: real): int
.UNINDENT
.INDENT 7.0
.TP
.B proc cmp_abs_ui(b: uint): int
.UNINDENT
.INDENT 7.0
.TP
.B proc sgn(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc and(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc ior(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc xor(a: BigInt, b: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc com(a: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc popcount(): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc hamdist(b: BigInt): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc scan0(starting_bit: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc scan1(starting_bit: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc setbit(bit_index: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc clrbit(bit_index: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc combit(bit_index: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc tstbit(bit_index: uint): int
.UNINDENT
.INDENT 7.0
.TP
.B proc fits_ulong_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc fits_slong_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc fits_uint_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc fits_sint_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc fits_ushort_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc fits_sshort_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc odd_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc even_p(): int
.UNINDENT
.INDENT 7.0
.TP
.B proc sizeinbase(base: int): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc realloc2(nbits: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc get_limbn(n: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc size(): size_t
.UNINDENT
.INDENT 7.0
.TP
.B proc debugprint()
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc BigInt.writeThis(writer)
.UNINDENT
.INDENT 0.0
.TP
.B proc jacobi(a: BigInt, b: BigInt): int
.UNINDENT
.INDENT 0.0
.TP
.B proc legendre(a: BigInt, p: BigInt): int
.UNINDENT
.INDENT 0.0
.TP
.B proc kronecker(a: BigInt, b: BigInt): int
.UNINDENT
.INDENT 0.0
.TP
.B proc kronecker_si(a: BigInt, b: int): int
.UNINDENT
.INDENT 0.0
.TP
.B proc kronecker_ui(a: BigInt, b: uint): int
.UNINDENT
.INDENT 0.0
.TP
.B proc si_kronecker(a: int, b: BigInt): int
.UNINDENT
.INDENT 0.0
.TP
.B proc ui_kronecker(a: uint, b: BigInt): int
.UNINDENT
.INDENT 0.0
.TP
.B class GMPRandom
.INDENT 7.0
.TP
.B var state: gmp_randstate_t
.UNINDENT
.INDENT 7.0
.TP
.B proc GMPRandom()
.UNINDENT
.INDENT 7.0
.TP
.B proc GMPRandom(twister: bool)
.UNINDENT
.INDENT 7.0
.TP
.B proc GMPRandom(a: BigInt, c: uint, m2exp: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc GMPRandom(size: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc GMPRandom(a: GMPRandom)
.UNINDENT
.INDENT 7.0
.TP
.B proc GMPRandom.~GMPRandom()
.UNINDENT
.INDENT 7.0
.TP
.B proc seed(seed: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc seed(seed: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc urandomb_ui(nbits: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc urandomm_ui(n: uint): uint
.UNINDENT
.INDENT 7.0
.TP
.B proc urandomb(r: BigInt, nbits: uint)
.UNINDENT
.INDENT 7.0
.TP
.B proc urandomm(r: BigInt, n: BigInt)
.UNINDENT
.INDENT 7.0
.TP
.B proc rrandomb(r: BigInt, nbits: uint)
.UNINDENT
.UNINDENT
.SS Help
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Help;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Functions for producing program help and usage.
.sp
Chapel programs can declare main to take arguments like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proc main(args: [] string) {
  for a in args {
    // process arguments
    writeln("Got argument ", a);
  }
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See doc/release/technotes/main.rst in a Chapel release for more
information on this feature.
.sp
Programs that use this feature might need to expand upon the usage message
that explains which config variables are available. To do so, this module
includes the \fI\%printUsage\fP function.
.INDENT 0.0
.TP
.B proc printUsage()
Print out a usage message for config variables. This function does not
exit. A typical use of this function would be to call it when \fB"\-\-help"\fP
or \fB"\-h"\fP are encountered when doing custom argument processing. In
addition to calling this function, programs with custom argument
processing should probably also print out a description of the arguments
that they take.  Once both help messages have been output, the program
would normally exit early \- for example, by returning from main.
.sp
A typical example might be this program, that accumulates a list of
filenames in addition to handling config variable arguments:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
use Help;

config const x = 5;

proc main(args: [] string) {
  var filenames: [1..0] string;

  var programName = args[0];

  for a in args[1..] {
    if a == "\-h" || a == "\-\-help" {
      writeln("Usage: ", programName, " <options> filename [filenames]");
      printUsage();
      exit(1); // returning 1 from main is also an option
    } else {
      filenames.push_back(a);
    }
  }

  writef("Got filenames = %ht\en", filenames);
  writef("Got configuration variable x = %ht\en", x);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS IO
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use IO;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for a variety of kinds of input and output.
.sp
Input/output (I/O) facilities in Chapel include the types \fI\%file\fP and
\fI\%channel\fP; the constants \fI\%stdin\fP, \fI\%stdout\fP and
\fI\%stderr\fP; the functions \fI\%open\fP, \fI\%file.close\fP,
\fI\%file.reader\fP, \fI\%file.writer\fP, \fI\%channel.read\fP,
\fI\%channel.write\fP, and many others.
.SS I/O Overview
.sp
A \fI\%file\fP in Chapel identifies a file in the underlying operating
system.  Reads and writes to a file are done via one or more channels
associated with the file.  Each \fI\%channel\fP uses a buffer to provide
sequential read or write access to its file, optionally starting at an offset.
.sp
For example, the following program opens a file and writes an integer to it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// open the file "test\-file.txt" for writing, creating it if
// it does not exist yet.
var myFile = open("test\-file.txt", iomode.cw);

// create a writing channel starting at file offset 0
// (start and end offsets can be specified when creating the
// channel)
var myWritingChannel = myFile.writer();

var x: int = 17;

// This function will write the human\-readable text version of x;
// binary I/O is also possible.
myWritingChannel.write(x);

// Now test\-file.txt contains:
// 17
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then, the following program can be used to read the integer:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// open the file "test\-file.txt" for reading only
var myFile = open("test\-file.txt", iomode.r);

// create a reading channel starting at file offset 0
// (start and end offsets can be specified when creating the
// channel)
var myReadingChannel = myFile.reader();

var x: int;

// Now read a textual integer. Note that the
// channel.read function returns a bool to indicate
// if it read something or if the end of the file
// was reached before something could be read.
var readSomething = myReadingChannel.read(x);

writeln("Read integer ", x);
// prints out:
// 17
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Design Rationale
.sp
Since channels operate independently, concurrent I/O to the same open file is
possible without contending for locks.  Furthermore, since the channel (and not
the file) stores the current file offset, it is straightforward to create
programs that access the same open file in parallel. Note that such parallel
access is not possible in C when multiple threads are using the same \fBFILE*\fP
to write to different regions of a file because of the race condition between
\fBfseek\fP and \fBfwrite\fP\&. Because of these issues, Chapel programmers wishing
to perform I/O will need to know how to open files as well as create channels.
.SS I/O Styles
.sp
Reading and writing of Chapel\(aqs basic types is regulated by an applicable
\fI\%iostyle\fP\&.  In particular, the I/O style controls whether binary or
text I/O should be performed. For binary I/O it specifies, for example, byte
order and string encoding. For text I/O it specifies string representation; the
base, field width and precision for numeric types; and so on.  Each channel has
an associated I/O style.  It applies to all read/write operations on that
channel, except when the program specifies explicitly an I/O style for a
particular read or write.
.sp
See the definition for the \fI\%iostyle\fP type. This type represents I/O
styles and provides details on formatting and other representation choices.
.sp
The default value of the \fI\%iostyle\fP type is undefined.  However, the
compiler\-generated constructor is available.  It can be used to generate the
default I/O style, with or without modifications. In addition, the function
\fI\%defaultIOStyle\fP will return the default I/O style just as \fBnew
iostyle()\fP will.
.sp
The I/O style for an I/O operation can be provided through an optional
\fBstyle=\fP argument in a variety of places:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
when performing the I/O, e.g. in calls to \fI\%channel.write\fP or
\fI\%channel.read\fP
.IP \(bu 2
when creating the channel with \fI\%file.reader\fP or \fI\%file.writer\fP
.IP \(bu 2
or when creating the file with e.g. \fI\%open\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Note that \fI\%file.reader\fP, or \fI\%file.writer\fP will copy the file\(aqs I/O
style if a \fBstyle=\fP argument is not provided. Also note that I/O functions on
channels will by default use the I/O style stored with that channel.
.sp
A channel\(aqs I/O style may be retrieved using \fI\%channel._style\fP and set
using \fI\%channel._set_style\fP\&. These functions should only be called while
the channel lock is held, however. See \fI\%Synchronization of Channel Data and Avoiding Data Races\fP
for more information on channel locks.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fI\%iostyle\fP is work in progress: the fields and/or their types may
change. Among other changes, we expect to be replacing the types of some
multiple\-choice fields from integral to enums.
.UNINDENT
.UNINDENT
.sp
As an example for specifying an I/O style, the code below specifies the minimum width for writing numbers so array elements are aligned in the output:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stdout.writeln(MyArray, new iostyle(min_width=10));
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
I/O facilities in Chapel also include several other ways to control I/O
formatting. There is support for \fI\%formatted I/O\fP
with \fI\%channel.readf\fP and \fI\%channel.writef\fP\&.  It is possible to write
data to strings (see "The write and writeln Methods on Strings" in the Chapel
language specification) which can then be further modified or combined
programmatically. Lastly, record or class implementations can provide custom
functions implementing read or write operations for that type (see "The
readThis, writeThis, and readWriteThis Methods" in the Chapel language
specification).
.SS Files
.sp
There are several functions that open a file and return a \fI\%file\fP including \fI\%open\fP, \fI\%opentmp\fP, \fI\%openmem\fP, \fI\%openfd\fP, and \fI\%openfp\fP\&.
.sp
Once a file is open, it is necessary to create associated channel(s) \- see
\fI\%file.reader\fP and \fI\%file.writer\fP \- to write to and/or read from the
file.
.sp
Use the \fI\%file.fsync\fP function to explicitly synchronize the file to
ensure that file data is committed to the file\(aqs underlying device for
persistence.
.sp
To release any resources associated with a file, it is necessary to first close
any channels using that file (with \fI\%channel.close\fP) and then the file
itself (with \fI\%file.close\fP).
.SS Functions for Channel Creation
.sp
\fI\%file.writer\fP creates a channel for writing to a file, and
\fI\%file.reader\fP create a channel for reading from a file.
.SS Synchronization of Channel Data and Avoiding Data Races
.sp
Channels (and files) contain locks in order to keep their operation safe for
multiple tasks. When creating a channel, it is possible to disable the lock
(for performance reasons) by passing \fBlocking=false\fP to e.g.  file.writer().
Some channel methods \- in particular those beginning with the underscore \-
should only be called on locked channels.  With these methods, it is possible
to get or set the channel style, or perform I/O "transactions" (see
\fI\%channel._mark\fP). To use these methods, first lock the channel with
channel.lock(), call the methods you need, and then unlock the channel with
channel.unlock(). Note that in the future, we may move to alternative ways of
calling these functions that guarantee that they are not called on a channel
without the appropriate locking.
.sp
Besides data races that can occur if locking is not used in channels when it
should be, it is also possible for there to be data races on file data that is
buffered simultaneously in multiple channels.  The main way to avoid such data
races is the \fI\%channel.flush\fP synchronization operation.
\fI\%channel.flush\fP will make all writes to the channel, if any, available to
concurrent viewers of its associated file, such as other channels or other
applications accessing this file concurrently. See the note below for
more details on the situation in which this kind of data race can occur.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Since channels can buffer data until \fI\%channel.flush\fP is called, it is
possible to write programs that have undefined behaviour because of race
conditions on channel buffers. In particular, the problem comes up for
programs that make:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
concurrent operations on multiple channels that operate on overlapping
regions of a file
.IP \(bu 2
where at least one of the overlapping channels is a writing channel
.IP \(bu 2
and where data could be stored more than one of the overlapping channel\(aqs
buffers at the same time (ie, write and read ordering are not enforced
through \fI\%channel.flush\fP and other mean such as sync variables).
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Note that it is possible in some cases to create a \fI\%file\fP that does
not allow multiple channels at different offsets. Channels created on such
files will not change the file\(aqs position based on a \fBstart=\fP offset
arguments. Instead, each read or write operation will use the file
descriptor\(aqs current position. Therefore, only one channel should be created
for files created in the following situations:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
with \fI\%openfp\fP
.IP \(bu 2
with \fI\%openfd\fP when provided a non\-seekable system file descriptor
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Performing I/O with Channels
.sp
Channels contain read and write methods, which are generic methods that can
read or write anything, and can also take optional arguments such as I/O style
or to return an error instead of halting. These functions generally take any
number of arguments. See:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%channel.write\fP
.IP \(bu 2
\fI\%channel.writeln\fP
.IP \(bu 2
\fI\%channel.writebits\fP
.IP \(bu 2
\fI\%channel.writef\fP (see also \fI\%Formatted I/O\fP)
.IP \(bu 2
\fI\%channel.read\fP
.IP \(bu 2
\fI\%channel.readln\fP
.IP \(bu 2
\fI\%channel.readbits\fP
.IP \(bu 2
\fI\%channel.readf\fP (see also \fI\%Formatted I/O\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.sp
In addition, there are several convenient synonyms for \fI\%channel.write\fP and
\fI\%channel.read\fP:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%channel.readwrite\fP
.IP \(bu 2
the \fI\%<~> operator\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Sometimes it\(aqs important to flush the buffer in a channel \- to do that, use the
.flush() method. Flushing the buffer will make all writes available to other
applications or other views of the file (ie, it will call e.g. the OS call
pwrite).  It is also possible to close a channel, which will implicitly
flush it and release any buffer memory used by the channel.  Note that if you
need to ensure that data from a channel is on disk, you\(aqll have to call
\fI\%channel.flush\fP or \fI\%channel.close\fP and then \fI\%file.fsync\fP on
the related file.
.SS Functions for Closing Channels
.sp
A channel must be closed in order to free the resources allocated for it,
to ensure that data written to it is visible to other channels,
or to allow the associated file to be closed.
.sp
See \fI\%channel.close\fP\&.
.sp
It is an error to perform any I/O operations on a channel
that has been closed.
It is an error to close a file when it has channels that
have not been closed.
.sp
In the future we plan to implement reference counting for files
and channels. Each file and channel will be closed automatically
when no references remain to it. For example, if only a local
variable refers to a channel, the channel will be closed
when that variable goes out of scope.
.sp
The ability for the program to close a file or a channel
explicitly will remain available.
.SS The \fBstdin\fP, \fBstdout\fP, and \fBstderr\fP Channels
.sp
Chapel provides the predefined channels \fI\%stdin\fP, \fI\%stdout\fP, and
\fI\%stderr\fP to access the corresponding operating system streams standard
input, standard output, and standard error.
.sp
\fI\%stdin\fP supports reading;
\fI\%stdout\fP and \fI\%stderr\fP support writing.
.sp
All three channels are safe to use concurrently.
Their types\(aq \fBkind\fP argument is \fBdynamic\fP
.SS Error Handling
.sp
Most I/O routines accept an optional \fIerror=\fP argument. If that argument
is used, instead of halting when an error is encountered, the function
will return the error code.
.sp
These error codes are stored with the type \fBSysBasic.syserr\fP\&. Success is
represented by \fBSysBasic.ENOERR\fP\&. The error codes and their meaning
are described in \fBSysBasic\fP\&. Some of these error codes that are commonly used within the I/O implementation  include:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBSysBasic.EEOF\fP \- the end of file was reached
.IP \(bu 2
\fBSysBasic.ESHORT\fP \- a read or write only returned part of the
requested data
.IP \(bu 2
\fBSysBasic.EFORMAT\fP \- data read did not adhere to the requested format
.IP \(bu 2
\fBSysBasic.EILSEQ\fP \- illegal multibyte sequence (e.g. there was a
UTF\-8 format error)
.IP \(bu 2
\fBSysBasic.EOVERFLOW\fP \- data read did not fit into requested type
(e.g. reading 1000 into a \fIuint(8)\fP).
.UNINDENT
.UNINDENT
.UNINDENT
.sp
An error code can be converted to a string using the function
\fBError.errorToString\fP\&.
.SS Ensuring Successful I/O
.sp
It is possible \- in some situations \- for I/O to fail without returning an
error. In cases where a programmer wants to be sure that there was no error
writing the data to disk, it is important to call \fI\%file.fsync\fP to make
sure that data has arrived on disk without an error. Many errors can be
reported with typical operation, but some errors can only be reported by the
system during \fI\%file.close\fP or even \fI\%file.fsync\fP\&.
.sp
When a file (or channel) is closed, data written to that file will be written
to disk eventually by the operating system. If an application needs to be sure
that the data is immediately written to persistent storage, it should use
\fI\%file.fsync\fP prior to closing the file.
.SS Correspondence to C I/O
.sp
It is not possible to seek, read, or write to a file directly.
Create a channel to proceed.
.sp
\fI\%channel.flush\fP in Chapel has the same conceptual meaning as fflush() in
C.  However, fflush() is not necessarily called in channel.flush().  Unlike
fsync(), which is actually called in file.fsync() in Chapel.
.sp
The iomode constants in Chapel have the same meaning as the following
strings passed to fopen() in C:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
iomode.r   "r"
.IP \(bu 2
iomode.rw  "r+"
.IP \(bu 2
iomode.cw  "w"
.IP \(bu 2
iomode.cwr "w+"
.UNINDENT
.UNINDENT
.UNINDENT
.sp
However, open() in Chapel does not necessarily invoke fopen().
.SS Bytes Type
.sp
A \fBBuffers.bytes\fP object is just some data in memory along with a
size. Bytes objects are reference counted, and the memory will be freed when
nothing refers to the bytes object any more.
.SS Buffers
.sp
A \fBBuffers.buffer\fP stores some number subsections of bytes objects.
It is efficient to go to a particular offset in a buffer, and to push or pop
bytes objects from the beginning or end of a buffer.
.sp
Buffers are used internally in each channel.
.SS Formatted I/O
.sp
See below for a \fI\%sample\-based overview\fP
of the format strings. Further below, we describes the format string syntax
\fI\%in detail\fP\&. Finally, we demonstrate the
functionality with \fI\%example function calls\fP\&.
.SS Overview of Format Strings
.sp
In a manner similar to C\(aqs \(aqprintf\(aq and \(aqscanf\(aq, the IO package includes
\fI\%channel.writef\fP and \fI\%channel.readf\fP functions. These functions take
in a format string and some arguments. The \fI\%string.format\fP method is also
available and is loosely equivalent to C\(aqs \(aqsprintf\(aq. For example, one might do:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
writef("My favorite %s is %i\en", "number", 7);

var s:string = "My favorite %s is %i".format("number", 7);
writeln(s);

// prints:
// My favorite number is 7
// My favorite number is 7
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following sections offer a tour through the conversions to illustrate the
common cases. A more precise definition follows in the "Format String
Syntax in Detail" section below.
.sp
In this file, we use "integral" to refer to the Chapel types int or uint and
"floating\-point" to refer to real, imaginary, or complex, of any bit width.
.SS Formatted I/O for C Programmers
.sp
This table is designed to help C programmers understand the equivalent
Chapel format specifiers.
.TS
center;
|l|l|l|.
_
T{
C
T}	T{
Chapel
T}	T{
Meaning
T}
_
T{
%i
T}	T{
%i
T}	T{
an integer in decimal
T}
_
T{
%d
T}	T{
%i
T}	T{
an integer in decimal
T}
_
T{
%u
T}	T{
%u
T}	T{
an unsigned integer in decimal
T}
_
T{
%x
T}	T{
%xu
T}	T{
an unsigned integer in hexadecimal
T}
_
T{
%g
T}	T{
%r
T}	T{
real number in exponential or decimal (if compact)
T}
_
T{
%7.2g
T}	T{
%7.2r
T}	T{
real, 2 significant digits, padded to 7 columns
T}
_
T{
%f
T}	T{
%dr
T}	T{
real number always in decimal
T}
_
T{
%7.3f
T}	T{
%7.3dr
T}	T{
real, 3 digits after \fB\&.\fP, padded to 7 columns
T}
_
T{
%e
T}	T{
%er
T}	T{
real number always in exponential
T}
_
T{
%7.3e
T}	T{
%7.3er
T}	T{
real, 3 digits after \fB\&.\fP, padded to 7 columns
T}
_
T{
%s
T}	T{
%s
T}	T{
a string without any quoting
T}
_
.TE
.sp
Unlike in C, a value of the wrong type will be cast appropriately \- so for
example printing 2 (an \fBint\fP)  with \fB%.2dr\fP will result in \fB2.00\fP\&.  Note
that \fB%n\fP and \fB%t\fP are equivalent to \fB%r\fP for real conversions and \fB%i\fP
for numeric conversions; so these are also equivalent to \fB%i\fP \fB%d\fP or
\fB%g\fP in C. Also note that Chapel format strings includes many capabilities
not available with C formatted I/O routines \- including quoted strings,
binary numbers, complex numbers, and raw binary I/O.
.SS Generic Numeric Conversions
.INDENT 0.0
.TP
.B \fB%{##.###}\fP
decimal number padded on the left with spaces to 2 digits before
the point, rounded to 3 after. Works with integral, real, imaginary,
or complex arguments.
.sp
In all cases, the output is padded on the left to the total length
of the conversion specifier (6 in this example).  The output
can be longer, when needed to accommodate the number.
.TP
.B \fB%{##}\fP
integral value padded out to 2 digits. Also works with real, imaginary
or complex numbers by rounding them to integers. Numbers with more
digits will take up more space instead of being truncated.
.UNINDENT
.sp
In both conversions above, an imaginary argument gets an \(aqi\(aq afterwards
and the entire expression is padded out to the width of ##### digits.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
writef("|${#####}|\en", 2.0i);
     // outputs:
     //   |   2i|

writef("|%{#####.#}|\en", 2.0i);
     // outputs:
     //   |   2.0i|
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Complex arguments are printed in the format a + bi, where each of a and b is
rounded individually as if printed under that conversion on its own. Then, the
formatted complex number is padded to the requested size. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
writef("|%{#########}|\en", 1.0+2.0i);
     // outputs:
     //   |   1 + 2i|

writef("|%{#########.#}|\en", 1.0+2.0i);
     // outputs:
     //   | 1.0 + 2.0i|
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See \fI\%# Specifiers\fP for more details
on this conversion type.
.INDENT 0.0
.TP
.B \fB%n\fP
a "number" \- equivalent to one of %i, %u, %r, %m, or %z below,
depending on the type
.TP
.B \fB%17n\fP
a number padded out to 17 columns
.TP
.B \fB%.4n\fP
a number with 4 significant digits or a precision of 4
.UNINDENT
.SS Integral Conversions
.INDENT 0.0
.TP
.B \fB%i\fP or \fB%di\fP
a signed integer in decimal, possibly negative
(note \- when reading an \fB%i\fP, \fB\-\fP is allowed)
.TP
.B \fB%u\fP or \fB%du\fP
an unsigned decimal integer
(note \- when reading a \fB%u\fP, \fB\-\fP is not allowed)
.TP
.B \fB%bi\fP
a binary signed integer
.TP
.B \fB%bu\fP
a binary unsigned integer
.TP
.B \fB%@bu\fP
a binary unsigned integer prefixed with \fB0b\fP
.TP
.B \fB%oi\fP
an octal signed integer
.TP
.B \fB%ou\fP
an octal unsigned integer
.TP
.B \fB%@ou\fP
an octal unsigned integer prefixed with \fB0o\fP
.TP
.B \fB%xu\fP
a hexadecimal unsigned integer
.TP
.B \fB%xi\fP
a hexadecimal signed integer
.TP
.B \fB%@xu\fP
a hexadecimal unsigned integer prefixed with \fB0x\fP
.TP
.B \fB%Xu\fP
a hexadecimal unsigned integer in uppercase
.TP
.B \fB%@Xu\fP
a hexadecimal unsigned integer prefixed with \fB0X\fP and uppercase
.TP
.B \fB%17i\fP
a decimal integer padded on the left with spaces to 17 columns
(That is, it is right\-justified in a 17\-column field.
Padding width is ignored when reading integers)
.TP
.B \fB%*i\fP
as with \fB%17i\fP but read the minimum width from the preceding argument
.TP
.B \fB%017i\fP
a decimal integer padded on the left with zeros to 17 columns
.TP
.B \fB%\-17i\fP
a decimal integer left\-justified (padded on the right) to 17 columns
.TP
.B \fB%+i\fP
a decimal integer showing \fB+\fP for positive numbers
.TP
.B \fB% i\fP
a decimal integer with a space for positive numbers
.TP
.B \fB%|4i\fP
output 4 raw, binary bytes of the passed integer in native endianness
.TP
.B \fB%<4i\fP
output 4 raw, binary bytes of the passed integer little endian
.TP
.B \fB%>4i\fP
output 4 raw, binary bytes of the passed integer big endian
.TP
.B \fB%<8i\fP
output 8 raw, binary bytes of the passed integer little endian
(byte widths of 1, 2, 4, and 8 are supported for integral conversions)
.UNINDENT
.SS Real Conversions
.INDENT 0.0
.TP
.B \fB%r\fP
a real number with decimal or exponential notation, where
exponential is chosen if the decimal version would be too long
.TP
.B \fB%6r\fP
as with \fB%r\fP but padded on the left to 6 columns (ie right\-justified)
.TP
.B \fB%\-6r\fP
as with \fB%r\fP but padded on the right to 6 columns (ie left\-justified)
.TP
.B \fB%.4r\fP
as with \fB%r\fP but with 4 significant digits
.TP
.B \fB%.*r\fP
as with \fB%.4r\fP but with significant digits read from preceding argument
.TP
.B \fB%6.4r\fP
as with \fB%r\fP but padded on the left to 6 columns
and with 4 significant digits
.TP
.B \fB%*.*r\fP
as with \fB%6.4r\fP but read minimum width and significant digits from
preceding arguments
.TP
.B \fB%dr\fP
a real number in decimal notation, e.g. \fB12.34\fP
.TP
.B \fB%6dr\fP
a decimal number padded on the left to 6 columns (right\-justified)
.TP
.B \fB%.4dr\fP
a decimal number with 4 digits after the radix point
.TP
.B \fB%6.4dr\fP
a decimal number padded on the left to 6 columns and with 4 digits
after the radix point
(width and precision are ignored when reading numbers in readf)
.TP
.B \fB%er\fP
a real number in exponential notation, e.g. \fB8.2e\-23\fP
.TP
.B \fB%Er\fP
like %er but with the \(aqe\(aq in uppercase, e.g. \fB8.2E\-23\fP
.TP
.B \fB%.4er\fP
exponential notation with 4 digits after the period, e.g. \fB8.2000e\-23\fP
.TP
.B \fB%xer\fP
hexadecimal number using p to mark exponent e.g. \fB6c.3f7p\-2a\fP
.TP
.B \fB%|4r\fP
emit 4 raw, binary bytes of the passed number in native endianness
.TP
.B \fB%<8r\fP
emit 8 raw, binary bytes of the passed number in little endian
.TP
.B \fB%<4r\fP
emit 4 raw, binary bytes of the passed number in little endian
(\fB<\fP \fB|\fP and \fB>\fP are supported for widths 4 or 8)
.UNINDENT
.SS Complex and Imaginary Conversions
.INDENT 0.0
.TP
.B \fB%m\fP
an imaginary number, like a real with \fB%r\fP but ends with an \fBi\fP
.TP
.B \fB%z\fP
print complex number with \fB%r\fP for each part in the format \fBa + bi\fP
.TP
.B \fB%@z\fP
print complex number with \fB%r\fP for each part in the format \fB(a,b)\fP
.TP
.B \fB%6z\fP
as with \fB%z\fP but pad the entire complex number out to 6 columns
.TP
.B \fB%6.4z\fP
print a and b 4 significant digits and pad the entire complex
number out to 6 columns
.TP
.B \fB%dz\fP
print a and b with \fB%dr\fP
.TP
.B \fB%ez\fP
print a and b with \fB%er\fP
.TP
.B \fB%|4m\fP
same as \fB%|4r\fP
.TP
.B \fB%|8z\fP
emit 8 raw, binary bytes of native\-endian complex (a,b are each 4 bytes)
.TP
.B \fB%<16z\fP
emit 16 raw, binary bytes of little\-endian complex (a,b each 8 bytes)
.UNINDENT
.SS String and Bytes Conversions
.INDENT 0.0
.TP
.B \fB%s\fP
a string. When reading, read until whitespace.
Note that if you want to be able to read your string back in,
you should use one of the quoted or encoded binary versions (see below),
since generally with %s it\(aqs not clear where the string ends.
.TP
.B \fB%c\fP
a single Unicode character (argument should be a string or an integral
storing the character code)
.TP
.B \fB%17s\fP
.INDENT 7.0
.IP \(bu 2
when writing \- a string left padded (right justified) to 17 columns
.IP \(bu 2
when reading \- read up to 17 bytes or a whitespace, whichever comes
first, rounding down to whole characters
.UNINDENT
.TP
.B \fB%\-17s\fP
.INDENT 7.0
.IP \(bu 2
when writing \- a string right padded (left justified) to 17 columns
.UNINDENT
.TP
.B \fB%.17s\fP
.INDENT 7.0
.IP \(bu 2
when writing \- a string truncated to 17 columns. When combined
with quoting strings, for example \fB%.17"S\fP, the conversion
will print ... after a string if it was truncated. The
truncation includes leaving room for the quotes and \-
if needed \- the periods, so the shortest truncated
string is \fB""...\fP  Generally, you won\(aqt be able to read
these back in.
.IP \(bu 2
when reading \- read exactly 17 Unicode code points
.UNINDENT
.TP
.B \fB%|17s\fP
.INDENT 7.0
.IP \(bu 2
when writing \- emit string but cause runtime error if length
does not match
.IP \(bu 2
when reading \- read exactly 17 bytes (error if we read < 17 bytes)
.UNINDENT
.TP
.B \fB%|*s\fP
as with %17s but the length is specified in the argument before the string.
.TP
.B \fB%"S\fP
use double\-quotes to delimit string
.TP
.B \fB%\(aqS\fP
use single\-quotes to delimit string
.TP
.B \fB%cS\fP
use any character (c) to delimit string
.TP
.B \fB%{(S)}\fP
quoted string, starting with \fB(\fP, ending with \fB)\fP, where the
parens could be replaced by arbitrary characters
.TP
.B \fB%*S\fP
quoted string, the arg before the string to specifies quote character
.TP
.B \fB%|0S\fP
write a string null\-terminated or read bytes until a null\-terminator
.TP
.B \fB%|*S\fP
means read bytes until a terminator byte. The terminator byte is read
from the argument before the string.
.TP
.B \fB%|1S\fP \fB%|2S\fP \fB%|4S\fP and \fB%|8S\fP
work with encoded strings storing a length
and then the string data. The digit before \fBS\fP is
the number of bytes of length which is by default
stored native endian. \fB<\fP, \fB|\fP, \fB>\fP can be used
to specify the endianness of the length field,
for example \fB%<8S\fP is 8 bytes of little\-endian length
and then string data.
.TP
.B \fB%|vS\fP
as with \fB%|1S\fP\-\fB%|8S\fP but the string length is encoded using a
variable\-length byte scheme (which is always the same no matter what
endianness). In this scheme, the high bit of each encoded length byte
records whether or not there are more length bytes (and the remaining
bits encode the length in a big\-endian manner).
.TP
.B \fB%|*vS\fP or \fB%|*0S\fP
read an encoded string but limit it to a number of bytes
read from the argument before the string; when writing
cause a runtime error if the string is longer than the
maximum.
.TP
.B \fB%/a+/\fP
where any regular expression can be used instead of \fBa+\fP
consume one or more \(aqa\(aqs when reading, gives an error when printing,
and does not assign to any arguments
(note \- regular expression support is dependent on RE2 build;
see \fBRegexp\fP)
.TP
.B \fB%/(a+)/\fP
consume one or more \(aqa\(aqs and then set the corresponding string
argument to the read value
.TP
.B \fB%17/a+/\fP
match a regular expression up to 17 bytes
(note that \fB%.17/a+/\fP, which would mean to match 17 characters,
is not supported).
.TP
.B \fB%/*/\fP
next argument contains the regular expression to match
.UNINDENT
.SS General Conversions
.INDENT 0.0
.TP
.B \fB%t\fP
read or write the object according to its readThis/writeThis routine
.TP
.B \fB%jt\fP
read or write an object in JSON format using readThis/writeThis
.TP
.B \fB%ht\fP
read or write an object in Chapel syntax using readThis/writeThis
.TP
.B \fB%|t\fP
read or write an object in binary native\-endian with readThis/writeThis
.TP
.B \fB%<t\fP
read or write an object little\-endian in binary with readThis/writeThis
.TP
.B \fB%>t\fP
read or write an object big\-endian in binary with readThis/writeThis
.UNINDENT
.SS Note About Whitespace
.sp
When reading, \fB\en\fP in a format string matches any zero or more space
characters other than newline and then exactly one newline character. In
contrast, \fB" "\fP matches at least one space character of any kind.
.sp
When writing, whitespace is printed from the format string just like any
other literal would be.
.sp
Finally, space characters after a binary conversion will be ignored, so
that a binary format string can appear more readable.
.SS Format String Syntax in Detail
.sp
Chapel\(aqs format strings are simpler than those in C in one way: it is no longer
necessary to specify the types of the arguments in the format string. For
example, in C the l in %ld is specifying the type of the argument for integer
(decimal) conversion. That is not necessary in Chapel since the compiler is
able to use type information from the call.
.sp
Format strings in Chapel consist of:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
conversion specifiers e.g. \fB"%xi"\fP (described below)
.IP \(bu 2
newline e.g. \fB"\en"\fP
.INDENT 2.0
.IP \(bu 2
when writing \- prints a newline
.IP \(bu 2
when reading \- reads any amount of non\-newline whitespace and then
exactly one newline. Causes the format string not to
match if it did not read a newline.
.UNINDENT
.IP \(bu 2
other whitespace e.g. \fB" "\fP
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
when writing \- prints as the specified whitespace
.IP \(bu 2
when reading \- matches at least one character of whitespace, possibly
including newlines.
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
other text e.g. "test"
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
when writing \- prints the specified text
.IP \(bu 2
when reading \- matches the specified text
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS # Specifiers
.sp
All # specifiers must be enclosed in \fB%{}\fP syntax, for example \fB%{#}\fP is the
shortest one, and \fB%{#.#}\fP is a more typical one. The integer portion of the
number will be padded out to match the number of \fB#\fP s before the decimal
point, and the number of \fB#\fP s after the decimal point indicate how many
digits to print after the decimal point. In other words, display how many
digits to use when printing a floating\-point number by using the # symbol to
stand for digits. The fractional portion of the number will be rounded
appropriately and extra space will be made if the integer portion is too small:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
writef("n:%{###.###}\en", 1.2349);
     // outputs:
     // n:  1.235
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This syntax also works for numbers without a decimal point by rounding them
appropriately.
.sp
A # specifier may start with a \fB\&.\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
writef("%{.##}\en", 0.777);
     // outputs:
     //  0.78
.ft P
.fi
.UNINDENT
.UNINDENT
.SS % Specifiers
.sp
Specifiers starting with % offer quite a few options. First, some basic
rules.
.INDENT 0.0
.TP
.B \fB%%\fP
means a literal \fB%\fP
.TP
.B \fB\en\fP
means a literal newline
.TP
.B \fB\e\e\fP
means a single backslash
.TP
.B \fB%{}\fP
curly braces can wrap a \fB%\fP or \fB#\fP conversion specifier. That way, even
odd specifiers can be interpreted unambiguously. Some of the more complex
features require the use of the \fB%{}\fP syntax, but it\(aqs always
acceptable to use curly braces to make the format string clearer.
Curly braces are required for # conversion specifiers.
.UNINDENT
.sp
In general, a \fB%\fP specifier consists of either text or binary conversions:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
%
[optional endian flag (binary conversions only)]
[optional flags]
[optional field width or size in bytes]
[optional . then precision]
[optional base flag]
[optional exponential type]
[conversion type]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Going through each section for text conversions:
.INDENT 0.0
.TP
.B [optional flags]
.INDENT 7.0
.TP
.B \fB@\fP
means "alternate form". It means to print out a base when not using
decimal (e.g. \fB0xFFF\fP or \fB0b101011\fP); and it will format a complex
number with parens instead of as e.g. \fB1.0+2.0i\fP
.TP
.B \fB+\fP
means to show a plus sign when printing positive numbers
.TP
.B \fB0\fP
means to pad numeric conversions with 0 instead of space
.TP
.B \fB" "\fP
(a space) leaves a blank before a positive number
(in order to help line up with negative numbers)
.TP
.B \fB\-\fP
left\-justify the converted value instead of right\-justifying.
Note, if both \fB0\fP and \fB\-\fP are given, the effect is as if only \fB\-\fP
were given.
.TP
.B \fB~\fP
when reading a record or class instance, skip over fields in the input not
present in the Chapel type. This flag currently only works in combination
with the JSON format.  This flag allows a Chapel program to describe only the
relevant fields in a record when the input might contain many more fields.
.UNINDENT
.TP
.B [optional field width]
When printing numeric or string values, the field width specifies the number
of \fIcolumns\fP that the conversion should use to display the value. It can be
\fB*\fP, which means to read the field width from an integral argument before
the converted value.
.sp
For string conversions in readf (\fB%s\fP \fB%"\fP \fB%\(aq\fP \fB%//\fP), the field
width specifies the maximum number of bytes to read.
.sp
For numeric conversions in readf, the field width is ignored.
.TP
.B [optional . then precision]
When printing floating point values, the precision is used to control
the number of decimal digits to print.  For \fB%r\fP conversions, it
specifies the number of significant digits to print; for \fB%dr\fP or \fB%er\fP
conversions, it specifies the number of digits following the decimal point.
It can also be \fB*\fP, which means to read the precision from an integral
argument before the converted value.
.sp
For textual string conversions in writef, (\fB%s\fP \fB%"\fP \fB%\(aq\fP), the
precision indicates the maximum number of columns to print \- and the result
will be truncated if it does not fit. In readf for these textual string
conversions, the precision indicates the maximum number of characters
(e.g. Unicode code points) to input.
.sp
The precision is silently ignored for integral conversions
(\fB%i\fP, \fB%u\fP, etc) and for \fB%//\fP conversions.
.TP
.B [optional base flag]
.INDENT 7.0
.TP
.B \fBd\fP
means decimal (and not exponential for floating\-point)
.TP
.B \fBx\fP
means lower\-case hexadecimal
.TP
.B \fBX\fP
means upper\-case hexadecimal
.TP
.B \fBo\fP
means octal
.TP
.B \fBb\fP
means binary
.TP
.B \fBj\fP
means JSON\-style strings, numbers, and structures
.TP
.B \fBh\fP
means Chapel\-style strings, numbers, and structures
.TP
.B \fB\(aq\fP
means single\-quoted string (with \e and \(aq)
.TP
.B \fB"\fP
means double\-quoted string (with \e and ")
.UNINDENT
.TP
.B [optional exponential type]
.INDENT 7.0
.TP
.B \fBe\fP
means floating\-point conversion printing exponential \fB\-12.34e+56\fP
.TP
.B \fBE\fP
means floating\-point conversion printing uppercase
exponential \fB\-12.34E+56\fP
.UNINDENT
.TP
.B [conversion type]
.INDENT 7.0
.TP
.B \fBt\fP
means \fItype\-based\fP or \fIthing\fP \- uses writeThis/readThis but ignores
width and precision
.TP
.B \fBn\fP
means type\-based number, allowing width and precision
.TP
.B \fBi\fP
means integral conversion
.TP
.B \fBu\fP
means unsigned integral conversion
.TP
.B \fBr\fP
means real conversion (e.g. \fB12.23\fP)
.TP
.B \fBm\fP
means imaginary conversion with an \fBi\fP after it (e.g. \fB12.23i\fP)
.TP
.B \fBz\fP
means complex conversion
.TP
.B \fBs\fP
means string conversion
.TP
.B \fBS\fP
means a quoted string conversion
.TP
.B \fB{cS}\fP
means string conversion with quote char \fIc\fP
.TP
.B \fB{*S}\fP
means string conversion with quote char in argument before the string
.TP
.B \fB{xSy}\fP
means string conversion with left and right quote chars \fIx\fP and \fIy\fP
.TP
.B \fB/.../\fP
means a regular expression (for reading only)
.TP
.B \fB{/.../xyz}\fP
means regular expression with flags \fIxyz\fP
.TP
.B \fBc\fP
means a Unicode character \- either the first character in a string
or an integral character code
.UNINDENT
.UNINDENT
.sp
For binary conversions:
.INDENT 0.0
.TP
.B [optional endian flag]
.INDENT 7.0
.TP
.B \fB<\fP
means little\-endian
.TP
.B \fB>\fP
means big\-endian
.TP
.B \fB|\fP
means native\-endian
.UNINDENT
.TP
.B [optional size in bytes]
This is the number of bytes the format should read or write in this
conversion. For integral conversions (e.g. \fB%|i\fP) it specifies the number
of bytes in the integer, and 1, 2, 4, and 8 are supported. For real and
imaginary conversions, 4 and 8 are supported. For complex conversions,
8 and 16 are supported. The size in bytes is \fIrequired\fP for binary
integral and floating\-point conversions.
.sp
The size can be \fB*\fP, which means that the number of bytes is read
from the argument before the conversion.
.sp
For strings, if a terminator or length field is specified, exactly this
number is the maximum size in bytes; if the terminator or length is not
specified, the string must be exactly that size (and if the argument is not
exactly that number of bytes it will cause an error even when writing).
.TP
.B [conversion type]
.INDENT 7.0
.TP
.B \fBt\fP
means \fItype\-based\fP or \fIthing\fP \- to read or write with readThis/writeThis
.TP
.B \fBn\fP
means type\-based number (size is not mandatory)
.TP
.B \fBi\fP
means integral. Note that the size is mandatory for binary integral
conversions
.TP
.B \fBu\fP
means unsigned integral. Note that the size is mandatory for binary
integral conversions
.TP
.B \fBr\fP
means real. Note that the size is mandatory for binary real conversions
.TP
.B \fBm\fP
works the same as \fBr\fP for binary conversions
.TP
.B \fBz\fP
means complex. Note that the size is mandatory for binary complex
conversions
.TP
.B \fBs\fP
.INDENT 7.0
.IP \(bu 2
means string binary I/O
.IP \(bu 2
\fB%|17s\fP means exactly 17 byte string
.UNINDENT
.TP
.B \fB0S\fP/\fB1S\fP/\fB2S\fP/\fB4S\fP/\fB8S\fP
.INDENT 7.0
.IP \(bu 2
mean encoded string binary I/O:
.IP \(bu 2
\fB%|0S\fP means null\-terminated string
.IP \(bu 2
\fB%{|S*}\fP means  next\-argument specifies string terminator byte
.IP \(bu 2
\fB%|1S\fP means a one\-byte length and then the string
.IP \(bu 2
\fB%|2S\fP means a two\-byte length and then the string
.IP \(bu 2
\fB%|4S\fP means a four\-byte length and then the string
.IP \(bu 2
\fB%|8S\fP means an eight\-byte length and then the string
.IP \(bu 2
\fB%|vS\fP means a variable\-byte\-encoded length and then the string
.UNINDENT
.TP
.B \fBc\fP
means a Unicode character \- either the first character in a string
or an integral character code
.UNINDENT
.UNINDENT
.SS Formatted I/O Examples
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
writef("%5i %5s %5r\en", 1, "test", 6.34);
     // outputs:
     //    1  test  6.34

writef("%2.4z\en", 43.291 + 279.112i);
     // outputs:
     // 43.29 + 279.1i

writef("%<4u", 0x11223344);
     // outputs:
     // (hexdump of the output)
     // 4433 2211
writef("%>4u", 0x11223344);
     // outputs:
     // (hexdump of the output)
     // 1122 3344
writef("%<4i %<4i", 2, 32);
     // outputs:
     // (hexdump of the output \-\- note that spaces after
     //  a binary format specifier are ignored)
     // 0200 0000 2000 0000


writef("%|0S\en", "test");
     // outputs:
     // (hexdump of the output)
     // 7465 7374 000a
writef("%|1S\en", "test");
     // outputs:
     // (hexdump of the output)
     // 0474 6573 740a
writef("%>2S\en", "test");
     // outputs:
     // (hexdump of the output)
     // 0004 7465 7374 0a
writef("%>4S\en", "test");
     // outputs:
     // (hexdump of the output)
     // 0000 0004 7465 7374 0a
writef("%>8S\en", "test");
     // outputs:
     // (hexdump of the output)
     // 0000 0000 0000 0004 7465 7374 0a
writef("%|vS\en", "test");
     // outputs:
     // (hexdump of the output)
     // 04 7465 7374 0a

writef(\(aq%"S\en\(aq, "test \e"\e" \e\(aq\e\(aq !");
     // outputs:
     // "test \e"\e" \(aq\(aq !"
writef("%\(aqS\en", "test \e"\e" \e\(aq\e\(aq !");
     // outputs:
     // \(aqtest "" \e\(aq\e\(aq !\(aq
writef("%{(S)}\en", "test ()", "(", ")");
     // outputs:
     // (test (\e))


writef("%40s|\en", "test");
writef("%\-40s|\en", "test");
     // outputs:
     //                                     test|
     // test                                    |

writef("123456\en");
writef("%6.6\(aqS\en", "a");
writef("%6.6\(aqS\en", "abcdefg");
writef("%.3\(aqS\en", "a");
writef("%.3\(aqS\en", "abcd");
     // outputs:
     // 123456
     //    \(aqa\(aq
     // \(aqa\(aq...
     // \(aqa\(aq
     // \(aq\(aq...


var s:string;
var got = readf(" %c", s);
// if the input is " a", "\ena", "  a", etc, s will contain "a"
// if the input is "b", got will be false and s will contain ""

var s:string;
var got = readf("\en%c", s);
// if the input is "\ena", or " \ena", s will contain "a"
// if the input is "b", got will be false and s will be ""

var got = readf("%/a+/");
// if the input is "a" or "aa" (and so on), got will return true
// if the input is "c" got will be false

var s:string;
var got = readf("%/a(b+)/", s);
// if the input is "c" got will be false and s will be ""
// if the input is "ab", got will be true and s will be "b"
// if the input is "abb", got will be true and s will be "bb"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS IO Functions and Types
.INDENT 0.0
.TP
.B enum iomode { r = 1, cw = 2, rw = 3, cwr = 4 }
The \fI\%iomode\fP type is an enum.
When used as arguments when opening files,
its constants have the following meaning:
.INDENT 7.0
.IP \(bu 2
\fBiomode.r\fP \- open an existing file for reading.
.IP \(bu 2
\fBiomode.rw\fP \- open an existing file for reading and writing.
.IP \(bu 2
\fBiomode.cw\fP \- create a new file for writing.
If the file already exists, its contents are removed
when the file is opened in this mode.
.IP \(bu 2
\fBiomode.cwr\fP \- as with \fBiomode.cw\fP but reading from the
file is also allowed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B enum iokind { dynamic = 0, native = 1, big = 2, little = 3 }
The \fI\%iokind\fP type is an enum. When used as arguments to the
\fI\%channel\fP type, its constants have the following meaning:
.INDENT 7.0
.IP \(bu 2
\fBiokind.big\fP means binary I/O with big\-endian byte order is performed
when writing/reading basic types from the channel.
.IP \(bu 2
\fBiokind.little\fP means binary I/O with little\-endian byte order
(similar to \fBiokind.big\fP but with little\-endian byte order).
.IP \(bu 2
\fBiokind.native\fP means binary I/O in native byte order
(similar to \fBiokind.big\fP but with the byte order that is native
to the target platform).
.IP \(bu 2
\fBiokind.dynamic\fP means that the applicable I/O style has full effect
and as a result the kind varies at runtime.
.UNINDENT
.sp
In the case of \fBiokind.big\fP, \fBiokind.little\fP, and
\fBiokind.native\fP the applicable \fI\%iostyle\fP is consulted when
writing/reading strings, but not for other basic types.
.sp
There are synonyms available for these values:
.INDENT 7.0
.IP \(bu 2
\fI\%iodynamic\fP = \fBiokind.dynamic\fP
.IP \(bu 2
\fI\%ionative\fP = \fBiokind.native\fP
.IP \(bu 2
\fI\%iobig\fP = \fBiokind.big\fP
.IP \(bu 2
\fI\%iolittle\fP = \fBiokind.little\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B param iodynamic = iokind.dynamic
A synonym for \fBiokind.dynamic\fP; see \fI\%iokind\fP
.UNINDENT
.INDENT 0.0
.TP
.B param ionative = iokind.native
A synonym for \fBiokind.native\fP; see \fI\%iokind\fP
.UNINDENT
.INDENT 0.0
.TP
.B param iobig = iokind.big
A synonym for \fBiokind.big\fP; see \fI\%iokind\fP
.UNINDENT
.INDENT 0.0
.TP
.B param iolittle = iokind.little
A synonym for \fBiokind.little\fP; see \fI\%iokind\fP
.UNINDENT
.INDENT 0.0
.TP
.B enum iostringstyle { len1b_data = \-1, len2b_data = \-2, len4b_data = \-4, len8b_data = \-8, lenVb_data = \-10, data_toeof = \-65280, data_null = \-256 }
This enum contains values used to control binary I/O with strings
via the \fBstr_style\fP field in \fI\%iostyle\fP\&.
.INDENT 7.0
.IP \(bu 2
\fBiostringstyle.len1b_data\fP indicates a string format of 1 byte of
length followed by length bytes of string data.
.IP \(bu 2
\fBiostringstyle.len2b_data\fP indicates a string format of 2 bytes of
length followed by length bytes of string data.
.IP \(bu 2
\fBiostringstyle.len4b_data\fP indicates a string format of 4 bytes of
length followed by length bytes of string data.
.IP \(bu 2
\fBiostringstyle.len8b_data\fP indicates a string format of 8 bytes of
length followed by length bytes of string data.
.IP \(bu 2
\fBiostringstyle.lenVb_data\fP indicates a string format of a variable
number of bytes of length, encoded with high\-bit meaning more bytes
of length follow, and where the 7\-bits of length from each byte store
the 7\-bit portions of the length in order from least\-significant to
most\-significant. This way of encoding a variable\-byte length  matches
\fI\%Google Protocol Buffers\fP\&.
.IP \(bu 2
\fBiostringstyle.data_toeof\fP indicates a string format that contains
string data until the end of the file
.IP \(bu 2
\fBiostringstyle.data_null\fP indicates a string that is terminated
by a zero byte. It can be combined with other numeric
values to indicate a string terminated by a particular byte. For example,
to indicate a string terminated by \fB$\fP (which in ASCII has byte value 0x24),
one would use the value \fBiostringstyle.data_null|0x24\fP\&.
.IP \(bu 2
A positive and nonzero value indicates that a string of exactly that many
bytes should be read or written.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc stringStyleTerminated(terminator: uint(8))
This method returns the appropriate \fI\%iostyle\fP \fBstr_style\fP value
to indicate a string format where strings are terminated by a
particular byte.
.INDENT 7.0
.TP
.B Arguments
\fBterminator\fP \-\- a byte value that the strings will be terminated by
.TP
.B Returns
a value that indicates a string format where strings
are terminated by the terminator byte. This value is appropriate
to store in \fI\%iostyle.str_style\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc stringStyleNullTerminated()
This method returns the appropriate \fI\%iostyle\fP \fBstr_style\fP value
to indicate a string format where strings are terminated by a
zero byte.
.UNINDENT
.INDENT 0.0
.TP
.B proc stringStyleExactLen(len: int(64))
This method returns the appropriate \fI\%iostyle\fP \fBstr_style\fP value
to indicate a string format where strings have an exact length.
.UNINDENT
.INDENT 0.0
.TP
.B proc stringStyleWithVariableLength()
This method returns the appropriate \fI\%iostyle\fP \fBstr_style\fP value
to indicate a string format where string data is preceded by a variable\-byte
length as described in \fI\%iostringstyle\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc stringStyleWithLength(lengthBytes: int)
This method returns the appropriate \fI\%iostyle\fP \fBstr_style\fP value
to indicate a string format where string data is preceded by a \fBlengthBytes\fP
of length. Only lengths of 1, 2, 4, or 8 are supported; if this method
is called with any other length, it will halt with an error.
.UNINDENT
.INDENT 0.0
.TP
.B const IOHINT_NONE = 0: c_int
IOHINT_NONE means normal operation, nothing special
to hint. Expect to use NONE most of the time.
The other hints can be bitwise\-ORed in.
.UNINDENT
.INDENT 0.0
.TP
.B const IOHINT_RANDOM = QIO_HINT_RANDOM
IOHINT_RANDOM means we expect random access to a file
.UNINDENT
.INDENT 0.0
.TP
.B const IOHINT_SEQUENTIAL = QIO_HINT_SEQUENTIAL
IOHINT_SEQUENTIAL means expect sequential access. On
Linux, this should double the readahead.
.UNINDENT
.INDENT 0.0
.TP
.B const IOHINT_CACHED = QIO_HINT_CACHED
IOHINT_CACHED means we expect the entire file
to be cached and/or we pull it in all at
once. May request readahead on the entire file.
.UNINDENT
.INDENT 0.0
.TP
.B const IOHINT_PARALLEL = QIO_HINT_PARALLEL
IOHINT_PARALLEL means that we expect to have many
channels working with this file in parallel.
It might change the reading/writing implementation
to something more efficient in that scenario.
.UNINDENT
.INDENT 0.0
.TP
.B record iostyle
The \fI\%iostyle\fP type represents I/O styles
defining how Chapel\(aqs basic types should be read or written.
.sp
See \fI\%The stdin, stdout, and stderr Channels\fP\&.
.INDENT 7.0
.TP
.B var binary: uint(8) = 0
Perform binary I/O? 1 \- yes, 0 \- no.
This field is ignored for \fI\%iokind\fP values other than \fBdynamic\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B var byteorder: uint(8) = iokind.native: uint(8)
What byte order should we use when performing binary I/O?
This field is ignored for \fI\%iokind\fP values other than \fBdynamic\fP\&.
It should be set to a value in \fI\%iokind\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B var str_style: int(64) = \-10
What string format should we use when writing strings
in binary mode? See \fI\%iostringstyle\fP for more information
on what the values of \fBstr_style\fP mean.
.UNINDENT
.INDENT 7.0
.TP
.B var min_width_columns: uint(32) = 0
When performing text I/O, pad out to this many columns
.UNINDENT
.INDENT 7.0
.TP
.B var max_width_columns: uint(32) = max(uint(32))
When performing text I/O, do not use more than this many columns
.UNINDENT
.INDENT 7.0
.TP
.B var max_width_characters: uint(32) = max(uint(32))
When performing text I/O, do not use more than this many characters
.UNINDENT
.INDENT 7.0
.TP
.B var max_width_bytes: uint(32) = max(uint(32))
When performing text I/O, do not use more than this many bytes
.UNINDENT
.INDENT 7.0
.TP
.B var string_start: style_char_t = 34
What character do we start strings with, when appropriate?
.UNINDENT
.INDENT 7.0
.TP
.B var string_end: style_char_t = 34
What character do we end strings with, when appropriate?
.UNINDENT
.INDENT 7.0
.TP
.B var string_format: uint(8) = 0
How should we format strings when performing text I/O?
.INDENT 7.0
.IP \(bu 2
\fBQIO_STRING_FORMAT_WORD\fP means string is as\-is;
reading reads until whitespace.
.IP \(bu 2
\fBQIO_STRING_FORMAT_BASIC\fP means only escape \fIstring_end\fP and \fB\e\fP
with \fB\e\fP
.IP \(bu 2
\fBQIO_STRING_FORMAT_CHPL\fP means  escape \fIstring_end\fP
\fB\e\fP \fB\(aq\fP \fB"\fP \fB\en\fP with \fB\e\fP and
nonprinting characters \fBc = 0xXY\fP with \fB\exXY\fP
.IP \(bu 2
\fBQIO_STRING_FORMAT_JSON\fP means  escape \fIstring_end\fP \fB"\fP and \fB\e\fP
with \fB\e\fP, and nonprinting characters \fBc = \euABCD\fP
.IP \(bu 2
\fBQIO_STRING_FORMAT_TOEND\fP means string is as\-is; reading reads until
\fIstring_end\fP
.IP \(bu 2
\fBQIO_STRING_FORMAT_TOEOF\fP means string is as\-is; reading reads until
end of file
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B var base: uint(8) = 0
.UNINDENT
.INDENT 7.0
.TP
.B var point_char: style_char_t = 46
.UNINDENT
.INDENT 7.0
.TP
.B var exponent_char: style_char_t = 101
.UNINDENT
.INDENT 7.0
.TP
.B var other_exponent_char: style_char_t = 112
.UNINDENT
.INDENT 7.0
.TP
.B var positive_char: style_char_t = 43
.UNINDENT
.INDENT 7.0
.TP
.B var negative_char: style_char_t = 45
.UNINDENT
.INDENT 7.0
.TP
.B var i_char: style_char_t = 105
.UNINDENT
.INDENT 7.0
.TP
.B var prefix_base: uint(8) = 1
.UNINDENT
.INDENT 7.0
.TP
.B var pad_char: style_char_t = 32
.UNINDENT
.INDENT 7.0
.TP
.B var showplus: uint(8) = 0
.UNINDENT
.INDENT 7.0
.TP
.B var uppercase: uint(8) = 0
.UNINDENT
.INDENT 7.0
.TP
.B var leftjustify: uint(8) = 0
.UNINDENT
.INDENT 7.0
.TP
.B var showpoint: uint(8) = 0
.UNINDENT
.INDENT 7.0
.TP
.B var showpointzero: uint(8) = 1
.UNINDENT
.INDENT 7.0
.TP
.B var precision: int(32) = \-1
.UNINDENT
.INDENT 7.0
.TP
.B var realfmt: uint(8) = 0
Formatting of real numbers:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
0 means  print out \(aqsignificant_digits\(aq number of significant digits
(%g in printf)
.IP \(bu 2
1 means  print out \(aqprecision\(aq number of digits after the decimal point
(%f)
.IP \(bu 2
2 means  always use exponential and \(aqprecision\(aq number of digits (%e)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B var complex_style: uint(8) = 0
.UNINDENT
.INDENT 7.0
.TP
.B var array_style: uint(8) = 0
.UNINDENT
.INDENT 7.0
.TP
.B var aggregate_style: uint(8) = 0
.UNINDENT
.INDENT 7.0
.TP
.B var tuple_style: uint(8) = 0
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc defaultIOStyle(): iostyle
.INDENT 7.0
.TP
.B Returns
the default I/O style. See \fI\%iostyle\fP
and \fI\%I/O Styles\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc iostyle.native(str_style: int(64) = stringStyleWithVariableLength()): iostyle
Get an I/O style indicating binary I/O in native byte order.
.INDENT 7.0
.TP
.B Arguments
\fBstr_style\fP \-\- see \fI\%iostringstyle\fP \- which format to use when reading
or writing strings. Defaults to variable\-byte length.
.TP
.B Returns
the requested \fI\%iostyle\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc iostyle.big(str_style: int(64) = stringStyleWithVariableLength()): iostyle
Get an I/O style indicating binary I/O in big\-endian byte order.
.INDENT 7.0
.TP
.B Arguments
\fBstr_style\fP \-\- see \fI\%iostringstyle\fP \- which format to use when reading
or writing strings. Defaults to variable\-byte length.
.TP
.B Returns
the requested \fI\%iostyle\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc iostyle.little(str_style: int(64) = stringStyleWithVariableLength()): iostyle
Get an I/O style indicating binary I/O in little\-endian byte order.
.INDENT 7.0
.TP
.B Arguments
\fBstr_style\fP \-\- see \fI\%iostringstyle\fP \- which format to use when reading
or writing strings. Defaults to variable\-byte length.
.TP
.B Returns
the requested \fI\%iostyle\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc iostyle.text(): iostyle
Get an I/O style indicating text I/O.
.INDENT 7.0
.TP
.B Returns
the requested \fI\%iostyle\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B type iohints = c_int
A value of the \fI\%iohints\fP type defines a set of hints about the I/O that
the file or channel will perform.  These hints may be used by the
implementation to select optimized versions of the I/O operations.
.sp
The \fI\%iohints\fP type is implementation\-defined.
The following \fI\%iohints\fP constants are provided:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%IOHINT_NONE\fP defines an empty set, which provides no hints.
.IP \(bu 2
\fI\%IOHINT_RANDOM\fP suggests to expect random access.
.IP \(bu 2
\fI\%IOHINT_SEQUENTIAL\fP suggests to expect sequential access.
.IP \(bu 2
\fI\%IOHINT_CACHED\fP suggests that the file data is or should be
cached in memory, possibly all at once.
.IP \(bu 2
\fI\%IOHINT_PARALLEL\fP suggests to expect many channels
working with this file in parallel.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Other hints might be added in the future.
.sp
The following binary operators are defined on \fI\%iohints\fP:
.INDENT 7.0
.IP \(bu 2
\fB|\fP for set union
.IP \(bu 2
\fB&\fP for set intersection
.IP \(bu 2
\fB==\fP for set equality
.IP \(bu 2
\fB1=\fP for set inequality
.UNINDENT
.sp
When an \fI\%iohints\fP formal has default intent, the
actual is copied to the formal upon a function call and
the formal cannot be assigned within the function.
.sp
The default value of the \fI\%iohints\fP type is undefined.
.UNINDENT
.INDENT 0.0
.TP
.B record file
The \fI\%file\fP type is implementation\-defined.  A value of the
\fI\%file\fP type refers to the state that is used by the implementation to
identify and interact with the OS file.
.sp
When a \fI\%file\fP formal argument has default intent, the
actual is copied to the formal upon a function call and
the formal cannot be assigned within the function.
.sp
The default value of the \fI\%file\fP type does not represent any OS file.
It is illegal to perform any I/O operations on the default value.
.UNINDENT
.INDENT 0.0
.TP
.B proc file.check()
Halt if a file is invalid
.UNINDENT
.INDENT 0.0
.TP
.B proc file.close(out error: syserr)
Close a file.
.sp
In order to free the resources allocated for a file, it
must be closed using this method.
.sp
It is an error to perform any I/O operations on a file
that has been closed.
It is an error to close a file when it has channels that
have not been closed.
.sp
Closing a file does not guarantee immediate persistence of the performed
updates, if any. In cases where immediate persistence is important,
\fI\%file.fsync\fP should be used for that purpose prior to closing the file.
In particular, even though closing the file might complete without errors,
the data written might not persist in the event of a severe error like
running out of storage space or power loss. See also
\fI\%Ensuring Successful I/O\fP\&.
.sp
In the future, we hope to automatically close files when the file variable
goes out of scope and all channels using that file are closed. The ability
for a program to close a file will remain available.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.fsync(out error: syserr)
Sync a file to disk.
.sp
Commits file data to the device associated with this file.
Data written to the file by a channel will be committed
only if the channel has been closed or flushed.
.sp
This function will typically call the \fBfsync\fP system call.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.getPath(out error: syserr): string
Get the path to an open file.
.sp
Note that not all files have a path (e.g. files opened with \fI\%openmem\fP),
and that this function may not work on all operating systems.
.sp
The function \fBPath.file.realPath\fP is an alternative way
to get the path to a file.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.tryGetPath(): string
Get the path to an open file, or return "unknown" if there was
a problem getting the path to the open file.
.UNINDENT
.INDENT 0.0
.TP
.B proc file.path: string
Get the path to an open file. Halt if there is an error getting the path.
.UNINDENT
.INDENT 0.0
.TP
.B proc file.length(): int(64)
Get the current length of an open file. Note that the length can always
change if other channels, tasks or programs are writing to the file.
.INDENT 7.0
.TP
.B Returns
the current file length
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc open(out error: syserr, path: string = "", mode: iomode, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle(), url: string = ""): file
Open a file on a filesystem or stored at a particular URL. Note that once the
file is open, you will need to use a \fI\%file.reader\fP or \fI\%file.writer\fP
to create a channel to actually perform I/O operations
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBpath\fP \-\- which file to open (for example, "some/file.txt"). This argument
is required unless the \fBurl=\fP argument is used.
.IP \(bu 2
\fBiomode\fP \-\- specify whether to open the file for reading or writing and
whether or not to create the file if it doesn\(aqt exist.
See \fI\%iomode\fP\&.
.IP \(bu 2
\fBhints\fP \-\- optional argument to specify any hints to the I/O system about
this file. See \fI\%iohints\fP\&.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to specify I/O style associated with this file.
The provided style will be the default for any channels created for
on this file, and that in turn will be the default for all I/O
operations performed with those channels.
.IP \(bu 2
\fBurl\fP \-\- optional argument to specify a URL to open. See \fBCurl\fP and
\fBHDFS\fP for more information on \fBurl=\fP support for those
systems. If HDFS is enabled, this function supports \fBurl=\fP
arguments of the form "hdfs://<host>:<port>/<path>". If Curl is
enabled, this function supports \fBurl=\fP starting with
\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP, \fBftps://\fP, \fBsmtp://\fP,
\fBsmtps://\fP, \fBimap://\fP, or \fBimaps://\fP
.UNINDENT
.TP
.B Returns
an open file to the requested resource. If the \fBerror=\fP argument
was provided and the file was not opened because of an error, returns
the default \fI\%file\fP value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc openfd(fd: fd_t, out error: syserr, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle()): file
Create a Chapel file that works with a system file descriptor  Note that once
the file is open, you will need to use a \fI\%file.reader\fP or
\fI\%file.writer\fP to create a channel to actually perform I/O operations
.sp
The system file descriptor will be closed when the Chapel file is closed.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This function can be used to create Chapel files that refer to system file
descriptors that do not support the \fBseek\fP functionality. For example, file
descriptors that represent pipes or open socket connections have this
property. In that case, the resulting file value should only be used with one
\fI\%channel\fP at a time.
The I/O system will ignore the channel offsets when reading or writing
to files backed by non\-seekable file descriptors.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBfd\fP \-\- a system file descriptor (obtained with \fBSys.sys_open\fP or
\fBSys.sys_connect\fP for example).
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBhints\fP \-\- optional argument to specify any hints to the I/O system about
this file. See \fI\%iohints\fP\&.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to specify I/O style associated with this file.
The provided style will be the default for any channels created for
on this file, and that in turn will be the default for all I/O
operations performed with those channels.
.UNINDENT
.TP
.B Returns
an open \fI\%file\fP using the specified file descriptor.
If the \fBerror=\fP argument
was provided and the file was not opened because of an error, returns
the default \fI\%file\fP value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc openfp(fp: _file, out error: syserr, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle()): file
Create a Chapel file that works with an open C file (ie a \fBFILE*\fP).  Note
that once the file is open, you will need to use a \fI\%file.reader\fP or
\fI\%file.writer\fP to create a channel to actually perform I/O operations
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The resulting file value should only be used with one \fI\%channel\fP at a
time. The I/O system will ignore the channel offsets when reading or writing
to a file opened with \fI\%openfp\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBfp\fP \-\- a C \fBFILE*\fP to work with
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBhints\fP \-\- optional argument to specify any hints to the I/O system about
this file. See \fI\%iohints\fP\&.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to specify I/O style associated with this file.
The provided style will be the default for any channels created for
on this file, and that in turn will be the default for all I/O
operations performed with those channels.
.UNINDENT
.TP
.B Returns
an open \fI\%file\fP that uses the underlying FILE* argument.
If the \fBerror=\fP argument
was provided and the file was not opened because of an error, returns
the default \fI\%file\fP value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc opentmp(out error: syserr, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle()): file
Open a temporary file. Note that once the file is open, you will need to use a
\fI\%file.reader\fP or \fI\%file.writer\fP to create a channel to actually
perform I/O operations.
.sp
The temporary file will be created in an OS\-dependent temporary directory,
for example "/tmp" is the typical location. The temporary file will be
deleted upon closing.
.sp
Temporary files are always opened with \fI\%iomode\fP \fBiomode.cwr\fP;
that is, a new file is created that supports both writing and reading.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBhints\fP \-\- optional argument to specify any hints to the I/O system about
this file. See \fI\%iohints\fP\&.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to specify I/O style associated with this file.
The provided style will be the default for any channels created for
on this file, and that in turn will be the default for all I/O
operations performed with those channels.
.UNINDENT
.TP
.B Returns
an open temporary file. If the \fBerror=\fP argument
was provided and the file was not opened because of an error, returns
the default \fI\%file\fP value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc openmem(out error: syserr, style: iostyle = defaultIOStyle())
Open a file that is backed by a buffer in memory that will not persist when the
file is closed.  Note that once the file is open, you will need to use a
\fI\%file.reader\fP or \fI\%file.writer\fP to create a channel to actually
perform I/O operations.
.sp
The resulting file supports both reading and writing.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to specify I/O style associated with this file.
The provided style will be the default for any channels created for
on this file, and that in turn will be the default for all I/O
operations performed with those channels.
.UNINDENT
.TP
.B Returns
an open memory file. If the \fBerror=\fP argument
was provided and the file was not opened because of an error, returns
the default \fI\%file\fP value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record channel
A channel supports either sequential reading or sequential writing to an
underlying \fI\%file\fP object. A channel can buffer data. Read operations
on the channel might return old data. Write operations might not have an
immediate effect. Use \fI\%channel.flush\fP to control this buffering.
.sp
The \fI\%channel\fP type is implementation\-defined.
A value of the \fI\%channel\fP type refers to the state that is used
to implement the channel operations.
.sp
When a \fI\%channel\fP formal has default intent, the
actual is copied to the formal upon a function call and
the formal cannot be assigned within the function.
.sp
The default value of the \fI\%channel\fP type is not associated
with any file and so cannot be used to perform I/O.
.sp
The \fI\%channel\fP type is generic.
.INDENT 7.0
.TP
.B param writing: bool
writing is a boolean indicating whether the channels of this type
support writing (when \fItrue\fP) or reading (when \fIfalse\fP).
.UNINDENT
.INDENT 7.0
.TP
.B param kind: iokind
kind is an enum \fI\%iokind\fP that allows narrowing
this channel\(aqs I/O style for more efficient binary I/O.
.UNINDENT
.INDENT 7.0
.TP
.B param locking: bool
locking is a boolean indicating whether it is safe to use this
channel concurrently (when \fItrue\fP).
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record ioChar
Represents a Unicode code point. I/O routines (such as \fI\%channel.read\fP
and \fI\%channel.write\fP) can use arguments of this type in order to read or
write a single Unicode code point.
.INDENT 7.0
.TP
.B var ch: int(32)
The code point value
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record ioNewline
Represents a newline character or character sequence (ie \fB\en\fP). I/O routines
(such as \fI\%channel.read\fP and \fI\%channel.write\fP) can use arguments of
this type in order to read or write a newline. This is different from \(aqn\(aq
because an ioNewline always produces an actual newline, but in some cases
writing \fB\en\fP will produce an escaped string (such as \fB"\en"\fP).
.sp
When reading an ioNewline, read routines will skip any character sequence
(including e.g. letters and numbers) to get to the newline character unless
\fBskipWhitespaceOnly\fP is set to true.
.INDENT 7.0
.TP
.B var skipWhitespaceOnly: bool = false
Normally, we will skip anything at all to get to a n,
but if skipWhitespaceOnly is set, it will be an error
if we run into non\-space characters other than n.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record ioLiteral
Used to represent a constant string we want to read or write.
.sp
When writing, the ioLiteral is output without any quoting or escaping.
.sp
When reading, the ioLiteral must be matched exactly \- or else the read call
will return an error with code \fBSysBasic.EFORMAT\fP\&.
.INDENT 7.0
.TP
.B var val: string
The value of the literal
.UNINDENT
.INDENT 7.0
.TP
.B var ignoreWhiteSpace: bool = true
Should read operations using this literal ignore and consume
whitespace before the literal?
.UNINDENT
.INDENT 7.0
.TP
.B proc writeThis(f)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record ioBits
Represents a value with a particular bit length that we want to read or write.
The I/O will always be done in binary mode.
.INDENT 7.0
.TP
.B var v: uint(64)
The bottom \fBnbits\fP of v will be read or written
.UNINDENT
.INDENT 7.0
.TP
.B var nbits: int(8)
How many of the low\-order bits of \fBv\fP should we read or write?
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.lock(out error: syserr)
Acquire a channel\(aqs lock.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.unlock()
Release a channel\(aqs lock.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.offset(): int(64)
Return the current offset of a channel. Note that other operations
on the channel (e.g. by other tasks) might change the offset. If you
are doing another operation on the channel based upon the current offset,
you should use \fI\%channel.lock\fP, \fI\%channel._offset\fP, and
\fI\%channel.unlock\fP to prevent race conditions.
.INDENT 7.0
.TP
.B Returns
the current offset of the channel
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.advance(amount: int(64), ref error: syserr)
Move a channel offset forward.
.sp
For a reading channel, this function will consume the next \fBamount\fP
bytes. If EOF is reached, the channel position may be left at the
EOF.
.sp
For a writing channel, this function will write \fBamount\fP zeros \- or some
other data if it is stored in the channel\(aqs buffer, for example with
\fI\%channel._mark\fP and \fI\%channel._revert\fP\&.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel._offset(): int(64)
For a channel locked with \fI\%channel.lock\fP, return the offset
of that channel.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel._mark(): syserr
.INDENT 7.0
.INDENT 3.5
\fImark\fP a channel \- that is, save the current offset of the channel on its
\fImark stack\fP\&. This function should only be called on a channel that is
already locked with with \fI\%channel.lock\fP\&.
.sp
The \fImark stack\fP stores several channel offsets. For any channel offset that
is between the minimum and maximum value in the \fImark stack\fP, I/O operations
on the channel will keep that region of the file buffered in memory so that
those operations can be un\-done. As a result, it is possible to perform \fII/O
transactions\fP on a channel. The basic steps for an \fII/O transaction\fP are:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
lock the channel with \fI\%channel.lock\fP
(or work on an already\-locked channel)
.IP \(bu 2
\fImark\fP the current position with \fI\%channel._mark\fP
.IP \(bu 2
do something speculative (e.g. try to read 200 bytes of anything followed
by a \(aqB\(aq)
.IP \(bu 2
if the speculative operation was successful,  commit the changes by
calling \fI\%channel._commit\fP
.IP \(bu 2
if the speculative operation was not successful, go back to the \fImark\fP by
calling \fI\%channel._revert\fP\&. Subsequent I/O operations will work
as though nothing happened.
.IP \(bu 2
unlock the channel with \fI\%channel.unlock\fP if necessary
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Note that it is possible to request an entire file be buffered in memory
using this feature, for example by \fImarking\fP at offset=0 and then
advancing to the end of the file. It is important to be aware of these
memory space requirements.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Returns
an error code, if an error was encountered.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel._revert()
Abort an \fII/O transaction\fP\&. See \fI\%channel._mark\fP\&. This function should
only be called on a channel that has already been locked and marked.  This
function will pop the last element from the \fImark stack\fP and then leave the
previous channel offset unchanged.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel._commit()
Commit an \fII/O transaction\fP\&. See \fI\%channel._mark\fP\&. This function should
only be called on a channel that has already been locked and marked.  This
function will pop the last element from the \fImark stack\fP and then set the
channel offset to the popped offset.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel._style(): iostyle
Return the current style used by a channel. This function should only be
called on a locked channel.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel._set_style(style: iostyle)
Set the style associated with a channel. This function should only
be called on a locked channel.
.UNINDENT
.INDENT 0.0
.TP
.B proc openreader(out err: syserr, path: string = "", param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints = IOHINT_NONE, url: string = ""): channel(false, kind, locking)
Open a file at a particular path or URL and return a reading channel for it.
This function is equivalent to calling \fI\%open\fP and then
\fI\%file.reader\fP on the resulting file.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerr\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBpath\fP \-\- which file to open (for example, "some/file.txt"). This argument
is required unless the \fBurl=\fP argument is used.
.IP \(bu 2
\fBkind\fP \-\- \fI\%iokind\fP compile\-time argument to determine the
corresponding parameter of the \fI\%channel\fP type. Defaults
to \fBiokind.dynamic\fP, meaning that the associated
\fI\%iostyle\fP controls the formatting choices.
.IP \(bu 2
\fBlocking\fP \-\- compile\-time argument to determine whether or not the
channel should use locking; sets the
corresponding parameter of the \fI\%channel\fP type.
Defaults to true, but when safe, setting it to false
can improve performance.
.IP \(bu 2
\fBstart\fP \-\- zero\-based byte offset indicating where in the file the
channel should start reading. Defaults to 0.
.IP \(bu 2
\fBend\fP \-\- zero\-based byte offset indicating where in the file the
channel should no longer be allowed to read. Defaults
to a \fBmax(int)\fP \- meaning no end point.
.IP \(bu 2
\fBhints\fP \-\- optional argument to specify any hints to the I/O system about
this file. See \fI\%iohints\fP\&.
.IP \(bu 2
\fBurl\fP \-\- optional argument to specify a URL to open. See \fBCurl\fP and
\fBHDFS\fP for more information on \fBurl=\fP support for those
systems. If HDFS is enabled, this function supports \fBurl=\fP
arguments of the form "hdfs://<host>:<port>/<path>". If Curl is
enabled, this function supports \fBurl=\fP starting with
\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP, \fBftps://\fP, \fBsmtp://\fP,
\fBsmtps://\fP, \fBimap://\fP, or \fBimaps://\fP
.UNINDENT
.TP
.B Returns
an open reading channel to the requested resource. If the \fBerror=\fP
argument was provided and the channel was not opened because of an
error, returns the default \fI\%channel\fP value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc openwriter(out err: syserr, path: string = "", param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints = IOHINT_NONE, url: string = ""): channel(true, kind, locking)
Open a file at a particular path or URL and return a writing channel for it.
This function is equivalent to calling \fI\%open\fP with \fBiomode.cwr\fP and then
\fI\%file.writer\fP on the resulting file.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerr\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBpath\fP \-\- which file to open (for example, "some/file.txt"). This argument
is required unless the \fBurl=\fP argument is used.
.IP \(bu 2
\fBkind\fP \-\- \fI\%iokind\fP compile\-time argument to determine the
corresponding parameter of the \fI\%channel\fP type. Defaults
to \fBiokind.dynamic\fP, meaning that the associated
\fI\%iostyle\fP controls the formatting choices.
.IP \(bu 2
\fBlocking\fP \-\- compile\-time argument to determine whether or not the
channel should use locking; sets the
corresponding parameter of the \fI\%channel\fP type.
Defaults to true, but when safe, setting it to false
can improve performance.
.IP \(bu 2
\fBstart\fP \-\- zero\-based byte offset indicating where in the file the
channel should start writing. Defaults to 0.
.IP \(bu 2
\fBend\fP \-\- zero\-based byte offset indicating where in the file the
channel should no longer be allowed to write. Defaults
to a \fBmax(int)\fP \- meaning no end point.
.IP \(bu 2
\fBhints\fP \-\- optional argument to specify any hints to the I/O system about
this file. See \fI\%iohints\fP\&.
.IP \(bu 2
\fBurl\fP \-\- optional argument to specify a URL to open. See \fBCurl\fP and
\fBHDFS\fP for more information on \fBurl=\fP support for those
systems. If HDFS is enabled, this function supports \fBurl=\fP
arguments of the form "hdfs://<host>:<port>/<path>". If Curl is
enabled, this function supports \fBurl=\fP starting with
\fBhttp://\fP, \fBhttps://\fP, \fBftp://\fP, \fBftps://\fP, \fBsmtp://\fP,
\fBsmtps://\fP, \fBimap://\fP, or \fBimaps://\fP
.UNINDENT
.TP
.B Returns
an open reading channel to the requested resource. If the \fBerror=\fP
argument was provided and the channel was not opened because of an
error, returns the default \fI\%channel\fP value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.reader(out error: syserr, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints = IOHINT_NONE, style: iostyle = this._style): channel(false, kind, locking)
Create a \fI\%channel\fP that supports reading from a file. See
\fI\%I/O Overview\fP\&.
.sp
The \fBstart=\fP and \fBend=\fP arguments define the region of the file that the
channel will read from.  These are byte offsets; the beginning of the file is
at the offset 0.  The defaults for these arguments enable the channel to
access the entire file.
.sp
A channel will never read beyond its maximum end position. In addition,
reading from a channel beyond the end of the underlying file will not extend
that file.  Reading beyond the end of the file or beyond the end offset of
the channel will produce the error \fBEEOF\fP (and return \fIfalse\fP in many
cases such as \fI\%channel.read\fP) to indicate that the end was reached.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBkind\fP \-\- \fI\%iokind\fP compile\-time argument to determine the
corresponding parameter of the \fI\%channel\fP type. Defaults
to \fBiokind.dynamic\fP, meaning that the associated
\fI\%iostyle\fP controls the formatting choices.
.IP \(bu 2
\fBlocking\fP \-\- compile\-time argument to determine whether or not the
channel should use locking; sets the
corresponding parameter of the \fI\%channel\fP type.
Defaults to true, but when safe, setting it to false
can improve performance.
.IP \(bu 2
\fBstart\fP \-\- zero\-based byte offset indicating where in the file the
channel should start reading. Defaults to 0.
.IP \(bu 2
\fBend\fP \-\- zero\-based byte offset indicating where in the file the
channel should no longer be allowed to read. Defaults
to a \fBmax(int)\fP \- meaning no end point.
.IP \(bu 2
\fBhints\fP \-\- provide hints about the I/O that this channel will perform. See
\fI\%iohints\fP\&. The default value of \fI\%IOHINT_NONE\fP
will cause the channel to use the hints provided when opening
the file.
.IP \(bu 2
\fBstyle\fP \-\- provide a \fI\%iostyle\fP to use with this channel. The
default value will be the \fI\%iostyle\fP associated with
this file.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.lines(out error: syserr, param locking: bool = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints = IOHINT_NONE, in local_style: iostyle = this._style)
Iterate over all of the lines in a file.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.TP
.B Returns
an object which yields strings read from the file
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.writer(out error: syserr, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints = IOHINT_NONE, style: iostyle = this._style): channel(true, kind, locking)
Create a \fI\%channel\fP that supports writing to a file. See
\fI\%I/O Overview\fP\&.
.sp
The \fBstart=\fP and \fBend=\fP arguments define the region of the file that the
channel will write to.  These are byte offsets; the beginning of the file is
at the offset 0.  The defaults for these arguments enable the channel to
access the entire file.
.sp
When a channel writes to a file, it will replace file data that was
previously stored at the relevant offset. If the offset is beyond the
end of the file, the file will be extended.
.sp
A channel will never write beyond its maximum end position.  It will extend
the file only as necessary to store data written to the channel. In other
words, specifying end here does not impact the file size directly; it
impacts only the section of the file that this channel can write to. After
all channels to a file are closed, that file will have a size equal to the
last position written to by any channel.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.IP \(bu 2
\fBkind\fP \-\- \fI\%iokind\fP compile\-time argument to determine the
corresponding parameter of the \fI\%channel\fP type. Defaults
to \fBiokind.dynamic\fP, meaning that the associated
\fI\%iostyle\fP controls the formatting choices.
.IP \(bu 2
\fBlocking\fP \-\- compile\-time argument to determine whether or not the
channel should use locking; sets the
corresponding parameter of the \fI\%channel\fP type.
Defaults to true, but when safe, setting it to false
can improve performance.
.IP \(bu 2
\fBstart\fP \-\- zero\-based byte offset indicating where in the file the
channel should start writing. Defaults to 0.
.IP \(bu 2
\fBend\fP \-\- zero\-based byte offset indicating where in the file the
channel should no longer be allowed to write. Defaults
to a \fBmax(int)\fP \- meaning no end point.
.IP \(bu 2
\fBhints\fP \-\- provide hints about the I/O that this channel will perform. See
\fI\%iohints\fP\&. The default value of \fI\%IOHINT_NONE\fP
will cause the channel to use the hints provided when opening
the file.
.IP \(bu 2
\fBstyle\fP \-\- provide a \fI\%iostyle\fP to use with this channel. The
default value will be the \fI\%iostyle\fP associated with
this file.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readwrite(x)
For a writing channel, writes as with \fI\%channel.write\fP\&.
For a reading channel, reads as with \fI\%channel.read\fP\&.
Stores any error encountered in the channel. Does not return anything.
.UNINDENT
.INDENT 0.0
.TP
.B proc <~>(ch: channel, x)
The 
.sp
This \fI<~>\fP operator is the same as calling \fI\%channel.readwrite\fP,
except that it returns the channel so that multiple operator
calls can be chained together.
.INDENT 7.0
.TP
.B Returns
ch
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc <~>(r: channel, lit: ioLiteral)
Overload to support reading an \fI\%IO.ioLiteral\fP without
passing ioLiterals by reference, so that
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
reader <~> new ioLiteral("=")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
works without requiring an explicit temporary value to store
the ioLiteral.
.UNINDENT
.INDENT 0.0
.TP
.B proc <~>(r: channel, nl: ioNewline)
Overload to support reading an \fI\%IO.ioNewline\fP without
passing ioNewline by reference, so that
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
reader <~> new ioNewline("=")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
works without requiring an explicit temporary value to store
the ioNewline.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readWriteLiteral(lit: string, ignoreWhiteSpace = true)
Explicit call for reading or writing a literal as an
alternative to using \fI\%IO.ioLiteral\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readWriteNewline()
Explicit call for reading or writing a newline as an
alternative to using \fI\%IO.ioNewline\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.binary(): bool
Returns \fItrue\fP if this channel is configured for binary I/O.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.error(): syserr
Return any saved error code.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.setError(e: syserr)
Save an error code.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.clearError()
Clear any saved error code.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.writeBytes(x, len: ssize_t)
Write a sequence of bytes.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.read(ref args ...?k, out error: syserr): bool
Returns true if we read all the args,
false if we encountered EOF (or possibly another error and didn\(aqt halt)
.UNINDENT
.INDENT 0.0
.TP
.B proc stringify(args ...?k): string
Creates a string representing the result of writing the arguments.
.sp
Writes each argument, possibly using a \fIwriteThis\fP method,
to a string and returns the result.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.read(ref args ...?k, style: iostyle, out error: syserr): bool
Read values from a channel. The input will be consumed atomically \- the
channel lock will be held while reading all of the passed values.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBargs\fP \-\- a list of arguments to read. Basic types are handled
internally, but for other types this function will call
value.readThis() with a \fBReader\fP argument as described
in the specification.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to provide an \fI\%iostyle\fP for this read.
If this argument is not provided, use the current style
associated with this channel.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
\fItrue\fP if the read succeeded, and \fIfalse\fP on error or end of file.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readline(arg: [] uint(8), out numRead: int, start = arg.domain.low, amount = arg.domain.high\-start, out error: syserr): bool
Read a line into a Chapel array of bytes. Reads until a \fB\en\fP is reached.
The \fB\en\fP is consumed but not returned in the array.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBarg\fP \-\- A 1D DefaultRectangular array which must have at least 1 element.
.IP \(bu 2
\fBnumRead\fP \-\- The number of bytes read.
.IP \(bu 2
\fBstart\fP \-\- Index to begin reading into.
.IP \(bu 2
\fBamount\fP \-\- The maximum amount of bytes to read.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
true if the bytes were read without error.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readline(ref arg: string, out error: syserr): bool
Read a line into a Chapel string. Reads until a \fB\en\fP is reached.
The \fB\en\fP is included in the resulting string.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBarg\fP \-\- a string to receive the line
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
\fItrue\fP if a line was read without error, \fIfalse\fP on error or EOF
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readstring(ref str_out: string, len: int(64) = \-1, out error: syserr): bool
read a given number of bytes from a channel
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBstr_out\fP \-\- The string to be read into
.IP \(bu 2
\fBlen\fP \-\- Read up to len bytes from the channel, up until EOF
(or some kind of I/O error). If the default value of \-1
is provided, read until EOF starting from the channel\(aqs
current offset.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
\fItrue\fP if we read something, \fIfalse\fP on EOF or error
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readbits(out v: integral, nbits: integral, out error: syserr): bool
Read bits with binary I/O
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBv\fP \-\- where to store the read bits. This value will have its \fInbits\fP
least\-significant bits set.
.IP \(bu 2
\fBnbits\fP \-\- how many bits to read
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
\fItrue\fP if the bits were read without error, \fIfalse\fP on error or EOF
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.writebits(v: integral, nbits: integral, out error: syserr): bool
Write bits with binary I/O
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBv\fP \-\- a value containing \fInbits\fP bits to write the least\-significant bits
.IP \(bu 2
\fBnbits\fP \-\- how many bits to write
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
\fItrue\fP if the bits were written without error, \fIfalse\fP on error
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readln(ref args ...?k, style: iostyle, out error: syserr): bool
Read values from a channel and then consume any bytes until
newline is reached. The input will be consumed atomically \- the
channel lock will be held while reading all of the passed values.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBargs\fP \-\- a list of arguments to read. This routine can be called
with zero or more such arguments. Basic types are handled
internally, but for other types this function will call
value.readThis() with a \fBReader\fP argument as described
in the specification.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to provide an \fI\%iostyle\fP for this read.
If this argument is not provided, use the current style
associated with this channel.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
\fItrue\fP if the read succeeded, and \fIfalse\fP on error or end of file.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.read(type t)
Read a value of passed type.
Halts if an error is encountered.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
It is difficult to handle errors or to handle reaching the end of
the file with this function. If such cases are important please use
the \fI\%channel.read\fP returning the values read in arguments instead.
.UNINDENT
.UNINDENT
.sp
For example, the following line of code reads a value of type \fIint\fP
from \fI\%stdin\fP and uses it to initialize a variable \fBx\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var x = stdin.read(int)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
\fBt\fP \-\- the type to read
.TP
.B Returns
the value read
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readln(type t)
Read a value of passed type followed by a newline.
Halts if an error is encountered.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
It is difficult to handle errors or to handle reaching the end of
the file with this function. If such cases are important please use
\fI\%channel.readln\fP instead.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
\fBt\fP \-\- the type to read
.TP
.B Returns
the value read
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readln(type t ...?numTypes)
Read values of passed types followed by a newline
and return a tuple containing the read values.
Halts if an error is encountered.
.INDENT 7.0
.TP
.B Arguments
\fBt\fP \-\- more than one type to read
.TP
.B Returns
a tuple of the read values
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.read(type t ...?numTypes)
Read values of passed types and return a tuple containing the read values.
Halts if an error is encountered.
.INDENT 7.0
.TP
.B Arguments
\fBt\fP \-\- more than one type to read
.TP
.B Returns
a tuple of the read values
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.write(args ...?k, style: iostyle, out error: syserr): bool
Write values to a channel. The output will be produced atomically \-
the channel lock will be held while writing all of the passed
values.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBargs\fP \-\- a list of arguments to write. Basic types are handled
internally, but for other types this function will call
value.writeThis() with the channel as an argument.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to provide an \fI\%iostyle\fP for this write.
If this argument is not provided, use the current style
associated with this channel.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
\fItrue\fP if the write succeeded
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.writeln(args ...?k, style: iostyle, out error: syserr): bool
Write values to a channel followed by a newline.  The output will be
produced atomically \- the channel lock will be held while writing all of the
passed values.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBargs\fP \-\- a variable number of arguments to write. This method can be
called with zero or more arguments. Basic types are handled
internally, but for other types this function will call
value.writeThis() with the channel as an argument.
.IP \(bu 2
\fBstyle\fP \-\- optional argument to provide an \fI\%iostyle\fP for this write.
If this argument is not provided, use the current style
associated with this channel.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
\fItrue\fP if the write succeeded
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.flush(out error: syserr)
Makes all writes to the channel, if any, available to concurrent viewers
of its associated file, such as other channels or other applications
accessing this file concurrently.
Unlike \fI\%file.fsync\fP, this does not commit the written data
to the file\(aqs device.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.assertEOF(error: string)
Assert that a channel has reached end\-of\-file.
Halts with an error message if the receiving channel is not currently
at EOF.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- an optional string argument which will be printed
out if the assert fails. The default prints "Not at EOF".
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.close(out error: syserr)
Close a channel. Implicitly performs the \fI\%channel.flush\fP operation
(see \fI\%Synchronization of Channel Data and Avoiding Data Races\fP).
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.isclosed()
Return \fItrue\fP if a channel is currently closed.
.UNINDENT
.INDENT 0.0
.TP
.B record ItemReader
Wrapper class on a channel to make it only read values
of a single type. Also supports an iterator yielding
the read values.
.INDENT 7.0
.TP
.B type ItemType
What type do we read and yield?
.UNINDENT
.INDENT 7.0
.TP
.B param kind: iokind
the kind field for our channel
.UNINDENT
.INDENT 7.0
.TP
.B param locking: bool
the locking field for our channel
.UNINDENT
.INDENT 7.0
.TP
.B var ch: channel(false, kind, locking)
our channel
.UNINDENT
.INDENT 7.0
.TP
.B proc read(out arg: ItemType, out error: syserr): bool
read a single item, returning an error
.UNINDENT
.INDENT 7.0
.TP
.B proc read(out arg: ItemType): bool
read a single item, halting on error
.UNINDENT
.INDENT 7.0
.TP
.B iter these()
iterate through all items of that type read from the channel
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.itemReader(type ItemType, param kind: iokind = iokind.dynamic)
Create and return an \fI\%ItemReader\fP that can yield read values of
a single type.
.UNINDENT
.INDENT 0.0
.TP
.B record ItemWriter
.INDENT 7.0
.TP
.B type ItemType
What type do we write?
.UNINDENT
.INDENT 7.0
.TP
.B param kind: iokind
the kind field for our channel
.UNINDENT
.INDENT 7.0
.TP
.B param locking: bool
the locking field for our channel
.UNINDENT
.INDENT 7.0
.TP
.B var ch: channel(true, kind, locking)
our channel
.UNINDENT
.INDENT 7.0
.TP
.B proc write(arg: ItemType, out error: syserr): bool
write a single item, returning an error
.UNINDENT
.INDENT 7.0
.TP
.B proc write(arg: ItemType): bool
write a single item, halting on error
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.itemWriter(type ItemType, param kind: iokind = iokind.dynamic)
Create and return an \fI\%ItemWriter\fP that can write values of
a single type.
.UNINDENT
.INDENT 0.0
.TP
.B const stdin: channel(false, iokind.dynamic, true) = AppendExpr.Call08
standard input, otherwise known as file descriptor 0
.UNINDENT
.INDENT 0.0
.TP
.B const stdout: channel(true, iokind.dynamic, true) = AppendExpr.Call08
standard output, otherwise known as file descriptor 1
.UNINDENT
.INDENT 0.0
.TP
.B const stderr: channel(true, iokind.dynamic, true) = AppendExpr.Call08
standard error, otherwise known as file descriptor 2
.UNINDENT
.INDENT 0.0
.TP
.B proc write(args ...?n)
Equivalent to stdout.write. See \fI\%channel.write\fP
.UNINDENT
.INDENT 0.0
.TP
.B proc writeln(args ...?n)
Equivalent to stdout.writeln. See \fI\%channel.writeln\fP
.UNINDENT
.INDENT 0.0
.TP
.B proc read(ref args ...?n): bool
Equivalent to stdin.read. See \fI\%channel.read\fP
.UNINDENT
.INDENT 0.0
.TP
.B proc readln(ref args ...?n): bool
Equivalent to stdin.readln. See \fI\%channel.readln\fP
.UNINDENT
.INDENT 0.0
.TP
.B proc readln(type t ...?numTypes)
Equivalent to stdin.readln. See \fI\%channel.readln\fP for types
.UNINDENT
.INDENT 0.0
.TP
.B proc read(type t ...?numTypes)
Equivalent to stdin.read. See \fI\%channel.read\fP for types
.UNINDENT
.INDENT 0.0
.TP
.B proc unlink(path: string, out error: syserr)
Delete a file. This function is likely to be replaced
by \fBFileSystem.remove\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBpath\fP \-\- the path to the file to remove
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc unicodeSupported(): bool
.INDENT 7.0
.TP
.B Returns
\fItrue\fP if this version of the Chapel runtime supports UTF\-8 output.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.writef(fmtStr: string, args ...?k, out error: syserr): bool
Write arguments according to a format string. See
\fI\%Formatted I/O\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBfmt\fP \-\- the format string
.IP \(bu 2
\fBargs\fP \-\- the arguments to write
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.readf(fmtStr: string, ref args ...?k, out error: syserr): bool
Read arguments according to a format string. See
\fI\%Formatted I/O\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBfmt\fP \-\- the format string
.IP \(bu 2
\fBargs\fP \-\- the arguments to read
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
true if all arguments were read according to the format string,
false on EOF. If the format did not match the input, returns
false with error=EFORMAT or halts if no error argument was
provided.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc writef(fmt: string, args ...?k): bool
Call \fBstdout.writef\fP; see \fI\%channel.writef\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc readf(fmt: string, ref args ...?k): bool
Call \fBstdout.readf\fP; see \fI\%channel.readf\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.skipField(out error: syserr)
Skip a field in the current aggregate format. This method is currently only
supported for JSON format and returns ENOTSUP for other formats. In other
formats, it may not be possible in general to know when a field ends.
.sp
The field skipped includes a field name and value but not a following
separator. For example, for a JSON format channel, given the input:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
"fieldName":"fieldValue", "otherField":3
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
this function will skip to (but leave unread) the comma after
the first field value.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc string.format(args ...?k, out error: syserr): string
Return a new string consisting of values formatted according to a
format string.  See \fI\%Formatted I/O\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBthis\fP \-\- the format string
.IP \(bu 2
\fBargs\fP \-\- the arguments to format
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
the resulting string
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.extractMatch(m: reMatch, ref arg, ref error: syserr)
Sets arg to the string of a match.
.sp
Assumes that the channel has been marked before where
the captures are being returned. Will change the channel
position to just after the match. Will not do anything
if error is set.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBm\fP \-\- a \fBRegexp.reMatch\fP storing a location that matched
.IP \(bu 2
\fBarg\fP \-\- an argument to retrieve the match into. If it is not a string,
the string match will be cast to arg.type.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.search(re: regexp, ref captures ...?k, ref error: syserr): reMatch
Search for an offset in the channel matching the
passed regular expression, possibly pulling out capture groups.
If there is a match, leaves the channel position at the
match. If there is no match, the channel position will be
advanced to the end of the channel (or end of the file).
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBre\fP \-\- a \fBRegexp.regexp\fP record representing a compiled
regular expression.
.IP \(bu 2
\fBcaptures\fP \-\- an optional variable number of arguments in which to
store the regions of the file matching the capture groups
in the regular expression.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
the region of the channel that matched
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc channel.match(re: regexp, ref captures ...?k, ref error: syserr): reMatch
Match, starting at the current position in the channel,
against a regexp, possibly pulling out capture groups.
If there was a match, leaves the channel position at
the match. If there was no match, leaves the channel
position where it was at the start of this call.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBre\fP \-\- a \fBRegexp.regexp\fP record representing a compiled
regular expression.
.IP \(bu 2
\fBcaptures\fP \-\- an optional variable number of arguments in which to
store the regions of the file matching the capture groups
in the regular expression.
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture an error code. If this argument
is not provided and an error is encountered, this function
will halt with an error message.
.UNINDENT
.TP
.B Returns
the region of the channel that matched
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B iter channel.matches(re: regexp, param captures = 0, maxmatches: int = max(int))
Enumerates matches in the string as well as capture groups.
.sp
Yields tuples of \fBRegexp.reMatch\fP objects, the 1st is always
the match for the whole pattern.
.sp
At the time each match is returned, the channel position is
at the start of that match. Note though that you would have
to use \fI\%channel.advance\fP to get to the position of a capture group.
.sp
After returning each match, advances to just after that
match and looks for another match. Thus, it will not return
overlapping matches.
.sp
In the end, leaves the channel position at the end of the
last reported match (if we ran out of maxmatches)
or at the end of the channel (if we no longer matched)
.sp
Holds the channel lock for the duration of the search.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBre\fP \-\- a \fBRegexp.regexp\fP record representing a compiled
regular expression.
.IP \(bu 2
\fBcaptures\fP \-\- an optional compile\-time constant representing the number
of captures to be yielded in tuple elements.
.IP \(bu 2
\fBmaxmatches\fP \-\- the maximum number of matches to report.
.UNINDENT
.TP
.B Yields
tuples of \fBRegexp.reMatch\fP objects, where the first element
is the whole pattern.  The tuples will have 1+captures elements.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.getchunk(start: int(64) = 0, end: int(64) = max(int(64))): (int(64), int(64))
Returns (chunk start, chunk end) for the first chunk in the file
containing data in the region start..end\-1. Note that the returned
chunk might not cover all of the region in question.
.sp
Returns (0,0) if no such value exists.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBstart\fP \-\- the file offset (starting from 0) where the region begins
.IP \(bu 2
\fBend\fP \-\- the file offset just after the region
.UNINDENT
.TP
.B Returns
a tuple of (chunkStart, chunkEnd) so that the bytes
in chunkStart..chunkEnd\-1 are stored in a manner that makes
reading that chunk at a time most efficient
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.localesForRegion(start: int(64), end: int(64))
Returns the \(aqbest\(aq locale to run something working with the region
of the file in start..end\-1.
.sp
This \fImust\fP return the same result when called from different locales.
Returns a domain of locales that are "best" for the given region. If no
locales are "best" we return a domain containing all locales.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBstart\fP \-\- the file offset (starting from 0) where the region begins
.IP \(bu 2
\fBend\fP \-\- the file offset just after the region
.UNINDENT
.TP
.B Returns
a set of locales that are best for working with this region
.TP
.B Return type
domain(locale)
.UNINDENT
.UNINDENT
.SS List
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use List;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This module provides a simple singly linked list.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This module is expected to change in the future.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record list
A singly linked list.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%destroy\fP must be called to reclaim any memory used by the list.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B type eltType
The type of the data stored in every node.
.UNINDENT
.INDENT 7.0
.TP
.B var length: int
The number of nodes in the list.
.UNINDENT
.INDENT 7.0
.TP
.B proc size
Synonym for length.
.UNINDENT
.INDENT 7.0
.TP
.B iter these()
Iterate over the list, yielding each element.
.INDENT 7.0
.TP
.B Yield type
eltType
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc ref append(e: eltType)
Append \fIe\fP to the list.
.UNINDENT
.INDENT 7.0
.TP
.B proc push_back(e: eltType)
Synonym for append.
.UNINDENT
.INDENT 7.0
.TP
.B proc append(e: eltType, es: eltType ...?k)
Append all of the supplied arguments to the list.
.UNINDENT
.INDENT 7.0
.TP
.B proc prepend(e: eltType)
Prepend \fIe\fP to the list.
.UNINDENT
.INDENT 7.0
.TP
.B proc push_front(e: eltType)
Synonym for prepend.
.UNINDENT
.INDENT 7.0
.TP
.B proc concat(l: list(eltType))
Append all the elements in \fIl\fP to the end of the list.
.UNINDENT
.INDENT 7.0
.TP
.B proc ref remove(x: eltType)
Remove the first encountered instance of \fIx\fP from the list.
.UNINDENT
.INDENT 7.0
.TP
.B proc pop_front(): eltType
Remove the first element from the list and return it.
It is an error to call this function on an empty list.
.UNINDENT
.INDENT 7.0
.TP
.B proc destroy()
Delete every node in the list.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc makeList(x ...?k)
Construct a new \fI\%list\fP containing all of the supplied arguments.
.INDENT 7.0
.TP
.B Arguments
\fBx\fP : \fIT\fP \-\- Every argument must be of type \fIT\fP\&.
.TP
.B Return type
list(T)
.UNINDENT
.UNINDENT
.SS Math
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Math;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This module provides mathematical constants and functions.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
All Chapel programs automatically \fBuse\fP this module by default.
An explicit \fBuse\fP statement is not necessary.
.UNINDENT
.UNINDENT
.sp
It includes wrappers for many of the constants in functions in
the C Math library, which is part of the C Language Standard (ISO/IEC 9899)
as described in Section 7.12.  Please consult that standard for an
authoritative description of the expected properties of those constants and
routines.
.sp
In general, where the C math library provides a \fIdouble\fP and a \fIfloat\fP version
of a function, the float version has a suffix \(aqf\(aq.  In the Chapel interface,
the suffix is dropped, and the type of the operand determines which version is
called \-\- according to the usual function overloading and resolution rules.
Normally, the result has the same precision
as the argument(s).  Please consult the C standard for specifics.
.sp
Rounding \-\- The rounding mode for floating\-point addition (subtraction) is
implementation\-defined.
.sp
Error Handling \-\- At present, Chapel does not provide control over error
handling in the Math module.  The default behavior is as if the macro
\fBmath_errhandling\fP is set to 0: Given erroneous input at run\-time,
all math functions will return an implementation\-defined value; no
exception will be generated.
.INDENT 0.0
.TP
.B param e = 2.71828
e \- exp(1) or  the base of the natural logarithm
.UNINDENT
.INDENT 0.0
.TP
.B param log2_e = 1.4427
log2(e)
.UNINDENT
.INDENT 0.0
.TP
.B param log10_e = 0.434294
log10(e)
.UNINDENT
.INDENT 0.0
.TP
.B param ln_2 = 0.693147
log(2) (natural logarithm)
.UNINDENT
.INDENT 0.0
.TP
.B param ln_10 = 2.30259
log(10) (natural logarithm)
.UNINDENT
.INDENT 0.0
.TP
.B param pi = 3.14159
pi \- the circumference/the diameter of a circle
.UNINDENT
.INDENT 0.0
.TP
.B param half_pi = 1.5708
pi/2
.UNINDENT
.INDENT 0.0
.TP
.B param quarter_pi = 0.785398
pi/4
.UNINDENT
.INDENT 0.0
.TP
.B param recipr_pi = 0.31831
1/pi
.UNINDENT
.INDENT 0.0
.TP
.B param twice_recipr_pi = 0.63662
2/pi
.UNINDENT
.INDENT 0.0
.TP
.B param twice_recipr_sqrt_pi = 1.12838
2/sqrt(pi)
.UNINDENT
.INDENT 0.0
.TP
.B param sqrt_2 = 1.41421
sqrt(2)
.UNINDENT
.INDENT 0.0
.TP
.B param recipr_sqrt_2 = 0.707107
1/sqrt(2)
.UNINDENT
.INDENT 0.0
.TP
.B proc abs(i: int(?w))
Returns the absolute value of the integer argument.
.INDENT 7.0
.TP
.B Return type
The type of \fIi\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc abs(i: uint(?w))
Returns the absolute value of the unsigned integer argument.
.INDENT 7.0
.TP
.B Return type
The type of \fIi\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc abs(param i: integral) param
Returns the absolute value of the integer param argument \fIi\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc abs(r: real(64)): real(64)
Returns the magnitude of the real argument \fIr\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc abs(x: real(32)): real(32)
Returns the magnitude of the real argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc abs(im: imag(64)): real(64)
Returns the real magnitude of the imaginary argument \fIim\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc abs(im: imag(32)): real(32)
Returns the real magnitude of the imaginary argument \fIim\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc abs(z: complex(?w)): real(/(w, 2))
Returns the real magnitude of the complex argument \fIz\fP\&.
.INDENT 7.0
.TP
.B Return type
The type of the real component of the argument (== \fIw\fP/2).
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc carg(z: complex(?w)): real(/(w, 2))
Returns the real phase angle of complex argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc acos(x: real(64)): real(64)
Returns the arc cosine of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than \-1 or greater than 1.
.UNINDENT
.INDENT 0.0
.TP
.B proc acos(x: real(32)): real(32)
Returns the arc cosine of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than \-1 or greater than 1.
.UNINDENT
.INDENT 0.0
.TP
.B proc acos(z: complex(64)): complex(64)
Returns the arc cosine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc acos(z: complex(128)): complex(128)
Returns the arc cosine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc acosh(x: real(64)): real(64)
Returns the inverse hyperbolic cosine of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than 1.
.UNINDENT
.INDENT 0.0
.TP
.B proc acosh(x: real(32)): real(32)
Returns the inverse hyperbolic cosine of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than 1.
.UNINDENT
.INDENT 0.0
.TP
.B proc acosh(z: complex(64)): complex(64)
Returns the inverse hyperbolic cosine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc acosh(z: complex(128)): complex(128)
Returns the inverse hyperbolic cosine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc asin(x: real(64)): real(64)
Returns the arc sine of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than \-1 or greater than 1.
.UNINDENT
.INDENT 0.0
.TP
.B proc asin(x: real(32)): real(32)
Returns the arc sine of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than \-1 or greater than 1.
.UNINDENT
.INDENT 0.0
.TP
.B proc asin(z: complex(64)): complex(64)
Returns the arc sine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc asin(z: complex(128)): complex(128)
Returns the arc sine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc asinh(x: real(64)): real(64)
Returns the inverse hyperbolic sine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc asinh(x: real(32)): real(32)
Returns the inverse hyperbolic sine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc asinh(z: complex(64)): complex(64)
Returns the inverse hyperbolic sine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc asinh(z: complex(128)): complex(128)
Returns the inverse hyperbolic sine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc atan(x: real(64)): real(64)
Returns the arc tangent of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc atan(x: real(32)): real(32)
Returns the arc tangent of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc atan(z: complex(64)): complex(64)
Returns the arc tangent of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc atan(z: complex(128)): complex(128)
Returns the arc tangent of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc atan2(y: real(64), x: real(64)): real(64)
Returns the arc tangent of the ratio of the two arguments.
.sp
This is equivalent to
the arc tangent of \fIy\fP / \fIx\fP except that the signs of \fIy\fP
and \fIx\fP are used to determine the quadrant of the result.
.UNINDENT
.INDENT 0.0
.TP
.B proc atan2(y: real(32), x: real(32)): real(32)
Returns the arc tangent of the two arguments.
.sp
This is equivalent to
the arc tangent of \fIy\fP / \fIx\fP except that the signs of \fIy\fP
and \fIx\fP are used to determine the quadrant of the result.
.UNINDENT
.INDENT 0.0
.TP
.B proc atanh(x: real(64)): real(64)
Returns the inverse hyperbolic tangent of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than \-1 or greater than 1.
.UNINDENT
.INDENT 0.0
.TP
.B proc atanh(x: real(32)): real(32)
Returns the inverse hyperbolic tangent of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than \-1 or greater than 1.
.UNINDENT
.INDENT 0.0
.TP
.B proc atanh(z: complex(64)): complex(64)
Returns the inverse hyperbolic tangent of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc atanh(z: complex(128)): complex(128)
Returns the inverse hyperbolic tangent of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cbrt(x: real(64)): real(64)
Returns the cube root of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cbrt(x: real(32)): real(32)
Returns the cube root of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc ceil(x: real(64)): real(64)
Returns the value of the argument \fIx\fP rounded up to the nearest integer.
.UNINDENT
.INDENT 0.0
.TP
.B proc ceil(x: real(32)): real(32)
Returns the value of the argument \fIx\fP rounded up to the nearest integer.
.UNINDENT
.INDENT 0.0
.TP
.B proc conjg(z: complex(?w)): complex(w)
Returns the complex conjugate of the argument \fIz\fP\&.
.INDENT 7.0
.TP
.B Return type
A complex number of the same type as \fIz\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc cproj(z: complex(?w)): real(/(w, 2))
Returns the projection of \fIz\fP on a Riemann sphere.
.UNINDENT
.INDENT 0.0
.TP
.B proc cos(x: real(64)): real(64)
Returns the cosine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cos(x: real(32)): real(32)
Returns the cosine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cos(z: complex(64)): complex(64)
Returns the cosine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cos(z: complex(128)): complex(128)
Returns the cosine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cosh(x: real(64)): real(64)
Returns the hyperbolic cosine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cosh(x: real(32)): real(32)
Returns the hyperbolic cosine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cosh(z: complex(64)): complex(64)
Returns the hyperbolic cosine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc cosh(z: complex(128)): complex(128)
Returns the hyperbolic cosine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc divceil(param m: integral, param n: integral) param
Returns \fI\%ceil\fP(\fIm\fP/\fIn\fP),
i.e., the fraction \fIm\fP/\fIn\fP rounded up to the nearest integer.
.sp
If the arguments are of unsigned type, then
fewer conditionals will be evaluated at run time.
.UNINDENT
.INDENT 0.0
.TP
.B proc divceil(m: integral, n: integral)
Returns \fI\%ceil\fP(\fIm\fP/\fIn\fP),
i.e., the fraction \fIm\fP/\fIn\fP rounded up to the nearest integer.
.sp
If the arguments are of unsigned type, then
fewer conditionals will be evaluated at run time.
.UNINDENT
.INDENT 0.0
.TP
.B proc divceilpos(m: integral, n: integral)
A variant of \fI\%divceil\fP that performs no runtime checks.
The user must ensure that both arguments are strictly positive
(not 0) and are of a signed integer type (not \fIuint\fP).
.UNINDENT
.INDENT 0.0
.TP
.B proc divfloor(param m: integral, param n: integral) param
Returns \fI\%floor\fP(\fIm\fP/\fIn\fP),
i.e., the fraction \fIm\fP/\fIn\fP rounded down to the nearest integer.
.sp
If the arguments are of unsigned type, then
fewer conditionals will be evaluated at run time.
.UNINDENT
.INDENT 0.0
.TP
.B proc divfloor(m: integral, n: integral)
Returns \fI\%floor\fP(\fIm\fP/\fIn\fP),
i.e., the fraction \fIm\fP/\fIn\fP rounded down to the nearest integer.
.sp
If the arguments are of unsigned type, then
fewer conditionals will be evaluated at run time.
.UNINDENT
.INDENT 0.0
.TP
.B proc divfloorpos(m: integral, n: integral)
A variant of \fI\%divfloor\fP that performs no runtime checks.
The user must ensure that both arguments are strictly positive
(not 0) and are of a signed integer type (not \fIuint\fP).
.UNINDENT
.INDENT 0.0
.TP
.B proc erf(x: real(64)): real(64)
Returns the error function of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc erf(x: real(32)): real(32)
Returns the error function of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc erfc(x: real(64)): real(64)
Returns the complementary error function of the argument.
This is equivalent to 1.0 \- \fI\%erf\fP(\fIx\fP).
.UNINDENT
.INDENT 0.0
.TP
.B proc erfc(x: real(32)): real(32)
Returns the complementary error function of the argument.
This is equivalent to 1.0 \- \fI\%erf\fP(\fIx\fP).
.UNINDENT
.INDENT 0.0
.TP
.B proc exp(x: real(64)): real(64)
Returns the value of the Napierien \fIe\fP raised to the power of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc exp(x: real(32)): real(32)
Returns the value of the Napierien \fIe\fP raised to the power of the argument.
.UNINDENT
.INDENT 0.0
.TP
.B proc exp(z: complex(64)): complex(64)
Returns the value of the Napierien \fIe\fP raised to the power of the argument.
.UNINDENT
.INDENT 0.0
.TP
.B proc exp(z: complex(128)): complex(128)
Returns the value of the Napierien \fIe\fP raised to the power of the argument.
.UNINDENT
.INDENT 0.0
.TP
.B proc exp2(x: real(64)): real(64)
Returns the value of \fI2\fP raised to the power of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc exp2(x: real(32)): real(32)
Returns the value of \fI2\fP raised to the power of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc expm1(x: real(64)): real(64)
Returns one less than the value of the Napierien \fIe\fP raised to the power
of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc expm1(x: real(32)): real(32)
Returns one less than the value of the Napierien \fIe\fP raised to the power
of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc floor(x: real(64)): real(64)
Returns the value of the argument \fIx\fP rounded down to the nearest integer.
.UNINDENT
.INDENT 0.0
.TP
.B proc floor(x: real(32)): real(32)
Returns the value of the argument \fIx\fP rounded down to the nearest integer.
.UNINDENT
.INDENT 0.0
.TP
.B proc INFINITY: real(64)
Returns a value for which \fI\%isinf\fP will return \fItrue\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc isfinite(x: real(64)): bool
Returns \fItrue\fP if the argument \fIx\fP is a representation of a finite value;
\fIfalse\fP otherwise.
.UNINDENT
.INDENT 0.0
.TP
.B proc isfinite(x: real(32)): bool
Returns \fItrue\fP if the argument \fIx\fP is a representation of a finite value;
\fIfalse\fP otherwise.
.UNINDENT
.INDENT 0.0
.TP
.B proc isinf(x: real(64)): bool
Returns \fItrue\fP if the argument \fIx\fP is a representation of \fIinfinity\fP;
\fIfalse\fP otherwise.
.UNINDENT
.INDENT 0.0
.TP
.B proc isinf(x: real(32)): bool
Returns \fItrue\fP if the argument \fIx\fP is a representation of \fIinfinity\fP;
\fIfalse\fP otherwise.
.UNINDENT
.INDENT 0.0
.TP
.B proc isnan(x: real(64)): bool
Returns \fItrue\fP if the argument \fIx\fP does not represent a valid number;
\fIfalse\fP otherwise.
.UNINDENT
.INDENT 0.0
.TP
.B proc isnan(x: real(32)): bool
Returns \fItrue\fP if the argument \fIx\fP does not represent a valid number;
\fIfalse\fP otherwise.
.UNINDENT
.INDENT 0.0
.TP
.B proc ldexp(x: real(64), n: int(32)): real(64)
Multiply by an integer power of 2.
Returns x * 2**n.
.UNINDENT
.INDENT 0.0
.TP
.B proc ldexp(x: real(32), n: int(32)): real(32)
.UNINDENT
.INDENT 0.0
.TP
.B proc lgamma(x: real(64)): real(64)
Returns the natural logarithm of the absolute value
of the gamma function of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc lgamma(x: real(32)): real(32)
Returns the natural logarithm of the absolute value
of the gamma function of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc log(x: real(64)): real(64)
Returns the natural logarithm of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than or equal to zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc log(x: real(32)): real(32)
Returns the natural logarithm of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than or equal to zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc log(z: complex(64)): complex(64)
Returns the natural logarithm of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc log(z: complex(128)): complex(128)
Returns the natural logarithm of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc log10(x: real(64)): real(64)
Returns the base 10 logarithm of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than or equal to zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc log10(x: real(32)): real(32)
Returns the base 10 logarithm of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than or equal to zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc log1p(x: real(64)): real(64)
Returns the natural logarithm of \fIx\fP + 1.
.sp
It is an error if \fIx\fP is less than or equal to \-1.
.UNINDENT
.INDENT 0.0
.TP
.B proc log1p(x: real(32)): real(32)
Returns the natural logarithm of \fIx\fP + 1.
.sp
It is an error if \fIx\fP is less than or equal to \-1.
.UNINDENT
.INDENT 0.0
.TP
.B proc logBasePow2(in val: int(?w), baseLog2)
Returns the log to the base \fI2**baseLog2\fP of the given \fIin\fP value.
If \fIbaseLog2\fP is \fI1\fP, then returns the log to the base \fI2\fP;
if \fIbaseLog2\fP is \fI2\fP, then returns the log to the base \fI4\fP, etc.
Any fractional part is discarded.
.INDENT 7.0
.TP
.B Return type
\fIint\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc logBasePow2(in val: uint(?w), baseLog2)
Returns the log to the base \fI2**baseLog2\fP of the given \fIin\fP value.
If \fIbaseLog2\fP is \fI1\fP, then returns the log to the base \fI2\fP;
if \fIbaseLog2\fP is \fI2\fP, then returns the log to the base \fI4\fP, etc.
Any fractional part is discarded.
.INDENT 7.0
.TP
.B Return type
\fIint\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc log2(x: real(64)): real(64)
Returns the base 2 logarithm of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than or equal to zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc log2(x: real(32)): real(32)
Returns the base 2 logarithm of the argument \fIx\fP\&.
.sp
It is an error if \fIx\fP is less than or equal to zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc log2(in val: int(?w))
Returns the base 2 logarithm of the argument \fIx\fP\&.
.INDENT 7.0
.TP
.B Return type
\fIint(64)\fP
.UNINDENT
.sp
It is an error if \fIx\fP is less than or equal to zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc log2(in val: uint(?w))
Returns the base 2 logarithm of the argument \fIx\fP\&.
.INDENT 7.0
.TP
.B Return type
\fIint(64)\fP
.UNINDENT
.sp
It is an error if \fIx\fP is less than or equal to zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc mod(param m: integral, param n: integral) param
Computes the mod operator on the two arguments, defined as
\fBmod(m,n) = m \- n * floor(m / n)\fP\&.
.sp
The result is always >= 0 if \fIn\fP > 0.
It is an error if \fIn\fP == 0.
.UNINDENT
.INDENT 0.0
.TP
.B proc mod(m: integral, n: integral)
Computes the mod operator on the two arguments, defined as
\fBmod(m,n) = m \- n * floor(m / n)\fP\&.
.sp
If the arguments are of unsigned type, then
fewer conditionals will be evaluated at run time.
.sp
The result is always >= 0 if \fIn\fP > 0.
It is an error if \fIn\fP == 0.
.UNINDENT
.INDENT 0.0
.TP
.B proc mod(x: real(?w), y: real(w)): real(w)
Computes the mod operator on the two numbers, defined as
\fBmod(x,y) = x \- y * floor(x / y)\fP\&.
.sp
The return value has the same type as \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc NAN: real(64)
Returns a value for which \fI\%isnan\fP will return \fItrue\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc nearbyint(x: real(64)): real(64)
Returns the rounded integral value of the argument \fIx\fP determined by the
current rounding direction.  \fI\%nearbyint\fP will not raise the "inexact"
floating\-point exception.
.UNINDENT
.INDENT 0.0
.TP
.B proc nearbyint(x: real(32)): real(32)
Returns the rounded integral value of the argument \fIx\fP determined by the
current rounding direction.  \fI\%nearbyint\fP will not raise the "inexact"
floating\-point exception.
.UNINDENT
.INDENT 0.0
.TP
.B proc rint(x: real(64)): real(64)
Returns the rounded integral value of the argument \fIx\fP determined by the
current rounding direction.  \fI\%rint\fP may raise the "inexact" floating\-point
exception.
.UNINDENT
.INDENT 0.0
.TP
.B proc rint(x: real(32)): real(32)
Returns the rounded integral value of the argument \fIx\fP determined by the
current rounding direction.  \fI\%rint\fP may raise the "inexact" floating\-point
exception.
.UNINDENT
.INDENT 0.0
.TP
.B proc round(x: real(64)): real(64)
Returns the rounded integral value of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc round(x: real(32)): real(32)
Returns the rounded integral value of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sgn(i: int(?w)): int(8)
Returns the signum function of the integer argument \fIi\fP:
1 if positive, \-1 if negative, 0 if zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc sgn(i: uint(?w)): uint(8)
Returns the signum function of the unsigned integer argument \fIi\fP:
1 if positive, \-1 if negative, 0 if zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc sgn(param i: integral) param
Returns the signum function of the integer param argument \fIi\fP:
1 if positive, \-1 if negative, 0 if zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc sgn(x: real(?w)): int(8)
Returns the signum function of the real argument \fIx\fP:
1 if positive, \-1 if negative, 0 if zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc sin(x: real(64)): real(64)
Returns the sine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sin(x: real(32)): real(32)
Returns the sine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sin(z: complex(64)): complex(64)
Returns the sine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sin(z: complex(128)): complex(128)
Returns the sine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sinh(x: real(64)): real(64)
Returns the hyperbolic sine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sinh(x: real(32)): real(32)
Returns the hyperbolic sine of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sinh(z: complex(64)): complex(64)
Returns the hyperbolic sine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sinh(z: complex(128)): complex(128)
Returns the hyperbolic sine of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sqrt(x: real(64)): real(64)
Returns the square root of the argument \fIx\fP\&.
.sp
It is an error if the \fIx\fP is less than zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc sqrt(x: real(32)): real(32)
Returns the square root of the argument \fIx\fP\&.
.sp
It is an error if  \fIx\fP is less than zero.
.UNINDENT
.INDENT 0.0
.TP
.B proc sqrt(z: complex(64)): complex(64)
Returns the square root of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc sqrt(z: complex(128)): complex(128)
Returns the square root of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tan(x: real(64)): real(64)
Returns the tangent of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tan(x: real(32)): real(32)
Returns the tangent of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tan(z: complex(64)): complex(64)
Returns the tangent of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tan(z: complex(128)): complex(128)
Returns the tangent of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tanh(x: real(64)): real(64)
Returns the hyperbolic tangent of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tanh(x: real(32)): real(32)
Returns the hyperbolic tangent of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tanh(z: complex(64)): complex(64)
Returns the hyperbolic tangent of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tanh(z: complex(128)): complex(128)
Returns the hyperbolic tangent of the argument \fIz\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tgamma(x: real(64)): real(64)
Returns the absolute value of the gamma function of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc tgamma(x: real(32)): real(32)
Returns the absolute value of the gamma function of the argument \fIx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc trunc(x: real(64)): real(64)
Returns the nearest integral value to the argument \fIx\fP that is not larger
than \fIx\fP in absolute value.
.UNINDENT
.INDENT 0.0
.TP
.B proc trunc(x: real(32)): real(32)
Returns the nearest integral value to the argument \fIx\fP that is not larger
than \fIx\fP in absolute value.
.UNINDENT
.SS Memory
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Memory;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fI\%Memory\fP module provides procedures which report information
about memory usage.  With one exception, to use these procedures you
must enable memory tracking.  Do this by setting one or more of the
config vars below, using appropriate \fB\-\-configVarName=value\fP or
\fB\-sconfigVarName=value\fP command line options when you run the
program.  If memory tracking is not enabled, calling any procedure
described here, other than \fI\%locale.physicalMemory\fP, will cause
the program to halt with an error message.
.INDENT 0.0
.TP
.B \fBmemTrack\fP: \fIbool\fP:
Enable memory tracking.  This causes memory allocations and
deallocations to be internally tracked, to support logging them on
the fly and/or producing any of several kinds of memory\-related
reports, described below.
.TP
.B \fBmemLeaks\fP: \fIbool\fP:
Enable memory tracking and produce detailed information about
leaked memory by invoking \fI\%printMemAllocs\fP implicitly when
the program terminates normally.
.TP
.B \fBmemLeaksByType\fP: \fIbool\fP:
Enable memory tracking and produce summary information about
leaked memory by invoking \fI\%printMemAllocsByType\fP implicitly
when the program terminates normally.
.TP
.B \fBmemLeaksLog\fP: \fIc_string\fP:
Enable memory tracking and append a report to the named file when
the program terminates normally.
The report contains the compilation command used to build the
program, the execution command used to run it, the summary
allocation statistics produced by \fI\%printMemAllocStats\fP, and the
summary information about leaked memory produced by
\fI\%printMemAllocsByType\fP\&.
.TP
.B \fBmemStats\fP: \fIbool\fP:
Enable memory tracking and produce summary memory statistics by
invoking \fI\%printMemAllocStats\fP implicitly at normal program
termination.
.TP
.B \fBmemMax\fP: \fIuint\fP:
If the value is greater than 0 (zero), enable memory tracking
and use the value as a limit on the number of bytes of memory
that can be allocated per top\-level (network\-connected) locale.
If during execution the amount of allocated memory exceeds this
limit on any locale, halt the program with a message saying so.
.UNINDENT
.sp
The following two config variables do not enable memory tracking;
they only modify how it is done.
.INDENT 0.0
.TP
.B \fBmemThreshold\fP: \fIuint\fP:
If this is set to a value greater than 0 (zero), only allocation
requests larger than this are tracked and/or reported.
.TP
.B \fBmemLog\fP: \fIc_string\fP:
Memory reporting is written to this file.  By default it is the
\fBstdout\fP associated with the process (not the Chapel channel
with the same name).  Setting this config variable to a file path
causes the reporting to be written to that named file instead.
In multilocale executions each top\-level locale produces output
to its own file, with a dot (\(aq.\(aq) and the locale ID appended to
this path.
.UNINDENT
.INDENT 0.0
.TP
.B enum MemUnits { Bytes, KB, MB, GB }
The amount of memory returned by \fI\%locale.physicalMemory\fP can
be expressed either as individual bytes or as chunks of 2**10,
2**20, or 2**30 bytes.
.UNINDENT
.INDENT 0.0
.TP
.B proc locale.physicalMemory(unit: MemUnits = MemUnits.Bytes, type retType = int(64))
How much physical memory is present on this locale?
.sp
Note that this is a physical quantity and does not take into account
things like virtual memory support which might allow for allocating
a larger amount, or system or user limits which might prevent
allocating so much.
.sp
\fINote:\fP Unlike the other procedures in the \fI\%Memory\fP module, this
one does not require memory tracking to be enabled.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBunit\fP : \fI\%MemUnits\fP \-\- Units in which the returned value is to be expressed.
.IP \(bu 2
\fBretType\fP : \fItype\fP \-\- Type of the returned value.  Defaults to \fIint(64)\fP\&.
.UNINDENT
.TP
.B Returns
Size of physical memory on the locale where the call is made.
.TP
.B Return type
\fIretType\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc memoryUsed()
How much memory is this program currently using on this locale?
.sp
This is the amount of memory known to be currently allocated on the
calling top\-level (network\-connected) locale by the program, through
Chapel mechanisms.  It does not include memory allocated directly
from the system, outside of Chapel mechanisms, such as allocations
made by code written in other languages and linked into the program.
.INDENT 7.0
.TP
.B Returns
Amount of allocated memory, in bytes.
.TP
.B Return type
\fIuint(64)\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc printMemAllocs(thresh = 0)
Print detailed information about allocated memory to \fBmemLog\fP\&.
The report contains a section for each top\-level locale, containing
a table of entries for the allocations made on that locale.  Each
entry shows the source file and line at which the allocation was
requested, the address and size (bytes) of the allocated space, and
a description of the type of information the requesting code said it
was going to store there.
.INDENT 7.0
.TP
.B Arguments
\fBthresh\fP : \fIint\fP \-\- Do not print entries whose size is less than this.
Defaults to 0.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc printMemAllocsByType()
Print summary information about allocated memory to \fBmemLog\fP\&.  The
report contains a section for each top\-level locale, containing a
table of entries, one for each different allocation type for which
at least one allocation exists on that locale.  The entries show the
type (that is, the string the code requesting the allocation used to
describe what it would store there) and the total number of
allocations and bytes allocated for that type.
.UNINDENT
.INDENT 0.0
.TP
.B proc printMemAllocStats()
Print summary memory statistics to \fBmemLog\fP\&.  The report contains
a section for each top\-level locale showing the number of bytes of
memory currently allocated, the maximum number allocated at any
point during execution (the high\-water mark), and the sum of the
sizes of all allocation and deallocation requests.
.UNINDENT
.INDENT 0.0
.TP
.B proc startVerboseMem()
Start on\-the\-fly reporting of memory allocations and deallocations
done on any locale.  Continue reporting until \fI\%stopVerboseMem\fP
is called.
.sp
The reporting output consists of a single line describing each
memory allocation or deallocation, written to \fBmemLog\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc stopVerboseMem()
Stop on\-the\-fly reporting of memory allocations and deallocations
done on any locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc startVerboseMemHere()
Start on\-the\-fly reporting of memory allocations and deallocations
done on this locale.  Continue reporting until
\fI\%stopVerboseMemHere\fP is called.
.sp
The reporting output consists of a single line describing each
memory allocation or deallocation, written to \fBmemLog\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc stopVerboseMemHere()
Stop on\-the\-fly reporting of memory allocations and deallocations
done on this locale.
.UNINDENT
.SS Path
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Path;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A file utilities library, specifically related to path operations
.sp
The Path module focuses on manipulation of the path to a file or directory.
Also provided are constant values representing common idioms that may vary
across operating systems (though rarely in the modern era), such as general
references to a parent directory or the current directory.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This module is currently under development and will expand significantly
in upcoming releases.  Stay tuned!
.UNINDENT
.UNINDENT
.sp
Operations which occur on the files or directories referred to by these paths
may be found in \fBFileSystem\fP (for operations \fIon\fP the file) or \fBIO\fP
(for operations \fIwithin\fP the file).
.INDENT 0.0
.TP
.B proc basename(name: string): string
Returns the basename of the file name provided.  For instance, in the
name \fI/foo/bar/baz\fP, this function would return \fIbaz\fP, while \fI/foo/bar/\fP
would yield the empty string.  Note that this is different from the Unix
basename function.
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- a string file name.  Note that this string does not have to be
a valid file name, as the file itself will not be affected.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const curDir = "."
Represents generally the current directory
.UNINDENT
.INDENT 0.0
.TP
.B proc dirname(name: string): string
Returns the parent directory of the file name provided.  For instance,
in the name \fI/foo/bar/baz\fP, this function would return \fI/foo/bar\fP, as
would a call with \fI/foo/bar/\fP as the argument.
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- a string file name.  Note that this string does not have to be
a valid file name, as the file itself will not be affected.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const parentDir = ".."
Represents generally the parent directory
.UNINDENT
.INDENT 0.0
.TP
.B const pathSep = "/"
Denotes the separator between a directory and its child.
.UNINDENT
.INDENT 0.0
.TP
.B proc realPath(name: string): string
Given a path \fIname\fP, attempts to determine the canonical path referenced.
This resolves and removes any \fI\%curDir\fP and \fI\%parentDir\fP uses
present, as well as any symbolic links.  Returns the result
.sp
Will halt with an error message if one is detected.
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- A path to resolve.  If the path does not refer to a valid file
or directory, an error will occur.
.TP
.B Returns
A canonical version of the argument.
.TP
.B Return type
\fIstring\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.realPath(): string
Determines the canonical path referenced by the \fBfile\fP record
performing this operation.  This resolves and removes any \fI\%curDir\fP and
\fI\%parentDir\fP uses present, as well as any symbolic links.  Returns the
result
.sp
Will halt with an error message if one is detected.
.INDENT 7.0
.TP
.B Returns
A canonical path to the file referenced by this \fBfile\fP
record.  If the \fBfile\fP record is not valid, an error will
occur
.TP
.B Return type
\fIstring\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc splitPath(name: string): (string, string)
Split name into a tuple that is equivalent to (\fI\%dirname\fP,
\fI\%basename\fP).  The second part of the tuple will never contain a slash.
Examples:
.sp
\fIsplitPath("foo/bar")\fP will yield \fI("foo", "bar")\fP
.sp
\fIsplitPath("bar")\fP will yield \fI("", "bar")\fP
.sp
\fIsplitPath("foo/")\fP will yield \fI("foo", "")\fP
.sp
\fIsplitPath("")\fP will yield \fI("", "")\fP
.sp
\fIsplitPath("/")\fP will yield \fI("/", "")\fP
.sp
With the exception of a path of the empty string or just "/", the original
path can be recreated from this function\(aqs returned parts by joining them
with the path separator character:
.sp
\fIdirname\fP + "/" + \fIbasename\fP
.INDENT 7.0
.TP
.B Arguments
\fBname\fP : \fIstring\fP \-\- path to be split
.UNINDENT
.UNINDENT
.SS Random
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Random;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBSubmodules\fP
.SS NPBRandom
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Random.NPBRandom;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
NAS Parallel Benchmark RNG
.sp
The pseudorandom number generator (PRNG) implemented by
this module uses the algorithm from the NAS Parallel Benchmarks
(NPB, available at: \fI\%http://www.nas.nasa.gov/publications/npb.html\fP),
which can be used to generate random values of type \fIreal(64)\fP,
\fIimag(64)\fP, and \fIcomplex(128)\fP\&.
.sp
Paraphrasing the comments from the NPB reference implementation:
.INDENT 0.0
.INDENT 3.5
This generator returns uniform pseudorandom real values in the
range (0, 1) by using the linear congruential generator
.INDENT 0.0
.INDENT 3.5
\fIx_{k+1} = a x_k  (mod 2**46)\fP
.UNINDENT
.UNINDENT
.sp
where 0 < x_k < 2**46 and 0 < a < 2**46.  This scheme
generates 2**44 numbers before repeating.  The generated values
are normalized to be between 0 and 1, i.e., 2**(\-46) * x_k.
.sp
This generator should produce the same results on any computer
with at least 48 mantissa bits for \fIreal(64)\fP data.
.UNINDENT
.UNINDENT
.sp
To generate \fIcomplex\fP elements, consecutive pairs of random numbers are
assigned to the real and imaginary components, respectively.
.sp
The values generated by this NPB RNG do not include 0.0 and 1.0.
.sp
We have tested this implementation with TestU01 (available at
\fI\%http://simul.iro.umontreal.ca/testu01/tu01.html\fP ). In our experiments with
TestU01 1.2.3 and the Crush suite (which consists of 144 statistical
tests), this NPB RNG failed 41/144 tests. As a linear congruential
generator, this RNG has known statistical problems that TestU01
was able to detect.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This module is currently restricted to generating \fIreal(64)\fP,
\fIimag(64)\fP, and \fIcomplex(128)\fP complex values.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class NPBRandomStream
Models a stream of pseudorandom numbers.  See the module\-level
notes for \fI\%NPBRandom\fP for details on the PRNG used.
.INDENT 7.0
.TP
.B type eltType = real(64)
Specifies the type of value generated by the NPBRandomStream.
Currently, only \fIreal(64)\fP, \fIimag(64)\fP, and \fIcomplex(128)\fP are
supported.
.UNINDENT
.INDENT 7.0
.TP
.B param parSafe: bool = true
Indicates whether or not the NPBRandomStream needs to be
parallel\-safe by default.  If multiple tasks interact with it in
an uncoordinated fashion, this must be set to \fItrue\fP\&.  If it will
only be called from a single task, or if only one task will call
into it at a time, setting to \fIfalse\fP will reduce overhead related
to ensuring mutual exclusion.
.UNINDENT
.INDENT 7.0
.TP
.B const seed: int(64)
The seed value for the PRNG.  It must be an odd integer in the
interval [1, 2**46).
.UNINDENT
.INDENT 7.0
.TP
.B proc NPBRandomStream(seed: int(64) = SeedGenerator.oddCurrentTime, param parSafe: bool = true, type eltType = real(64))
Constructs a new stream of random numbers using the specified seed
and parallel safety.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The NPB generator requires an odd seed value. Constructing
an NPBRandomStream with an even seed value will cause a call to
halt(). Only the lower 46 bits of the seed will be used.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP : \fIint(64)\fP \-\- The seed to use for the PRNG.  Defaults to
\fIoddCurrentTime\fP from \fBSeedGenerator\fP\&.
.IP \(bu 2
\fBparSafe\fP : \fIbool\fP \-\- The parallel safety setting.  Defaults to \fItrue\fP\&.
.IP \(bu 2
\fBeltType\fP : \fItype\fP \-\- The element type to be generated.  Defaults to \fIreal(64)\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc getNext(): eltType
Returns the next value in the random stream.
.sp
Real numbers generated by the NPB RNG are in (0,1). It is not
possible for this particular RNG to generate 0.0 or 1.0.
.INDENT 7.0
.TP
.B Returns
The next value in the random stream as type \fI\%eltType\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc skipToNth(n: integral)
Advances/rewinds the stream to the \fIn\fP\-th value in the sequence.
.INDENT 7.0
.TP
.B Arguments
\fBn\fP : \fIintegral\fP \-\- The position in the stream to skip to.  Must be > 0.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc getNth(n: integral): eltType
Advance/rewind the stream to the \fIn\fP\-th value and return it
(advancing the stream by one).  This is equivalent to
\fI\%skipToNth()\fP followed by \fI\%getNext()\fP\&.
.INDENT 7.0
.TP
.B Arguments
\fBn\fP : \fIintegral\fP \-\- The position in the stream to skip to.  Must be > 0.
.TP
.B Returns
The \fIn\fP\-th value in the random stream as type \fI\%eltType\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc fillRandom(arr: [] eltType)
Fill the argument array with pseudorandom values.  This method is
identical to the standalone \fBfillRandom\fP procedure,
except that it consumes random values from the
\fI\%NPBRandomStream\fP object on which it\(aqs invoked rather
than creating a new stream for the purpose of the call.
.INDENT 7.0
.TP
.B Arguments
\fBarr\fP : [] \fI\%eltType\fP \-\- The array to be filled
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc iterate(D: domain, type resultType = real)
Returns an iterable expression for generating \fID.numIndices\fP random
numbers. The RNG state will be immediately advanced by \fID.numIndices\fP
before the iterable expression yields any values.
.sp
The returned iterable expression is useful in parallel contexts,
including standalone and zippered iteration. The domain will determine
the parallelization strategy.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBD\fP \-\- a domain
.IP \(bu 2
\fBresultType\fP \-\- the type of number to yield
.UNINDENT
.TP
.B Returns
an iterable expression yielding random \fIresultType\fP values
.UNINDENT
.UNINDENT
.UNINDENT
.SS PCGRandom
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Random.PCGRandom;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Permuted Linear Congruential Random Number Generator
.sp
This module provides PCG random number generation routines.
See \fI\%http://www.pcg\-random.org/\fP
and the paper, \fIPCG: A Family of Simple Fast Space\-Efficient Statistically
Good Algorithms for Random Number Generation\fP by M.E. O\(aqNeill.
.sp
It also includes some Chapel\-specific features, such as generating real,
imag, and complex numbers; and generating numbers in a range in parallel.
These features are not available in the reference implementations of PCG.
.sp
The related module \fBPCGRandomLib\fP provides a lower\-level interface to
many PCG functions.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The interface provided by this module is expected to change.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class RandomStream
Models a stream of pseudorandom numbers generated by the PCG random number
generator.  See \fI\%http://www.pcg\-random.org/\fP and the paper, \fIPCG: A Family
of Simple Fast Space\-Efficient Statistically Good Algorithms for Random
Number Generation\fP by M.E. O\(aqNeill.
.sp
This class builds upon the \fBpcg_setseq_64_xsh_rr_32_rng\fP PCG RNG
which has 64 bits of state and 32 bits of output.
.sp
While the PCG RNG used here is believed to have good statistical
properties, it is not suitable for generating key material for encryption
since the output of this RNG may be predictable.
Additionally, if statistical properties of the random numbers are very
important, another strategy may be required.
.sp
We have good confidence that the random numbers generated by this class
match the C PCG reference implementation and have specifically verified
equal output given the same seed. However, this implementation differs
from the C PCG reference implementation in how it produces random integers
within particular bounds (with \fI\%RandomStream.getNext\fP using \fImin\fP
and \fImax\fP arguments). In addition, this implementation directly supports
the generation of random \fIreal\fP values, unlike the C PCG implementation.
.sp
Smaller numbers, such as \fIuint(8)\fP or \fIuint(16)\fP, are generated from
the high\-order bits of the 32\-bit output.
.sp
To generate larger numbers, several 32\-bit\-output RNGs are ganged
together.  This strategy is recommended by the author of PCG (and
demonstrated in the file \fIpcg32x2\-demo.c\fP\&. Each of these 32\-bit RNGs has a
different sequence constant and so will be independent and uncorrelated.
For example, to generate 128\-bit complex numbers, this RNG will use
4 ganged 32\-bit PCG RNGs with different sequence constants. One impact of
this approach is that this implementation will only generate 2**64
different complex numbers with a given seed (for example).
.sp
This class also supports generating integers within particular bounds.
When that is required, this class uses a strategy different from the PCG
reference implementation in order to work better in a parallel setting. In
particular, when more than 1 random value is required as part of
generating a value in a range, conceptually it uses more ganged\-together
RNGs (as with the 32x2 strategy). Each new value beyond the first that
is computed will be computed with a different ganged\-together RNG.
This strategy is meant to avoid statistical bias. While we have tested
this strategy to our satisfaction, it has not been subject to rigorous
analysis and may have undesirable statistical properties.
.sp
When generating a real, imaginary, or complex number, this implementation
uses the strategy of generating a 64\-bit unsigned integer and then
multiplying it by 2.0**\-64 in order to convert it to a floating point
number. While this does construct a uniform distribution on rounded
floating point values, it leaves out many possible real values (for
example, 2**\-128). We believe that this strategy has reasonable
statistical properties. One side effect of this strategy is that the real
number 1.0 can be generated because of rounding. The real number 0.0 can
be generated because PCG can produce the value 0 as a random integer.
.sp
We have tested this implementation with TestU01 (available at
\fI\%http://simul.iro.umontreal.ca/testu01/tu01.html\fP ).  We measured our
implementation with TestU01 1.2.3 and the Crush suite, which consists of
144 statistical tests. The results were:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
no failures for generating uniform reals
.IP \(bu 2
1 failure for generating 32\-bit values (which is also true for the
reference version of PCG with the same configuration)
.IP \(bu 2
0 failures for generating 64\-bit values (which we provided to TestU01
as 2 different 32\-bit values since it only accepts 32 bits at a time)
.IP \(bu 2
0 failures for generating bounded integers (which we provided to
TestU01 by requesting values in [0..,2**31+2**30+1) until we
had two values < 2**31, removing the top 0 bit, and then combining
the top 16 bits into the value provided to TestU01).
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This class is currently called RandomStream, but at some point
we expect to rename it PCGRandomStream. At that point, RandomStream
will represent the default RNG and will initially refer to
PCGRandomStream.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B type eltType
Specifies the type of value generated by the PCGRandomStream.
All numeric types are supported: \fIint\fP, \fIuint\fP, \fIreal\fP, \fIimag\fP,
\fIcomplex\fP, and \fIbool\fP types of all sizes.
.UNINDENT
.INDENT 7.0
.TP
.B param parSafe: bool = true
Indicates whether or not the PCGRandomStream needs to be
parallel\-safe by default.  If multiple tasks interact with it in
an uncoordinated fashion, this must be set to \fItrue\fP\&.  If it will
only be called from a single task, or if only one task will call
into it at a time, setting to \fIfalse\fP will reduce overhead related
to ensuring mutual exclusion.
.UNINDENT
.INDENT 7.0
.TP
.B const seed: int(64)
The seed value for the PRNG.
.UNINDENT
.INDENT 7.0
.TP
.B proc RandomStream(seed: int(64) = SeedGenerator.currentTime, param parSafe: bool = true, type eltType = real(64))
Constructs a new stream of random numbers using the specified seed
and parallel safety.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP : \fIint(64)\fP \-\- The seed to use for the PRNG.  Defaults to
\fIcurrentTime\fP from \fBRandomSupport.SeedGenerator\fP\&.
Can be any int(64) value.
.IP \(bu 2
\fBparSafe\fP : \fIbool\fP \-\- The parallel safety setting.  Defaults to \fItrue\fP\&.
.IP \(bu 2
\fBeltType\fP : \fItype\fP \-\- The element type to be generated.  Defaults to \fIreal(64)\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc getNext(type resultType = eltType): resultType
Returns the next value in the random stream.
.sp
Generated reals are in [0,1] \- both 0.0 and 1.0 are possible values.
Imaginary numbers are analogously in [0i, 1i]. Complex numbers will
consist of a generated real and imaginary part, so 0.0+0.0i and 1.0+1.0i
are possible.
.sp
Generated integers cover the full value range of the integer.
.INDENT 7.0
.TP
.B Arguments
\fBresultType\fP \-\- the type of the result. Defaults to \fI\%eltType\fP\&.
\fIresultType\fP must be the same or a smaller size number.
.TP
.B Returns
The next value in the random stream as type \fIresultType\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc getNext(min: eltType, max: eltType): eltType
Return the next random value but within a particular range.
Returns a number in [\fImin\fP, \fImax\fP] (inclusive).
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
For integers, this class uses a strategy for generating a value
in a particular range that has not been subject to rigorous
study and may have statistical problems.
.sp
For real numbers, this class generates a random value in [max, min]
by computing a random value in [0,1] and scaling and shifting that
value. Note that not all possible floating point values in
the interval [\fImin\fP, \fImax\fP] can be constructed in this way.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc skipToNth(n: integral)
Advances/rewinds the stream to the \fIn\fP\-th value in the sequence.
The first corresponds to n=1. It is an error to call this
routine with n <= 0.
.INDENT 7.0
.TP
.B Arguments
\fBn\fP : \fIintegral\fP \-\- The position in the stream to skip to.  Must be > 0.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc getNth(n: integral): eltType
Advance/rewind the stream to the \fIn\fP\-th value and return it
(advancing the stream by one).  This is equivalent to
\fI\%skipToNth()\fP followed by \fI\%getNext()\fP\&.
.INDENT 7.0
.TP
.B Arguments
\fBn\fP : \fIintegral\fP \-\- The position in the stream to skip to.  Must be > 0.
.TP
.B Returns
The \fIn\fP\-th value in the random stream as type \fI\%eltType\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc fillRandom(arr: [] eltType)
Fill the argument array with pseudorandom values.  This method is
identical to the standalone \fBfillRandom\fP procedure,
except that it consumes random values from the
\fI\%RandomStream\fP object on which it\(aqs invoked rather
than creating a new stream for the purpose of the call.
.INDENT 7.0
.TP
.B Arguments
\fBarr\fP : [] \fI\%eltType\fP \-\- The array to be filled
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc shuffle(arr: [])
Randomly shuffle a 1\-D non\-strided array.
.UNINDENT
.INDENT 7.0
.TP
.B proc permutation(arr: [] eltType)
Produce a random permutation, storing it in a 1\-D array.
The resulting array will include each value from low..high
exactly once, where low and high refer to the array\(aqs domain.
.UNINDENT
.INDENT 7.0
.TP
.B proc iterate(D: domain, type resultType = eltType)
Returns an iterable expression for generating \fID.numIndices\fP random
numbers. The RNG state will be immediately advanced by \fID.numIndices\fP
before the iterable expression yields any values.
.sp
The returned iterable expression is useful in parallel contexts,
including standalone and zippered iteration. The domain will determine
the parallelization strategy.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBD\fP \-\- a domain
.IP \(bu 2
\fBresultType\fP \-\- the type of number to yield
.UNINDENT
.TP
.B Returns
an iterable expression yielding random \fIresultType\fP values
.UNINDENT
.UNINDENT
.UNINDENT
.SS PCGRandomLib
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Random.PCGRandomLib;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Low\-level PCG RNG implementation.
.sp
This module includes a number of low\-level PCG random functions.
See \fI\%http://www.pcg\-random.org/\fP
and the paper, \fIPCG: A Family of Simple Fast Space\-Efficient Statistically
Good Algorithms for Random Number Generation\fP by M.E. O\(aqNeill.
.sp
This module provides the following low\-level PCG RNGs:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%pcg_setseq_64_xsh_rr_32_rng\fP (the default PCG RNG)
.IP \(bu 2
\fI\%pcg_setseq_64_rxs_m_xs_64_rng\fP
.IP \(bu 2
\fI\%pcg_setseq_32_rxs_m_xs_32_rng\fP
.IP \(bu 2
\fI\%pcg_setseq_16_rxs_m_xs_16_rng\fP
.IP \(bu 2
\fI\%pcg_setseq_8_rxs_m_xs_8_rng\fP
.IP \(bu 2
\fI\%pcg_setseq_N_rxs_m_xs_N_rng\fP which is a generalization of the
above
.UNINDENT
.UNINDENT
.UNINDENT
.sp
These names come from the PCG paper and reference implementations.  The
first integer is the number of state bits, and the last integer is the
number of output bits. The other parts describe the permutation function in
the LCG.
.sp
Conceptually, a PCG RNG consists of three things:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
the algorithm variant (e.g. pcg_setseq_64_xsh_rr_32_rng)
.IP \(bu 2
the current state
.IP \(bu 2
the RNG sequence constant
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Note that the sequence constant must be odd for this generator to
function correctly. The function \fI\%pcg_getvalid_inc\fP is available
to construct an odd number based upon an arbitrary input.
.sp
When using these low\-level interfaces, the sequence constant is not
actually stored inside the RNG. Instead, users of this interface
must pass the same sequence constant used in \fIsrandom\fP to each of
the other calls for that RNG object.
.sp
Besides storing the RNG state in the record, each of these PCG RNGs
include at least the following methods:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fIsrandom\fP to initialize the state from a seed
.IP \(bu 2
\fIrandom\fP to produce the next random value
.IP \(bu 2
\fIadvance\fP to skip ahead some number of steps in RNG generation
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record pcg_setseq_64_xsh_rr_32_rng
Low\-level PCG random number generation interface (64\-bits of state,
32\-bits output).
.sp
This record implements the same RNG as pcg32_random_r does in
PCG\-C\-0.94.
.sp
This RNG has 64\-bits of internal state and outputs 32\-bits at a time.
.sp
This RNG will iterate through all possible 64\-bit values of state.
The sequence constant chooses between 2**63 random sequences that the
RNG is iterating through.
.INDENT 7.0
.TP
.B var state: uint(64)
The RNG state
.UNINDENT
.INDENT 7.0
.TP
.B proc srandom(seed: uint(64), inc: uint(64))
Seed the random number generator.
This function corresponds to pcg32_srandom_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP \-\- The initial internal state.
.IP \(bu 2
\fBinc\fP \-\- The sequence constant.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc random(inc: uint(64)): uint(32)
Get the next 32\-bit random number.
This function corresponds to pcg32_random_r.
.INDENT 7.0
.TP
.B Arguments
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.TP
.B Returns
32 bits generated by the RNG.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc bounded_random(inc: uint(64), bound: uint(32))
Generate a random number in [0,bound).
.sp
This function corresponds to pcg32_boundedrand_r and can
call the random\-number generator more than once.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.IP \(bu 2
\fBbound\fP \-\- The returned value will be < \fIbound\fP\&.
.UNINDENT
.TP
.B Returns
a random number in [0,bound).
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc bounded_random_vary_inc(inc: uint(64), bound: uint(32), seed: uint(64), skip: uint(64), next_inc: uint(64), inc_increment: uint(64))
Generate a random number in [0,bound).
.sp
This function corresponds to pcg32_boundedrand_r, but has one
difference. Because parallel random number generation relies
upon advancing to a known position, this function only advances
the RNG state once per call. Where the pcg32_boundedrand_r would
advance the RNG state multiple times, this function creates
a new RNGs with the same initial seed but different sequence
numbers and uses those when more random numbers are needed.
In this way, this strategy is similar to the strategy
for generating 64\-bit numbers by pairing 32\-bit PCG RNGs.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \fInextint\fP and \fIinc_increment\fP values need to define a sequence of
increments that is different from other increments used. Otherwise,
these streams will not be independent.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This a strategy for generating a value in a particular range that
has not been subject to rigorous study and may have statistical
problems. Additionally, its performance could be improved
in the case that this function is called many times
in a row by caching the temporary RNGs at their current position.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.IP \(bu 2
\fBbound\fP \-\- The returned value will be < \fIbound\fP\&.
.IP \(bu 2
\fBseed\fP \-\- The seed this RNG started with
.IP \(bu 2
\fBskip\fP \-\- How many numbers, before this one, has this RNG generated?
.IP \(bu 2
\fBnextinc\fP \-\- The first increment to pass to pcg_getvalid_inc and that should be unique for this RNG. Defaults to 100.
.IP \(bu 2
\fBinc_increment\fP \-\- Advance nextinc by inc_increment each time a new value is needed.
.UNINDENT
.TP
.B Returns
a random number in [0,bound).
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc advance(inc: uint(64), delta: uint(64))
Advance the RNG. Adjusts the state of the RNG to be the
same as if \fIdelta\fP calls were made to \fIrandom\fP\&.
.sp
This function corresponds to pcg32_advance_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.IP \(bu 2
\fBdelta\fP \-\- The number of steps to jump ahead
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record pcg_setseq_64_rxs_m_xs_64_rng
Low\-level PCG random number generation interface (64\-bits of state,
64\-bits output).
.sp
This record implements the same RNG as pcg64i_random_r does
in PCG\-C\-0.94.
.sp
This RNG has 64\-bits of internal state and outputs 64\-bits at a time.
.sp
This generator produces each 64\-bit value exactly once.
.sp
This generator should be considered insecure since it reveals
its entire internal state with each output.
.INDENT 7.0
.TP
.B var state: uint(64)
The RNG state
.UNINDENT
.INDENT 7.0
.TP
.B proc srandom(seed: uint(64), inc: uint(64))
Seed the random number generator.
This function corresponds to pcg64i_srandom_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP \-\- The initial internal state.
.IP \(bu 2
\fBinc\fP \-\- The sequence constant.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc random(inc: uint(64)): uint(64)
Get the next 64\-bit random number.
This function corresponds to pcg64i_random_r.
.INDENT 7.0
.TP
.B Arguments
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.TP
.B Returns
64 bits generated by the RNG.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc advance(inc: uint(64), delta: uint(64))
Advance the RNG. Adjusts the state of the RNG to be the
same as if \fIdelta\fP calls were made to \fIrandom\fP\&.
.sp
This function corresponds to pcg64i_advance_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.IP \(bu 2
\fBdelta\fP \-\- The number of steps to jump ahead
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record pcg_setseq_32_rxs_m_xs_32_rng
Low\-level PCG random number generation interface (32\-bits of state,
32\-bits output).
.sp
This record implements the same RNG as pcg32i_random_r does
in PCG\-C\-0.94.
.sp
This RNG has 32\-bits of internal state and outputs 32\-bits at a time.
.sp
This generator produces each 32\-bit value exactly once.
.sp
This generator should be considered insecure since it reveals
its entire internal state with each output.
.INDENT 7.0
.TP
.B var state: uint(32)
The RNG state
.UNINDENT
.INDENT 7.0
.TP
.B proc srandom(seed: uint(32), inc: uint(32))
Seed the random number generator.
This function corresponds to pcg32i_srandom_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP \-\- The initial internal state.
.IP \(bu 2
\fBinc\fP \-\- The sequence constant
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc random(inc: uint(32)): uint(32)
Get the next 32\-bit random number.
This function corresponds to pcg32i_random_r.
.INDENT 7.0
.TP
.B Arguments
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.TP
.B Returns
32 bits generated by the RNG.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc advance(inc: uint(32), delta: uint(32))
Advance the RNG. Adjusts the state of the RNG to be the
same as if \fIdelta\fP calls were made to \fIrandom\fP\&.
.sp
This function corresponds to pcg32i_advance_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.IP \(bu 2
\fBdelta\fP \-\- The number of steps to jump ahead
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record pcg_setseq_16_rxs_m_xs_16_rng
Low\-level PCG random number generation interface (16\-bits of state,
16\-bits output).
.sp
This record implements the same RNG as pcg16i_random_r does
in PCG\-C\-0.94.
.sp
This RNG has 16\-bits of internal state and outputs 16\-bits at a time.
.sp
This generator produces each 16\-bit value exactly once.
.sp
This generator should be considered insecure since it reveals
its entire internal state with each output.
.INDENT 7.0
.TP
.B var state: uint(16)
The RNG state
.UNINDENT
.INDENT 7.0
.TP
.B proc srandom(seed: uint(16), inc: uint(16))
Seed the random number generator.
This function corresponds to pcg16i_srandom_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP \-\- The initial internal state.
.IP \(bu 2
\fBinc\fP \-\- The sequence constant
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc random(inc: uint(16)): uint(16)
Get the next 16\-bit random number.
This function corresponds to pcg16i_random_r.
.INDENT 7.0
.TP
.B Arguments
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.TP
.B Returns
16 bits generated by the RNG.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc advance(inc: uint(16), delta: uint(16))
Advance the RNG. Adjusts the state of the RNG to be the
same as if \fIdelta\fP calls were made to \fIrandom\fP\&.
.sp
This function corresponds to pcg16i_advance_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.IP \(bu 2
\fBdelta\fP \-\- The number of steps to jump ahead
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record pcg_setseq_8_rxs_m_xs_8_rng
Low\-level PCG random number generation interface (8\-bits of state,
8\-bits output).
.sp
This record implements the same RNG as pcg8i_random_r does
in PCG\-C\-0.94.
.sp
This RNG has 8\-bits of internal state and outputs 8\-bits at a time.
.sp
This generator produces each 8\-bit value exactly once.
.sp
This generator should be considered insecure since it reveals
its entire internal state with each output.
.INDENT 7.0
.TP
.B var state: uint(8)
The RNG state
.UNINDENT
.INDENT 7.0
.TP
.B proc srandom(seed: uint(8), inc: uint(8))
Seed the random number generator.
This function corresponds to pcg16i_srandom_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP \-\- The initial internal state.
.IP \(bu 2
\fBinc\fP \-\- The sequence constant
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc random(inc: uint(8)): uint(8)
Get the next 16\-bit random number.
This function corresponds to pcg16i_random_r.
.INDENT 7.0
.TP
.B Arguments
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.TP
.B Returns
16 bits generated by the RNG.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc advance(inc: uint(8), delta: uint(8))
Advance the RNG. Adjusts the state of the RNG to be the
same as if \fIdelta\fP calls were made to \fIrandom\fP\&.
.sp
This function corresponds to pcg16i_advance_r.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.IP \(bu 2
\fBdelta\fP \-\- The number of steps to jump ahead
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record pcg_setseq_N_rxs_m_xs_N_rng
Low\-level PCG random number generation interface for N bits of
state, N bits output. This generator can be useful for generating
a permutation since it produces each N\-bit output exactly once
and N is variable.
.sp
This record implements an N\-bit random number generator based upon
\fI\%pcg_setseq_64_rxs_m_xs_64_rng\fP,
\fI\%pcg_setseq_32_rxs_m_xs_32_rng\fP,
\fI\%pcg_setseq_16_rxs_m_xs_16_rng\fP,
\fI\%pcg_setseq_8_rxs_m_xs_8_rng\fP, and a custom generalization of
these generators. This generator always truncates its internal state to N
bits.
.sp
This generator should be considered insecure since it reveals its
entire internal state with each output.  It produces each N\-bit value
exactly once.
.INDENT 7.0
.TP
.B const N
the number of bits in state and in each output random number
.UNINDENT
.INDENT 7.0
.TP
.B var state: uint
The RNG state
.UNINDENT
.INDENT 7.0
.TP
.B proc srandom(seed: uint, inc: uint)
Seed the random number generator.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP \-\- The initial internal state.
.IP \(bu 2
\fBinc\fP \-\- The sequence constant
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc random(inc: uint): uint
Get the next N\-bit random number.
.INDENT 7.0
.TP
.B Arguments
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.TP
.B Returns
N bits generated by the RNG.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc advance(inc: uint, delta: uint)
Advance the RNG. Adjusts the state of the RNG to be the
same as if \fIdelta\fP calls were made to \fIrandom\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinc\fP \-\- The sequence constant (same as passed to \fIsrandom\fP)
.IP \(bu 2
\fBdelta\fP \-\- The number of steps to jump ahead
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc pcg_getvalid_inc(initseq: uint(64)): uint(64)
The \fIinc\fP field in the PCG RNG must be odd.
This function arranges for that to be the case given any input.
.UNINDENT
.SS RandomSupport
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Random.RandomSupport;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Seed generation for pseudorandom number generation
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
For many of the functions in \fBRandom\fP, if no seed is provided by the
user, one is chosen based on the current time in microseconds, allowing
for some degree of variability in seed selection.  The intent of
\fI\%SeedGenerator\fP is to provide a menu of other options for
initializing the random stream seed, but few options are implemented
at present. In particular, it would be useful to allow multiple tasks to
create different seeds at the same time, or to allow different
functions running at the same time to produce different seeds.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record SeedGenerator
Provides methods to help generate seeds when the user doesn\(aqt want
to create one.  It currently supports two type methods. Both start
with the current time.
.INDENT 7.0
.TP
.B proc type currentTime: int(64)
Generate a seed based on the current time in microseconds as
reported by \fBTime.getCurrentTime\fP\&. This seed is not
suitable for the NPB RNG since that requires an odd seed.
.UNINDENT
.INDENT 7.0
.TP
.B proc type oddCurrentTime: int(64)
Generate an odd seed based on the current time in microseconds as
reported by \fBTime.getCurrentTime\fP\&. This seed is suitable
for the NPB RNG.
.UNINDENT
.UNINDENT
.sp
Support for pseudorandom number generation
.sp
This module defines an abstraction for a stream of pseudorandom numbers,
\fI\%RandomStreamInterface\fP\&. Use \fI\%makeRandomStream\fP to
create such an stream. Each stream supports methods to get the next
random number in the stream (\fI\%getNext\fP),
to fast\-forward to a specific value in the stream
(\fI\%skipToNth\fP and
\fI\%getNth\fP), to iterate over random values
possibly in parallel (\fI\%iterate\fP), or to
fill an array with random numbers in parallel
(\fI\%fillRandom\fP).
.sp
The module also provides several standalone convenience functions that can be
used without manually creating a \fI\%RandomStreamInterface\fP object.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%fillRandom\fP fills an array with random numbers in parallel
.IP \(bu 2
\fI\%shuffle\fP randomly re\-arranges the elements of an array
.IP \(bu 2
\fI\%permutation\fP creates a random permutation and stores it in an
array.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
In these and other methods, generated integer values are uniformly
distributed from \fImin(T)\fP to \fImax(T)\fP, where \fIT\fP is the integral type and the
boundaries are included. Generated floating point values are uniformly
distributed in [0.0, 1.0] with the caveat that it currently depends on the
RNG whether the boundary values 0.0 and 1.0 can be produced.
.sp
Use \fI\%makeRandomStream\fP or the constructor for a specific RNG
implementation to get a RandomStream. See the documentation for
each RNG implementation for more information:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBPCGRandom\fP
.IP \(bu 2
\fBNPBRandom\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Right now, \fBNPBRandomStream\fP and
\fBRandomStream\fP are available (where
\fBRandomStream\fP implements the PCG algorithm). In the
future, we expect that \fIPCGRandomStream\fP will be available as another name
for the PCG RNG stream.  At that point, \fIRandomStream\fP will change to a
type alias for the default RNG. The function \fI\%makeRandomStream\fP is
available to avoid compatibility problems from this naming change.
Programs that need to specifically request PCG should do so with
\fI\%makeRandomStream\fP until the name \fIPCGRandomStream\fP is available..
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The RandomStream API (\fI\%RandomStreamInterface\fP) is expected to
change.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B enum RNG { PCG = 1, NPB = 2 }
Select between different supported RNG algorithms.
See \fBPCGRandom\fP and \fBNPBRandom\fP for details on
these algorithms.
.UNINDENT
.INDENT 0.0
.TP
.B param defaultRNG = RNG.PCG
The default RNG. The current default is PCG \- see \fBPCGRandom\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc fillRandom(arr: [], seed: int(64) = SeedGenerator.oddCurrentTime, param algorithm = defaultRNG)
Fill an array of numeric elements with pseudorandom values in parallel using
a new stream implementing \fI\%RandomStreamInterface\fP created
specifically for this call.  The first \fIarr.size\fP values from the stream
will be assigned to the array\(aqs elements in row\-major order. The
parallelization strategy is determined by the array.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
\fBNPBRandom\fP only supports \fIreal(64)\fP, \fIimag(64)\fP, and \fIcomplex(128)\fP
numeric types. \fBPCGRandom\fP supports all primitive numeric types.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBarr\fP : \fI[] T\fP \-\- The array to be filled, where T is a primitive numeric type
.IP \(bu 2
\fBseed\fP : \fIint(64)\fP \-\- The seed to use for the PRNG.  Defaults to
\fIoddCurrentTime\fP from \fBRandomSupport.SeedGenerator\fP\&.
.IP \(bu 2
\fBalgorithm\fP : \fI\%RNG\fP \-\- A param indicating which algorithm to use. Defaults to PCG.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc shuffle(arr: [], seed: int(64) = SeedGenerator.oddCurrentTime, param algorithm = RNG.PCG)
Shuffle the elements of an array into a random order.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBarr\fP \-\- a 1\-D non\-strided array
.IP \(bu 2
\fBseed\fP \-\- the seed to use when shuffling. Defaults to
\fIoddCurrentTime\fP from \fBRandomSupport.SeedGenerator\fP\&.
.IP \(bu 2
\fBalgorithm\fP : \fI\%RNG\fP \-\- A param indicating which algorithm to use. Defaults to PCG.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc permutation(arr: [], seed: int(64) = SeedGenerator.oddCurrentTime, param algorithm = RNG.PCG)
Produce a random permutation, storing it in a 1\-D array.
The resulting array will include each value from low..high
exactly once, where low and high refer to the array\(aqs domain.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBarr\fP \-\- a 1\-D non\-strided array
.IP \(bu 2
\fBseed\fP \-\- the seed to use when creating the permutation. Defaults to
\fIoddCurrentTime\fP from \fBRandomSupport.SeedGenerator\fP\&.
.IP \(bu 2
\fBalgorithm\fP : \fI\%RNG\fP \-\- A param indicating which algorithm to use. Defaults to PCG.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc makeRandomStream(seed: int(64) = SeedGenerator.oddCurrentTime, param parSafe: bool = true, type eltType = real(64), param algorithm = defaultRNG)
Constructs a new stream of random numbers using the specified seed
and parallel safety.  Ensures that the seed value meets the PRNG\(aqs
constraints.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \fBNPBRandom\fP RNG will halt if provided an even seed.
\fBPCGRandom\fP has no restrictions on the provided seed value.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBseed\fP : \fIint(64)\fP \-\- The seed to use for the PRNG.  Defaults to \fIoddCurrentTime\fP from
\fBRandomSupport.SeedGenerator\fP\&.
.IP \(bu 2
\fBparSafe\fP : \fIbool\fP \-\- The parallel safety setting.  Defaults to \fItrue\fP\&.
.IP \(bu 2
\fBeltType\fP : \fItype\fP \-\- The element type to be generated.  Defaults to \fIreal(64)\fP\&.
.IP \(bu 2
\fBalgorithm\fP : \fI\%RNG\fP \-\- A param indicating which algorithm to use. Defaults to PCG.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class RandomStreamInterface
Models a stream of pseudorandom numbers.  This class is defined for
documentation purposes and should not be instantiated. See
\fBPCGRandom\fP and \fBNPBRandom\fP for RNGs that can be
instantiated. To create a random stream, use \fI\%makeRandomStream\fP\&.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This RandomStreamInterface is expected to change.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
At present, different implementations of this interface can vary in
whether or not they can generate 0.0 and/or 1.0.  (e.g. They can be
generated by \fBPCGRandom\fP but not by \fBNPBRandom\fP).
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
We plan to support general serial and parallel iterator methods on
\fI\%RandomStreamInterface\fP; however, providing the full suite of
iterators is not possible with our current parallel iterator framework.
Specifically, if \fI\%RandomStreamInterface\fP is a follower in a
zippered iteration context, there is no way for it to update the total
number of random numbers generated in a safe/sane/coordinated way.  We are
exploring a revised leader\-follower iterator framework that would support
this idiom (and other cursor\-based ones).  With Chapel\(aqs recent support
for standalone parallel iterators, one could define a standalone parallel
iterator for \fI\%RandomStreamInterface\fP, but this effort has not yet
been taken on.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The \fI\%RandomStreamInterface\fP is included here only for documentation
and does not help with compilation in any way.  In the future, we hope to
turn it into an interface.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B type eltType = real(64)
Specifies the type of value generated by the RandomStream.
Not all RandomStream implementations support all types.
.UNINDENT
.INDENT 7.0
.TP
.B param parSafe: bool = true
Indicates whether or not the RandomStream needs to be
parallel\-safe by default.  If multiple tasks interact with it in
an uncoordinated fashion, this must be set to \fItrue\fP\&.  If it will
only be called from a single task, or if only one task will call
into it at a time, setting to \fIfalse\fP will reduce overhead related
to ensuring mutual exclusion.
.UNINDENT
.INDENT 7.0
.TP
.B const seed: int(64)
The seed value for the PRNG.  There may be constraints upon
legal values depending on the specific RNG.
.UNINDENT
.INDENT 7.0
.TP
.B proc getNext(): eltType
Returns the next value in the random stream.
.INDENT 7.0
.TP
.B Returns
The next value in the random stream as type \fI\%eltType\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc skipToNth(n: integral)
Advances/rewinds the stream to the \fIn\fP\-th value in the sequence.
The first value is with n=1.
.INDENT 7.0
.TP
.B Arguments
\fBn\fP : \fIintegral\fP \-\- The position in the stream to skip to.  Must be > 0.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc getNth(n: integral): eltType
Advance/rewind the stream to the \fIn\fP\-th value and return it
(advancing the stream by one).  This is equivalent to
\fI\%skipToNth()\fP followed by \fI\%getNext()\fP\&.
.INDENT 7.0
.TP
.B Arguments
\fBn\fP : \fIintegral\fP \-\- The position in the stream to skip to.  Must be > 0.
.TP
.B Returns
The \fIn\fP\-th value in the random stream as type \fI\%eltType\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc fillRandom(arr: [] eltType)
Fill the argument array with pseudorandom values.  This method is
identical to the standalone \fI\%fillRandom\fP procedure,
except that it consumes random values from the
\fI\%RandomStreamInterface\fP object on which it\(aqs invoked rather
than creating a new stream for the purpose of the call.
.INDENT 7.0
.TP
.B Arguments
\fBarr\fP : [] \fI\%eltType\fP \-\- The array to be filled
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc iterate(D: domain, type resultType = eltType)
Returns an iterable expression for generating \fID.numIndices\fP random
numbers. The RNG state will be immediately advanced by \fID.numIndices\fP
before the iterable expression yields any values.
.sp
The returned iterable expression is useful in parallel contexts,
including standalone and zippered iteration. The domain will determine
the parallelization strategy.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBD\fP \-\- a domain
.IP \(bu 2
\fBresultType\fP \-\- the type of number to yield
.UNINDENT
.TP
.B Returns
an iterable expression yielding random \fIresultType\fP values
.UNINDENT
.UNINDENT
.UNINDENT
.SS Reflection
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Reflection;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Functions for finding out about fields, functions, and methods.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
There are several ways in which this module could be improved upon:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
the methods here might be better as type methods,
so you could use \fIR.numFields()\fP instead of \fInumFields(R)\fP\&.
.IP \(bu 2
\fBgetField\fP does not yet return a mutable value.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc numFields(type t) param: int
Return the number of fields in a class or record as a param.
The count of fields includes types and param fields.
.UNINDENT
.INDENT 0.0
.TP
.B proc getFieldName(type t, param i: int) param: string
Get the name of the ith field in a class or record.
Causes a compilation error if \fIi\fP is not in 1..numFields(t).
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBt\fP \-\- a class or record type
.IP \(bu 2
\fBi\fP \-\- which field to get the name of
.UNINDENT
.TP
.B Returns
the name of the field, as a param string
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getField(const ref x: ?t, param i: int) const ref
Get the ith field in a class or record.
Causes a compilation error if \fIi\fP is not in 1..numFields(t).
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBx\fP \-\- a class or record
.IP \(bu 2
\fBi\fP \-\- which field to get
.UNINDENT
.TP
.B Returns
an rvalue referring to that field.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getField(const ref x: ?t, param s: string) const ref
Get a field in a class or record by name.
Will generate a compilation error if a field with that name
is not found.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBx\fP \-\- a class or record
.IP \(bu 2
\fBs\fP \-\- the name of a field
.UNINDENT
.TP
.B Returns
an rvalue referring to that field.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getFieldRef(ref x: ?t, param i: int) ref
Get a mutable ref to the ith field in a class or record.
Causes a compilation error if \fIi\fP is not in 1..numFields(t)
or if the argument is not mutable.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBx\fP \-\- a class or record
.IP \(bu 2
\fBi\fP \-\- which field to get
.UNINDENT
.TP
.B Returns
an rvalue referring to that field.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getFieldRef(ref x: ?t, param s: string) ref
Get a mutable ref to a field in a class or record by name.
Will generate a compilation error if a field with that name
is not found or if the class or record is not mutable.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBx\fP \-\- a class or record
.IP \(bu 2
\fBs\fP \-\- the name of a field
.UNINDENT
.TP
.B Returns
an rvalue referring to that field.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getFieldIndex(type t, param s: string) param: int
Get a field index in a class or record, or 0 if
the field is not found.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBt\fP \-\- a class or record type
.IP \(bu 2
\fBs\fP \-\- the name of a field
.UNINDENT
.TP
.B Returns
an index \fIi\fP usable in getField, or 0 if the field was not found.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc hasField(type t, param s: string) param: bool
Returns \fItrue\fP if a class or record has a field named \fIs\fP,
or \fIfalse\fP otherwise.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBt\fP \-\- a class or record type
.IP \(bu 2
\fBs\fP \-\- the name of a field
.UNINDENT
.TP
.B Returns
\fItrue\fP if the field is present.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc canResolve(param fname: string) param: bool
Returns true if a function named \fIfname\fP taking in no arguments
could be called in the current scope.
.UNINDENT
.INDENT 0.0
.TP
.B proc canResolve(param fname: string, args ...) param: bool
Returns true if a function named \fIfname\fP taking the arguments in args
could be called in the current scope.
.UNINDENT
.INDENT 0.0
.TP
.B proc canResolveMethod(obj, param fname: string) param: bool
Returns true if a method on \fIobj\fP named \fIfname\fP taking in no arguments
could be called in the current scope.
.UNINDENT
.INDENT 0.0
.TP
.B proc canResolveMethod(obj, param fname: string, args ...) param: bool
Returns true if a method on \fIobj\fP named \fIfname\fP taking the arguments in args
could be called in the current scope.
.UNINDENT
.SS Regexp
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Regexp;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Regular expression support.
.sp
The regular expression support is built on top of the RE2 regular expression
library. As such, the exact regular expression syntax available is the syntax
from RE2, which is available within the RE2 project at
\fI\%https://github.com/google/re2\fP and included here for your convenience.
.SS Enabling Regular Expression Support
.sp
Setting the environment variable CHPL_REGEXP to re2 will enable regular
expression support with the RE2 library:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_REGEXP=re2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then, rebuild Chapel. The RE2 library will be expanded from a release included
in the Chapel distribution.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
if re2 support is not enabled (which is the default), all features
described below will compile successfully, but will result in an internal
error at \fIrun time\fP, saying "No Regexp Support".
.UNINDENT
.UNINDENT
.SS Using Regular Expression Support
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Regexp;
var myRegexp = compile("a+");
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now you can use these methods on regular expressions: \fI\%regexp.search\fP,
\fI\%regexp.match\fP, \fI\%regexp.split\fP, \fI\%regexp.matches\fP\&.
.sp
You can also use the string versions of these methods: \fI\%string.search\fP,
\fI\%string.match\fP, \fI\%string.split\fP, or \fI\%string.matches\fP\&.
.sp
Lastly, you can include regular expressions in the format string for
\fBreadf\fP for searching on QIO channels using the \fB%/<regexp>/\fP
syntax.
.SS Regular Expression Examples
.INDENT 0.0
.TP
.B \fBa+\fP
Match one or more \fBa\fP characters
.TP
.B \fB[[:space:]]*\fP or \fB\es*\fP (which would be \fB"\e\es*"\fP in a string)
Match zero or more spaces
.TP
.B \fB[[:digit:]]+\fP or \fB\ed+\fP (which would be \fB"\e\ed+"\fP in a string)
Match one or more digits
.TP
.B \fB([a\-zA\-Z0\-9]+[[:space:]]+=[[:space:]]+[0\-9]+\fP
Match sequences of the form \fI<letters\-and\-digits> <spaces>\fP \fB=\fP \fI<digits>\fP
.UNINDENT
.SS RE2 regular expression syntax reference
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Single characters:
\&.            any character, possibly including newline (s=true)
[xyz]        character class
[^xyz]       negated character class
\ed           Perl character class (see below)
\eD           negated Perl character class (see below)
[:alpha:]    ASCII character class
[:^alpha:]   negated ASCII character class
\epN          Unicode character class (one\-letter name)
\ep{Greek}    Unicode character class
\ePN          negated Unicode character class (one\-letter name)
\eP{Greek}    negated Unicode character class

Composites:
xy           «x» followed by «y»
x|y          «x» or «y» (prefer «x»)

Repetitions:
x*           zero or more «x», prefer more
x+           one or more «x», prefer more
x?           zero or one «x», prefer one
x{n,m}       «n» or «n»+1 or ... or «m» «x», prefer more
x{n,}        «n» or more «x», prefer more
x{n}         exactly «n» «x»
x*?          zero or more «x», prefer fewer
x+?          one or more «x», prefer fewer
x??          zero or one «x», prefer zero
x{n,m}?      «n» or «n»+1 or ... or «m» «x», prefer fewer
x{n,}?       «n» or more «x», prefer fewer
x{n}?        exactly «n» «x»

Grouping:
(re)         numbered capturing group
(?P<name>re) named & numbered capturing group
(?:re)       non\-capturing group
(?flags)     set flags within current group; non\-capturing
(?flags:re)  set flags during re; non\-capturing

Flags:
i            case\-insensitive (default false)
m            multi\-line mode: «^» and «$» match begin/end line in addition to
               begin/end text (default false)
s            let «.» match «\en» (default false)
U            ungreedy: swap meaning of «x*» and «x*?», «x+» and «x+?», etc.
               (default false)

Flag syntax is:
  «xyz»   (set)
  «\-xyz»  (clear)
  «xy\-z»  (set «xy», clear «z»)

Empty strings:
^            at beginning of text or line («m»=true)
$            at end of text (like «\ez» not «\eZ») or line («m»=true)
\eA           at beginning of text
\eb           at word boundary («\ew» on one side and «\eW», «\eA», or «\ez» on the
               other)
\eB           not a word boundary
\ez           at end of text

Escape sequences:
\ea           bell (== \e007)
\ef           form feed (== \e014)
\et           horizontal tab (== \e011)
\en           newline (== \e012)
\er           carriage return (== \e015)
\ev           vertical tab character (== \e013)
\e*           literal «*», for any punctuation character «*»
\e123         octal character code (up to three digits)
\ex7F         hex character code (exactly two digits)
\ex{10FFFF}   hex character code
\eC           match a single byte even in UTF\-8 mode
\eQ...\eE      literal text «...» even if «...» has punctuation

Character class elements:
x            single character
A\-Z          character range (inclusive)
\ed           Perl character class (see below)
[:foo:]      ASCII character class «foo»
\ep{Foo}      Unicode character class «Foo»
\epF          Unicode character class «F» (one\-letter name)

Named character classes as character class elements:
[\ed]         digits (== \ed)
[^\ed]        not digits (== \eD)
[\eD]         not digits (== \eD)
[^\eD]        not not digits (== \ed)
[[:name:]]   named ASCII class inside character class (== [:name:])
[^[:name:]]  named ASCII class inside negated character class (== [:^name:])
[\ep{Name}]   named Unicode property inside character class (== \ep{Name})
[^\ep{Name}]  named Unicode property inside negated character class (==\eP{Name})

Perl character classes:
\ed           digits (== [0\-9])
\eD           not digits (== [^0\-9])
\es           whitespace (== [\et\en\ef\er ])
\eS           not whitespace (== [^\et\en\ef\er ])
\ew           word characters (== [0\-9A\-Za\-z_])
\eW           not word characters (== [^0\-9A\-Za\-z_])

ASCII character classes::
  Note \-\- you must use these within a [] group! so if you want
          to match any number of spaces, use [[:space:]]* or \es*

[:alnum:]    alphanumeric (== [0\-9A\-Za\-z])
[:alpha:]    alphabetic (== [A\-Za\-z])
[:ascii:]    ASCII (== [\ex00\-\ex7F])
[:blank:]    blank (== [\et ])
[:cntrl:]    control (== [\ex00\-\ex1F\ex7F])
[:digit:]    digits (== [0\-9])
[:graph:]    graphical (== [!\-~] ==
               [A\-Za\-z0\-9!"#$%&\(aq()*+,\e\-./:;<=>?@[\e\e\e]^_\(ga{|}~])
[:lower:]    lower case (== [a\-z])
[:print:]    printable (== [ \-~] == [[:graph:]])
[:punct:]    punctuation (== [!\-/:\-@[\-\(ga{\-~])
[:space:]    whitespace (== [\et\en\ev\ef\er ])
[:upper:]    upper case (== [A\-Z])
[:word:]     word characters (== [0\-9A\-Za\-z_])
[:xdigit:]   hex digit (== [0\-9A\-Fa\-f])

Unicode character class names\-\-general category:
C            other
Cc           control
Cf           format
Co           private use
Cs           surrogate
L            letter
Ll           lowercase letter
Lm           modifier letter
Lo           other letter
Lt           titlecase letter
Lu           uppercase letter
M            mark
Mc           spacing mark
Me           enclosing mark
Mn           non\-spacing mark
N            number
Nd           decimal number
Nl           letter number
No           other number
P            punctuation
Pc           connector punctuation
Pd           dash punctuation
Pe           close punctuation
Pf           final punctuation
Pi           initial punctuation
Po           other punctuation
Ps           open punctuation
S            symbol
Sc           currency symbol
Sk           modifier symbol
Sm           math symbol
So           other symbol
Z            separator
Zl           line separator
Zp           paragraph separator
Zs           space separator

Unicode character class names\-\-scripts (with explanation where non\-trivial):
Arabic
Armenian
Balinese
Bengali
Bopomofo
Braille
Buginese
Buhid
Canadian_Aboriginal
Carian
Cham
Cherokee
Common       characters not specific to one script
Coptic
Cuneiform
Cypriot
Cyrillic
Deseret
Devanagari
Ethiopic
Georgian
Glagolitic
Gothic
Greek
Gujarati
Gurmukhi
Han
Hangul
Hanunoo
Hebrew
Hiragana
Inherited    inherit script from previous character
Kannada
Katakana
Kayah_Li
Kharoshthi
Khmer
Lao
Latin
Lepcha
Limbu
Linear_B
Lycian
Lydian
Malayalam
Mongolian
Myanmar
New_Tai_Lue  aka Simplified Tai Lue
Nko
Ogham
Ol_Chiki
Old_Italic
Old_Persian
Oriya
Osmanya
Phags_Pa
Phoenician
Rejang
Runic
Saurashtra
Shavian
Sinhala
Sundanese
Syloti_Nagri
Syriac
Tagalog
Tagbanwa
Tai_Le
Tamil
Telugu
Thaana
Thai
Tibetan
Tifinagh
Ugaritic
Vai
Yi

Vim character classes:
\ed      digits (== [0\-9])
\eD      not «\ed»
\ew      word character
\eW      not «\ew»
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Regular Expression Types and Methods
.INDENT 0.0
.TP
.B proc compile(pattern: string, out error: syserr, utf8 = true, posix = false, literal = false, nocapture = false, ignorecase = false, multiline = false, dotnl = false, nongreedy = false): regexp
Compile a regular expression. If the optional error argument is provided,
this routine will return an error code if compilation failed. Otherwise, it
will halt with an error message.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP \-\- the string regular expression to compile.
See \fI\%RE2 regular expression syntax reference\fP for details. Note that
you may have to escape backslashes. For example, to
get the regular expression \fB\es\fP, you\(aqd have to write
\fB"\e\es"\fP because the \fB\e\fP is the escape character within
Chapel string literals
.IP \(bu 2
\fBerror\fP \-\- (optional) if provided, return an error code instead of halting
if an error is encountered
.IP \(bu 2
\fButf8\fP \-\- (optional, default true) set to \fItrue\fP to create a regular
expression matching UTF\-8; \fIfalse\fP for binary or ASCII only.
.IP \(bu 2
\fBposix\fP \-\- (optional) set to true to disable non\-POSIX regular expression
syntax
.IP \(bu 2
\fBliteral\fP \-\- (optional) set to true to treat the regular expression as a
literal (ie, create a regexp matching \fBpattern\fP as a string
rather than as a regular expression).
.IP \(bu 2
\fBnocapture\fP \-\- (optional) set to true in order to disable all capture groups
in the regular expression
.IP \(bu 2
\fBignorecase\fP \-\- (optional) set to true in order to ignore case when
matching. Note that this can be set inside the regular
expression with \fB(?i)\fP\&.
.IP \(bu 2
\fBmultiline\fP \-\- (optional) set to true in order to activate multiline mode
(meaning that \fB^\fP and \fB$\fP match the beginning and end
of a line instead of just the beginning and end of the text.
Note that this can be set inside a regular expression
with \fB(?m)\fP\&.
.IP \(bu 2
\fBdotnl\fP \-\- (optional, default false) set to true in order to allow \fB\&.\fP
to match a newline. Note that this can be set inside the
regular expression with \fB(?s)\fP\&.
.IP \(bu 2
\fBnongreedy\fP \-\- (optional) set to true in order to prefer shorter matches for
repetitions; for example, normally x* will match as many x
characters as possible and x*? will match as few as possible.
This flag swaps the two, so that x* will match as few as
possible and x*? will match as many as possible. Note that
this flag can be set inside the regular expression with
\fB(?U)\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record reMatch
The reMatch record records a regular expression search match
or a capture group.
.sp
Regular expression search routines normally return one of these.
Also, this type can be passed as a capture group argument.
Lastly, something of type reMatch can be checked for a match
in a simple if statement, as in:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var m:reMatch = ...;
if m then do_something_if_matched();
if !m then do_something_if_not_matched();
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B var matched: bool
true if the regular expression search matched successfully
.UNINDENT
.INDENT 7.0
.TP
.B var offset: int
0\-based offset into the string or channel that matched; \-1 if matched=false
.UNINDENT
.INDENT 7.0
.TP
.B var length: int
the length of the match. 0 if matched==false
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc string(m: reMatch)
This function extracts the part of a string matching a regular
expression or capture group. This method is intended to be
called on the same string used as the \fItext\fP in a regular
expression search.
.INDENT 7.0
.TP
.B Arguments
\fBm\fP \-\- a match (e.g. returned by \fI\%regexp.search\fP)
.TP
.B Returns
the portion of \fBthis\fP referred to by the match
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record regexp
This class represents a compiled regular expression. Regular expressions
are currently cached on a per\-thread basis and are reference counted.
To create a compiled regular expression, use the compile function.
.sp
A regexp can be cast to a string (resulting in the pattern that
was compiled). A string can be cast to a regexp (resulting in a compiled
regexp).
.INDENT 7.0
.TP
.B proc ok: bool
did this regular expression compile ?
.UNINDENT
.INDENT 7.0
.TP
.B proc error(): string
.INDENT 7.0
.TP
.B Returns
a string describing any error encountered when compiling this
regular expression
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc search(text: ?t, ref captures ...?k): reMatch
Search within the passed text for the first match at any offset to this
regular expression.  This routine will try matching the regular expression
at different offsets until a match is found. If you want to only match at
the beginning of the pattern, you can start your pattern with \fB^\fP and
end it with \fB$\fP or use \fI\%regexp.match\fP\&. If a capture group was not
matched, the corresponding argument will get the default value for its
type.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBtext\fP \-\- a string to search
.IP \(bu 2
\fBcaptures\fP \-\- (optional) what to capture from the regular expression. These
should be strings or types that strings can cast to.
.UNINDENT
.TP
.B Returns
an \fI\%reMatch\fP object representing the offset in text
where a match occurred
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc match(text: ?t, ref captures ...?k): reMatch
Check for a match to this regular expression at the start of the passed
text. If a capture group was not matched, the corresponding argument will
get the default value for its type.
.sp
For example, this function can be used to check to see if a string
fits a particular template:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
if myregexp.match("some string") {
  do_something_if_matched();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBtext\fP \-\- a string to search
.IP \(bu 2
\fBcaptures\fP \-\- what to capture from the regular expression. These should
be strings or types that strings can cast to.
.UNINDENT
.TP
.B Returns
an \fI\%reMatch\fP object representing the offset in text
where a match occurred
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B iter split(text: ?t, maxsplit: int = 0)
Split the text by occurrences of this regular expression.
If capturing parentheses are used in pattern, then the text of all
groups in the pattern are also returned as part of the resulting array.
If \fImaxsplit\fP is nonzero, at most maxsplit splits occur, and the
remaining text is returned as the last element.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBtext\fP \-\- a string to split
.IP \(bu 2
\fBmaxsplit\fP \-\- if nonzero, the maximum number of splits to do
.UNINDENT
.TP
.B Yields
each split portion, one at a time
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B iter matches(text: ?t, param captures = 0, maxmatches: int = max(int))
Enumerates matches in the string as well as capture groups.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBtext\fP \-\- the string to search
.IP \(bu 2
\fBcaptures\fP \-\- (compile\-time constant) the size of the captures to return
.IP \(bu 2
\fBmaxmatches\fP \-\- the maximum number of matches to return
.UNINDENT
.TP
.B Yields
tuples of \fI\%reMatch\fP objects, the 1st is always
the match for the whole pattern and the rest are the capture groups.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc subn(repl: string, text: ?t, global = true): (string, int)
Perform the same operation as \fI\%regexp.sub\fP but return a tuple
containing the new string and the number of substitutions made.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBrepl\fP \-\- replace matches with this string
.IP \(bu 2
\fBtext\fP : \fIstring\fP \-\- the text to search and replace within
.IP \(bu 2
\fBglobal\fP \-\- if true, replace multiple matches
.UNINDENT
.TP
.B Returns
a tuple containing (new string, number of substitutions made)
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B proc sub(repl: string, text: ?t, global = true)
Find matches to this regular expression and create a new string in which
those matches are replaced by repl.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBrepl\fP \-\- replace matches with this string
.IP \(bu 2
\fBtext\fP : \fIstring\fP \-\- the text to search and replace within
.IP \(bu 2
\fBglobal\fP \-\- if true, replace multiple matches
.UNINDENT
.TP
.B Returns
the new string
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc string.search(needle: string, ignorecase = false): reMatch
Compile a regular expression and search the receiving string for matches at
any offset using \fI\%regexp.search\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBneedle\fP \-\- the regular expression to search for
.IP \(bu 2
\fBignorecase\fP \-\- true to ignore case in the regular expression
.UNINDENT
.TP
.B Returns
an \fI\%reMatch\fP object representing the offset in the
receiving string where a match occurred
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc string.search(needle: regexp, ref captures ...?k): reMatch
Search the receiving string for a regular expression already compiled
by calling \fI\%regexp.search\fP\&. Search for matches at any offset.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBneedle\fP \-\- the compiled regular expression to search for
.IP \(bu 2
\fBcaptures\fP \-\- (optional) what to capture from the regular expression. These
should be strings or types that strings can cast to.
.UNINDENT
.TP
.B Returns
an \fI\%reMatch\fP object representing the offset in the
receiving string where a match occurred
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc string.match(pattern: regexp, ref captures ...?k): reMatch
Match the receiving string to a regular expression already compiled
by calling \fI\%regexp.match\fP\&. Only return matches where the match
encompasses the entire string.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP \-\- the compiled regular expression to match
.IP \(bu 2
\fBcaptures\fP \-\- (optional) what to capture from the regular expression. These
should be strings or types that strings can cast to.
.UNINDENT
.TP
.B Returns
an \fI\%reMatch\fP object representing the offset in the
receiving string where a match occurred
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B iter string.split(pattern: regexp, maxsplit: int = 0)
Split the the receiving string by occurrences of the passed regular
expression by calling \fI\%regexp.split\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP \-\- the regular expression to use to split
.IP \(bu 2
\fBmaxsplit\fP \-\- if nonzero, the maximum number of splits to do
.UNINDENT
.TP
.B Yields
each split portion, one at a time
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B iter string.matches(pattern: regexp, param captures = 0, maxmatches: int = max(int))
Enumerates matches in the receiving string as well as capture groups
by calling \fI\%regexp.matches\fP\&.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBpattern\fP \-\- the regular expression to find matches
.IP \(bu 2
\fBcaptures\fP \-\- (compile\-time constant) the size of the captures to return
.IP \(bu 2
\fBmaxmatches\fP \-\- the maximum number of matches to return
.UNINDENT
.TP
.B Yields
tuples of \fI\%reMatch\fP objects, the 1st is always
the match for the whole pattern and the rest are the capture groups.
.UNINDENT
.UNINDENT
.SS Spawn
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Spawn;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
New in version 1.12: Spawn module added.

.sp
Support launching and interacting with other programs.
.sp
Using functions in this module, one can create a subprocess
and possibly capture its output. It is also possible to provide
input to a subprocess.
.sp
To start a subprocess, use \fI\%spawn\fP or \fI\%spawnshell\fP\&.  To wait for
the subprocess process to finish, use the \fI\%subprocess.wait\fP or
\fI\%subprocess.communicate\fP functions.
.sp
This example program produces a listing of files in the current directory with
names that begin with \fBtest.\fP by using the \fBls\fP command. The
output will be mixed in with the Chapel program\(aqs output.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Spawn;

var sub = spawn(["ls", "test.*"]);
sub.wait();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This version also runs the \fBls\fP command but uses a pipe
to read the output from the \fBls\fP command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Spawn;

var sub = spawn(["ls", "test.*"], stdout=PIPE);

var line:string;
while sub.stdout.readline(line) {
  write("ls returned: ", line);
}

sub.wait();
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, this version uses pipes to provide input to
a subprocess in addition to capturing its output. This
version uses the \fBcat\fP command, which just prints
back its input.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Spawn;

var sub = spawn(["cat"], stdin=PIPE, stdout=PIPE);

sub.stdin.writeln("Hello");
sub.stdin.writeln("World");

sub.communicate();

var line:string;
while sub.stdout.readline(line) {
  write("Got line: ", line);
}
sub.close();

// prints out:
// Got line: Hello
// Got line: World
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
As of Chapel v1.12, creating a subprocess that uses \fI\%PIPE\fP to provide
input or capture output does not work when using the ugni communications layer
with hugepages enabled and when using more than one locale. In this
circumstance, the program will halt with an error message. These scenarios do
work when using GASNet instead of the ugni layer.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record subprocess
This record represents a subprocess.
.sp
Note that the subprocess will not be waited for if this record
goes out of scope. Channels opened to communicate with the subprocess
will be closed if the record goes out of scope, however.
.sp
Generally, it is important to call \fI\%subprocess.wait\fP to wait for the
process to complete. If the parent process is using pipes to communicate
with the subprocess, the parent process may call \fI\%subprocess.close\fP
in order to close the pipes and free any buffers. Such calls are
generally not needed since the channels will be closed when the
subprocess record is automatically destroyed.
.INDENT 7.0
.TP
.B param kind: iokind
The kind of a subprocess is used to create the types
for any channels that are necessary.
.UNINDENT
.INDENT 7.0
.TP
.B param locking: bool
As with kind, this value is used to create the types
for any channels that are necessary.
.UNINDENT
.INDENT 7.0
.TP
.B var pid: int(64)
The Process ID number of the spawned process
.UNINDENT
.INDENT 7.0
.TP
.B var running: bool
\fIfalse\fP if this library knows that the subprocess is not running
.UNINDENT
.INDENT 7.0
.TP
.B var exit_status: int
The exit status from the subprocess, or possibly a value >= 256
if there was en error when creating the subprocess
.UNINDENT
.INDENT 7.0
.TP
.B proc stdin
Access the stdin pipe for the subprocess. The parent process
can write to the subprocess through this pipe if the subprocess
was created with stdin=PIPE.
.sp
Causes a fatal error if the subprocess does not have a
stdin pipe open.
.UNINDENT
.INDENT 7.0
.TP
.B proc stdout
Access the stdout pipe for the subprocess. The parent process
can read from the subprocess through this pipe if the subprocess
was created with stdout=PIPE.
.sp
Causes a fatal error if the subprocess does not have a
stdout pipe open.
.UNINDENT
.INDENT 7.0
.TP
.B proc stderr
Access the stderr pipe for the subprocess. The parent process
can read from the subprocess through this pipe if the subprocess
was created with stderr=PIPE.
.sp
Causes a fatal error if the subprocess does not have a
stderr pipe open.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const FORWARD = QIO_FD_FORWARD
FORWARD indicates that the child process should inherit
the stdin/stdout/stderr of this process.
.UNINDENT
.INDENT 0.0
.TP
.B const CLOSE = QIO_FD_CLOSE
CLOSE indicates that the child process should close
its stdin/stdout/stderr.
.UNINDENT
.INDENT 0.0
.TP
.B const PIPE = QIO_FD_PIPE
PIPE indicates that the spawn operation should set up
a pipe between the parent process and the child process
so that the parent process can provide input to the
child process or capture its output.
.UNINDENT
.INDENT 0.0
.TP
.B const STDOUT = QIO_FD_TO_STDOUT
STDOUT indicates that the stderr stream of the child process
should be forwarded to its stdout stream.
.UNINDENT
.INDENT 0.0
.TP
.B proc spawn(args: [] string, env: [] string = Spawn.empty_env, executable = "", stdin: ?t = FORWARD, stdout: ?u = FORWARD, stderr: ?v = FORWARD, param kind = iokind.dynamic, param locking = true)
Create a subprocess.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBargs\fP \-\- An array of strings storing the command to run and
its arguments. The command to run is always the first argument.
The command could be found in the current PATH or
it could be a full path to a file to execute. If the
executable argument is set, the first argument will
be the name of the spawned program provided to that
program and typically shown in process listings.
.IP \(bu 2
\fBenv\fP \-\- An array of strings storing the environment to use when
spawning the child process instead of forwarding the
current environment. By default, this argument
is an empty array. In that case,
the current environment will be forwarded to the child
process.
.IP \(bu 2
\fBexecutable\fP \-\- By default, the executable argument is "". In that
case, the program to launch is the first element
of the args array. If the executable
argument is provided, it will be used instead of
the first element of the args array as the program
to launch. In either case, the program could be
found by searching the PATH.
.IP \(bu 2
\fBstdin\fP \-\- indicates how the standard input of the child process
should be handled. It could be \fI\%FORWARD\fP,
\fI\%CLOSE\fP, \fI\%PIPE\fP, or a file
descriptor number to use. Defaults to \fI\%FORWARD\fP\&.
.IP \(bu 2
\fBstdout\fP \-\- indicates how the standard output of the child process
should be handled. It could be \fI\%FORWARD\fP,
\fI\%CLOSE\fP, \fI\%PIPE\fP, or a file
descriptor number to use. Defaults to \fI\%FORWARD\fP\&.
.IP \(bu 2
\fBstderr\fP \-\- indicates how the standard error of the child process
should be handled. It could be \fI\%FORWARD\fP,
\fI\%CLOSE\fP, \fI\%PIPE\fP, \fI\%STDOUT\fP, or
a file descriptor number to use. Defaults to
\fI\%FORWARD\fP\&.
.IP \(bu 2
\fBkind\fP \-\- What kind of channels should be created when
\fI\%PIPE\fP is used. This argument is used to set
\fI\%subprocess.kind\fP in the resulting subprocess.
Defaults to \fBIO.iokind\fP \fBiokind.dynamic\fP\&.
.IP \(bu 2
\fBlocking\fP \-\- Should channels created use locking?
This argument is used to set \fI\%subprocess.locking\fP
in the resulting subprocess. Defaults to \fItrue\fP\&.
.UNINDENT
.TP
.B Returns
a \fI\%subprocess\fP with kind and locking set according
to the arguments.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc spawnshell(command: string, env: [] string = Spawn.empty_env, stdin: ?t = FORWARD, stdout: ?u = FORWARD, stderr: ?v = FORWARD, executable = "/bin/sh", shellarg = "\-c", param kind = iokind.dynamic, param locking = true)
Create a subprocess by invoking a shell.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Since the command string is passed to a shell, it is
very unsecure to pass user input to this command
without proper quoting.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBcommand\fP \-\- A string representing the command to run.
This string will be interpreted by the shell.
.IP \(bu 2
\fBenv\fP \-\- An array of strings storing the environment to use when
spawning the child process instead of forwarding the
current environment. By default, this argument
is an empty array. In that case,
the current environment will be forwarded to the child
process.
.IP \(bu 2
\fBstdin\fP \-\- indicates how the standard input of the child process
should be handled. It could be \fI\%FORWARD\fP,
\fI\%CLOSE\fP, \fI\%PIPE\fP, or a file
descriptor number to use. Defaults to \fI\%FORWARD\fP\&.
.IP \(bu 2
\fBstdout\fP \-\- indicates how the standard output of the child process
should be handled. It could be \fI\%FORWARD\fP,
\fI\%CLOSE\fP, \fI\%PIPE\fP, or a file
descriptor number to use. Defaults to \fI\%FORWARD\fP\&.
.IP \(bu 2
\fBstderr\fP \-\- indicates how the standard error of the child process
should be handled. It could be \fI\%FORWARD\fP,
\fI\%CLOSE\fP, \fI\%PIPE\fP, \fI\%STDOUT\fP, or
a file descriptor number to use. Defaults to
\fI\%FORWARD\fP\&.
.IP \(bu 2
\fBexecutable\fP \-\- By default, the executable argument is "/bin/sh".
That directs the subprocess to run the /bin/sh shell
in order to interpret the command string.
.IP \(bu 2
\fBshellarg\fP \-\- An argument to pass to the shell before
the command string. By default this is "\-c".
.IP \(bu 2
\fBkind\fP \-\- What kind of channels should be created when
\fI\%PIPE\fP is used. This argument is used to set
\fI\%subprocess.kind\fP in the resulting subprocess.
Defaults to \fBIO.iokind\fP \fBiokind.dynamic\fP\&.
.IP \(bu 2
\fBlocking\fP \-\- Should channels created use locking?
This argument is used to set \fI\%subprocess.locking\fP
in the resulting subprocess. Defaults to \fItrue\fP\&.
.UNINDENT
.TP
.B Returns
a \fI\%subprocess\fP with kind and locking set according
to the arguments.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc subprocess.poll(out error: syserr)
Check to see if a child process has terminated.
If the child process has terminated, after this
call, \fI\%running\fP will be \fIfalse\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc subprocess.wait(out error: syserr, buffer = true)
Wait for a child process to complete. After this function
returns, \fI\%running\fP is \fIfalse\fP and
\fI\%exit_status\fP stores the exit code returned
by the subprocess.
.sp
If \fIbuffer\fP is \fItrue\fP, then this call will handle cases in which
stdin, stdout, or stderr for the child process is \fI\%PIPE\fP by writing
any input to the child process and buffering up the output of the child
process as necessary while waiting for it to terminate. It will do
so in the same manner as \fI\%subprocess.communicate\fP\&.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Do not use \fIbuffer\fP \fIfalse\fP when using \fI\%PIPE\fP for stdin,
stdout, or stderr.  If \fIbuffer\fP is \fIfalse\fP, this function does not
try to send any buffered input to the child process and so could result
in a hang if the child process is waiting for input to finish.
Similarly, this function does not consume the output from the child
process and so the child process could hang while waiting to write data
to its output while the parent process is waiting for it to complete
(and not consuming its output).
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture any error encountered
when waiting for the child process.
.IP \(bu 2
\fBbuffer\fP \-\- if \fItrue\fP, buffer input and output pipes (see above).
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc subprocess.communicate(out error: syserr)
Wait for a child process to complete. After this function
returns, \fI\%running\fP is \fIfalse\fP and
\fI\%exit_status\fP stores the exit code returned
by the subprocess.
.sp
This function handles cases in which stdin, stdout, or stderr
for the child process is \fI\%PIPE\fP by writing any
input to the child process and buffering up the output
of the child process as necessary while waiting for
it to terminate.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture any error encountered
when waiting for the child process.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc subprocess.close(out error: syserr)
Close any open channels and pipes for interacting with a subprocess.  This
function does not wait for the subprocess to complete.  Note that it is
generally not necessary to call this function since these channels will be
closed when the subprocess record goes out of scope.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture any error encountered
when closing the pipes.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc subprocess.send_signal(out error: syserr, signal: int)
Send a signal to a child process.
.sp
Declarations for POSIX.1.2008 signals are provided in this module.
These include \fISIGABRT\fP, \fISIGALRM\fP, \fISIGBUS\fP, \fISIGCHLD\fP, \fISIGCONT\fP,
\fISIGFPE\fP, \fISIGHUP\fP, \fISIGILL\fP, \fISIGINT\fP, \fISIGKILL\fP, \fISIGPIPE\fP, \fISIGQUIT\fP,
\fISIGSEGV\fP, \fISIGSTOP\fP, \fISIGTERM\fP, \fISIGTRAP\fP, \fISIGTSTP\fP, \fISIGTTIN\fP,
\fISIGTTOU\fP, \fISIGURG\fP, \fISIGUSR1\fP, \fISIGUSR2\fP, \fISIGXCPU\fP, \fISIGXFSZ\fP\&.
.sp
See your system\(aqs documentation for their meaning:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
man signal
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Other values for \fIsignal\fP are system\-specific and can be declared in this
way, for example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
extern const SIGPOLL: c_int;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBsignal\fP \-\- the signal to send
.IP \(bu 2
\fBerror\fP \-\- optional argument to capture any error encountered
when sending a signal to the child process
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc subprocess.kill(out error: syserr)
Unconditionally kill the child process.  The associated signal,
\fISIGKILL\fP, cannot be caught by the child process. See
\fI\%subprocess.send_signal\fP\&.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture any error encountered
when killing the child process
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc subprocess.terminate(out error: syserr)
Request termination of the child process.  The associated signal,
\fISIGTERM\fP, may be caught and handled by the child process. See
\fI\%subprocess.send_signal\fP\&.
.INDENT 7.0
.TP
.B Arguments
\fBerror\fP \-\- optional argument to capture any error encountered
when terminating the child process
.UNINDENT
.UNINDENT
.SS Sys
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Sys;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for low\-level programming and system calls.
.sp
This module is for low\-level programming. It provides Chapel versions of
many POSIX/Linux C library or system calls. For documentation on these
system calls and constants, please see your system\(aqs manual pages.
.sp
Each of the functions in this file provides the same functionality
as the corresponding function without the \fBsys_\fP prefix, except that
the \fBsys_\fP versions all return an error code (of type \fBerr_t\fP)
and return any other values (such as how much was read) through an out
argument.
.sp
For example, you can find more about the \fBmmap\fP call with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
man mmap
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The call available here, \fI\%sys_mmap\fP, always returns an error
code (or 0 for no error). The pointer value normally returned by \fBmmap\fP
will be returned through the final \fBret_out\fP argument.
.INDENT 0.0
.TP
.B const O_RDONLY: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_WRONLY: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_RDWR: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_APPEND: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_CREAT: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_DSYNC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_EXCL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_NOCTTY: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_NONBLOCK: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_RSYNC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_SYNC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const O_TRUNC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_UNIX: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_LOCAL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_INET: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_INET6: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_IPX: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_NETLINK: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_X25: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_AX25: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_ATMPVC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_APPLETALK: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const AF_PACKET: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SOCK_STREAM: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SOCK_DGRAM: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SOCK_SEQPACKET: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SOCK_RAW: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SOCK_RDM: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SOCK_NONBLOCK: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SOCK_CLOEXEC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_CONFIRM: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_DONTROUTE: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_DONTWAIT: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_EOR: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_MORE: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_NOSIGNAL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_OOB: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_CMSG_CLOEXEC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_ERRQUEUE: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_PEEK: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_TRUNC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_WAITALL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const MSG_CTRUNC: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SHUT_RD: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SHUT_WR: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const SHUT_RDWR: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPPROTO_IP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPPROTO_IPV6: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPPROTO_TCP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPPROTO_UDP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_ADD_MEMBERSHIP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_DROP_MEMBERSHIP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_HDRINCL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_MTU: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_MTU_DISCOVER: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_MULTICAST_IF: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_MULTICAST_LOOP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_MULTICAST_TTL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_OPTIONS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_PKTINFO: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_RECVERR: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_RECVOPTS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_RECVTOS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_RECVTTL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_RETOPTS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_ROUTER_ALERT: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_TOS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IP_TTL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_ADDRFORM: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_ADD_MEMBERSHIP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_DROP_MEMBERSHIP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_MTU: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_MTU_DISCOVER: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_MULTICAST_HOPS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_MULTICAST_IF: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_MULTICAST_LOOP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_PKTINFO: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_RTHDR: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_AUTHHDR: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_DSTOPTS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_HOPOPTS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_HOPLIMIT: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_RECVERR: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_ROUTER_ALERT: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_UNICAST_HOPS: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const IPV6_V6ONLY: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_CORK: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_DEFER_ACCEPT: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_INFO: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_KEEPCNT: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_KEEPIDLE: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_KEEPINTVL: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_LINGER2: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_MAXSEG: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_NODELAY: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_QUICKACK: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_SYNCNT: c_int
.UNINDENT
.INDENT 0.0
.TP
.B const TCP_WINDOW_CLAMP: c_int
.UNINDENT
.INDENT 0.0
.TP
.B type sys_sockaddr_storage_t
SOCKET STRUCTURE TYPES
.UNINDENT
.INDENT 0.0
.TP
.B record sys_sockaddr_t
.INDENT 7.0
.TP
.B var addr: sys_sockaddr_storage_t
.UNINDENT
.INDENT 7.0
.TP
.B var len: socklen_t
.UNINDENT
.INDENT 7.0
.TP
.B proc sys_sockaddr_t()
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record sys_addrinfo_t
.INDENT 7.0
.TP
.B var ai_flags: c_int
.UNINDENT
.INDENT 7.0
.TP
.B var ai_family: c_int
.UNINDENT
.INDENT 7.0
.TP
.B var ai_socktype: c_int
.UNINDENT
.INDENT 7.0
.TP
.B var ai_protocol: c_int
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B type sys_addrinfo_ptr_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_addrinfo_ptr_t.flags: c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_addrinfo_ptr_t.family: c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_addrinfo_ptr_t.socktype: c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_addrinfo_ptr_t.socktype: c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_addrinfo_ptr_t.addr: sys_sockaddr_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_addrinfo_ptr_t.next: sys_addrinfo_ptr_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_init_sys_sockaddr(ref addr: sys_sockaddr_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_strerror(error: err_t, ref string_out: c_string): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_readlink(path: c_string, ref string_out: c_string): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getenv(name: c_string, ref string_out: c_string): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_open(pathname: c_string, flags: c_int, mode: mode_t, ref fd_out: fd_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_close(fd: fd_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_mmap(addr: c_void_ptr, length: size_t, prot: c_int, flags: c_int, fd: fd_t, offset: off_t, ref ret_out: c_void_ptr): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_munmap(addr: c_void_ptr, length: size_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_fcntl(fd: fd_t, cmd: c_int, ref ret_out: c_int): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_fcntl_long(fd: fd_t, cmd: c_int, arg: c_long, ref ret_out: c_int): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_fcntl_ptr(fd: fd_t, cmd: c_int, arg: c_void_ptr, ref ret_out: c_int): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_dup(oldfd: fd_t, ref fd_out: fd_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_dup2(oldfd: fd_t, newfd: fd_t, ref fd_out: fd_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_pipe(ref read_fd_out: fd_t, ref write_fd_out: fd_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_accept(sockfd: fd_t, ref add_out: sys_sockaddr_t, ref fd_out: fd_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_bind(sockfd: fd_t, ref addr: sys_sockaddr_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_connect(sockfd: fd_t, ref addr: sys_sockaddr_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getaddrinfo(node: c_string, service: c_string, ref hints: sys_addrinfo_t, ref res_out: sys_addrinfo_ptr_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getaddrinfo_flags(res: sys_addrinfo_ptr_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getaddrinfo_family(res: sys_addrinfo_ptr_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getaddrinfo_socktype(res: sys_addrinfo_ptr_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getaddrinfo_protocol(res: sys_addrinfo_ptr_t): c_int
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getaddrinfo_addr(res: sys_addrinfo_ptr_t): sys_sockaddr_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getaddrinfo_next(res: sys_addrinfo_ptr_t): sys_addrinfo_ptr_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_freeaddrinfo(res: sys_addrinfo_ptr_t)
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getnameinfo(ref addr: sys_sockaddr_t, ref host_out: c_string, ref serv_outc_: c_string, flags: c_int): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getpeername(sockfd: fd_t, ref addr: sys_sockaddr_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getsockname(sockfd: fd_t, ref addr: sys_sockaddr_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_getsockopt(sockfd: fd_t, level: c_int, optname: c_int, optval: c_void_ptr, ref optlen: socklen_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_setsockopt(sockfd: fd_t, level: c_int, optname: c_int, optval: c_void_ptr, optlen: socklen_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_listen(sockfd: fd_t, backlog: c_int): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_shutdown(sockfd: fd_t, how: c_int): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_socket(_domain: c_int, _type: c_int, protocol: c_int, ref sockfd_out: fd_t): err_t
.UNINDENT
.INDENT 0.0
.TP
.B proc sys_socketpair(_domain: c_int, _type: c_int, protocol: c_int, ref sockfd_out_a: fd_t, ref sockfd_out_b: fd_t): err_t
.UNINDENT
.SS SysBasic
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use SysBasic;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Types for low\-level programming and C integration.
.sp
This module provides basic types when those types are not
platform\-dependent. The module \fBSysCTypes\fP contains the
platform\-dependent declarations for C compatibility.
.sp
This module also defines the error types \fI\%syserr\fP and \fI\%err_t\fP\&.
.sp
When should one use \fI\%syserr\fP and when should one use \fI\%err_t\fP?
\fI\%err_t\fP is a system error code (a \fIc_int\fP by a nicer name to
indicate its purpose). \fI\%syserr\fP is an enhanced error that might also
include an error message. All user\-facing Chapel library code, or user
Chapel code, should generally use \fI\%syserr\fP\&. When wrapping functions
or declaring them in C, use \fI\%err_t\fP to indicate that a function is
returning an error code.
.sp
A note about the error code documentation in this file. Error descriptions
for system errors are included here for convenience only. Other
documentation, such as system man pages or the POSIX specification are the
authority on system error codes.
.INDENT 0.0
.TP
.B type c_float = real(32)
The type corresponding to a C float
.UNINDENT
.INDENT 0.0
.TP
.B type c_double = real(64)
The type corresponding to a C double
.UNINDENT
.INDENT 0.0
.TP
.B type off_t = int(64)
The type corresponding to C\(aqs off_t
.UNINDENT
.INDENT 0.0
.TP
.B type mode_t = uint(32)
The type corresponding to C\(aqs mode_t
.UNINDENT
.INDENT 0.0
.TP
.B type socklen_t = int(32)
The type corresponding to C\(aqs socklen_t
.UNINDENT
.INDENT 0.0
.TP
.B type syserr
A type storing an error code or an error message.
A syserr can be compared using == or != to an err_t (ie integer error code)
or to another syserr. A syserr can be cast to or from an err_t. It can be
assigned the value of an err_t or another syserr. In addition, syserr can be
checked directly in an if statement like so:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
var err: syserr;
if err then do writeln("err contains an error, ie err != ENOERR");
if !err then do writeln("err does not contain an error; err == ENOERR");
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When a \fI\%syserr\fP formal has default intent, the actual is copied to the
formal upon a function call and the formal cannot be assigned within the
function.
.sp
The default value of the \fI\%syserr\fP type is undefined.
.UNINDENT
.INDENT 0.0
.TP
.B type err_t = c_int
An integral error code. This is really just a \fIc_int\fP, but code is
clearer if you use err_t to indicate arguments, variables, and return types
that are system error codes.
.UNINDENT
.INDENT 0.0
.TP
.B type fd_t = c_int
A system file descriptor. This is really just a \fIc_int\fP, but code is
clearer if you use fd_t to indicate arguments, variables, and return types
that are system file descriptors.
.UNINDENT
.INDENT 0.0
.TP
.B proc ENOERR
The error code indicating that no error occurred (Chapel specific)
.UNINDENT
.INDENT 0.0
.TP
.B proc EEOF
An error code indicating the end of file has been reached (Chapel specific)
.UNINDENT
.INDENT 0.0
.TP
.B proc ESHORT
An error code indicating that the end of file or the end of the
input was reached before the requested amount of data could be read.
(Chapel specific)
.UNINDENT
.INDENT 0.0
.TP
.B proc EFORMAT
An error code indicating a format error; for example when reading a quoted
string literal, this would be returned if we never encountered the
opening quote. (Chapel specific)
.UNINDENT
.INDENT 0.0
.TP
.B const E2BIG: err_t
Argument list too long. The number of bytes used for the argument and
environment list of the new process exceeded the current limit. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EACCES: err_t
Permission denied. An attempt was made to access a file in a way forbidden
by its file access permissions. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EADDRINUSE: err_t
Address already in use. Only one usage of each address is normally permitted.
(POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EADDRNOTAVAIL: err_t
Can\(aqt assign requested address. Normally results from an attempt to create
a socket with an address not on this machine. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EAFNOSUPPORT: err_t
Address family not supported by protocol family. An address incompatible
with the requested protocol was used. For example, you should not
necessarily expect to be able to use NS addresses with ARPA Internet
protocols. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EAGAIN: err_t
Resource temporarily unavailable. This is a temporary condition and later
calls to the same routine may complete normally. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EALREADY: err_t
Operation already in progress. An operation was attempted on a non\-blocking
object that already had an operation in progress. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EBADE: err_t
Invalid exchange (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EBADF: err_t
Bad file descriptor. A file descriptor argument was out of range, referred
to no open file, or a read (write) request was made to a file that was only
open for writing (reading). (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EBADFD: err_t
File descriptor in bad state (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EBADMSG: err_t
Bad message. A corrupted message was detected. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EBADR: err_t
Invalid request descriptor (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EBADRQC: err_t
Invalid request code (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EBADSLT: err_t
Invalid slot (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EBUSY: err_t
Device or resource busy. An attempt to use a system resource which was in
use at the time in a manner which would have conflicted with the request.
(POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ECANCELED: err_t
Operation canceled. The scheduled operation was canceled. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ECHILD: err_t
No child processes. A wait or waitpid system call was executed by a
process that had no existing or unwaited\-for child processes. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ECHRNG: err_t
Channel number out of range (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ECOMM: err_t
Communication error on send (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ECONNABORTED: err_t
Software caused connection abort. A connection abort was caused internal
to your host machine. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ECONNREFUSED: err_t
Connection refused. No connection could be made because the target machine
actively refused it. This usually results from trying to connect to a
service that is inactive on the foreign host. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ECONNRESET: err_t
Connection reset by peer. A connection was forcibly closed by a peer. This
normally results from a loss of the connection on the remote socket due to a
timeout or a reboot. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EDEADLK: err_t
Resource deadlock avoided. An attempt was made to lock a system resource
that would have resulted in a deadlock situation. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EDESTADDRREQ: err_t
Destination address required. A required address was omitted from an
operation on a socket. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EDOM: err_t
Numerical argument out of domain. A numerical input argument was outside
the defined domain of the mathematical function. (POSIX.1, C99)
.UNINDENT
.INDENT 0.0
.TP
.B const EDQUOT: err_t
Disc quota exceeded. A write system call to an ordinary file, the creation
of a directory or symbolic link, or the creation of a directory entry failed
because the user\(aqs quota of disk blocks was exhausted, or the allocation of
an inode for a newly created file failed because the user\(aqs quota of inodes
was exhausted. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EEXIST: err_t
File exists. An existing file was mentioned in an inappropriate context, for
instance, as the new link name in a link system call. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EFAULT: err_t
Bad address. The system detected an invalid address in attempting to
use an argument of a call. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EFBIG: err_t
File too large. The size of a file exceeded the maximum. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EHOSTDOWN: err_t
Host is down. A socket operation failed because the destination host was
down. (linux, FreeBSD)
.UNINDENT
.INDENT 0.0
.TP
.B const EHOSTUNREACH: err_t
No route to host. A socket operation was attempted to an unreachable host.
(POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EIDRM: err_t
Identifier removed. An IPC identifier was removed while the current
process was waiting on it. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EILSEQ: err_t
Illegal byte sequence. While decoding a multibyte character the function
came along an invalid or an incomplete sequence of bytes or the given wide
character is invalid.
.sp
This error might be returned for example in the case of an illegal UTF\-8
byte sequence. (POSIX.1, C99)
.UNINDENT
.INDENT 0.0
.TP
.B const EINPROGRESS: err_t
Operation now in progress. An operation that takes a long time to complete
(such as a connect system call) was attempted on a non\-blocking object.
(POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EINTR: err_t
Interrupted system call. An asynchronous signal (such as SIGINT or SIGQUIT)
was caught by the process during the execution of an interruptible function.
If the signal handler performs a normal return, the interrupted system call
will seem to have returned the error condition. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EINVAL: err_t
Invalid argument. Some invalid argument was supplied. (For example,
specifying an undefined signal to a signal system call or a kill system
call). (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EIO: err_t
Input/output error. Some physical input or output error occurred. This
error will not be reported until a subsequent operation on the same file
descriptor and may be lost (over written) by any subsequent errors. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EISCONN: err_t
Socket is already connected. A connect system call was made on an already
connected socket; or, a sendto or sendmsg system call on a connected socket
specified a destination when already connected. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EISDIR: err_t
Is a directory. An attempt was made to open a directory with write mode
specified. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EISNAM: err_t
Is a named type file (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EKEYEXPIRED: err_t
Key has expired (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EKEYREJECTED: err_t
Key was rejected by service (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EKEYREVOKED: err_t
Key has been revoked (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EL2HLT: err_t
Level 2 halted (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EL2NSYNC: err_t
Level 2 not synchronized (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EL3HLT: err_t
Level 3 halted (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EL3RST: err_t
Level 3 halted (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ELIBACC: err_t
Cannot access a needed shared library (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ELIBBAD: err_t
Accessing a corrupted shared library (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ELIBMAX: err_t
Attempting to link in too many shared libraries (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ELIBSCN: err_t
lib section in a.out corrupted (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ELIBEXEC: err_t
Cannot exec a shared library directly (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ELOOP: err_t
Too many levels of symbolic links. A path name lookup involved more than 32
(MAXSYMLINKS) symbolic links. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EMEDIUMTYPE: err_t
Wrong medium type (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EMFILE: err_t
Too many open files. Maximum number of file descriptors allowable in the
process has been reached and requests for an open cannot be satisfied until
at least one has been closed. The getdtablesize system call will obtain the
current limit. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EMLINK: err_t
Too many links. Maximum allowable hard links to a single file has been
exceeded. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EMSGSIZE: err_t
Message too long. A message sent on a socket was larger than the internal
message buffer or some other network limit. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EMULTIHOP: err_t
Multihop attempted. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENAMETOOLONG: err_t
File name too long. A component of a path name exceeded {NAME_MAX}
characters, or an entire path name exceeded {PATH_MAX} characters. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENETDOWN: err_t
Network is down. A socket operation encountered a dead network. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENETRESET: err_t
Network dropped connection on reset. The host you were connected to crashed
and rebooted. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENETUNREACH: err_t
Network is unreachable. A socket operation was attempted to an unreachable
network. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENFILE: err_t
Too many open files in system. Maximum number of open files allowable on
the system has been reached and requests for an open cannot be satisfied
until at least one has been closed. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOBUFS: err_t
No buffer space available. An operation on a socket or pipe was not
performed because the system lacked sufficient buffer space or because a
queue was full. (POSIX.1 XSI STREAMS option)
.UNINDENT
.INDENT 0.0
.TP
.B const ENODATA: err_t
No  message is available on the STREAM head read queue (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENODEV: err_t
Operation not supported by device. An attempt was made to apply an
inappropriate function to a device, for example, trying to read a write\-only
device such as a printer. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOENT: err_t
No such file or directory. A component of a specified pathname did not
exist, or the pathname was an empty string. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOEXEC: err_t
Exec format error. A request was made to execute a file that, although it
has the appropriate permissions, was not in the format required for an
executable file. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOKEY: err_t
Required key not available (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOLCK: err_t
No locks available. A system\-imposed limit on the number of simultaneous
file locks was reached. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOLINK: err_t
Link has been severed. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOMEDIUM: err_t
No medium found (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOMEM: err_t
Cannot allocate memory. The new process image required more memory than
was allowed by the hardware or by system\-imposed memory management
constraints. A lack of swap space is normally temporary; however, a lack of
core is not. Soft limits may be increased to their corresponding hard
limits. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOMSG: err_t
No message of desired type. An IPC message queue does not contain a message
of the desired type, or a message catalog does not contain the requested
message. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENONET: err_t
Machine is not on the network (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOPKG: err_t
Package not installed  (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOPROTOOPT: err_t
Protocol not available. A bad option or level was specified in a
getsockopt or setsockopt system call. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOSPC: err_t
No space left on device. A write system call to an ordinary file, the
creation of a directory or symbolic link, or the creation of a directory
entry failed because no more disk blocks were available on the file system,
or the allocation of an inode for a newly created file failed because no
more inodes were available on the file system. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOSR: err_t
No STREAM resources (POSIX.1 XSI STREAMS option)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOSTR: err_t
Not a STREAM (POSIX.1 XSI STREAMS option)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOSYS: err_t
Function not implemented. Attempted a system call that is not available on
this system. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOTBLK: err_t
Block device required.
A block device operation was attempted on a non\-block device or file.
(linux, FreeBSD)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOTCONN: err_t
Socket is not connected. An request to send or receive data was disallowed
because the socket was not connected and (when sending on a datagram socket)
no address was supplied. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOTDIR: err_t
Not a directory. A component of the specified pathname existed, but it was
not a directory, when a directory was expected. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOTEMPTY: err_t
Directory not empty. A directory with entries other than \(aq.\(aq and \(aq..\(aq was
supplied to a remove directory or rename call. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOTSOCK: err_t
Socket operation on non\-socket. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOTSUP: err_t
Operation not supported. The attempted operation is not supported for the
type of object referenced. Usually this occurs when a file descriptor
refers to a file or socket that cannot support this operation, for example,
trying to accept a connection on a datagram socket. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOTTY: err_t
Inappropriate ioctl for device. A control function (e.g. ioctl system
call) was attempted for a file or special device for which the operation was
inappropriate. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ENOTUNIQ: err_t
Name not unique on network (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ENXIO: err_t
Device not configured. Input or output on a special file referred to a
device that did not exist, or made a request beyond the limits of the
device. This error may also occur when, for example, a tape drive is
not online or no disk pack is loaded on a drive. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EOPNOTSUPP: err_t
Operation not supported. The attempted operation is not supported for the
type of object referenced. Usually this occurs when a file descriptor refers
to a file or socket that cannot support this operation, for example, trying
to accept a connection on a datagram socket. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EOVERFLOW: err_t
Value too large to be stored in data type. A numerical result of the
function was too large to be stored in the caller provided space. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EPERM: err_t
Operation not permitted. An attempt was made to perform an operation
limited to processes with appropriate privileges or to the owner of a file
or other resources. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EPFNOSUPPORT: err_t
Protocol family not supported. The protocol family has not been configured
into the system or no implementation for it exists. (linux, FreeBSD)
.UNINDENT
.INDENT 0.0
.TP
.B const EPIPE: err_t
Broken pipe. A write on a pipe, socket or FIFO for which there is no
process to read the data. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EPROTO: err_t
Protocol error. A device or socket encountered an unrecoverable
protocol error. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EPROTONOSUPPORT: err_t
Protocol not supported. The protocol has not been configured into the
system or no implementation for it exists. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EPROTOTYPE: err_t
Protocol wrong type for socket. A protocol was specified that does not sup\-
port the semantics of the socket type requested. For example, you cannot
use the ARPA Internet UDP protocol with type SOCK_STREAM. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ERANGE: err_t
Result too large. A numerical result of the function was too large to fit
in the available space (perhaps exceeded precision). (POSIX.1, C99)
.UNINDENT
.INDENT 0.0
.TP
.B const EREMCHG: err_t
Remote address changed (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EREMOTE: err_t
Object is remote (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EREMOTEIO: err_t
Remote I/O error (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ERESTART: err_t
Interrupted system call should be restarted (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EROFS: err_t
Read\-only file system. An attempt was made to modify a file or directory on
a file system that was read\-only at the time. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ESHUTDOWN: err_t
Can\(aqt send after socket shutdown. A request to send data was disallowed
because the socket had already been shut down with a previous shutdown system
call.
.UNINDENT
.INDENT 0.0
.TP
.B const ESPIPE: err_t
Illegal seek. An lseek system call was issued on a socket, pipe or FIFO.
(POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ESOCKTNOSUPPORT: err_t
Socket type not supported. The support for the socket type has not been
configured into the system or no implementation for it exists.
(linux, FreeBSD)
.UNINDENT
.INDENT 0.0
.TP
.B const ESRCH: err_t
No such process. No process could be found corresponding to that specified
by the given process ID. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ESTALE: err_t
Stale NFS file handle. An attempt was made to access an open file (on an
NFS file system) which is now unavailable as referenced by the file
descriptor. This may indicate the file was deleted on the NFS server or
some other catastrophic event occurred. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ESTRPIPE: err_t
Streams pipe error (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const ETIME: err_t
Timer expired (POSIX.1 XSI STREAMS option)
.UNINDENT
.INDENT 0.0
.TP
.B const ETIMEDOUT: err_t
Operation timed out. A connect or send system call failed because the
connected party did not properly respond after a period of time. (The
timeout period is dependent on the communication protocol.) (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const ETXTBSY: err_t
Text file busy. The new process was a pure procedure (shared text) file
which was open for writing by another process, or while the pure procedure
file was being executed an open system call requested write access. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EUCLEAN: err_t
Structure needs cleaning (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EUNATCH: err_t
Protocol driver not attached (linux only)
.UNINDENT
.INDENT 0.0
.TP
.B const EUSERS: err_t
Too many users. The quota system ran out of table entries.
(linux, FreeBSD)
.UNINDENT
.INDENT 0.0
.TP
.B const EWOULDBLOCK: err_t
Operation would block (may be same value as EAGAIN) (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EXDEV: err_t
Cross\-device link. A hard link to a file on another file system was
attempted. (POSIX.1)
.UNINDENT
.INDENT 0.0
.TP
.B const EXFULL: err_t
Exchange full (linux only)
.UNINDENT
.SS SysCTypes
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use SysCTypes;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B type c_int = integral
The type corresponding to the C int type
.UNINDENT
.INDENT 0.0
.TP
.B type c_uint = integral
The type corresponding to the C uint type
.UNINDENT
.INDENT 0.0
.TP
.B type c_long = integral
The type corresponding to the C long type
.UNINDENT
.INDENT 0.0
.TP
.B type c_ulong = integral
The type corresponding to the C unsigned long type
.UNINDENT
.INDENT 0.0
.TP
.B type c_longlong = integral
The type corresponding to the C long long type
.UNINDENT
.INDENT 0.0
.TP
.B type c_ulonglong = integral
The type corresponding to the C unsigned long long type
.UNINDENT
.INDENT 0.0
.TP
.B type c_char = integral
The type corresponding to the C char type
.UNINDENT
.INDENT 0.0
.TP
.B type c_schar = integral
The type corresponding to the C signed char type
.UNINDENT
.INDENT 0.0
.TP
.B type c_uchar = integral
The type corresponding to the C unsigned char type
.UNINDENT
.INDENT 0.0
.TP
.B type c_short = integral
The type corresponding to the C short type
.UNINDENT
.INDENT 0.0
.TP
.B type c_ushort = integral
The type corresponding to the C unsigned short type
.UNINDENT
.INDENT 0.0
.TP
.B type c_intptr = integral
The type corresponding to the C intptr_t type
.UNINDENT
.INDENT 0.0
.TP
.B type c_uintptr = integral
The type corresponding to the C uintptr_t type
.UNINDENT
.INDENT 0.0
.TP
.B type c_ptrdiff = integral
The type corresponding to the C ptrdiff_t type
.UNINDENT
.INDENT 0.0
.TP
.B type ssize_t = integral
The type corresponding to the C ssize_t type
.UNINDENT
.INDENT 0.0
.TP
.B type size_t = integral
The type corresponding to the C size_t type
.UNINDENT
.SS Time
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Time;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This module provides support for querying wall time in the local
timezone and implements a record \fI\%Timer\fP that provides basic
stopwatch behavior.  The stopwatch has the potential for microsecond
resolution and is intended to be useful for performance testing.
.INDENT 0.0
.TP
.B enum TimeUnits { microseconds, milliseconds, seconds, minutes, hours }
Specifies the units to be used when certain functions return a time
.UNINDENT
.INDENT 0.0
.TP
.B enum Day { sunday = 0, monday, tuesday, wednesday, thursday, friday, saturday }
Specifies the day of the week
.UNINDENT
.INDENT 0.0
.TP
.B proc getCurrentTime(unit: TimeUnits = TimeUnits.seconds): real(64)
.INDENT 7.0
.TP
.B Arguments
\fBunit\fP : \fI\%TimeUnits\fP \-\- The units for the returned value
.TP
.B Returns
The elapsed time since midnight, local time, in the units specified
.TP
.B Return type
\fIreal(64)\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc getCurrentDate()
.INDENT 7.0
.TP
.B Returns
(year, month, day) as a tuple of 3 ints
.UNINDENT
.sp
The month is in the range 1 to 12.
The day   is in the range 1 to 31
.UNINDENT
.INDENT 0.0
.TP
.B proc getCurrentDayOfWeek(): Day
.INDENT 7.0
.TP
.B Returns
The current day of the week
.TP
.B Return type
\fI\%Day\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc sleep(t: real, unit: TimeUnits = TimeUnits.seconds): void
Delay a task for a duration in the units specified
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBt\fP : \fIreal\fP \-\- The duration for the time to sleep
.IP \(bu 2
\fBunit\fP : \fI\%TimeUnits\fP \-\- The units for the duration
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record Timer
Implements basic stopwatch behavior with a potential resolution of
microseconds if supported by the runtime platform.
.sp
The \fBTimer\fP can be started, stopped, and cleared.
A \fBTimer\fP is either running or stopped.
.INDENT 7.0
.TP
.B proc clear(): void
Clears the elapsed time. If the timer is running then it is restarted
otherwise it remains in the stopped state.
.UNINDENT
.INDENT 7.0
.TP
.B proc start(): void
Starts the timer. It is an error to start a timer that is already running.
.UNINDENT
.INDENT 7.0
.TP
.B proc stop(): void
Stops the timer. It is an error to stop a timer that is not running.
.UNINDENT
.INDENT 7.0
.TP
.B proc elapsed(unit: TimeUnits = TimeUnits.seconds): real
Returns the cumulative elapsed time, in the units specified, between
all pairs of calls to \fI\%start\fP and \fI\%stop\fP
since the timer was created or the last call to \fI\%clear\fP\&.
If the timer is running, the elapsed time since the last call to
\fI\%start\fP is added to the return value.
.INDENT 7.0
.TP
.B Arguments
\fBunit\fP : \fI\%TimeUnits\fP \-\- The units for the returned value
.TP
.B Returns
The elapsed time in the units specified
.TP
.B Return type
\fIreal(64)\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Types
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Types;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Functions related to predefined types.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
All Chapel programs automatically \fBuse\fP this module by default.
An explicit \fBuse\fP statement is not necessary.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc isType(e) param
Returns \fItrue\fP if the argument is a type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isParam(e) param
Returns \fItrue\fP if the argument is a param.
.UNINDENT
.INDENT 0.0
.TP
.B proc isPrimitiveType(type t) param
Returns \fItrue\fP if the type \fIt\fP is a primitive type,
as defined by the language specification.
.UNINDENT
.INDENT 0.0
.TP
.B proc isNumericType(type t) param
Returns \fItrue\fP if the type \fIt\fP is one the following types, of any width:
\fIint\fP, \fIuint\fP, \fIreal\fP, \fIimag\fP, \fIcomplex\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc isIntegralType(type t) param
Returns \fItrue\fP if the type \fIt\fP is one the following types, of any width:
\fIint\fP, \fIuint\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc isFloatType(type t) param
Returns \fItrue\fP if the type \fIt\fP is one the following types, of any width:
\fIreal\fP, \fIimag\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc isVoidType(type t) param
Returns \fItrue\fP if the type \fIt\fP is the \fIvoid\fP type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isBoolType(type t) param
Returns \fItrue\fP if the type \fIt\fP is a \fIbool\fP type, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isIntType(type t) param
Returns \fItrue\fP if the type \fIt\fP is an \fIint\fP type, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isUintType(type t) param
Returns \fItrue\fP if the type \fIt\fP is a \fIuint\fP type, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isEnumType(type t) param
Returns \fItrue\fP if the type \fIt\fP is an \fIenum\fP type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isComplexType(type t) param
Returns \fItrue\fP if the type \fIt\fP is a \fIcomplex\fP type, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isRealType(type t) param
Returns \fItrue\fP if the type \fIt\fP is a \fIreal\fP type, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isImagType(type t) param
Returns \fItrue\fP if the type \fIt\fP is an \fIimag\fP type, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isStringType(type t) param
Returns \fItrue\fP if the type \fIt\fP is the \fIstring\fP type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isPrimitive(e) param
Returns \fItrue\fP if the argument is a primitive type,
as defined by the language specification, or a value of a primitive type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isNumeric(e) param
Returns \fItrue\fP if the argument is one the following types, of any width:
\fIint\fP, \fIuint\fP, \fIreal\fP, \fIimag\fP, \fIcomplex\fP, or a value of such a type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isIntegral(e) param
Returns \fItrue\fP if the argument is one the following types, of any width:
\fIint\fP, \fIuint\fP, or a value of such a type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isFloat(e) param
Returns \fItrue\fP if the argument is one the following types, of any width:
\fIreal\fP, \fIimag\fP, or a value of such a type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isBool(e) param
Returns \fItrue\fP if the argument is a \fIbool\fP type or value, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isInt(e) param
Returns \fItrue\fP if the argument is an \fIint\fP type or value, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isUint(e) param
Returns \fItrue\fP if the argument is a \fIuint\fP type or value, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isReal(e) param
Returns \fItrue\fP if the argument is a \fIreal\fP type or value, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isImag(e) param
Returns \fItrue\fP if the argument is an \fIimag\fP type or value, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isComplex(e) param
Returns \fItrue\fP if the argument is a \fIcomplex\fP type or value, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isString(e) param
Returns \fItrue\fP if the argument is a string or the \fIstring\fP type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isEnum(e) param
Returns \fItrue\fP if the argument is an \fIenum\fP type or value, of any width.
.UNINDENT
.INDENT 0.0
.TP
.B proc isTuple(e) param
Returns \fItrue\fP if the argument is a tuple type or value.
.UNINDENT
.INDENT 0.0
.TP
.B proc isHomogeneousTuple(e: _tuple) param
Returns \fItrue\fP if the argument is a homogeneous tuple.
The argument must be a tuple or any type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isClass(e) param
Returns \fItrue\fP if the argument is a class type or value.
.UNINDENT
.INDENT 0.0
.TP
.B proc isRecord(e) param
Returns \fItrue\fP if the argument is a record type or value.
.UNINDENT
.INDENT 0.0
.TP
.B proc isUnion(e) param
Returns \fItrue\fP if the argument is a union type or value.
.UNINDENT
.INDENT 0.0
.TP
.B proc isRange(e) param
Returns \fItrue\fP if the argument is a range type or value.
.UNINDENT
.INDENT 0.0
.TP
.B proc isDmap(e) param
Returns \fItrue\fP if the argument is a domain map or a domain map type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isDomain(e) param
Returns \fItrue\fP if the argument is a domain or a domain type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isArray(e) param
Returns \fItrue\fP if the argument is an array or an array type.
.UNINDENT
.INDENT 0.0
.TP
.B proc isSync(e) param
Returns \fItrue\fP if the argument is a \fIsync\fP type or a \fIsync\fP variable.
.UNINDENT
.INDENT 0.0
.TP
.B proc isSingle(e) param
Returns \fItrue\fP if the argument is a \fIsingle\fP type or a \fIsingle\fP variable.
.UNINDENT
.INDENT 0.0
.TP
.B proc isAtomic(e) param
Returns \fItrue\fP if the argument is an \fIatomic\fP type or an \fIatomic\fP variable.
.UNINDENT
.INDENT 0.0
.TP
.B proc isSubtype(type sub, type super) param
Returns \fItrue\fP if the type \fIsub\fP is a subtype of the type \fIsuper\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc isProperSubtype(type sub, type super) param
Returns \fItrue\fP if the type \fIsub\fP is a subtype of the type \fIsuper\fP
and is not \fIsuper\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc numBits(type t) param
Returns the number of bits used to store the values of type \fIt\fP\&.
This is available for all numeric types, fixed\-width \fIbool\fP types,
and \fBenum\fP types.
It is not available for default\-width \fIbool\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc numBytes(type t) param
Returns the number of bytes used to store the values of type \fIt\fP\&.
This is available for all numeric types, fixed\-width \fIbool\fP types,
and \fBenum\fP types.
It is not available for default\-width \fIbool\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc min(type t) param
Returns the minimum value the type \fIt\fP can store.
\fIt\fP can be one of the following types, of any width:
\fIbool\fP, \fIint\fP, \fIuint\fP, \fIreal\fP, \fIimag\fP, \fIcomplex\fP\&.
When \fIt\fP is a \fIbool\fP type, it returns \fIfalse\fP\&.
When \fIt\fP is \fIreal\fP, \fIimag\fP, or \fIcomplex\fP type,
it is a non\-\fBparam\fP function.
.UNINDENT
.INDENT 0.0
.TP
.B proc max(type t) param
Returns the maximum value the type \fIt\fP can store.
\fIt\fP can be one of the following types, of any width:
\fIbool\fP, \fIint\fP, \fIuint\fP, \fIreal\fP, \fIimag\fP, \fIcomplex\fP\&.
When \fIt\fP is a \fIbool\fP type, it returns \fIfalse\fP\&.
When \fIt\fP is a \fIreal\fP, \fIimag\fP, or \fIcomplex\fP type,
it is a non\-\fBparam\fP function.
.UNINDENT
.INDENT 0.0
.TP
.B proc integral.safeCast(type T): T
Returns \fIthis\fP, cast to the type \fIT\fP\&.
Generates a run\-time error if \fIthis\fP cannot be represented by \fIT\fP,
for example \fB(\-1).safeCast(uint)\fP or \fB256.safeCast(uint(8))\fP\&.
.sp
This method performs the minimum number of runtime checks.
For example, when casting from \fIuint(8)\fP to \fIuint(64)\fP,
no checks at all will be done.
.UNINDENT
.SS UtilReplicatedVar
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use UtilReplicatedVar;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for user\-level replicated variables.
.sp
A "replicated" variable is a variable for which there is a copy on each locale.
Referencing a replicated variable
(in a stylized way, see \fI\%below\fP)
accesses its copy on the current locale.
.sp
Features:
.INDENT 0.0
.IP \(bu 2
The variable\(aqs copies are not synchronized automatically among the locales.
.UNINDENT
.sp
Limitations:
.INDENT 0.0
.IP \(bu 2
It is "user\-level", i.e. the user is required to handle the variable
in specific ways to achieve the desired result.
.IP \(bu 2
Tree\-shape communication (like for reductions) is not provided.
.IP \(bu 2
Using a replicated variable of an array type is not straightforward.
Workaround: declare that array itself as replicated, then access it normally,
e.g.:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var replArray: [MyDomain dmapped ReplicatedDist()] real;
.ft P
.fi
.UNINDENT
.UNINDENT
.SS How to use replicated variables
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use UtilReplicatedVar;

// declare a replicated variable of the type \(aqMyType\(aq
var myRepVar: [rcDomain] MyType;

// access its copy on the current locale (read or write) (either option)
\&... myRepVar(1) ...  // must use 1
\&... rcLocal(myRepVar) ...

// "replicate": assign \(aqvalToRep\(aq to copies on all locales
rcReplicate(myRepVar, valToRep);

// "collect": assign from each copy of \(aqmyRepVar\(aq to
// corresponding element of an array \(aqcollected\(aq
var collected: [LocaleSpace] MyType;
rcCollect(myRepVar, collected);

// access directly a remote copy on the locale \(aqremoteLoc\(aq (read or write)
\&... rcRemote(myRepVar, remoteLoc) ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Replicating over a subset of locales
.sp
To replicate a variable over a subset of locales, say \fBmyLocales\fP,
modify the above variable declarations as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
var myRepVar: [rcDomainBase dmapped ReplicatedDist(myLocales,
                 "over which to replicate \(aqmyRepVar\(aq")] MyType;
var collected: [myLocales.domain] MyType;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBmyLocales\fP must be "consistent", as defined for ReplicatedDist.
That is, for each \fBix\fP in \fBmyLocales.domain\fP,
\fBmyLocales[ix]\fP must equal \fBLocales[ix]\fP\&.
.sp
Tip: if the domain of the desired array of locales cannot be described
as a rectangular domain (which could be strided, multi\-dimensional,
and/or sparse), make that array\(aqs domain associative over int.
.SS Declarations
.INDENT 0.0
.TP
.B const rcDomainBase = {rcDomainIx..rcDomainIx}
Use this domain when replicating over a subset of locales,
as shown \fI\%above\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B const rcDomain = AppendExpr.Call09chpl__distributedrcDomainBase
Use this domain to declare a user\-level replicated variable,
as shown \fI\%above\fP .
.UNINDENT
.INDENT 0.0
.TP
.B proc rcReplicate(replicatedVar: [?D] ?MYTYPE, valToReplicate: MYTYPE): void
Assign a value \fIvalToReplicate\fP to copies of the replicated variable
\fIreplicatedVar\fP on all locales.
.UNINDENT
.INDENT 0.0
.TP
.B proc rcCollect(replicatedVar: [?D] ?MYTYPE, collected: [?CD] MYTYPE): void
Copy the value of the replicated variable \fIreplicatedVar\fP on each locale
into the element of the array \fIcollected\fP that corresponds to that locale.
.UNINDENT
.INDENT 0.0
.TP
.B proc rcLocal(replicatedVar: [?D] ?MYTYPE) ref: MYTYPE
Access the copy of \fIreplicatedVar\fP on the current locale.
.sp
This is equivalent to \fBreplicatedVar[1]\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B proc rcRemote(replicatedVar: [?D] ?MYTYPE, remoteLoc: locale) ref: MYTYPE
Access the copy of \fIreplicatedVar\fP on the locale \fIremoteLoc\fP\&.
.UNINDENT
.SS Index
.INDENT 0.0
.IP \(bu 2
Chapel Online Documentation Index
.UNINDENT
.SH PACKAGE MODULES
.sp
Package modules are libraries that currently live outside of the
Chapel Standard Library, either because they are not considered to be
fundamental enough or because they are not yet mature enough for
inclusion there.
.SS Curl
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use Curl;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Simple support for many network protocols with libcurl
.sp
This module provides support for libcurl, enabling Chapel programs
to work with many network protocols.
.sp
The \fI\%curl homepage\fP describes libcurl thus:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
libcurl is a free and easy\-to\-use client\-side URL transfer library, supporting
DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3,
POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP.  libcurl supports
SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload,
proxies, cookies, user+password authentication (Basic, Digest, NTLM,
Negotiate, Kerberos), file transfer resume, http proxy tunneling and more!
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Dependencies
.sp
The Curl functionality in Chapel is dependent on libcurl. For information on
how to install libcurl, see the
\fI\%curl installation instructions\fP
.sp
The environment variables CHPL_AUXIO_INCLUDE and CHPL_AUXIO_LIBS must be set to
point to the include and lib directories for libcurl respectively. More
information on these variables can be found in auxIO.rst
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If libcurl is installed system\-wide you should not need to set these
variables.
.UNINDENT
.UNINDENT
.SS Enabling Curl Support
.sp
Once you have ensured that libcurl is installed, and have the two variables
above defined, set the environment variable CHPL_AUX_FILESYS to \(aqcurl\(aq to enable
Curl support:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_AUX_FILESYS=curl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then, rebuild Chapel by executing \(aqmake\(aq from $CHPL_HOME:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If Curl support is not enabled (which is the default), all features
described below will compile successfully but will result in an error at
runtime, saying: "No Curl Support".
.UNINDENT
.UNINDENT
.sp
For information on how to enable and use Curl while also using other auxiliary
IO extensions, as well as how to setup the CHPL_AUXIO_INCLUDE and
CHPL_AUXIO_LIBS environment variables see doc/technotes/auxIO.rst in a
Chapel release.
.SS Using Curl Support in Chapel
.INDENT 0.0
.TP
.B Chapel support for libcurl exposes two interfaces:
.INDENT 7.0
.IP 1. 3
A standard file I/O interface
.IP 2. 3
Bindings to libcurl\(aqs curl_easy_setopt and curl_easy_perform
.UNINDENT
.TP
.B Interface 1:
Since we do not support multiple readers on the same Curl handle, it is
recommended that Chapel programs use \fBopenreader\fP and
\fBopenwriter\fP in order to open up channels on a URL. Examples of how
\fBopenreader\fP and \fBopenwriter\fP work can be found below.
You may also open up a curl handle on a URL via \fBopen\fP
\fI(url=..., mode=...)\fP, and then open up channels, or use the second interface
described below to set options on that handle before opening up a channel on
the handle. Note that in this last case, Chapel programs must not open
multiple channels for the same file backed by a curl handle.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The URL is the last parameter to \fBopen\fP\&. Therefore when you are
opening a URL if you are not using all of the parameters for
\fBopen()\fP or \fBopenreader\fP/\fBopenwriter\fP, you
MUST specify all arguments by name, e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
open(url="https://example.com", iomode.r);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will result in a compile time error. You would, instead, need to use:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
open(url="https://example.com", mode=iomode.r).
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B Interface 2:
Many times when we are connecting to a URL (FTP, IMAP, SMTP, HTTP) we have to
give extra information to the Curl handle. This is done via the setopt()
interface.  Documentation on the various options, as well as the functions
that are referenced below can be found \fI\%here\fP
.INDENT 7.0
.TP
.B Types:
.INDENT 7.0
.IP \(bu 2
\fI\%slist\fP
.UNINDENT
.TP
.B Methods:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fI\%slist.append\fP
.IP \(bu 2
\fI\%slist.free\fP
.IP \(bu 2
\fI\%file.setopt\fP
.IP \(bu 2
\fI\%file.perform\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Calling \fBclose\fP on the file will disconnect the underlying
Curl handle.
.UNINDENT
.UNINDENT
.sp
Here are some simple code snippets demonstrating these two interfaces:
.SS Example 1
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// This example uses the first interface

var writer = openwriter("out.txt");
// Open a URL and get a reader on a section of the site
var reader = openreader(url="https://example.com");

var str:string;

// While we can read a line from example.com, write it to \(aqout.txt\(aq
while(reader.readline(str)) do
  writer.write(str);
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example 2
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// This example uses the first interface
var str:string;
var reader = openreader(url="https://example.com");
reader.readstring(str);
reader.close();

// Write out to a URL via Curl
var writer = openwriter("https://127.0.0.1:1080");
writer.write(str);
writer.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example 3
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Open a file on our local file system
var f = openwriter("out.txt");
// Now get a curl handle
var c = openreader(url="https://example.com");
var str:string;

// Read from example.com and write it out to out.txt
c.readstring(str);
f.write(str);

// Disconnect and free the curl handle and channel, and close the local file and
// channel
c.close();
f.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example 4
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// This example uses the second interface

// Open a file with a curl handle as the internal file
var c = open(url="https://example.com", mode=iomode.r);
// do a standard perform operation on the underlying curl handle
c.perform(); // This will print to stdout
// disconnect and free the curl handle
c.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example 5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// This example uses the second interface + the first interface

var c = open(url="https://example.com", mode=iomode.r);
var str:string;
// Set verbose output from curl
c.setopt(curlopt_verbose, true);

// now read into the string
var reader = c.reader();
reader.readstring(str);
writeln(str);
reader.close();
c.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example 6
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Connect to an IMAP site, and fetch mail from the inbox
config const username = "user";
config const password = "xxxx";
config const imapSite = "your_imap_site_here";

var handle = open(url=imapSite+"/INBOX/;UID=1", mode=iomode.r);
var reader = handle.reader();
var str:string;

handle.setopt((curlopt_username, username),
              (curlopt_password, password));

//Calling this would give the same output
// handle.perform();

reader.readstring(str);
write(str);

reader.close();
handle.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Example 7
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// This example shows a more complex example of how the two interfaces can work
// together: We use the second (setopt) interface to set the various options we
// need on a given curl handle, and then open a writer on that handle to write
// out via curl.

config const url      = "smtp goes here";

config const from     = "<some\-email>";
config const to       = "<some\-email>";
config const cc       = "<some\-email>";

config const username = "username";
config const password = "password";

config const subject  = "Testing Curl in Chapel (SMTP)";
config const message  = "Hello! This is a message sent via Chapel!";


var handle = open(url=url, mode=iomode.cw);

var recipients:slist;
recipients.append(to);
recipients.append(cc);

var arr = "To: " + to + "\er\en" +
          "From: " + from + "\er\en" +
          "Cc: " + cc + "\er\en" +
          "Subject: " + subject + "\er\en" + "\er\en" + message;


handle.setopt((curlopt_username       , username),
              (curlopt_password       , password),
              (curlopt_mail_from      , from),
              (curlopt_use_ssl        , 3),
              (curlopt_ssl_verifypeer , false),
              (curlopt_ssl_verifyhost , false),
              (curlopt_mail_rcpt      , recipients.list),
              (curlopt_verbose        , true));

// Create a writer on the curl handle.
var writer = handle.writer();

// Now write out to Curl to send the email
writer.write(arr);

// recipients.free(); // BAD: This will free the data while it is in use!
writer.close();
// Note here how we free the slist AFTER we close the writer. This way we can
// ensure that we do not free data that is currently in use by curl.
recipients.free();
handle.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Curl Support Types and Functions
.INDENT 0.0
.TP
.B proc file.setopt(opt: c_int, arg): bool
This function is the equivalent to the
\fI\%curl_easy_setopt\fP
function in libcurl. It sets information on the curl file handle
that can change libcurl\(aqs behavior.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBopt\fP \-\- the curl option to set. This file makes available lower
case versions of these curl options (e.g. use curlopt_url
instead of CURLOPT_URL in your Chapel program)
.IP \(bu 2
\fBarg\fP : \fIint\fP, \fIstring\fP, \fIbool\fP, or \fIslist\fP \-\- the value to set the curl option specified by opt.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.setopt(args ...?k)
Set curl options on a curl file. It is equivalent to the
curl_setopt_array you might find in PHP.
.sp
For example, you might do:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
curlfile.setopt((curlopt_username, username),
                (curlopt_password, password));
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments
\fBargs\fP \-\- any number of tuples of the form (curl_option, value). For each
curl_option, this function will setopt it to its value.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc file.perform(): bool
Perform any blocking file transfer operations on the curl file.
This function calls
\fI\%curl_easy_perform\fP\&.
.sp
Corresponds to
\fI\%curl_easy_perform\fP
where the file has been opened up by specifying that \fIurl=<some url>\fP\&.
.INDENT 7.0
.TP
.B Returns
true on success. This version halts if an error is encountered,
but future versions will support returning an error code instead
of halting.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B record slist
.INDENT 7.0
.INDENT 3.5
A linked list of strings used in many curl setopt calls. This type
corresponds to the libcurl type curl_slist.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The slist type is not reference counted. Therefore the user is responsible
for freeing the slist when they are done with it with \fI\%slist.free\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc slist.append(str: string)
Append the string argument to an slist. This function is the same
as calling
\fI\%curl_slist_append\fP
.sp
This function halts if an error is encountered. Future versions will
support returning an error code instead of halting.
.INDENT 7.0
.TP
.B Arguments
\fBstr\fP \-\- a string argument to append
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc slist.free()
Free an slist. Chapel programs must call this function after using an slist.
Programs must ensure that there are no ongoing connections using
this slist when it is freed. For an example, see \fI\%Example 7\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_file: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_WRITEDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_url: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_URL.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_port: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PORT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_proxy: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROXY.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_userpwd: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_USERPWD.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_proxyuserpwd: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROXYUSERPWD.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_range: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_RANGE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_infile: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_READDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_errorbuffer: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_ERRORBUFFER.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_writefunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_WRITEFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_readfunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_READFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_timeout: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_TIMEOUT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_infilesize: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_INFILESIZE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_postfields: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_POSTFIELDS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_referer: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_REFERER.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftpport: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTPPORT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_useragent: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_USERAGENT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_low_speed_limit: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_LOW_SPEED_LIMIT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_low_speed_time: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_LOW_SPEED_TIME.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_resume_from: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_RESUME_FROM.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_cookie: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_COOKIE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_httpheader: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTPHEADER.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_httppost: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTPPOST.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sslcert: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSLCERT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_keypasswd: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_KEYPASSWD.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_crlf: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CRLF.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_quote: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_QUOTE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_writeheader: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HEADERDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_cookiefile: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_COOKIEFILE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sslversion: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSLVERSION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_timecondition: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_TIMECONDITION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_timevalue: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_TIMEVALUE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_customrequest: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CUSTOMREQUEST.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_stderr: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_STDERR.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_postquote: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_POSTQUOTE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_writeinfo: c_int
This curlopt setting is deprecated
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_verbose: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_VERBOSE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_header: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HEADER.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_noprogress: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_NOPROGRESS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_nobody: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_NOBODY.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_failonerror: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FAILONERROR.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_upload: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_UPLOAD.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_post: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_POST.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_dirlistonly: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_DIRLISTONLY.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_append: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_APPEND.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_netrc: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_NETRC.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_followlocation: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FOLLOWLOCATION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_transfertext: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_TRANSFERTEXT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_put: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PUT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_progressfunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROGRESSFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_progressdata: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROGRESSDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_autoreferer: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_AUTOREFERER.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_proxyport: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROXYPORT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_postfieldsize: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_POSTFIELDSIZE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_httpproxytunnel: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTPPROXYTUNNEL.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_interface: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_INTERFACE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_krblevel: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_KRBLEVEL.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssl_verifypeer: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_cainfo: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CAINFO.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_maxredirs: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAXREDIRS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_filetime: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FILETIME.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_telnetoptions: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_TELNETOPTIONS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_maxconnects: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAXCONNECTS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_closepolicy: c_int
This option is deprecated
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_fresh_connect: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FRESH_CONNECT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_forbid_reuse: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FORBID_REUSE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_random_file: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_RANDOM_FILE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_egdsocket: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_EGDSOCKET.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_connecttimeout: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CONNECTTIMEOUT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_headerfunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HEADERFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_httpget: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTPGET.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssl_verifyhost: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_cookiejar: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_COOKIEJAR.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssl_cipher_list: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSL_CIPHER_LIST.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_http_version: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTP_VERSION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_use_epsv: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_USE_EPSV.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sslcerttype: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSLCERTTYPE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sslkey: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSLKEY.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sslkeytype: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSLKEYTYPE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sslengine: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSLENGINE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sslengine_default: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSLENGINE_DEFAULT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_dns_use_global_cache: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_DNS_USE_GLOBAL_CACHE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_dns_cache_timeout: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_DNS_CACHE_TIMEOUT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_prequote: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PREQUOTE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_debugfunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_DEBUGFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_debugdata: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_DEBUGDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_cookiesession: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_COOKIESESSION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_capath: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CAPATH.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_buffersize: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_BUFFERSIZE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_nosignal: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_NOSIGNAL.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_share: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SHARE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_proxytype: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROXYTYPE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_encoding: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_ACCEPT_ENCODING.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_private: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PRIVATE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_http200aliases: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTP200ALIASES.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_unrestricted_auth: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_UNRESTRICTED_AUTH.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_use_eprt: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_USE_EPRT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_httpauth: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTPAUTH.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssl_ctx_function: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSL_CTX_FUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssl_ctx_data: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSL_CTX_DATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_create_missing_dirs: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_CREATE_MISSING_DIRS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_proxyauth: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROXYAUTH.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_response_timeout: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_RESPONSE_TIMEOUT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ipresolve: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_IPRESOLVE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_maxfilesize: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAXFILESIZE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_infilesize_large: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_INFILESIZE_LARGE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_resume_from_large: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_RESUME_FROM_LARGE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_maxfilesize_large: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAXFILESIZE_LARGE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_netrc_file: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_NETRC_FILE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_use_ssl: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_USE_SSL.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_postfieldsize_large: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_POSTFIELDSIZE_LARGE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_tcp_nodelay: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_TCP_NODELAY.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftpsslauth: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTPSSLAUTH.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ioctlfunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_IOCTLFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ioctldata: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_IOCTLDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_account: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_ACCOUNT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_cookielist: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_COOKIELIST.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ignore_content_length: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_IGNORE_CONTENT_LENGTH.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_skip_pasv_ip: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_SKIP_PASV_IP.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_filemethod: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_FILEMETHOD.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_localport: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_LOCALPORT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_localportrange: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_LOCALPORTRANGE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_connect_only: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CONNECT_ONLY.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_conv_from_network_function: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CONV_FROM_NETWORK_FUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_conv_to_network_function: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CONV_TO_NETWORK_FUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_conv_from_utf8_function: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CONV_FROM_UTF8_FUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_max_send_speed_large: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAX_SEND_SPEED_LARGE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_max_recv_speed_large: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAX_RECV_SPEED_LARGE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_alternative_to_user: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_ALTERNATIVE_TO_USER.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sockoptfunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SOCKOPTFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_sockoptdata: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SOCKOPTDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssl_sessionid_cache: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSL_SESSIONID_CACHE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssh_auth_types: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSH_AUTH_TYPES.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssh_public_keyfile: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSH_PUBLIC_KEYFILE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssh_private_keyfile: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSH_PRIVATE_KEYFILE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ftp_ssl_ccc: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_FTP_SSL_CCC.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_timeout_ms: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_TIMEOUT_MS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_connecttimeout_ms: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CONNECTTIMEOUT_MS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_http_transfer_decoding: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTP_TRANSFER_DECODING.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_http_content_decoding: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_HTTP_CONTENT_DECODING.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_new_file_perms: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_NEW_FILE_PERMS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_new_directory_perms: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_NEW_DIRECTORY_PERMS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_postredir: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_POSTREDIR.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_ssh_host_public_key_md5: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_opensocketfunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_OPENSOCKETFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_opensocketdata: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_OPENSOCKETDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_copypostfields: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_COPYPOSTFIELDS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_proxy_transfer_mode: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROXY_TRANSFER_MODE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_seekfunction: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SEEKFUNCTION.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_seekdata: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SEEKDATA.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_crlfile: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CRLFILE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_issuercert: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_ISSUERCERT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_address_scope: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_ADDRESS_SCOPE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_certinfo: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_CERTINFO.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_username: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_USERNAME.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_password: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PASSWORD.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_proxyusername: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROXYUSERNAME.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_proxypassword: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROXYPASSWORD.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_noproxy: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_NOPROXY.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_tftp_blksize: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_TFTP_BLKSIZE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_socks5_gssapi_service: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SOCKS5_GSSAPI_SERVICE.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_socks5_gssapi_nec: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_SOCKS5_GSSAPI_NEC.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_protocols: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_PROTOCOLS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_redir_protocols: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_REDIR_PROTOCOLS.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_lastentry: c_int
All other curlopt values will be less than this one
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_mail_from: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAIL_FROM.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_mail_rcpt: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAIL_RCPT.html\fP
.UNINDENT
.INDENT 0.0
.TP
.B const curlopt_mail_auth: c_int
See \fI\%https://curl.haxx.se/libcurl/c/CURLOPT_MAIL_AUTH.html\fP
.UNINDENT
.SS FFTW
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use FFTW;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Single\-threaded FFT computations via key routines from FFTW (version 3)
.sp
This module defines Chapel wrappers for key single\-threaded 64\-bit
routines from FFTW (\fI\%http://www.fftw.org\fP), version 3.  For
multi\-threaded routines, refer to the \fBFFTW_MT\fP module.  Over
time, the intention is to expand these modules to support additional
routines, prioritizing based on requests and feedback from users.
.sp
To use this module:
.INDENT 0.0
.IP 1. 3
Ensure that FFTW (version 3) is installed on your system and that
the header and library files (e.g., fftw3.h, libfftw3.*) are
either installed in a standard system location or that your C
compiler\(aqs environment variables are set up to find them
(alternatively, the Chapel compiler\(aqs \fB\-I\fP and \fB\-L\fP flags can
be used to specify these locations).
.IP 2. 3
Add \fBuse FFTW;\fP to your Chapel code.
.IP 3. 3
Compile and run your Chapel program as usual.
.UNINDENT
.sp
As in standard FFTW usage, the flow is to:
.INDENT 0.0
.IP 1. 3
Create plan(s) using the \fI\%plan_dft*\fP routines.
.IP 2. 3
Execute the plan(s) one or more times using \fI\%execute\fP\&.
.IP 3. 3
Destroy the plan(s) using \fI\%destroy_plan\fP\&.
.IP 4. 3
Call \fI\%cleanup\fP\&.
.UNINDENT
.sp
Note that each of the Chapel \fI\%plan_dft*\fP routines
support both \fIin\-place\fP and \fIout\-of\-place\fP versions of the
transforms, where the former versions use a single array for both
input and output, and the latter use two distinct arrays.
.sp
In future versions of this module, we anticipate improving the
plan_dft*() interfaces to make better use of Chapel features and
move further away from C\-isms (like the overloaded role of \fIflags\fP
and the use of C\-based types).  Such features are expected to take
advantage of Chapel\(aqs support for default argument values and
keyword\-based argument passing.  We are also thinking about changing
the interface for the in\-place routines to use array slicing rather
than separate arguments for the array and domain.
.INDENT 0.0
.TP
.B config param noFFTWsizeChecks = false
Controls execution\-time array size checks in the FFTW
\fI\%plan_dft\fP routines (set to \fItrue\fP to disable checks).
.UNINDENT
.INDENT 0.0
.TP
.B type fftw_plan
An opaque type used to store and reuse FFTW plans across multiple
routines.
.UNINDENT
.INDENT 0.0
.TP
.B proc plan_dft(input: [?Din] complex(128), output: [?Dout] complex(128), sign: c_int, flags: c_uint): fftw_plan
Creates a plan for an out\-of\-place complex\-to\-complex DFT.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinput\fP : [] \fIcomplex(128)\fP \-\- The input array, which can be of any rank
.IP \(bu 2
\fBoutput\fP : [] \fIcomplex(128)\fP \-\- The output array, whose size and shape must match the input array\(aqs
.IP \(bu 2
\fBsign\fP : \fIc_int\fP \-\- \fI\%FFTW_FORWARD\fP or \fI\%FFTW_BACKWARD\fP
.IP \(bu 2
\fBflags\fP : \fIc_int\fP \-\- the bitwise\-or of any planning\-rigor or algorithm\-restriction flags that should be used in creating the plan (e.g., \fI\%FFTW_MEASURE\fP \fB|\fP \fI\%FFTW_PRESERVE_INPUT\fP)
.UNINDENT
.TP
.B Returns
The \fI\%fftw_plan\fP representing the resulting plan
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc plan_dft(arr: [] complex(128), sign: c_int, flags: c_uint): fftw_plan
Creates a plan for an in\-place complex\-to\-complex DFT.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBarr\fP : [] \fIcomplex(128)\fP \-\- The array to use as the in\-place input/output array.
.IP \(bu 2
\fBsign\fP : \fIc_int\fP \-\- \fI\%FFTW_FORWARD\fP or \fI\%FFTW_BACKWARD\fP
.IP \(bu 2
\fBflags\fP : \fIc_int\fP \-\- the bitwise\-or of any planning\-rigor or algorithm\-restriction flags that should be used in creating the plan (e.g., \fI\%FFTW_MEASURE\fP \fB|\fP \fI\%FFTW_PRESERVE_INPUT\fP)
.UNINDENT
.TP
.B Returns
The \fI\%fftw_plan\fP representing the resulting plan
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc plan_dft_r2c(input: [?Din] real(64), output: [?Dout] complex(128), flags: c_uint): fftw_plan
Create a plan for a real\-to\-complex, out\-of\-place DFT.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinput\fP : [] \fIreal(64)\fP \-\- The input array, which can be of any rank
.IP \(bu 2
\fBoutput\fP : [] \fIcomplex(128)\fP \-\- The output array, whose size and shape must match the input array\(aqs, except for the leading dimension which should be n/2 + 1, where n is the size of the input array\(aqs leading dimension.  See the \fI\%FFTW documentation\fP for more information.
.IP \(bu 2
\fBflags\fP : \fIc_int\fP \-\- the bitwise\-or of any planning\-rigor or algorithm\-restriction flags that should be used in creating the plan (e.g., \fI\%FFTW_MEASURE\fP \fB|\fP \fI\%FFTW_PRESERVE_INPUT\fP)
.UNINDENT
.TP
.B Returns
The \fI\%fftw_plan\fP representing the resulting plan
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc plan_dft_r2c(realDom: domain, arr: [?D] ?t, flags: c_uint): fftw_plan
Create a plan for a real\-to\-complex, in\-place DFT.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBrealDom\fP : \fIdomain\fP \-\- Describes the indices of the \(aqreal\(aq view of the array
.IP \(bu 2
\fBarr\fP : [] \fIT\fP where \fIT\fP is of type \fIreal(64)\fP or \fIcomplex(128)\fP \-\- 
.sp
The array to be used as the in\-place input/output array.  If passing in an array of \fIreal\fP elements, the leading dimension of the array must be padded to store 2(n/2 + 1) elements, where \fIn\fP is the size of the corresponding dimension of \fIrealDom\fP\&.  If passing in an array of \fIcomplex\fP elements, the leading dimension should be (n/2 + 1).  See the \fI\%FFTW documentation\fP for more information.

.IP \(bu 2
\fBflags\fP : \fIc_int\fP \-\- the bitwise\-or of any planning\-rigor or algorithm\-restriction flags that should be used in creating the plan (e.g., \fI\%FFTW_MEASURE\fP \fB|\fP \fI\%FFTW_PRESERVE_INPUT\fP)
.UNINDENT
.TP
.B Returns
The \fI\%fftw_plan\fP representing the resulting plan
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc plan_dft_c2r(input: [?Din] complex(128), output: [?Dout] real(64), flags: c_uint): fftw_plan
Create a plan for a complex\-to\-real, out\-of\-place DFT.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBinput\fP : [] \fIcomplex(128)\fP \-\- 
.sp
The input array, whose size and shape must match the output array\(aqs, except for the leading dimension which should be n/2 + 1, where n is the size of the output array\(aqs leading dimension.  See the \fI\%FFTW documentation\fP for more information.

.IP \(bu 2
\fBoutput\fP : [] \fIreal(64)\fP \-\- The output array
.IP \(bu 2
\fBflags\fP : \fIc_int\fP \-\- the bitwise\-or of any planning\-rigor or algorithm\-restriction flags that should be used in creating the plan (e.g., \fI\%FFTW_MEASURE\fP \fB|\fP \fI\%FFTW_PRESERVE_INPUT\fP)
.UNINDENT
.TP
.B Returns
The \fI\%fftw_plan\fP representing the resulting plan
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc plan_dft_c2r(realDom: domain, arr: [?D] ?t, flags: c_uint): fftw_plan
Create a plan for a complex\-to\-real, in\-place DFT.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBrealDom\fP : \fIdomain\fP \-\- Describes the indices of the \(aqreal\(aq view of the array
.IP \(bu 2
\fBarr\fP : [] \fIT\fP where \fIT\fP is of type \fIreal(64)\fP or \fIcomplex(128)\fP \-\- 
.sp
The array to be used as the in\-place input/output array.  If passing in an array of \fIreal\fP elements, the leading dimension of the array must be padded to store 2(n/2 + 1) elements, where \fIn\fP is the size of the corresponding dimension of \fIrealDom\fP\&.  If passing in an array of \fIcomplex\fP elements, the leading dimension should be (n/2 + 1).  See the \fI\%FFTW documentation\fP for more information.

.IP \(bu 2
\fBflags\fP : \fIc_int\fP \-\- the bitwise\-or of any planning\-rigor or algorithm\-restriction flags that should be used in creating the plan (e.g., \fI\%FFTW_MEASURE\fP \fB|\fP \fI\%FFTW_PRESERVE_INPUT\fP)
.UNINDENT
.TP
.B Returns
The \fI\%fftw_plan\fP representing the resulting plan
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc execute(const plan: fftw_plan)
Execute an FFTW plan.
.INDENT 7.0
.TP
.B Arguments
\fBplan\fP : \fIfftw_plan\fP \-\- The plan to execute, as computed by a \fIplan_dft*()\fP routine.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc destroy_plan(plan: fftw_plan)
Destroy an FFTW plan.
.INDENT 7.0
.TP
.B Arguments
\fBplan\fP : \fIfftw_plan\fP \-\- The plan to destroy
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc cleanup()
Clean up FFTW overall.
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_FORWARD: c_int
Request a forward transform (i.e., use a negative exponent in the transform).
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_BACKWARD: c_int
Request a backward transform (i.e., use a positive exponent in the transform).
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_ESTIMATE: c_uint
Specify that a simple heuristic should be used to pick a plan
quickly.  This will prevent the input/output arrays from being
overwritten during planning.
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_MEASURE: c_uint
Specify that FFTW should try and find an optimized plan by
computing several FFTs and measuring their execution time.
This can consume some time.
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_PATIENT: c_uint
Specify that FFTW should expend a greater effort finding an
optimized plan.
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_EXHAUSTIVE: c_uint
Specify that FFTW should expend an even greater effort finding an
optimized plan.
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_WISDOM_ONLY: c_uint
This is a special planning mode that is useful for querying
whether wisdom is available.  When using it, the plan is only
created when wisdom is available for the given problem; otherwise
a \fInull plan\fP is returned.  This can be combined with other flags
to create a plan if the wisdom available was created in that mode
(e.g., \fI\%FFTW_WISDOM_ONLY\fP \fB|\fP \fI\%FFTW_PATIENT\fP).  For more details on
this flag and the previous four, refer to \fI\%Section 4.3.2\fP of the FFTW manual
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_DESTROY_INPUT: c_uint
Specify that an out\-of\-place transform is permitted to overwrite
its input array with arbitrary data.  This permits more efficient
algorithms to be used in some cases.
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_PRESERVE_INPUT: c_uint
Specify that an out\-of\-place transform cannot change its input
array.
.UNINDENT
.INDENT 0.0
.TP
.B const FFTW_UNALIGNED: c_uint
Specify that the algorithm may not impose any unusual alignment
requirements on the input/output arrays.  This flag should not be
necessary for current Chapel use since the planner will
automatically detect such cases.  For more details on this flag
and the previous two, refer to \fI\%Section 4.3.2\fP of the FFTW manual.
.UNINDENT
.SS FFTW_MT
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use FFTW_MT;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multi\-threaded FFT computations via FFTW (version 3)
.sp
This module defines Chapel wrappers around key FFTW routines
supporting multithreaded execution.  It builds directly on the
\fBFFTW\fP module, inheriting all of its functionality, so refer to
that module for documentation on the transforms themselves.
.sp
To use this module:
.INDENT 0.0
.IP 1. 3
Ensure that FFTW (version 3) is installed on your system with
multi\-threaded support enabled and that the header and library
files (e.g., fftw3.h, libfftw3.*) are either installed in a
standard system location or that your C compiler\(aqs environment
variables are set up to find them (alternatively, the Chapel
compiler\(aqs \fB\-I\fP and \fB\-L\fP flags can be used to specify these
locations).
.IP 2. 3
Add \fBuse FFTW_MT;\fP to your Chapel code.
.IP 3. 3
Compile and run your Chapel program as usual.
.UNINDENT
.sp
The steps to making multi\-threaded FFTW calls are:
.INDENT 0.0
.IP 0. 4
By default, the module will initialize itself to use
\fBhere.maxTaskPar\fP threads per locale when calling
\fBplan_dft*\fP routines.  This
auto\-initialization can be disabled by setting
\fI\%autoInitFFTW_MT\fP to \fIfalse\fP at compile\-time and calling
\fI\%init_FFTW_MT\fP and \fI\%plan_with_nthreads\fP manually.  At
any time during program execution, the number of threads to be
used by FFTW can be changed by calling \fI\%plan_with_nthreads\fP
with a new value.
.IP 1. 4
Create, ...
.IP 2. 4
execute, ...
.IP 3. 4
\&...and destroy plans as in single\-threaded uses of \fBFFTW\fP\&.
.IP 4. 4
Call \fI\%cleanup_threads\fP to release the memory used by FFTW\(aqs
threads and \fBcleanup\fP as in single\-threaded uses of
\fBFFTW\fP\&.
.UNINDENT
.sp
Note that where the main \fBFFTW\fP module is a single\-locale
module, this one is multi\-locale in that, once it is initialized,
any locale can create and execute plans, though those plans will
only be valid on that locale.  Calls to \fI\%init_FFTW_MT\fP,
\fI\%plan_with_nthreads\fP and \fI\%cleanup_threads\fP will take
those actions across all locales.
.INDENT 0.0
.TP
.B config param autoInitFFTW_MT = true
By default, this module will call \fI\%init_FFTW_MT()\fP and
\fI\%plan_with_nthreads()\fP as part of its initialization.
Setting this to \fIfalse\fP at compile\-time will disable this
auto\-initialization, requiring these calls to be made
manually.
.UNINDENT
.INDENT 0.0
.TP
.B proc init_FFTW_MT()
Initialize the \fI\%FFTW_MT\fP module.  This has the effect of
calling the FFTW C routine \fBfftw_init_threads()\fP on all locales,
halting the Chapel program if any of the calls generate an error.
.UNINDENT
.INDENT 0.0
.TP
.B proc plan_with_nthreads(nthreads: int = 0)
Register the number of threads to use for multi\-threaded FFTW
plans on all locales.  If fewer than one thread is requested, each
locale will default to \fBhere.maxTaskPar\fP threads.  Note that
this routine can be called multiple times, overwriting previous
values.
.INDENT 7.0
.TP
.B Arguments
\fBnthreads\fP : \fIint\fP \-\- The number of threads to use.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B proc cleanup_threads()
Clean up the memory used by FFTW threads on all locales.
.UNINDENT
.SS HDFS
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use HDFS;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Support for Hadoop Distributed Filesystem
.sp
This module implements support for the
\fI\%Hadoop\fP
\fI\%Distributed Filesystem\fP (HDFS).
.SS Dependencies
.sp
The HDFS functionality in Chapel is dependent upon both Hadoop and Java being
installed.  Your \fBHADOOP_INSTALL\fP, \fBJAVA_INSTALL\fP and \fBCLASSPATH\fP
environment variables must be set as described below in
\fI\%Setting up Hadoop\fP\&.  Without this it will not compile with HDFS, even if
the flags are set. As well, the HDFS functionality is also dependent upon the
\fBCHPL_AUXIO_INCLUDE\fP and \fBCHPL_AUXIO_LIBS\fP environment variables being set
properly. For more information on how to set these properly, see
doc/technotes/auxIO.rst in a Chapel release.
.SS Enabling HDFS Support
.sp
Once you have ensured that Hadoop and Java are installed and have the
five variables above, defined, set the environment variable
CHPL_AUX_FILESYS to \(aqhdfs\(aq to enable HDFS support:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
export CHPL_AUX_FILESYS=hdfs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Then, rebuild Chapel by executing \(aqmake\(aq from $CHPL_HOME.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
make
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If HDFS support is not enabled (which is the default), all
features described below will compile successfully but will result in
an error at runtime such as: "No HDFS Support".
.UNINDENT
.UNINDENT
.SS Using HDFS Support in Chapel
.sp
There are three ways provided to open HDFS files within Chapel.
.SS Using an HDFS filesystem with open(url="hdfs://...")
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
// Open a file on HDFS connecting to the default HDFS instance
var f = open(mode=iomode.r, url="hdfs://host:port/path");

// Open up a reader and read from the file
var reader = f.reader();

// ...

reader.close();

f.close();
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Explicitly Using Replicated HDFS Connections and Files
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use HDFS;

// Connect to HDFS via the default username (or whichever you want)
//
var hdfs = hdfsChapelConnect("default", 0);

//
// Create a file per locale
//
var gfl  = hdfs.hdfsOpen("/user/johnDoe/isThisAfile.txt", iomode.r);

\&...
//
// On any given locale, you can get the local file for the locale that
// the task is currently running on via:
//
var fl = gfl.getLocal();

// This file can be used as with a traditional file in Chapel, by
// creating reader channels on it.

// When you are done and want to close the files and disconnect from
// HDFS, use:

gfl.hdfsClose();
hdfs.hdfsChapelDisconnect();
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Explicitly Using Local HDFS Connections and Files
.sp
The HDFS module file also supports non\-replicated values across
locales. So if you only wanted to connect to HDFS and open a file on
locale 1 you could do:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
on Locales[1] {
  var hdfs = hdfs_chapel_connect("default", 0);
  var fl = hdfs.hdfs_chapel_open("/user/johnDoe/myFile.txt", iomode.cw);
  ...
  var read = fl.reader();
  ...
  fl.close();
  hdfs.hdfs_chapel_disconnect();
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The only stipulations are that you cannot open a file in both read and
write mode at the same time. (i.e iomode.r and iomode.cw are the only
modes that are supported, due to HDFS limitations).
.SS Setting up Hadoop
.sp
If you have a working installation of Hadoop already, you can skip
this section, other than to set up your CLASSPATH environment
variable.  This section is written so that people without sudo
permission can install and use HDFS.  If you do have sudo permissions,
you can usually install all of these via a package manager.
.sp
The general outline for these instructions is:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
Install and point to the jdk to provide code Chapel needs to
compile against libhdfs (\fI\%Step 1\fP)
.IP 2. 3
Install Hadoop (\fI\%Step 2\fP)
.IP 3. 3
Set up Hadoop on (a) the local host or (b) a cluster of hosts
(\fI\%Step 3\fP)
.IP 4. 3
Start up HDFS (\fI\%Step 4\fP)
.IP 5. 3
Stop HDFS when you\(aqre done (\fI\%Step 5\fP)
.IP 6. 3
Set up Chapel to run in distributed mode (\fI\%Step 6\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.sp
First reflect your directory structure and version numbers (etc) in the
\fI\%sample .bashrc\fP and put it in your .bashrc (or
.bash_profile \-\- your choice) and source whichever one you put it into.
.INDENT 0.0
.IP 1. 3
Make sure you have a SERVER edition of the jdk installed and
point JAVA_INSTALL to it (see the same .bashrc below)
.UNINDENT
.INDENT 0.0
.IP 2. 3
Install Hadoop
.INDENT 3.0
.IP \(bu 2
Download the latest version of Hadoop and unpack it
.IP \(bu 2
Now in the unpacked directory, open conf/hadoop\-env.sh and edit:
.INDENT 3.0
.IP \(bu 2
set \fBJAVA_INSTALL\fP to be the part before \fBbin/\fP\&... when you do:
.INDENT 2.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
which java
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
set \fBHADOOP_CLASSPATH=$HADOOP_HOME/""*:$HADOOP_HOME/lib/""*:\fP
.UNINDENT
.IP \(bu 2
Now in conf/hdfs\-site.xml put the replication number that you
want for the field \fBdfs.replication\fP (this will set the
replication of blocks of the files in HDFS)
.IP \(bu 2
Now set up passwordless ssh, if you haven\(aqt yet:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
ssh\-keygen \-t dsa \-P \(aq\(aq \-f ~/.ssh/id_dsa
cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 3. 3
Set up Hadoop
.INDENT 3.0
.IP a. 3
For the local host \- See the
\fI\%Hadoop website\fP
for good documentation on how to do this.
.IP b. 3
For a cluster of hosts. If you want to run Hadoop over a cluster, there
are good tutorials online. Although it is usually as easy as making
edits to the following files in \fB$HADOOP_HOME/conf\fP:
.INDENT 3.0
.IP \(bu 2
adding the name of the nodes to \fBslaves\fP
.IP \(bu 2
putting what you want to be the namenode in \fBmasters\fP
.IP \(bu 2
putting the master node in \fBcore\-site.xml\fP and \fBmapred\-site.xml\fP
.IP \(bu 2
running:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
hadoop\-daemon.sh start datanode
hadoop\-daemon.sh start tasktracker
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
After this go to your datanode site and you should see a new
datanode.
.sp
A good online tutorial for this as well can be found here:
\fI\%http://hadoop.apache.org/docs/stable/hadoop\-project\-dist/hadoop\-common/ClusterSetup.html\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 4. 3
Start HDFS
.INDENT 3.0
.IP \(bu 2
Now all we need to do is format the namenode and start things up:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
hadoop namenode \-format
start\-all.sh  # (This will start hdfs and the tasktracker/jobtracker)
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
In general, hadoop has the same type of commands as bash,
usually in the form:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
hadoop dfs \-<command> <regular args to that command>
.ft P
.fi
.UNINDENT
.UNINDENT
.IP \(bu 2
At this point, you can compile and run Chapel programs using HDFS
.IP \(bu 2
You can check the status of Hadoop via http, for example on a local
host (e.g., for \fI\%3a above\fP), using:
.INDENT 3.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fBhttp://localhost:50070/\fP
.IP \(bu 2
\fBhttp://localhost:50030/\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For cluster mode (\fI\%3b\fP), you\(aqll use the name of the
master host in the URL and its port (see the web for details).
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 5. 3
Shut things down:
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
stop\-all.sh   # (This will stop hdfs and mapreduce)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 6. 3
Set up Chapel to run in distributed mode:
.INDENT 3.0
.IP \(bu 2
You\(aqll need to set up your Chapel environment to target multiple
locales in the standard way (see multilocale.rst and the
"Settings to run Chapel on multiple nodes" section of the
.bashrc below).
.IP \(bu 2
After this you should be able to run Chapel code with HDFS over
a cluster of computers the same way as you normally would.
.UNINDENT
.UNINDENT
.sp
Here is a sample .bashrc for using Hadoop within Chapel:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#
# For Hadoop
#
export HADOOP_INSTALL=<Place where you have Hadoop installed>
export HADOOP_HOME=$HADOOP_INSTALL
export HADOOP_VERSION=<Your Hadoop version number>
#
# Note that the following environment variables might contain more paths than
# those listed below if you have more than one IO system enabled. These are all
# that you will need in order to use HDFS (only)
#
export CHPL_AUXIO_INCLUDE="\-I$JAVA_INSTALL/include \-I$JAVA_INSTALL/include/linux  \-I$HADOOP_INSTALL/src/c++/libhdfs"
export CHPL_AUXIO_LIBS="\-L$JAVA_INSTALL/jre/lib/amd64/server \-L$HADOOP_INSTALL/c++/Linux\-amd64\-64/lib"

#
# So we can run things such as start\-all.sh etc. from anywhere and
# don\(aqt need to be in $HADOOP_INSTALL
#
export PATH=$PATH:$HADOOP_INSTALL/bin

#
# Point to the JDK installation
#
export JAVA_INSTALL=<Place where you have the jdk installed>

#
# Add Hadoop directories to the Java class path
#
export CLASSPATH=$CLASSPATH:$HADOOP_HOME/""*:$HADOOP_HOME/lib/""*:$HADOOP_HOME/conf/""*:$(hadoop classpath):

#
# So we don\(aqt have to "install" these things
#
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HADOOP_HOME/c++/Linux\-amd64\-64/lib:$HADOOP_HOME/src/c++/libhdfs:$JAVA_INSTALL/jre/lib/amd64/server:$JAVA_INSTALL:$HADOOP_HOME/lib:$JAVA_INSTALL/jre/lib/amd64:$CLASSPATH

#
# Settings to run Chapel on multiple nodes
#
export GASNET_SPAWNFN=S
export SSH_SERVERS=<the names of the computers in your cluster>
export SSH_CMD=ssh
export SSH_OPTIONS=\-x
export GASNET_ROUTE_OUTPUT=0
.ft P
.fi
.UNINDENT
.UNINDENT
.SS HDFS Support Types and Functions
.INDENT 0.0
.TP
.B record hdfsChapelFile
Holds a file per locale
.UNINDENT
.INDENT 0.0
.TP
.B record hdfsChapelFileSystem
Holds a connection to HDFS per locale
.UNINDENT
.INDENT 0.0
.TP
.B proc hdfsChapelConnect(out error: syserr, path: c_string, port: int): c_void_ptr
Make a connection to HDFS for a single locale
.UNINDENT
.INDENT 0.0
.TP
.B proc hdfsChapelConnect(path: string, port: int): hdfsChapelFileSystem
Connect to HDFS and create a filesystem ptr per locale
.UNINDENT
.INDENT 0.0
.TP
.B proc hdfsChapelFileSystem.hdfsChapelDisconnect()
Disconnect from the configured HDFS filesystem on each locale
.UNINDENT
.INDENT 0.0
.TP
.B proc hdfsChapelFileSystem.hdfsOpen(path: string, mode: iomode, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle()): hdfsChapelFile
Open a file on each locale
.UNINDENT
.INDENT 0.0
.TP
.B proc hdfsChapelFile.hdfsClose()
Close a file opened with \fI\%hdfsChapelFileSystem.hdfsOpen\fP
.UNINDENT
.INDENT 0.0
.TP
.B proc hdfsChapelFileSystem_local.hdfs_chapel_open(path: string, mode: iomode, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle()): file
Open a file on an HDFS filesystem for a single locale
.UNINDENT
.INDENT 0.0
.TP
.B proc hdfs_chapel_connect(path: string, port: int): hdfsChapelFileSystem_local
Connect to an HDFS filesystem on a single locale
.UNINDENT
.SS HDFSiterator
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use HDFSiterator;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Iterators for distributed iteration over Hadoop Distributed Filesystem
.sp
Iterators that can iterate over distributed data in an HDFS filesystem
in a distributed manner. See \fBHDFS\fP\&.
.INDENT 0.0
.TP
.B iter HDFSiter(path: string, type rec, regex: string)
Iterate through an HDFS file (available in the default configured
HDFS server) and yield records matching a regular expression.
.sp
Serial and leader\-follower versions of this iterator are available.
.INDENT 7.0
.TP
.B Arguments
.INDENT 7.0
.IP \(bu 2
\fBpath\fP \-\- the path to the file within the HDFS server
.IP \(bu 2
\fBrec\fP \-\- the type of the records to return
.IP \(bu 2
\fBregexp\fP \-\- a regular expression with the same number of captures as
the number of fields in the record type \fBrec\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS LAPACK
.sp
\fBUsage\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
use LAPACK;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Chapel idiomatic wrappers for the LAPACK library.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Because of the volume of procedures provided, and because their behavior is virtually unchanged, in\-depth documentation on each procedure\(aqs purpose and use is not given here.
.sp
Consult the \fI\%Netlibs LAPACK\fP site, and the \fI\%Netlibs\fP and \fI\%Intel\fP LAPACK documents for that information.
.sp
Additionally, only a small set of LAPACK procedures have been tested for correctness.
.UNINDENT
.UNINDENT
.SS Differences from LAPACK
.sp
The \fI\%XYYZZZ\fP naming convention for procedures has been only slightly modified with the removal of the type identifier in the procedure name,
creating a set of polymorphic procedures under the name YYZZZ.
.sp
Procedure arguments have been simplified.
Using the original Fortran documentation, groupings of arguments pertaining to matrices and arrays were found, and encapsulated by Chapel arrays.
.sp
For example, instead of
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
LAPACKE_sgesv(matrix_order : lapack_memory_order, n : c_int, nrhs : c_int, a : [] c_float, lda : c_int, ipiv : [] c_int, b : [] c_float, ldb : c_int) : c_int;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
the arguments n, nrhs, lda, and ldb can be encapsulated by properties of Chapel arrays and their domains, giving the LAPACK procedure:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gesv(matrix_order : lapack_memory_order, a : [] real(32), ipiv : [] c_int, b : [] real(32) ): c_int;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This requires that your matrices are stored in a two dimensional form.
.SS Type Adjustments
.sp
The LAPACKE types \fBlapack_int\fP, \fBlapack_float\fP, \fBlapack_double\fP, \fBlapack_complex_float\fP, \fBlapack_complex_double\fP, and \fBlapack_logical\fP are not defined at all, but rather are replaced by the types \fBc_int\fP, \fBreal(32)\fP, \fBreal(64)\fP, \fBcomplex(64)\fP, \fBcomplex(128)\fP, and \fBc_int\fP respectively.
.sp
The \fI\%lapack_memory_order\fP enumeration is a replacement for the \fBc_int\fP constants \fI\%LAPACK_ROW_MAJOR\fP and \fI\%LAPACK_COL_MAJOR\fP defined by LAPACK and used by \fBmatrix_order\fP which is an argument present in essentially all procedures.
The value of each enumeration is equivalent (both in type and value) of the LAPACK constants.
However the constants are also provided and can be used as well.
.sp
The \fBLAPACK_SELECT\fP types are function pointer types, whose procedures need to be declared and implemented in C, then be declared as \fBextern var\fP on the Chapel side.
See the dgees test (\fB$CHPL_HOME/test/modules/standard/LAPACK/dgees.chpl\fP) for a concrete example.
.SS Compiling with LAPACK
.sp
Using this module require that you have LAPACK (binaries and C interface) on your system, as it is not bundled with Chapel.
.sp
You can download and build the \fI\%Netlibs LAPACK\fP , if it is not already installed, and this section will assume usage of the Netlibs LAPACK.
You must also have libgfortran installed on your system (typically installed along with gcc).
.sp
To compile with LAPACK, Chapel needs to know:
.INDENT 0.0
.IP 1. 3
Where the LAPACKE header (lapacke.h) is.
.IP 2. 3
Where the libgfortran binary is (sometimes it is not to be found by \fBld\fP).
.IP 3. 3
Where the various LAPACK binaries (lapacke, lapack, and refblas) are.
.UNINDENT
.sp
Once the details are worked out, compiling is quite simple and nearly identical to how one would compile a C program to work with LAPACK.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-I$PATH_TO_LAPACKE_INCLUDE_DIR \e
     \-L$PATH_TO_LIBGFORTRAN \-lgfortran \e
     \-L$PATH_TO_LAPACK_BINARIES \-llapacke \-lapack \-lrefblas \e
     source.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As an example,
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
chpl \-I$HOME/LAPACK/lapacke/include \e
     \-L/usr/lib/gcc/stuff \-lgfortran \e
     \-L$HOME/LAPACK \-llapacke \-lapack \-lrefblas \e
     source.chpl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
would be the command to use if Netlibs LAPACK had been built in \fB$HOME/LAPACK\fP, and the libgfortran binary found to be located in \fB/usr/lib/gcc/stuff\fP
.sp
You can refer to the COMPOPTS file of the LAPACK test suit (\fB$CHPL_HOME/test/modules/standard/LAPACK/\fP) for an example
.SS Future Work
.sp
We anticipate the following additions:
.INDENT 0.0
.IP 1. 3
Better documentation on each individual procedure, mostly derived from the original Fortran documentation.
.IP 2. 3
Larger test coverage of the provided procedures.
.IP 3. 3
Enumerated values for arguments of procedures that currently take strings to denote different options.
.UNINDENT
.INDENT 0.0
.TP
.B type LAPACK_C_SELECT1
External function pointer type LAPACK_C_SELECT1.
.UNINDENT
.INDENT 0.0
.TP
.B type LAPACK_Z_SELECT1
External function pointer type LAPACK_Z_SELECT1.
.UNINDENT
.INDENT 0.0
.TP
.B type LAPACK_C_SELECT2
External function pointer type LAPACK_C_SELECT2.
.UNINDENT
.INDENT 0.0
.TP
.B type LAPACK_D_SELECT2
External function pointer type LAPACK_D_SELECT2.
.UNINDENT
.INDENT 0.0
.TP
.B type LAPACK_S_SELECT2
External function pointer type LAPACK_S_SELECT2.
.UNINDENT
.INDENT 0.0
.TP
.B type LAPACK_Z_SELECT2
External function pointer type LAPACK_Z_SELECT2.
.UNINDENT
.INDENT 0.0
.TP
.B type LAPACK_S_SELECT3
External function pointer type LAPACK_S_SELECT3.
.UNINDENT
.INDENT 0.0
.TP
.B type LAPACK_D_SELECT3
External function pointer type LAPACK_D_SELECT3.
.UNINDENT
.INDENT 0.0
.TP
.B const LAPACK_ROW_MAJOR: c_int
External const LAPACK_ROW_MAJOR.
.UNINDENT
.INDENT 0.0
.TP
.B const LAPACK_COL_MAJOR: c_int
External const LAPACK_COL_MAJOR.
.UNINDENT
.INDENT 0.0
.TP
.B const LAPACK_WORK_MEMORY_ERROR: c_int
External const LAPACK_WORK_MEMORY_ERROR.
.UNINDENT
.INDENT 0.0
.TP
.B const LAPACK_TRANSPOSE_MEMORY_ERROR: c_int
External const LAPACK_TRANSPOSE_MEMORY_ERROR.
.UNINDENT
.INDENT 0.0
.TP
.B enum lapack_memory_order { row_major = 101: c_int, column_major = 102: c_int }
Mirrors the \fI\%LAPACK_ROW_MAJOR\fP and \fI\%LAPACK_COL_MAJOR\fP consts defined by LAPACK.
.sp
The enum values values are the same as the const value such that \fBlapack_memory_order.row_major == LAPACK_ROW_MAJOR\fP and \fBlapack_memory_order.column_major == LAPACK_COL_MAJOR\fP, allowing the enum to be used with pure LAPACK procedures.
.UNINDENT
.INDENT 0.0
.TP
.B proc bdsdc(matrix_order: lapack_memory_order, uplo: string, compq: string, n: c_int, d: [] real(32), e: [] real(32), u: [] real(32), vt: [] real(32), q: [] real(32), iq: [] c_int): c_int
Wrapped procedure of LAPACKE_sbdsdc for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc bdsdc(matrix_order: lapack_memory_order, uplo: string, compq: string, n: c_int, d: [] real(64), e: [] real(64), u: [] real(64), vt: [] real(64), q: [] real(64), iq: [] c_int): c_int
Wrapped procedure of LAPACKE_dbdsdc for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc bdsqr(matrix_order: lapack_memory_order, uplo: string, d: [] real(32), e: [] real(32), vt: [] real(32), u: [] real(32), c: [] real(32)): c_int
Wrapped procedure of LAPACKE_sbdsqr for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc bdsqr(matrix_order: lapack_memory_order, uplo: string, d: [] real(64), e: [] real(64), vt: [] real(64), u: [] real(64), c: [] real(64)): c_int
Wrapped procedure of LAPACKE_dbdsqr for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc bdsqr(matrix_order: lapack_memory_order, uplo: string, d: [] real(32), e: [] real(32), vt: [] complex(64), u: [] complex(64), c: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cbdsqr for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc bdsqr(matrix_order: lapack_memory_order, uplo: string, d: [] real(64), e: [] real(64), vt: [] complex(128), u: [] complex(128), c: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zbdsqr for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc disna(job: string, m: c_int, n: c_int, d: [] real(32), sep: [] real(32)): c_int
Wrapped procedure of LAPACKE_sdisna for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc disna(job: string, m: c_int, n: c_int, d: [] real(64), sep: [] real(64)): c_int
Wrapped procedure of LAPACKE_ddisna for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbbrd(matrix_order: lapack_memory_order, vect: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), d: [] real(32), e: [] real(32), q: [] real(32), pt: [] real(32), c: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgbbrd for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbbrd(matrix_order: lapack_memory_order, vect: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), d: [] real(64), e: [] real(64), q: [] real(64), pt: [] real(64), c: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgbbrd for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbbrd(matrix_order: lapack_memory_order, vect: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), d: [] real(32), e: [] real(32), q: [] complex(64), pt: [] complex(64), c: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgbbrd for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbbrd(matrix_order: lapack_memory_order, vect: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), d: [] real(64), e: [] real(64), q: [] complex(128), pt: [] complex(128), c: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgbbrd for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbcon(matrix_order: lapack_memory_order, norm: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), ipiv: [] c_int, anorm: real(32), ref rcond: real(32)): c_int
Wrapped procedure of LAPACKE_sgbcon for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbcon(matrix_order: lapack_memory_order, norm: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), ipiv: [] c_int, anorm: real(64), ref rcond: real(64)): c_int
Wrapped procedure of LAPACKE_dgbcon for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbcon(matrix_order: lapack_memory_order, norm: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), ipiv: [] c_int, anorm: real(32), ref rcond: real(32)): c_int
Wrapped procedure of LAPACKE_cgbcon for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbcon(matrix_order: lapack_memory_order, norm: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), ipiv: [] c_int, anorm: real(64), ref rcond: real(64)): c_int
Wrapped procedure of LAPACKE_zgbcon for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbequ(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), r: [] real(32), c: [] real(32), ref rowcnd: real(32), ref colcnd: real(32), ref amax: real(32)): c_int
Wrapped procedure of LAPACKE_sgbequ for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbequ(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), r: [] real(64), c: [] real(64), ref rowcnd: real(64), ref colcnd: real(64), ref amax: real(64)): c_int
Wrapped procedure of LAPACKE_dgbequ for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbequ(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), r: [] real(32), c: [] real(32), ref rowcnd: real(32), ref colcnd: real(32), ref amax: real(32)): c_int
Wrapped procedure of LAPACKE_cgbequ for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbequ(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), r: [] real(64), c: [] real(64), ref rowcnd: real(64), ref colcnd: real(64), ref amax: real(64)): c_int
Wrapped procedure of LAPACKE_zgbequ for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbequb(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), r: [] real(32), c: [] real(32), ref rowcnd: real(32), ref colcnd: real(32), ref amax: real(32)): c_int
Wrapped procedure of LAPACKE_sgbequb for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbequb(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), r: [] real(64), c: [] real(64), ref rowcnd: real(64), ref colcnd: real(64), ref amax: real(64)): c_int
Wrapped procedure of LAPACKE_dgbequb for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbequb(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), r: [] real(32), c: [] real(32), ref rowcnd: real(32), ref colcnd: real(32), ref amax: real(32)): c_int
Wrapped procedure of LAPACKE_cgbequb for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbequb(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), r: [] real(64), c: [] real(64), ref rowcnd: real(64), ref colcnd: real(64), ref amax: real(64)): c_int
Wrapped procedure of LAPACKE_zgbequb for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbrfs(matrix_order: lapack_memory_order, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), afb: [] real(32), ipiv: [] c_int, b: [] real(32), x: [] real(32), ferr: [] real(32), berr: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgbrfs for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbrfs(matrix_order: lapack_memory_order, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), afb: [] real(64), ipiv: [] c_int, b: [] real(64), x: [] real(64), ferr: [] real(64), berr: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgbrfs for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbrfs(matrix_order: lapack_memory_order, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), afb: [] complex(64), ipiv: [] c_int, b: [] complex(64), x: [] complex(64), ferr: [] real(32), berr: [] real(32)): c_int
Wrapped procedure of LAPACKE_cgbrfs for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbrfs(matrix_order: lapack_memory_order, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), afb: [] complex(128), ipiv: [] c_int, b: [] complex(128), x: [] complex(128), ferr: [] real(64), berr: [] real(64)): c_int
Wrapped procedure of LAPACKE_zgbrfs for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbrfsx(matrix_order: lapack_memory_order, trans: string, equed: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), afb: [] real(32), ipiv: [] c_int, r: [] real(32), c: [] real(32), b: [] real(32), x: [] real(32), ref rcond: real(32), berr: [] real(32), n_err_bnds: c_int, err_bnds_norm: [] real(32), err_bnds_comp: [] real(32), nparams: c_int, params: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgbrfsx for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbrfsx(matrix_order: lapack_memory_order, trans: string, equed: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), afb: [] real(64), ipiv: [] c_int, r: [] real(64), c: [] real(64), b: [] real(64), x: [] real(64), ref rcond: real(64), berr: [] real(64), n_err_bnds: c_int, err_bnds_norm: [] real(64), err_bnds_comp: [] real(64), nparams: c_int, params: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgbrfsx for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbrfsx(matrix_order: lapack_memory_order, trans: string, equed: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), afb: [] complex(64), ipiv: [] c_int, r: [] real(32), c: [] real(32), b: [] complex(64), x: [] complex(64), ref rcond: real(32), berr: [] real(32), n_err_bnds: c_int, err_bnds_norm: [] real(32), err_bnds_comp: [] real(32), nparams: c_int, params: [] real(32)): c_int
Wrapped procedure of LAPACKE_cgbrfsx for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbrfsx(matrix_order: lapack_memory_order, trans: string, equed: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), afb: [] complex(128), ipiv: [] c_int, r: [] real(64), c: [] real(64), b: [] complex(128), x: [] complex(128), ref rcond: real(64), berr: [] real(64), n_err_bnds: c_int, err_bnds_norm: [] real(64), err_bnds_comp: [] real(64), nparams: c_int, params: [] real(64)): c_int
Wrapped procedure of LAPACKE_zgbrfsx for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsv(matrix_order: lapack_memory_order, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), ipiv: [] c_int, b: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgbsv for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsv(matrix_order: lapack_memory_order, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), ipiv: [] c_int, b: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgbsv for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsv(matrix_order: lapack_memory_order, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), ipiv: [] c_int, b: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgbsv for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsv(matrix_order: lapack_memory_order, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), ipiv: [] c_int, b: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgbsv for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsvx(matrix_order: lapack_memory_order, fact: string, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), afb: [] real(32), ipiv: [] c_int, ref equed: string, r: [] real(32), c: [] real(32), b: [] real(32), x: [] real(32), ref rcond: real(32), ferr: [] real(32), berr: [] real(32), rpivot: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgbsvx for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsvx(matrix_order: lapack_memory_order, fact: string, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), afb: [] real(64), ipiv: [] c_int, ref equed: string, r: [] real(64), c: [] real(64), b: [] real(64), x: [] real(64), ref rcond: real(64), ferr: [] real(64), berr: [] real(64), rpivot: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgbsvx for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsvx(matrix_order: lapack_memory_order, fact: string, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), afb: [] complex(64), ipiv: [] c_int, ref equed: string, r: [] real(32), c: [] real(32), b: [] complex(64), x: [] complex(64), ref rcond: real(32), ferr: [] real(32), berr: [] real(32), rpivot: [] real(32)): c_int
Wrapped procedure of LAPACKE_cgbsvx for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsvx(matrix_order: lapack_memory_order, fact: string, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), afb: [] complex(128), ipiv: [] c_int, ref equed: string, r: [] real(64), c: [] real(64), b: [] complex(128), x: [] complex(128), ref rcond: real(64), ferr: [] real(64), berr: [] real(64), rpivot: [] real(64)): c_int
Wrapped procedure of LAPACKE_zgbsvx for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsvxx(matrix_order: lapack_memory_order, fact: string, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), afb: [] real(32), ipiv: [] c_int, ref equed: string, r: [] real(32), c: [] real(32), b: [] real(32), x: [] real(32), ref rcond: real(32), ref rpvgrw: real(32), berr: [] real(32), n_err_bnds: c_int, err_bnds_norm: [] real(32), err_bnds_comp: [] real(32), nparams: c_int, params: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgbsvxx for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsvxx(matrix_order: lapack_memory_order, fact: string, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), afb: [] real(64), ipiv: [] c_int, ref equed: string, r: [] real(64), c: [] real(64), b: [] real(64), x: [] real(64), ref rcond: real(64), ref rpvgrw: real(64), berr: [] real(64), n_err_bnds: c_int, err_bnds_norm: [] real(64), err_bnds_comp: [] real(64), nparams: c_int, params: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgbsvxx for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsvxx(matrix_order: lapack_memory_order, fact: string, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), afb: [] complex(64), ipiv: [] c_int, ref equed: string, r: [] real(32), c: [] real(32), b: [] complex(64), x: [] complex(64), ref rcond: real(32), ref rpvgrw: real(32), berr: [] real(32), n_err_bnds: c_int, err_bnds_norm: [] real(32), err_bnds_comp: [] real(32), nparams: c_int, params: [] real(32)): c_int
Wrapped procedure of LAPACKE_cgbsvxx for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbsvxx(matrix_order: lapack_memory_order, fact: string, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), afb: [] complex(128), ipiv: [] c_int, ref equed: string, r: [] real(64), c: [] real(64), b: [] complex(128), x: [] complex(128), ref rcond: real(64), ref rpvgrw: real(64), berr: [] real(64), n_err_bnds: c_int, err_bnds_norm: [] real(64), err_bnds_comp: [] real(64), nparams: c_int, params: [] real(64)): c_int
Wrapped procedure of LAPACKE_zgbsvxx for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbtrf(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), ipiv: [] c_int): c_int
Wrapped procedure of LAPACKE_sgbtrf for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbtrf(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), ipiv: [] c_int): c_int
Wrapped procedure of LAPACKE_dgbtrf for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbtrf(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), ipiv: [] c_int): c_int
Wrapped procedure of LAPACKE_cgbtrf for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbtrf(matrix_order: lapack_memory_order, m: c_int, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), ipiv: [] c_int): c_int
Wrapped procedure of LAPACKE_zgbtrf for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbtrs(matrix_order: lapack_memory_order, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(32), ipiv: [] c_int, b: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgbtrs for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbtrs(matrix_order: lapack_memory_order, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] real(64), ipiv: [] c_int, b: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgbtrs for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbtrs(matrix_order: lapack_memory_order, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(64), ipiv: [] c_int, b: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgbtrs for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gbtrs(matrix_order: lapack_memory_order, trans: string, n: c_int, kl: c_int, ku: c_int, ab: [] complex(128), ipiv: [] c_int, b: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgbtrs for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebak(matrix_order: lapack_memory_order, job: string, side: string, ilo: c_int, ihi: c_int, scale: [] real(32), v: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgebak for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebak(matrix_order: lapack_memory_order, job: string, side: string, ilo: c_int, ihi: c_int, scale: [] real(64), v: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgebak for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebak(matrix_order: lapack_memory_order, job: string, side: string, ilo: c_int, ihi: c_int, scale: [] real(32), v: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgebak for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebak(matrix_order: lapack_memory_order, job: string, side: string, ilo: c_int, ihi: c_int, scale: [] real(64), v: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgebak for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebal(matrix_order: lapack_memory_order, job: string, a: [] real(32), ref ilo: c_int, ref ihi: c_int, scale: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgebal for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebal(matrix_order: lapack_memory_order, job: string, a: [] real(64), ref ilo: c_int, ref ihi: c_int, scale: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgebal for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebal(matrix_order: lapack_memory_order, job: string, a: [] complex(64), ref ilo: c_int, ref ihi: c_int, scale: [] real(32)): c_int
Wrapped procedure of LAPACKE_cgebal for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebal(matrix_order: lapack_memory_order, job: string, a: [] complex(128), ref ilo: c_int, ref ihi: c_int, scale: [] real(64)): c_int
Wrapped procedure of LAPACKE_zgebal for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebrd(matrix_order: lapack_memory_order, a: [] real(32), d: [] real(32), e: [] real(32), tauq: [] real(32), taup: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgebrd for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebrd(matrix_order: lapack_memory_order, a: [] real(64), d: [] real(64), e: [] real(64), tauq: [] real(64), taup: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgebrd for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebrd(matrix_order: lapack_memory_order, a: [] complex(64), d: [] real(32), e: [] real(32), tauq: [] complex(64), taup: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgebrd for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gebrd(matrix_order: lapack_memory_order, a: [] complex(128), d: [] real(64), e: [] real(64), tauq: [] complex(128), taup: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgebrd for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gecon(matrix_order: lapack_memory_order, norm: string, a: [] real(32), anorm: real(32), ref rcond: real(32)): c_int
Wrapped procedure of LAPACKE_sgecon for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gecon(matrix_order: lapack_memory_order, norm: string, a: [] real(64), anorm: real(64), ref rcond: real(64)): c_int
Wrapped procedure of LAPACKE_dgecon for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gecon(matrix_order: lapack_memory_order, norm: string, a: [] complex(64), anorm: real(32), ref rcond: real(32)): c_int
Wrapped procedure of LAPACKE_cgecon for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gecon(matrix_order: lapack_memory_order, norm: string, a: [] complex(128), anorm: real(64), ref rcond: real(64)): c_int
Wrapped procedure of LAPACKE_zgecon for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geequ(matrix_order: lapack_memory_order, a: [] real(32), r: [] real(32), c: [] real(32), ref rowcnd: real(32), ref colcnd: real(32), ref amax: real(32)): c_int
Wrapped procedure of LAPACKE_sgeequ for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geequ(matrix_order: lapack_memory_order, a: [] real(64), r: [] real(64), c: [] real(64), ref rowcnd: real(64), ref colcnd: real(64), ref amax: real(64)): c_int
Wrapped procedure of LAPACKE_dgeequ for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geequ(matrix_order: lapack_memory_order, a: [] complex(64), r: [] real(32), c: [] real(32), ref rowcnd: real(32), ref colcnd: real(32), ref amax: real(32)): c_int
Wrapped procedure of LAPACKE_cgeequ for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geequ(matrix_order: lapack_memory_order, a: [] complex(128), r: [] real(64), c: [] real(64), ref rowcnd: real(64), ref colcnd: real(64), ref amax: real(64)): c_int
Wrapped procedure of LAPACKE_zgeequ for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geequb(matrix_order: lapack_memory_order, a: [] real(32), r: [] real(32), c: [] real(32), ref rowcnd: real(32), ref colcnd: real(32), ref amax: real(32)): c_int
Wrapped procedure of LAPACKE_sgeequb for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geequb(matrix_order: lapack_memory_order, a: [] real(64), r: [] real(64), c: [] real(64), ref rowcnd: real(64), ref colcnd: real(64), ref amax: real(64)): c_int
Wrapped procedure of LAPACKE_dgeequb for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geequb(matrix_order: lapack_memory_order, a: [] complex(64), r: [] real(32), c: [] real(32), ref rowcnd: real(32), ref colcnd: real(32), ref amax: real(32)): c_int
Wrapped procedure of LAPACKE_cgeequb for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geequb(matrix_order: lapack_memory_order, a: [] complex(128), r: [] real(64), c: [] real(64), ref rowcnd: real(64), ref colcnd: real(64), ref amax: real(64)): c_int
Wrapped procedure of LAPACKE_zgeequb for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gees(matrix_order: lapack_memory_order, jobvs: string, sort: string, chlapack_select: LAPACK_S_SELECT2, a: [] real(32), ref sdim: c_int, wr: [] real(32), wi: [] real(32), vs: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgees for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gees(matrix_order: lapack_memory_order, jobvs: string, sort: string, chlapack_select: LAPACK_D_SELECT2, a: [] real(64), ref sdim: c_int, wr: [] real(64), wi: [] real(64), vs: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgees for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gees(matrix_order: lapack_memory_order, jobvs: string, sort: string, chlapack_select: LAPACK_C_SELECT1, a: [] complex(64), ref sdim: c_int, w: [] complex(64), vs: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgees for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gees(matrix_order: lapack_memory_order, jobvs: string, sort: string, chlapack_select: LAPACK_Z_SELECT1, a: [] complex(128), ref sdim: c_int, w: [] complex(128), vs: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgees for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geesx(matrix_order: lapack_memory_order, jobvs: string, sort: string, chlapack_select: LAPACK_S_SELECT2, sense: string, a: [] real(32), ref sdim: c_int, wr: [] real(32), wi: [] real(32), vs: [] real(32), ref rconde: real(32), ref rcondv: real(32)): c_int
Wrapped procedure of LAPACKE_sgeesx for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geesx(matrix_order: lapack_memory_order, jobvs: string, sort: string, chlapack_select: LAPACK_D_SELECT2, sense: string, a: [] real(64), ref sdim: c_int, wr: [] real(64), wi: [] real(64), vs: [] real(64), ref rconde: real(64), ref rcondv: real(64)): c_int
Wrapped procedure of LAPACKE_dgeesx for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geesx(matrix_order: lapack_memory_order, jobvs: string, sort: string, chlapack_select: LAPACK_C_SELECT1, sense: string, a: [] complex(64), ref sdim: c_int, w: [] complex(64), vs: [] complex(64), ref rconde: real(32), ref rcondv: real(32)): c_int
Wrapped procedure of LAPACKE_cgeesx for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geesx(matrix_order: lapack_memory_order, jobvs: string, sort: string, chlapack_select: LAPACK_Z_SELECT1, sense: string, a: [] complex(128), ref sdim: c_int, w: [] complex(128), vs: [] complex(128), ref rconde: real(64), ref rcondv: real(64)): c_int
Wrapped procedure of LAPACKE_zgeesx for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geev(matrix_order: lapack_memory_order, jobvl: string, jobvr: string, a: [] real(32), wr: [] real(32), wi: [] real(32), vl: [] real(32), vr: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgeev for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geev(matrix_order: lapack_memory_order, jobvl: string, jobvr: string, a: [] real(64), wr: [] real(64), wi: [] real(64), vl: [] real(64), vr: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgeev for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geev(matrix_order: lapack_memory_order, jobvl: string, jobvr: string, a: [] complex(64), w: [] complex(64), vl: [] complex(64), vr: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgeev for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geev(matrix_order: lapack_memory_order, jobvl: string, jobvr: string, a: [] complex(128), w: [] complex(128), vl: [] complex(128), vr: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgeev for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geevx(matrix_order: lapack_memory_order, balanc: string, jobvl: string, jobvr: string, sense: string, a: [] real(32), wr: [] real(32), wi: [] real(32), vl: [] real(32), vr: [] real(32), ref ilo: c_int, ref ihi: c_int, scale: [] real(32), ref abnrm: real(32), rconde: [] real(32), rcondv: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgeevx for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geevx(matrix_order: lapack_memory_order, balanc: string, jobvl: string, jobvr: string, sense: string, a: [] real(64), wr: [] real(64), wi: [] real(64), vl: [] real(64), vr: [] real(64), ref ilo: c_int, ref ihi: c_int, scale: [] real(64), ref abnrm: real(64), rconde: [] real(64), rcondv: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgeevx for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geevx(matrix_order: lapack_memory_order, balanc: string, jobvl: string, jobvr: string, sense: string, a: [] complex(64), w: [] complex(64), vl: [] complex(64), vr: [] complex(64), ref ilo: c_int, ref ihi: c_int, scale: [] real(32), ref abnrm: real(32), rconde: [] real(32), rcondv: [] real(32)): c_int
Wrapped procedure of LAPACKE_cgeevx for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geevx(matrix_order: lapack_memory_order, balanc: string, jobvl: string, jobvr: string, sense: string, a: [] complex(128), w: [] complex(128), vl: [] complex(128), vr: [] complex(128), ref ilo: c_int, ref ihi: c_int, scale: [] real(64), ref abnrm: real(64), rconde: [] real(64), rcondv: [] real(64)): c_int
Wrapped procedure of LAPACKE_zgeevx for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gehrd(matrix_order: lapack_memory_order, ilo: c_int, ihi: c_int, a: [] real(32), tau: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgehrd for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gehrd(matrix_order: lapack_memory_order, ilo: c_int, ihi: c_int, a: [] real(64), tau: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgehrd for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gehrd(matrix_order: lapack_memory_order, ilo: c_int, ihi: c_int, a: [] complex(64), tau: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgehrd for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gehrd(matrix_order: lapack_memory_order, ilo: c_int, ihi: c_int, a: [] complex(128), tau: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgehrd for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gejsv(matrix_order: lapack_memory_order, joba: string, jobu: string, jobv: string, jobr: string, jobt: string, jobp: string, a: [] real(32), sva: [] real(32), u: [] real(32), v: [] real(32), stat: [] real(32), istat: [] c_int): c_int
Wrapped procedure of LAPACKE_sgejsv for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gejsv(matrix_order: lapack_memory_order, joba: string, jobu: string, jobv: string, jobr: string, jobt: string, jobp: string, a: [] real(64), sva: [] real(64), u: [] real(64), v: [] real(64), stat: [] real(64), istat: [] c_int): c_int
Wrapped procedure of LAPACKE_dgejsv for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelq2(matrix_order: lapack_memory_order, a: [] real(32), tau: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgelq2 for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelq2(matrix_order: lapack_memory_order, a: [] real(64), tau: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgelq2 for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelq2(matrix_order: lapack_memory_order, a: [] complex(64), tau: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgelq2 for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelq2(matrix_order: lapack_memory_order, a: [] complex(128), tau: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgelq2 for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelqf(matrix_order: lapack_memory_order, a: [] real(32), tau: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgelqf for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelqf(matrix_order: lapack_memory_order, a: [] real(64), tau: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgelqf for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelqf(matrix_order: lapack_memory_order, a: [] complex(64), tau: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgelqf for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelqf(matrix_order: lapack_memory_order, a: [] complex(128), tau: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgelqf for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gels(matrix_order: lapack_memory_order, trans: string, a: [] real(32), b: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgels for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gels(matrix_order: lapack_memory_order, trans: string, a: [] real(64), b: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgels for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gels(matrix_order: lapack_memory_order, trans: string, a: [] complex(64), b: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgels for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gels(matrix_order: lapack_memory_order, trans: string, a: [] complex(128), b: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgels for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelsd(matrix_order: lapack_memory_order, a: [] real(32), b: [] real(32), s: [] real(32), rcond: real(32)): c_int
Wrapped procedure of LAPACKE_sgelsd for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelsd(matrix_order: lapack_memory_order, a: [] real(64), b: [] real(64), s: [] real(64), rcond: real(64)): c_int
Wrapped procedure of LAPACKE_dgelsd for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelsd(matrix_order: lapack_memory_order, a: [] complex(64), b: [] complex(64), s: [] real(32), rcond: real(32)): c_int
Wrapped procedure of LAPACKE_cgelsd for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelsd(matrix_order: lapack_memory_order, a: [] complex(128), b: [] complex(128), s: [] real(64), rcond: real(64)): c_int
Wrapped procedure of LAPACKE_zgelsd for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelss(matrix_order: lapack_memory_order, a: [] real(32), b: [] real(32), s: [] real(32), rcond: real(32)): c_int
Wrapped procedure of LAPACKE_sgelss for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelss(matrix_order: lapack_memory_order, a: [] real(64), b: [] real(64), s: [] real(64), rcond: real(64)): c_int
Wrapped procedure of LAPACKE_dgelss for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelss(matrix_order: lapack_memory_order, a: [] complex(64), b: [] complex(64), s: [] real(32), rcond: real(32)): c_int
Wrapped procedure of LAPACKE_cgelss for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelss(matrix_order: lapack_memory_order, a: [] complex(128), b: [] complex(128), s: [] real(64), rcond: real(64)): c_int
Wrapped procedure of LAPACKE_zgelss for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelsy(matrix_order: lapack_memory_order, a: [] real(32), b: [] real(32), jpvt: [] c_int, rcond: real(32)): c_int
Wrapped procedure of LAPACKE_sgelsy for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelsy(matrix_order: lapack_memory_order, a: [] real(64), b: [] real(64), jpvt: [] c_int, rcond: real(64)): c_int
Wrapped procedure of LAPACKE_dgelsy for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelsy(matrix_order: lapack_memory_order, a: [] complex(64), b: [] complex(64), jpvt: [] c_int, rcond: real(32)): c_int
Wrapped procedure of LAPACKE_cgelsy for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc gelsy(matrix_order: lapack_memory_order, a: [] complex(128), b: [] complex(128), jpvt: [] c_int, rcond: real(64)): c_int
Wrapped procedure of LAPACKE_zgelsy for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqlf(matrix_order: lapack_memory_order, a: [] real(32), tau: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgeqlf for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqlf(matrix_order: lapack_memory_order, a: [] real(64), tau: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgeqlf for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqlf(matrix_order: lapack_memory_order, a: [] complex(64), tau: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgeqlf for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqlf(matrix_order: lapack_memory_order, a: [] complex(128), tau: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgeqlf for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqp3(matrix_order: lapack_memory_order, a: [] real(32), jpvt: [] c_int, tau: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgeqp3 for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqp3(matrix_order: lapack_memory_order, a: [] real(64), jpvt: [] c_int, tau: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgeqp3 for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqp3(matrix_order: lapack_memory_order, a: [] complex(64), jpvt: [] c_int, tau: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgeqp3 for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqp3(matrix_order: lapack_memory_order, a: [] complex(128), jpvt: [] c_int, tau: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgeqp3 for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqpf(matrix_order: lapack_memory_order, a: [] real(32), jpvt: [] c_int, tau: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgeqpf for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqpf(matrix_order: lapack_memory_order, a: [] real(64), jpvt: [] c_int, tau: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgeqpf for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqpf(matrix_order: lapack_memory_order, a: [] complex(64), jpvt: [] c_int, tau: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgeqpf for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqpf(matrix_order: lapack_memory_order, a: [] complex(128), jpvt: [] c_int, tau: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgeqpf for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqr2(matrix_order: lapack_memory_order, a: [] real(32), tau: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgeqr2 for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqr2(matrix_order: lapack_memory_order, a: [] real(64), tau: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgeqr2 for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqr2(matrix_order: lapack_memory_order, a: [] complex(64), tau: [] complex(64)): c_int
Wrapped procedure of LAPACKE_cgeqr2 for the type complex(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqr2(matrix_order: lapack_memory_order, a: [] complex(128), tau: [] complex(128)): c_int
Wrapped procedure of LAPACKE_zgeqr2 for the type complex(128).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqrf(matrix_order: lapack_memory_order, a: [] real(32), tau: [] real(32)): c_int
Wrapped procedure of LAPACKE_sgeqrf for the type real(32).
.UNINDENT
.INDENT 0.0
.TP
.B proc geqrf(matrix_order: lapack_memory_order, a: [] real(64), tau: [] real(64)): c_int
Wrapped procedure of LAPACKE_dgeqrf for the type real(64).
.UNINDENT
.INDENT 0.0
.TP
.B proc