IO¶
Usage
use IO;
Submodules
Support for a variety of kinds of input and output.
Note
All Chapel programs automatically use
this module by default.
An explicit use
statement is not necessary.
Input/output (I/O) facilities in Chapel include the types file
and
channel
; the constants stdin
, stdout
and
stderr
; the functions open
, file.close
,
file.reader
, file.writer
, channel.read
,
channel.write
, and many others.
I/O Overview¶
A file
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 channel
uses a buffer to provide
sequential read or write access to its file, optionally starting at an offset.
For example, the following program opens a file and writes an integer to it:
// 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
Then, the following program can be used to read the integer:
// 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
Design Rationale¶
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 FILE*
to write to different regions of a file because of the race condition between
fseek
and fwrite
. Because of these issues, Chapel programmers wishing
to perform I/O will need to know how to open files as well as create channels.
I/O Styles¶
Reading and writing of Chapel's basic types is regulated by an applicable
iostyle
. 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.
See the definition for the iostyle
type. This type represents I/O
styles and provides details on formatting and other representation choices.
The default value of the iostyle
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
defaultIOStyle
will return the default I/O style just as new
iostyle()
will.
The I/O style for an I/O operation can be provided through an optional
style=
argument in a variety of places:
- when performing the I/O, e.g. in calls to
channel.write
orchannel.read
- when creating the channel with
file.reader
orfile.writer
- or when creating the file with e.g.
open
Note that file.reader
, or file.writer
will copy the file's I/O
style if a style=
argument is not provided. Also note that I/O functions on
channels will by default use the I/O style stored with that channel.
A channel's I/O style may be retrieved using channel._style
and set
using channel._set_style
. These functions should only be called while
the channel lock is held, however. See Synchronization of Channel Data and Avoiding Data Races
for more information on channel locks.
Note
iostyle
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.
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:
stdout.writeln(MyArray, new iostyle(min_width=10));
I/O facilities in Chapel also include several other ways to control I/O
formatting. There is support for formatted I/O
with channel.readf
and channel.writef
. Also note that record or
class implementations can provide custom functions implementing read or write
operations for that type (see The readThis(), writeThis(), and readWriteThis() Methods).
Files¶
There are several functions that open a file and return a file
including open
, opentmp
, openmem
, openfd
, and openfp
.
Once a file is open, it is necessary to create associated channel(s) - see
file.reader
and file.writer
- to write to and/or read from the
file.
Use the file.fsync
function to explicitly synchronize the file to
ensure that file data is committed to the file's underlying device for
persistence.
To release any resources associated with a file, it is necessary to first close
any channels using that file (with channel.close
) and then the file
itself (with file.close
).
Functions for Channel Creation¶
file.writer
creates a channel for writing to a file, and
file.reader
create a channel for reading from a file.
Synchronization of Channel Data and Avoiding Data Races¶
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 locking=false
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
channel.mark
and channel._mark
). 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.
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 channel.flush
synchronization operation.
channel.flush
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.
Note
Since channels can buffer data until channel.flush
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:
- concurrent operations on multiple channels that operate on overlapping regions of a file
- where at least one of the overlapping channels is a writing channel
- and where data could be stored more than one of the overlapping channel's buffers at the same time (ie, write and read ordering are not enforced through
channel.flush
and other mean such as sync variables).
Note that it is possible in some cases to create a file
that does
not allow multiple channels at different offsets. Channels created on such
files will not change the file's position based on a start=
offset
arguments. Instead, each read or write operation will use the file
descriptor's current position. Therefore, only one channel should be created
for files created in the following situations:
Performing I/O with Channels¶
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. These functions generally take any number of arguments and throw if there was an error. See:
In addition, there are several convenient synonyms for channel.write
and
channel.read
:
Sometimes it's 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'll have to call
channel.flush
or channel.close
and then file.fsync
on
the related file.
Functions for Closing Channels¶
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.
See channel.close
.
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.
Files and channels are reference counted. Each file and channel is closed automatically when no references to it remain. For example, if a local variable is the only reference to a channel, the channel will be closed when that variable goes out of scope. Programs may also close a file or channel explicitly.
The stdin
, stdout
, and stderr
Channels¶
Chapel provides the predefined channels stdin
, stdout
, and
stderr
to access the corresponding operating system streams standard
input, standard output, and standard error.
stdin
supports reading;
stdout
and stderr
support writing.
All three channels are safe to use concurrently.
Their types' kind
argument is dynamic
Error Handling¶
Most I/O routines throw a SysError.SystemError
, and can be handled
appropriately with try
and catch
. For legacy reasons most I/O routines
can also can accept an optional error= argument.
In this documentation, SystemError may include both the
SysError.SystemError
class proper and its subclasses.
Some of these subclasses commonly used within the I/O implementation include:
SysError.EOFError
- the end of file was reached
SysError.UnexpectedEOFError
- a read or write only returnedpart of the requested data
SysError.BadFormatError
- data read did not adhere to therequested format
Some of the legacy error codes used include:
SysBasic.EILSEQ
- illegal multibyte sequence (e.g. there was a UTF-8 format error)SysBasic.EOVERFLOW
- data read did not fit into requested type (e.g. reading 1000 into a uint(8)).
An error code can be converted to a string using the function
errorToString
.
Ensuring Successful I/O¶
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 file.fsync
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 file.close
or even file.fsync
.
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
file.fsync
prior to closing the file.
Correspondence to C I/O¶
It is not possible to seek, read, or write to a file directly. Create a channel to proceed.
channel.flush
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.
The iomode constants in Chapel have the same meaning as the following strings passed to fopen() in C:
- iomode.r "r"
- iomode.rw "r+"
- iomode.cw "w"
- iomode.cwr "w+"
However, open() in Chapel does not necessarily invoke fopen().
IO Functions and Types¶
-
enum
iomode
{ r = 1, cw = 2, rw = 3, cwr = 4 }¶ The
iomode
type is an enum. When used as arguments when opening files, its constants have the following meaning:iomode.r
- open an existing file for reading.iomode.rw
- open an existing file for reading and writing.iomode.cw
- create a new file for writing. If the file already exists, its contents are removed when the file is opened in this mode.iomode.cwr
- as withiomode.cw
but reading from the file is also allowed.
-
enum
iokind
{ dynamic = 0, native = 1, big = 2, little = 3 }¶ The
iokind
type is an enum. When used as arguments to thechannel
type, its constants have the following meaning:iokind.big
means binary I/O with big-endian byte order is performed when writing/reading basic types from the channel.iokind.little
means binary I/O with little-endian byte order (similar toiokind.big
but with little-endian byte order).iokind.native
means binary I/O in native byte order (similar toiokind.big
but with the byte order that is native to the target platform).iokind.dynamic
means that the applicable I/O style has full effect and as a result the kind varies at runtime.
In the case of
iokind.big
,iokind.little
, andiokind.native
the applicableiostyle
is consulted when writing/reading strings, but not for other basic types.There are synonyms available for these values:
-
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
str_style
field iniostyle
.iostringstyle.len1b_data
indicates a string format of 1 byte of length followed by length bytes of string data.iostringstyle.len2b_data
indicates a string format of 2 bytes of length followed by length bytes of string data.iostringstyle.len4b_data
indicates a string format of 4 bytes of length followed by length bytes of string data.iostringstyle.len8b_data
indicates a string format of 8 bytes of length followed by length bytes of string data.iostringstyle.lenVb_data
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 Google Protocol Buffers.iostringstyle.data_toeof
indicates a string format that contains only the string data without any length or terminator. When reading, this format will read a string until the end of the file is reached.iostringstyle.data_null
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$
(which in ASCII has byte value 0x24), one would use the valueiostringstyle.data_null|0x24
.- A positive and nonzero value indicates that a string of exactly that many bytes should be read or written.
-
enum
iostringformat
{ word = 0, basic = 1, chpl = 2, json = 3, toend = 4, toeof = 5 }¶ This enum contains values used to control text I/O with strings via the
string_format
field iniostyle
.iostringformat.word
means string is as-is; reading reads until whitespace. This is the default.iostringformat.basic
means only escape string_end and\
with\
iostringformat.chpl
means escape string_end\
'
"
\n
with\
and nonprinting charactersc = 0xXY
with\xXY
iostringformat.json
means escape string_end"
and\
with\
, and nonprinting charactersc = \uABCD
iostringformat.toend
means string is as-is; reading reads until string_endiostringformat.toeof
means string is as-is; reading reads until end of file
-
proc
stringStyleTerminated
(terminator: uint(8))¶ This method returns the appropriate
iostyle
str_style
value to indicate a string format where strings are terminated by a particular byte.Arguments: terminator -- a byte value that the strings will be terminated by Returns: a value that indicates a string format where strings are terminated by the terminator byte. This value is appropriate to store in iostyle.str_style
.
-
proc
stringStyleNullTerminated
()¶ This method returns the appropriate
iostyle
str_style
value to indicate a string format where strings are terminated by a zero byte.
-
proc
stringStyleExactLen
(len: int(64))¶ This method returns the appropriate
iostyle
str_style
value to indicate a string format where strings have an exact length.
-
proc
stringStyleWithVariableLength
()¶ This method returns the appropriate
iostyle
str_style
value to indicate a string format where string data is preceded by a variable-byte length as described iniostringstyle
.
-
proc
stringStyleWithLength
(lengthBytes: int) throws¶ Return the appropriate
iostyle
str_style
value to indicate a string format where string data is preceded by a lengthBytes of length. Only lengths of 1, 2, 4, or 8 are supported. When lengthBytes is 0, the returned value indicates variable-byte length.Throws SystemError: Thrown for an unsupported value of lengthBytes.
-
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.
-
const
IOHINT_RANDOM
= QIO_HINT_RANDOM¶ IOHINT_RANDOM means we expect random access to a file
-
const
IOHINT_SEQUENTIAL
= QIO_HINT_SEQUENTIAL¶ IOHINT_SEQUENTIAL means expect sequential access. On Linux, this should double the readahead.
-
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.
-
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.
-
record
iostyle
¶ The
iostyle
type represents I/O styles defining how Chapel's basic types should be read or written.See The stdin, stdout, and stderr Channels.
-
var
binary
: uint(8) = 0¶ Perform binary I/O? 1 - yes, 0 - no. This field is ignored for
iokind
values other thandynamic
.
-
var
byteorder
: uint(8) = iokind.native: uint(8)¶ What byte order should we use when performing binary I/O? This field is ignored for
iokind
values other thandynamic
. It should be set to a value iniokind
.
-
var
str_style
: int(64) = iostringstyle.data_toeof: int(64)¶ What string format should we use when writing strings in binary mode? See
iostringstyle
for more information on what the values ofstr_style
mean.
-
var
min_width_columns
: uint(32) = 0¶ When performing text I/O, pad out to this many columns
-
var
max_width_columns
: uint(32) = max(uint(32))¶ When performing text I/O, do not use more than this many columns
-
var
max_width_characters
: uint(32) = max(uint(32))¶ When performing text I/O, do not use more than this many characters
-
var
max_width_bytes
: uint(32) = max(uint(32))¶ When performing text I/O, do not use more than this many bytes
-
var
string_start
: style_char_t = 34¶ What character do we start strings with, when appropriate? Default is "
-
var
string_end
: style_char_t = 34¶ What character do we end strings with, when appropriate? Default is "
-
var
string_format
: uint(8) = iostringformat.word: uint(8)¶ How should we format strings when performing text I/O? See
iostringstyle
for more information on what the values ofstr_style
mean.
-
var
base
: uint(8) = 0¶ When reading or writing a numeric value in a text mode channel, what base should be used for the number? Default of 0 means decimal. Bases 2, 8, 10, 16 are supported for integers. Bases 10 and 16 are supported for real values.
-
var
point_char
: style_char_t = 46¶ When reading or writing a numeric value in a text mode channel, how is the integer portion separated from the fractional portion? Default is '.'
-
var
exponent_char
: style_char_t = 101¶ When reading or writing a numeric value in a text mode channel, how is the exponent written? Default is 'e'
-
var
other_exponent_char
: style_char_t = 112¶ When reading or writing a numeric value in a text mode channel, when base is > 10, how is the exponent written? Default is 'e'
-
var
positive_char
: style_char_t = 43¶ What character denotes a positive number? Default is '+'
-
var
negative_char
: style_char_t = 45¶ What character denotes a negative number? Default is '-'
-
var
i_char
: style_char_t = 105¶ What character follows an the imaginary number? Default is 'i'
-
var
prefix_base
: uint(8) = 1¶ When writing in a base other than 10, should the prefix be used? (e.g. hexadecimal numbers are prefixed with 0x)
-
var
pad_char
: style_char_t = 32¶ When padding with spaces, which pad character to use? Default is ' '
-
var
showplus
: uint(8) = 0¶ When printing a positive numeric value, should the + be shown?
-
var
uppercase
: uint(8) = 0¶ When printing a numeric value in hexadecimal, should it be uppercase?
-
var
leftjustify
: uint(8) = 0¶ When printing a numeric value in a field of specified width, should the number be on the left (that is padded on the right?). The default is to right-justify the number.
-
var
showpoint
: uint(8) = 0¶ When printing an integral value using a real format, should a trailing decimal point be included? If so, the value 0 will be written as '0.'
-
var
showpointzero
: uint(8) = 1¶ When printing an integral value using a real format, should a trailing decimal point and zero be included? If so, the value 0 will be written as '0.0'
-
var
precision
: int(32) = -1¶ Specifies the precision for real format conversions. See the description of realfmt below.
-
var
realfmt
: uint(8) = 0¶ Formatting of real numbers:
- 0 means print out 'precision' number of significant digits (%g in printf)
- 1 means print out 'precision' number of digits after the decimal point (%f)
- 2 means always use exponential and 'precision' number of digits (%e)
-
var
complex_style
: uint(8) = 0¶
-
var
array_style
: uint(8) = 0¶
-
var
aggregate_style
: uint(8) = 0¶
-
var
tuple_style
: uint(8) = 0¶
-
var
-
proc
defaultIOStyle
(): iostyle¶ Returns: the default I/O style. See iostyle
and I/O Styles
-
proc
iostyle.
native
(str_style: int(64) = stringStyleWithVariableLength()): iostyle¶ Get an I/O style indicating binary I/O in native byte order.
Arguments: str_style -- see iostringstyle
- which format to use when reading or writing strings. Defaults to variable-byte length.Returns: the requested iostyle
-
proc
iostyle.
big
(str_style: int(64) = stringStyleWithVariableLength()): iostyle¶ Get an I/O style indicating binary I/O in big-endian byte order.
Arguments: str_style -- see iostringstyle
- which format to use when reading or writing strings. Defaults to variable-byte length.Returns: the requested iostyle
-
proc
iostyle.
little
(str_style: int(64) = stringStyleWithVariableLength()): iostyle¶ Get an I/O style indicating binary I/O in little-endian byte order.
Arguments: str_style -- see iostringstyle
- which format to use when reading or writing strings. Defaults to variable-byte length.Returns: the requested iostyle
-
type
iohints
= c_int¶ A value of the
iohints
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.The
iohints
type is implementation-defined. The followingiohints
constants are provided:IOHINT_NONE
defines an empty set, which provides no hints.IOHINT_RANDOM
suggests to expect random access.IOHINT_SEQUENTIAL
suggests to expect sequential access.IOHINT_CACHED
suggests that the file data is or should be cached in memory, possibly all at once.IOHINT_PARALLEL
suggests to expect many channels working with this file in parallel.
Other hints might be added in the future.
The following binary operators are defined on
iohints
:|
for set union&
for set intersection==
for set equality1=
for set inequality
When an
iohints
formal has default intent, the actual is copied to the formal upon a function call and the formal cannot be assigned within the function.The default value of the
iohints
type is undefined.
-
record
file
¶ The
file
type is implementation-defined. A value of thefile
type refers to the state that is used by the implementation to identify and interact with the OS file.When a
file
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.The default value of the
file
type does not represent any OS file. It is illegal to perform any I/O operations on the default value.-
proc
init
()¶
-
proc
-
proc
file.
init=
(x: file)¶
-
proc
file.
check
() throws¶ Throw an error if this is not a valid representation of an OS file.
Throws SystemError: Indicates that this does not represent an OS file.
-
proc
file.
close
() throws¶ Close a file.
In order to free the resources allocated for a file, it must be closed using this method.
Closing a file does not guarantee immediate persistence of the performed updates, if any. In cases where immediate persistence is important,
file.fsync
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 Ensuring Successful I/O.Files are automatically closed when the file variable goes out of scope and all channels using that file are closed. Programs may also explicitly close a file using this method.
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.
Throws SystemError: Thrown if the file could not be closed.
-
proc
file.
fsync
() throws¶ Sync a file to disk.
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.
This function will typically call the
fsync
system call.Throws SystemError: Thrown if the file could not be synced.
-
proc
file.
path
: string throws¶ Get the path to an open file.
Note that not all files have a path (e.g. files opened with
openmem
), and that this function may not work on all operating systems.The function
Path.file.realPath
is an alternative way to get the path to a file.Throws SystemError: Thrown if the path could not be retrieved.
-
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.
-
proc
file.
length
(): int(64) throws¶ 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.
Returns: the current file length Throws SystemError: Thrown if the length could not be retrieved.
-
proc
open
(path: string = "", mode: iomode, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle(), url: string = ""): file throws¶ 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
file.reader
orfile.writer
to create a channel to actually perform I/O operationsArguments: - path -- which file to open (for example, "some/file.txt"). This argument
is required unless the
url=
argument is used. - iomode -- specify whether to open the file for reading or writing and
whether or not to create the file if it doesn't exist.
See
iomode
. - hints -- optional argument to specify any hints to the I/O system about
this file. See
iohints
. - style -- 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.
- url -- optional argument to specify a URL to open. See
Curl
andHDFS
for more information onurl=
support for those systems. If HDFS is enabled, this function supportsurl=
arguments of the form "hdfs://<host>:<port>/<path>". If Curl is enabled, this function supportsurl=
starting withhttp://
,https://
,ftp://
,ftps://
,smtp://
,smtps://
,imap://
, orimaps://
Returns: an open file to the requested resource.
Throws SystemError: Thrown if the file could not be opened.
- path -- which file to open (for example, "some/file.txt"). This argument
is required unless the
-
proc
openfd
(fd: fd_t, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle()): file throws¶ Create a Chapel file that works with a system file descriptor Note that once the file is open, you will need to use a
file.reader
orfile.writer
to create a channel to actually perform I/O operationsThe system file descriptor will be closed when the Chapel file is closed.
Note
This function can be used to create Chapel files that refer to system file descriptors that do not support the
seek
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 onechannel
at a time. The I/O system will ignore the channel offsets when reading or writing to files backed by non-seekable file descriptors.Arguments: - fd -- a system file descriptor (obtained with
Sys.sys_open
orSys.sys_connect
for example). - hints -- optional argument to specify any hints to the I/O system about
this file. See
iohints
. - style -- 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.
Returns: an open
file
using the specified file descriptor.Throws SystemError: Thrown if the file descriptor could not be retrieved.
- fd -- a system file descriptor (obtained with
-
proc
openfp
(fp: _file, hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle()): file throws¶ Create a Chapel file that works with an open C file (ie a
FILE*
). Note that once the file is open, you will need to use afile.reader
orfile.writer
to create a channel to actually perform I/O operationsNote
The resulting file value should only be used with one
channel
at a time. The I/O system will ignore the channel offsets when reading or writing to a file opened withopenfp
.Arguments: - fp -- a C
FILE*
to work with - hints -- optional argument to specify any hints to the I/O system about
this file. See
iohints
. - style -- 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.
Returns: an open
file
that uses the underlying FILE* argument.Throws SystemError: Thrown if the C file could not be retrieved.
- fp -- a C
-
proc
opentmp
(hints: iohints = IOHINT_NONE, style: iostyle = defaultIOStyle()): file throws¶ Open a temporary file. Note that once the file is open, you will need to use a
file.reader
orfile.writer
to create a channel to actually perform I/O operations.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.
Temporary files are always opened with
iomode
iomode.cwr
; that is, a new file is created that supports both writing and reading.Arguments: - hints -- optional argument to specify any hints to the I/O system about
this file. See
iohints
. - style -- 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.
Returns: an open temporary file.
Throws SystemError: Thrown if the temporary file could not be opened.
- hints -- optional argument to specify any hints to the I/O system about
this file. See
-
proc
openmem
(style: iostyle = defaultIOStyle()): file throws¶ 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
file.reader
orfile.writer
to create a channel to actually perform I/O operations.The resulting file supports both reading and writing.
Arguments: style -- 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. Returns: an open memory file. Throws SystemError: Thrown if the memory buffered file could not be opened.
-
record
channel
¶ A channel supports either sequential reading or sequential writing to an underlying
file
object. A channel can buffer data. Read operations on the channel might return old data. Write operations might not have an immediate effect. Usechannel.flush
to control this buffering.The
channel
type is implementation-defined. A value of thechannel
type refers to the state that is used to implement the channel operations.When a
channel
formal has default intent, the actual is copied to the formal upon a function call and the formal cannot be assigned within the function.The default value of the
channel
type is not associated with any file and so cannot be used to perform I/O.The
channel
type is generic.-
param
writing
: bool¶ writing is a boolean indicating whether the channels of this type support writing (when true) or reading (when false).
-
param
kind
: iokind¶ kind is an enum
iokind
that allows narrowing this channel's I/O style for more efficient binary I/O.
-
param
locking
: bool¶ locking is a boolean indicating whether it is safe to use this channel concurrently (when true).
-
param
-
proc
channel.
init=
(x: this.type)¶
-
record
ioChar
¶ Represents a Unicode codepoint. I/O routines (such as
channel.read
andchannel.write
) can use arguments of this type in order to read or write a single Unicode codepoint.-
var
ch
: int(32)¶ The codepoint value
-
var
-
record
ioNewline
¶ Represents a newline character or character sequence (ie
\n
). I/O routines (such aschannel.read
andchannel.write
) can use arguments of this type in order to read or write a newline. This is different from 'n' because an ioNewline always produces an actual newline, but in some cases writing\n
will produce an escaped string (such as"\n"
).When reading an ioNewline, read routines will skip any character sequence (including e.g. letters and numbers) to get to the newline character unless
skipWhitespaceOnly
is set to true.-
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.
-
var
-
record
ioLiteral
¶ Used to represent a constant string we want to read or write.
When writing, the ioLiteral is output without any quoting or escaping.
When reading, the ioLiteral must be matched exactly - or else the read call will return an error with code
SysBasic.EFORMAT
.-
var
val
: string¶ The value of the literal
-
var
ignoreWhiteSpace
: bool = true¶ Should read operations using this literal ignore and consume whitespace before the literal?
-
proc
writeThis
(f)¶
-
var
-
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.
-
var
v
: uint(64)¶ The bottom
nbits
of v will be read or written
-
var
nbits
: int(8)¶ How many of the low-order bits of
v
should we read or write?
-
var
-
proc
channel.
lock
() throws¶ Acquire a channel's lock.
Throws SystemError: Thrown if the lock could not be acquired.
-
proc
channel.
unlock
()¶ Release a channel's lock.
-
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
channel.lock
,channel._offset
, andchannel.unlock
to prevent race conditions.Returns: the current offset of the channel
-
proc
channel.
advance
(amount: int(64)) throws¶ Move a channel offset forward.
For a reading channel, this function will consume the next
amount
bytes. If EOF is reached, the channel position may be left at the EOF.For a writing channel, this function will write
amount
zeros - or some other data if it is stored in the channel's buffer, for example withchannel._mark
andchannel._revert
.Throws SystemError: Throws if the channel offset was not moved.
-
proc
channel.
advancePastByte
(byte: uint(8)) throws¶ Reads until
byte
is found and then leave the channel offset just after it.Throws: - EOFError -- if the requested byte could not be found.
- SystemError -- if another error occurred.
-
proc
channel.
mark
(): syserr¶ mark a channel - that is, save the current offset of the channel on its mark stack. This function can only be called on a channel with
locking==false
.The mark stack stores several channel offsets. For any channel offset that is between the minimum and maximum value in the mark stack, 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 I/O transactions on a channel. The basic steps for an I/O transaction are:
- mark the current position with
channel.mark
- do something speculative (e.g. try to read 200 bytes of anything followed by a 'B')
- if the speculative operation was successful, commit the changes by
calling
channel.commit
- if the speculative operation was not successful, go back to the mark by
calling
channel.revert
. Subsequent I/O operations will work as though nothing happened.
Note
Note that it is possible to request an entire file be buffered in memory using this feature, for example by marking at offset=0 and then advancing to the end of the file. It is important to be aware of these memory space requirements.
Returns: an error code, if an error was encountered. - mark the current position with
-
proc
channel.
revert
()¶ Abort an I/O transaction. See
channel.mark
. This function will pop the last element from the mark stack and then leave the previous channel offset unchanged. This function can only be called on a channel withlocking==false
.
-
proc
channel.
commit
()¶ Commit an I/O transaction. See
channel.mark
. This function will pop the last element from the mark stack and then set the channel offset to the popped offset. This function can only be called on a channel withlocking==false
.
-
proc
channel.
_offset
(): int(64)¶ For a channel locked with
channel.lock
, return the offset of that channel.
-
proc
channel.
_mark
(): syserr¶ This routine is identical to
channel.mark
except that it can be called on channels withlocking==true
and should be called only once the channel has been locked withchannel.lock
. The channel should not be unlocked withchannel.unlock
until after the mark has been committed withchannel._commit
or reverted withchannel._revert
.See
channel.mark
for details other than the locking discipline.Returns: an error code, if an error was encountered.
-
proc
channel.
_revert
()¶ Abort an I/O transaction. See
channel._mark
. This function will pop the last element from the mark stack and then leave the previous channel offset unchanged. This function should only be called on a channel that has already been locked and marked.
-
proc
channel.
_commit
()¶ Commit an I/O transaction. See
channel._mark
. This function will pop the last element from the mark stack and then set the channel offset to the popped offset. This function should only be called on a channel that has already been locked and marked.
-
proc
channel.
_style
(): iostyle¶ Return the current style used by a channel. This function should only be called on a locked channel.
-
proc
channel.
_set_style
(style: iostyle)¶ Set the style associated with a channel. This function should only be called on a locked channel.
-
proc
channel.
readWriteThisFromLocale
()¶ Return the locale on which an ongoing I/O was started with a channel. This method will return nil unless it is called on a channel that is the formal argument to a readThis, writeThis, or readWriteThis method.
-
proc
openreader
(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) throws¶ Open a file at a particular path or URL and return a reading channel for it. This function is equivalent to calling
open
and thenfile.reader
on the resulting file.Arguments: - path -- which file to open (for example, "some/file.txt"). This argument
is required unless the
url=
argument is used. - kind --
iokind
compile-time argument to determine the corresponding parameter of thechannel
type. Defaults toiokind.dynamic
, meaning that the associatediostyle
controls the formatting choices. - locking -- compile-time argument to determine whether or not the
channel should use locking; sets the
corresponding parameter of the
channel
type. Defaults to true, but when safe, setting it to false can improve performance. - start -- zero-based byte offset indicating where in the file the channel should start reading. Defaults to 0.
- end -- zero-based byte offset indicating where in the file the
channel should no longer be allowed to read. Defaults
to a
max(int)
- meaning no end point. - hints -- optional argument to specify any hints to the I/O system about
this file. See
iohints
. - url -- optional argument to specify a URL to open. See
Curl
andHDFS
for more information onurl=
support for those systems. If HDFS is enabled, this function supportsurl=
arguments of the form "hdfs://<host>:<port>/<path>". If Curl is enabled, this function supportsurl=
starting withhttp://
,https://
,ftp://
,ftps://
,smtp://
,smtps://
,imap://
, orimaps://
Returns: an open reading channel to the requested resource.
Throws SystemError: Thrown if a reading channel could not be returned.
- path -- which file to open (for example, "some/file.txt"). This argument
is required unless the
-
proc
openwriter
(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) throws¶ Open a file at a particular path or URL and return a writing channel for it. This function is equivalent to calling
open
withiomode.cwr
and thenfile.writer
on the resulting file.Arguments: - path -- which file to open (for example, "some/file.txt"). This argument
is required unless the
url=
argument is used. - kind --
iokind
compile-time argument to determine the corresponding parameter of thechannel
type. Defaults toiokind.dynamic
, meaning that the associatediostyle
controls the formatting choices. - locking -- compile-time argument to determine whether or not the
channel should use locking; sets the
corresponding parameter of the
channel
type. Defaults to true, but when safe, setting it to false can improve performance. - start -- zero-based byte offset indicating where in the file the channel should start writing. Defaults to 0.
- end -- zero-based byte offset indicating where in the file the
channel should no longer be allowed to write. Defaults
to a
max(int)
- meaning no end point. - hints -- optional argument to specify any hints to the I/O system about
this file. See
iohints
. - url -- optional argument to specify a URL to open. See
Curl
andHDFS
for more information onurl=
support for those systems. If HDFS is enabled, this function supportsurl=
arguments of the form "hdfs://<host>:<port>/<path>". If Curl is enabled, this function supportsurl=
starting withhttp://
,https://
,ftp://
,ftps://
,smtp://
,smtps://
,imap://
, orimaps://
Returns: an open writing channel to the requested resource.
Throws SystemError: Thrown if a writing channel could not be returned.
- path -- which file to open (for example, "some/file.txt"). This argument
is required unless the
-
proc
file.
reader
(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) throws¶ Create a
channel
that supports reading from a file. See I/O Overview.The
start=
andend=
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.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
EEOF
(and return false in many cases such aschannel.read
) to indicate that the end was reached.Arguments: - kind --
iokind
compile-time argument to determine the corresponding parameter of thechannel
type. Defaults toiokind.dynamic
, meaning that the associatediostyle
controls the formatting choices. - locking -- compile-time argument to determine whether or not the
channel should use locking; sets the
corresponding parameter of the
channel
type. Defaults to true, but when safe, setting it to false can improve performance. - start -- zero-based byte offset indicating where in the file the channel should start reading. Defaults to 0.
- end -- zero-based byte offset indicating where in the file the
channel should no longer be allowed to read. Defaults
to a
max(int)
- meaning no end point. - hints -- provide hints about the I/O that this channel will perform. See
iohints
. The default value ofIOHINT_NONE
will cause the channel to use the hints provided when opening the file. - style -- provide a
iostyle
to use with this channel. The default value will be theiostyle
associated with this file.
Throws SystemError: Thrown if a file reader channel could not be returned.
- kind --
-
proc
file.
lines
(param locking: bool = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints = IOHINT_NONE, in local_style: iostyle = this._style) throws¶ Iterate over all of the lines in a file.
Returns: an object which yields strings read from the file Throws SystemError: Thrown if an ItemReader could not be returned.
-
proc
file.
writer
(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: c_int = 0, style: iostyle = this._style): channel(true, kind, locking) throws¶ Create a
channel
that supports writing to a file. See I/O Overview.The
start=
andend=
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.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.
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.
Arguments: - kind --
iokind
compile-time argument to determine the corresponding parameter of thechannel
type. Defaults toiokind.dynamic
, meaning that the associatediostyle
controls the formatting choices. - locking -- compile-time argument to determine whether or not the
channel should use locking; sets the
corresponding parameter of the
channel
type. Defaults to true, but when safe, setting it to false can improve performance. - start -- zero-based byte offset indicating where in the file the channel should start writing. Defaults to 0.
- end -- zero-based byte offset indicating where in the file the
channel should no longer be allowed to write. Defaults
to a
max(int)
- meaning no end point. - hints -- provide hints about the I/O that this channel will perform. See
iohints
. The default value ofIOHINT_NONE
will cause the channel to use the hints provided when opening the file. - style -- provide a
iostyle
to use with this channel. The default value will be theiostyle
associated with this file.
Throws SystemError: Thrown if a file writer channel could not be returned.
- kind --
-
proc
channel.
readwrite
(const x)¶ For a writing channel, writes as with
channel.write
. For a reading channel, reads as withchannel.read
. Stores any error encountered in the channel. Does not return anything.
-
proc <~>(const ref ch: channel, x) const ref
The <~> operator
This <~> operator is the same as calling
channel.readwrite
, except that it returns the channel so that multiple operator calls can be chained together.Returns: ch
-
proc <~>(const ref r: channel, lit: ioLiteral) const ref
Overload to support reading an
IO.ioLiteral
without passing ioLiterals by reference, so thatreader <~> new ioLiteral("=")
works without requiring an explicit temporary value to store the ioLiteral.
-
proc <~>(const ref r: channel, nl: ioNewline) const ref
Overload to support reading an
IO.ioNewline
without passing ioNewline by reference, so thatreader <~> new ioNewline()
works without requiring an explicit temporary value to store the ioNewline.
-
proc
channel.
readWriteLiteral
(lit: string, ignoreWhiteSpace = true)¶ Explicit call for reading or writing a literal as an alternative to using
IO.ioLiteral
.
-
proc
channel.
readWriteNewline
()¶ Explicit call for reading or writing a newline as an alternative to using
IO.ioNewline
.
-
proc
channel.
binary
(): bool¶ Returns true if this channel is configured for binary I/O.
-
proc
channel.
error
(): syserr¶ Return any saved error code.
-
proc
channel.
setError
(e: syserr)¶ Save an error code.
-
proc
channel.
clearError
()¶ Clear any saved error code.
-
proc
channel.
writeBytes
(x, len: ssize_t): bool throws¶ Write a sequence of bytes.
Throws SystemError: Thrown if the byte sequence could not be written.
-
iter
channel.
lines
()¶ Iterate over all of the lines ending in
\n
in a channel - the channel lock will be held while iterating over the lines.Only serial iteration is supported.
Warning
This iterator executes on the current locale. This may impact multilocale performance if the current locale is not the same locale on which the channel was created.
Yields: lines ending in \n
in channel
-
proc
stringify
(const args ...?k): string¶ Creates a string representing the result of writing the arguments.
Writes each argument, possibly using a writeThis method, to a string and returns the result.
-
proc
channel.
read
(ref args ...?k): bool throws¶ returns true if read successfully, false if we encountered EOF
-
proc
channel.
read
(ref args ...?k, style: iostyle): bool throws Read values from a channel. The input will be consumed atomically - the channel lock will be held while reading all of the passed values.
Arguments: - args -- a list of arguments to read. Basic types are handled
internally, but for other types this function will call
value.readThis() with a
Reader
argument as described in The readThis(), writeThis(), and readWriteThis() Methods. - style -- optional argument to provide an
iostyle
for this read. If this argument is not provided, use the current style associated with this channel.
Returns: true if the read succeeded, and false on end of file.
Throws SystemError: Thrown if the channel could not be read.
- args -- a list of arguments to read. Basic types are handled
internally, but for other types this function will call
value.readThis() with a
-
proc
channel.
readline
(arg: [] uint(8), out numRead: int, start = arg.domain.low, amount = arg.domain.high-start+1): bool throws¶ Read a line into a Chapel array of bytes. Reads until a
\n
is reached. The\n
is returned in the array.Throws a SystemError if a line could not be read from the channel.
Arguments: - arg -- A 1D DefaultRectangular array which must have at least 1 element.
- numRead -- The number of bytes read.
- start -- Index to begin reading into.
- amount -- The maximum amount of bytes to read.
Returns: true if the bytes were read without error.
-
proc
channel.
readline
(ref arg: string): bool throws Read a line into a Chapel string. Reads until a
\n
is reached. The\n
is included in the resulting string.Arguments: arg -- a string to receive the line Returns: true if a line was read without error, false upon EOF Throws SystemError: Thrown if a string could not be read from the channel.
-
proc
channel.
readstring
(ref str_out: string, len: int(64) = -1): bool throws¶ read a given number of bytes from a channel
Arguments: - str_out -- The string to be read into
- len -- 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's current offset.
Returns: true if we read something, false upon EOF
Throws SystemError: Thrown if the bytes could not be read from the channel.
-
proc
channel.
readbits
(out v: integral, nbits: integral): bool throws¶ Read bits with binary I/O
Arguments: - v -- where to store the read bits. This value will have its nbits least-significant bits set.
- nbits -- how many bits to read
Returns: true if the bits were read without error, false upon EOF
Throws SystemError: Thrown if the bits could not be read from the channel.
-
proc
channel.
writebits
(v: integral, nbits: integral): bool throws¶ Write bits with binary I/O
Arguments: - v -- a value containing nbits bits to write the least-significant bits
- nbits -- how many bits to write
Returns: true if the bits were written without error, false on error
Throws: - IllegalArgumentError -- Thrown if writing more bits than fit into v.
- SystemError -- Thrown if the bits could not be written to the channel.
-
proc
channel.
readln
(ref args ...?k, style: iostyle): bool throws¶ 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.
Arguments: - args -- 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
Reader
argument as described in The readThis(), writeThis(), and readWriteThis() Methods. - style -- optional argument to provide an
iostyle
for this read. If this argument is not provided, use the current style associated with this channel.
Returns: true if the read succeeded, and false upon end of file.
Throws SystemError: Thrown if a line could not be read from the channel.
- args -- 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
-
proc
channel.
read
(type t) throws Read a value of passed type.
Note
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
channel.read
returning the values read in arguments instead.For example, the following line of code reads a value of type int from
stdin
and uses it to initialize a variablex
:var x = stdin.read(int)
Arguments: t -- the type to read Returns: the value read Throws SystemError: Thrown if the type could not be read from the channel.
-
proc
channel.
readln
(type t) throws Read a value of passed type followed by a newline.
Note
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
channel.readln
instead.Arguments: t -- the type to read Returns: the value read Throws SystemError: Thrown if the type could not be read from the channel.
-
proc
channel.
readln
(type t ...?numTypes) throws Read values of passed types followed by a newline and return a tuple containing the read values.
Arguments: t -- more than one type to read Returns: a tuple of the read values Throws SystemError: Thrown if the types could not be read from the channel.
-
proc
channel.
read
(type t ...?numTypes) throws Read values of passed types and return a tuple containing the read values.
Arguments: t -- more than one type to read Returns: a tuple of the read values Throws SystemError: Thrown if the types could not be read from the channel.
-
proc
channel.
write
(const args ...?k, style: iostyle): bool throws¶ Write values to a channel. The output will be produced atomically - the channel lock will be held while writing all of the passed values.
Arguments: - args -- 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.
- style -- optional argument to provide an
iostyle
for this write. If this argument is not provided, use the current style associated with this channel.
Returns: true if the write succeeded
Throws SystemError: Thrown if the values could not be written to the channel.
-
proc
channel.
writeln
(const args ...?k, style: iostyle): bool throws¶ 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.
Arguments: - args -- 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.
- style -- optional argument to provide an
iostyle
for this write. If this argument is not provided, use the current style associated with this channel.
Returns: true if the write succeeded
Throws SystemError: Thrown if the values could not be written to the channel.
-
proc
channel.
flush
() throws¶ 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
file.fsync
, this does not commit the written data to the file's device.Throws SystemError: Thrown if the flush fails.
-
proc
channel.
assertEOF
(errStr: string = "- Not at EOF")¶ Assert that a channel has reached end-of-file and that there was no error doing the read.
-
proc
channel.
close
() throws¶ Close a channel. Implicitly performs the
channel.flush
operation (see Synchronization of Channel Data and Avoiding Data Races).Throws SystemError: Thrown if the channel is not successfully closed.
-
proc
channel.
isclosed
()¶ Return true if a channel is currently closed.
-
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.
-
type
ItemType
¶ What type do we read and yield?
-
param
kind
: iokind¶ the kind field for our channel
-
param
locking
: bool¶ the locking field for our channel
-
var
ch
: channel(false, kind, locking)¶ our channel
-
proc
read
(out arg: ItemType): bool throws¶ read a single item, throwing on error
-
proc
read
(out arg: ItemType, out error: syserr): bool read a single item, returning an error
-
iter
these
()¶ iterate through all items of that type read from the channel
-
type
-
proc
channel.
itemReader
(type ItemType, param kind: iokind = iokind.dynamic)¶ Create and return an
ItemReader
that can yield read values of a single type.
-
record
ItemWriter
¶ -
type
ItemType
¶ What type do we write?
-
param
kind
: iokind¶ the kind field for our channel
-
param
locking
: bool¶ the locking field for our channel
-
var
ch
: channel(true, kind, locking)¶ our channel
-
proc
write
(arg: ItemType): bool throws¶ write a single item, throwing on error
-
proc
write
(arg: ItemType, out error: syserr): bool write a single item, returning an error
-
type
-
proc
channel.
itemWriter
(type ItemType, param kind: iokind = iokind.dynamic)¶ Create and return an
ItemWriter
that can write values of a single type.
-
const
stdin
: channel(false, iokind.dynamic, true) = stdinInit()¶ standard input, otherwise known as file descriptor 0
-
const
stdout
: channel(true, iokind.dynamic, true) = stdoutInit()¶ standard output, otherwise known as file descriptor 1
-
const
stderr
: channel(true, iokind.dynamic, true) = stderrInit()¶ standard error, otherwise known as file descriptor 2
-
proc
stdinInit
()¶
-
proc
stdoutInit
()¶
-
proc
stderrInit
()¶
-
proc
write
(const args ...?n)¶ Equivalent to try! stdout.write. See
channel.write
-
proc
writeln
(const args ...?n)¶ Equivalent to try! stdout.writeln. See
channel.writeln
-
proc
read
(ref args ...?n): bool throws¶ Equivalent to stdin.read. See
channel.read
-
proc
readln
(ref args ...?n): bool throws¶ Equivalent to stdin.readln. See
channel.readln
-
proc
readln
(type t ...?numTypes) throws Equivalent to stdin.readln. See
channel.readln
for types
-
proc
read
(type t ...?numTypes) throws Equivalent to stdin.read. See
channel.read
for types
-
proc
unlink
(path: string) throws¶ Delete a file. This function is likely to be replaced by
FileSystem.remove
.Arguments: path -- the path to the file to remove Throws SystemError: Thrown if the file is not successfully deleted.
-
proc
unicodeSupported
(): bool¶ Returns: true if this version of the Chapel runtime supports UTF-8 output.
-
proc
file.
getchunk
(start: int(64) = 0, end: int(64) = max(int(64))): (int(64), int(64)) throws¶ 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.
Returns (0,0) if no such value exists.
Arguments: - start -- the file offset (starting from 0) where the region begins
- end -- the file offset just after the region
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
Throws SystemError: Thrown if the chunk is not attained.
-
proc
file.
localesForRegion
(start: int(64), end: int(64))¶ Returns the 'best' locale to run something working with the region of the file in start..end-1.
This must 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.
Arguments: - start -- the file offset (starting from 0) where the region begins
- end -- the file offset just after the region
Returns: a set of locales that are best for working with this region
Return type: domain(locale)