Statements¶

Chapel is an imperative language with statements that may have side effects. Statements allow for the sequencing of program execution. Chapel provides the following statements:

statement:
  block-statement
  expression-statement
  assignment-statement
  swap-statement
  conditional-statement
  select-statement
  while-do-statement
  do-while-statement
  for-statement
  label-statement
  break-statement
  continue-statement
  param-for-statement
  require-statement
  use-statement
  import-statement
  defer-statement
  empty-statement
  return-statement
  yield-statement
  module-declaration-statement
  procedure-declaration-statement
  external-procedure-declaration-statement
  exported-procedure-declaration-statement
  iterator-declaration-statement
  method-declaration-statement
  type-declaration-statement
  variable-declaration-statement
  remote-variable-declaration-statement
  on-statement
  cobegin-statement
  coforall-statement
  begin-statement
  sync-statement
  serial-statement
  forall-statement
  delete-statement
  manage-statement

Individual statements are defined in the remainder of this chapter and additionally as follows:

return The Return Statement
yield The Yield Statement
module declaration Modules
procedure declaration Procedure Definitions
external procedure declaration Calling External Functions
exporting procedure declaration Calling Chapel Functions
iterator declaration Iterator Definitions
method declaration Class Methods
type declaration Types
variable declaration Variable Declarations
remote variable declaration Remote Variable Declarations
on statement The On Statement
cobegin, coforall, begin, sync, and serial statements Task Parallelism and Synchronization
forall Data Parallelism
delete Deleting Unmanaged Class Instances
manage The Manage Statement

Blocks¶

A block is a statement or a possibly empty list of statements that form their own scope. A block is given by

block-statement:
  { statements[OPT] }

statements:
  statement
  statement statements

Variables defined within a block are local variables (Local Variables).

The statements within a block are executed serially unless the block is in a cobegin statement (The Cobegin Statement).

Expression Statements¶

The expression statement evaluates an expression solely for side effects. The syntax for an expression statement is given by

expression-statement:
  variable-expression ;
  member-access-expression ;
  call-expression ;
  new-expression ;
  let-expression ;

Assignment Statements¶

An assignment statement assigns the value of an expression to another expression, for example, a variable. Assignment statements are given by

assignment-statement:
  lvalue-expression assignment-operator expression ;

assignment-operator: one of
   = += -= *= /= %= **= &= |= ^= &&= ||= <<= >>=

The assignment operators that contain a binary operator symbol as a prefix are compound assignment operators. The remaining assignment operator = is called simple assignment.

The expression on the left-hand side of the assignment operator must be a valid lvalue (LValue Expressions). It is evaluated before the expression on the right-hand side of the assignment operator, which can be any expression.

When the left-hand side is of a numerical type, there is an implicit conversion (Implicit Conversions) of the right-hand side expression to the type of the left-hand side expression.

For simple assignment, the validity and semantics of assigning between classes (Class Assignment), records (Record Assignment), unions (Union Assignment), tuples (Tuple Assignment), ranges (Range Assignment), domains (Domain Assignment), and arrays (Array Assignment) are discussed in these later sections.

A compound assignment is shorthand for applying the binary operator to the left- and right-hand side expressions and then assigning the result to the left-hand side expression. For numerical types, the left-hand side expression is evaluated only once, and there is an implicit conversion of the result of the binary operator to the type of the left-hand side expression. Thus, for example, x += y is equivalent to x = x + y where the expression x is evaluated once.

For all other compound assignments, Chapel provides a completely generic catch-all implementation defined in the obvious way. For example:

inline proc +=(ref lhs, rhs) {
  lhs = lhs + rhs;
}

Thus, compound assignment can be used with operands of arbitrary types, provided that the following provisions are met: If the type of the left-hand argument of a compound assignment operator op= is \(L\) and that of the right-hand argument is \(R\), then a definition for the corresponding binary operator op exists, such that \(L\) is coercible to the type of its left-hand formal and \(R\) is coercible to the type of its right-hand formal. Further, the result of op must be coercible to \(L\), and there must exist a definition for simple assignment between objects of type \(L\).

Both simple and compound assignment operators can be overloaded for different types using operator overloading (Function and Operator Overloading). In such an overload, the left-hand side expression should have ref intent and be modified within the body of the function. The return type of the function should be void.

The Swap Statement¶

The swap statement indicates to swap the values in the expressions on either side of the swap operator. Since both expressions are assigned to, each must be a valid lvalue expression (LValue Expressions).

The swap operator can be overloaded for different types using operator overloading (Function and Operator Overloading).

swap-statement:
  lvalue-expression swap-operator lvalue-expression ;

swap-operator:
  <=>

To implement the swap operation, the compiler uses temporary variables as necessary.

Example.

When resolved to the default swap operator, the following swap statement
var a, b: real;

a <=> b;
is semantically equivalent to:
const t = b;
b = a;
a = t;

The Conditional Statement¶

The conditional statement allows execution to choose between two statements based on the evaluation of an expression of bool type. The syntax for a conditional statement is given by

conditional-statement:
  'if' expression 'then' statement else-part[OPT]
  'if' expression block-statement else-part[OPT]
  'if' ctrl-decl 'then' statement else-part[OPT]
  'if' ctrl-decl block-statement else-part[OPT]

else-part:
  'else' statement

ctrl-decl:
  'var' identifier '=' expression
  'const' identifier '=' expression

A conditional statement evaluates an expression of bool type. If the expression evaluates to true, the first statement in the conditional statement is executed. If the expression evaluates to false and the optional else-clause exists, the statement following the else keyword is executed.

If the expression is a parameter, the conditional statement is folded by the compiler. If the expression evaluates to true, the first statement replaces the conditional statement. If the expression evaluates to false, the second statement, if it exists, replaces the conditional statement; if the second statement does not exist, the conditional statement is removed.

Each statement embedded in the conditional-statement has its own scope whether or not an explicit block surrounds it.

The control-flow declaration ctrl-decl, when used, declares a variable whose scope is the then-clause of the conditional statement. The expression must be of a class type. If it evaluates to nil, the else-clause is executed if present. Otherwise its value is stored in the declared variable and the then-clause is executed. If the expression’s type is borrowed or unmanaged, the variable’s type is its non-nilable variant (Nilable Class Types). Otherwise the variable stores a borrow of the expression’s value (Class Lifetime and Borrows), and its type is the non-nilable borrowed counterpart of the expression’s type. The variable can be modified within the then-clause if it is declared with the var keyword.

If the statement that immediately follows the optional then keyword is a conditional statement and it is not in a block, the else-clause is bound to the nearest preceding conditional statement without an else-clause. The statement in the else-clause can be a conditional statement, too.

Example (conditionals.chpl).

The following function prints two when x is 2 and B,four when x is 4.

proc condtest(x:int) {
  if x > 3 then
    if x > 5 then
      write("A,");
    else
      write("B,");

  if x == 2 then
    writeln("two");
  else if x == 4 then
    writeln("four");
  else
    writeln("other");
}

The Select Statement¶

The select statement is a multi-way variant of the conditional statement. The syntax is given by:

select-statement:
  'select' expression { when-statements }

when-statements:
  when-statement
  when-statement when-statements

when-statement:
  'when' expression-list 'do' statement
  'when' expression-list block-statement
  'otherwise' statement
  'otherwise' 'do' statement

expression-list:
  expression
  expression , expression-list

The expression that follows the keyword select, the select expression, is evaluated once and its value is then compared with the list of case expressions following each when keyword. These values are compared using the equality operator ==. If the expressions cannot be compared with the equality operator, a compile-time error is generated. The first case expression that contains an expression where that comparison is true will be selected and control transferred to the associated statement. If the comparison is always false, the statement associated with the keyword otherwise, if it exists, will be selected and control transferred to it. There may be at most one otherwise statement and it must be the last clause of the select statement.

Each statement embedded in the when-statement or the otherwise-statement has its own scope whether or not an explicit block surrounds it.

The While Do and Do While Loops¶

There are two variants of the while loop in Chapel. The syntax of the while-do loop is given by:

while-do-statement:
  'while' expression 'do' statement
  'while' expression block-statement
  'while' ctrl-decl 'do' statement
  'while' ctrl-decl block-statement

The syntax of the do-while loop is given by:

do-while-statement:
  'do' statement 'while' expression ;

In both variants, the expression evaluates to a value of type bool which determines when the loop terminates and control continues with the statement following the loop.

The while-do loop is executed as follows:

The expression is evaluated.
If the expression evaluates to false, the statement is not executed and control continues to the statement following the loop.
If the expression evaluates to true, the statement is executed and control continues to step 1, evaluating the expression again.

The do-while loop is executed as follows:

The statement is executed.
The expression is evaluated.
If the expression evaluates to false, control continues to the statement following the loop.
If the expression evaluates to true, control continues to step 1 and the statement is executed again.

In this second form of the loop, note that the statement is executed unconditionally the first time.

Example (while.chpl).

The following example illustrates the difference between the do-while-statement and the while-do-statement. The body of the do-while loop is always executed at least once, even if the loop conditional is already false when it is entered. The code
var t = 11;

writeln("Scope of do while loop:");
do {
  t += 1;
  writeln(t);
} while (t <= 10);

t = 11;
writeln("Scope of while loop:");
while (t <= 10) {
  t += 1;
  writeln(t);
}
produces the output
Scope of do while loop:
12
Scope of while loop:

Chapel do-while loops differ from those found in most other languages in one important regard. If the body of a do-while statement is a block statement and new variables are defined within that block statement, then the scope of those variables extends to cover the loop’s termination expression.

Example (do-while.chpl).

The following example demonstrates that the scope of the variable t includes the loop termination expression.
var i = 0;
do {
  var t = i;
  i += 1;
  writeln(t);
} while (t != 5);
produces the output
0
1
2
3
4
5

The control-flow declaration ctrl-decl, when used in a while-do loop, works similarly to how it does in a conditional statement (The Conditional Statement). It declares a variable whose scope is the loop body. Its expression must be of a class type. If it evaluates to nil, the loop exits. Otherwise its value is stored in the declared variable, the loop body is executed, and the control returns to evaluating the expression again. If the expression’s type is borrowed or unmanaged, the variable’s type is its non-nilable variant (Nilable Class Types). Otherwise the variable stores a borrow of the expression’s value (Class Lifetime and Borrows), and its type is the non-nilable borrowed counterpart of the expression’s type. The variable can be modified within the loop body if it is declared with the var keyword.

The For Loop¶

The for loop iterates over ranges, domains, arrays, iterators, or any class that implements an iterator named these. The syntax of the for loop is given by:

for-statement:
  'for' index-var-declaration 'in' iteratable-expression 'do' statement
  'for' index-var-declaration 'in' iteratable-expression block-statement
  'for' iteratable-expression 'do' statement
  'for' iteratable-expression block-statement

index-var-declaration:
  identifier
  tuple-grouped-identifier-list

iteratable-expression:
  expression
  'zip' ( expression-list )

The index-var-declaration declares new variable(s) for the scope of the loop. It may either specify a single new identifier or multiple identifiers grouped using a tuple notation in order to destructure the values returned by the iterator expression, as described in Splitting a Tuple into Multiple Indices of a Loop.

The index-var-declaration is optional and may be omitted if the indices do not need to be referenced in the loop (in which case the in keyword is omitted as well).

If the iteratable-expression begins with the keyword zip followed by a parenthesized expression-list, the listed expressions must support zippered iteration.

Zippered Iteration¶

When multiple iterand expressions are traversed in a loop using the zip keyword, the corresponding expressions yielded by each iterand are combined into a tuple, represented by the loop’s index variable(s). This is known as zippered iteration. The first iterand in the zip() expression is said to lead the loop’s iterations, determining the size and shape of the iteration space. Subsequent expressions follow the lead iterand. These follower iterands are expected to conform to the number and shape of values yielded by the leader. For example, if the first iterand is a 2D array with m rows and n columns, subsequent iterands will need to support iteration over a 2D m x n space as well.

Example (zipper.chpl).

The output of

for (i, j) in zip(1..3, 4..6) do
  write(i, " ", j, " ");

is

1 4 2 5 3 6

Parameter For Loops¶

Parameter for loops are unrolled by the compiler so that the index variable is a parameter rather than a variable. The syntax for a parameter for loop statement is given by:

param-for-statement:
  'for' 'param' identifier 'in' param-iteratable-expression 'do' statement
  'for' 'param' identifier 'in' param-iteratable-expression block-statement

param-iteratable-expression:
  range-literal
  range-literal 'by' integer-literal

Parameter for loops are restricted to iteration over range literals with an optional by expression where the bounds and stride must be parameters. The loop is then unrolled for each iteration.

The Break, Continue and Label Statements¶

The break- and continue-statements are used to alter the flow of control within a loop construct. A break-statement causes flow to exit the containing loop and resume with the statement immediately following it. A continue-statement causes control to jump to the end of the body of the containing loop and resume execution from there. By default, break- and continue-statements exit or skip the body of the immediately-containing loop construct.

The label-statement is used to name a specific loop so that break and continue can exit or resume a less-nested loop. Labels can only be attached to for-, while-do- and do-while-statements. When a break statement has a label, execution continues with the first statement following the loop statement with the matching label. When a continue statement has a label, execution continues at the end of the body of the loop with the matching label. If there is no containing loop construct with a matching label, a compile-time error occurs.

The syntax for label, break, and continue statements is given by:

break-statement:
  'break' identifier[OPT] ;

continue-statement:
  'continue' identifier[OPT] ;

label-statement:
  'label' identifier statement

A break statement cannot be used to exit a parallel loop The Forall Statement.

Rationale.

Breaks are not permitted in parallel loops because the execution order of the iterations of parallel loops is not defined.

Note

Future:

We expect to support a eureka concept which would enable one or more tasks to stop the execution of all current and future iterations of the loop.

Example.

In the following code, the index of the first element in each row of A that is equal to findVal is printed. Once a match is found, the continue statement is executed causing the outer loop to move to the next row.
label outer for i in 1..n {
  for j in 1..n {
    if A[i, j] == findVal {
      writeln("index: ", (i, j), " matches.");
      continue outer;
    }
  }
}

The Require Statement¶

The require statement provides a means to specify required files from within the program. This forms an alternative to listing them on the command line.

The filenames are relative to the directory from which the Chapel compiler was invoked. Any directories specified using the Chapel compiler’s -I or -L flags will also be searched for matching .h or .a files, respectively. Similarly, filenames that are .chpl files not containing a slash will be searched for in the usual module search path (see also Finding Toplevel Module Files).

require-statement:
  'require' string-or-identifier-list ;

string-or-identifier-list:
  string-or-identifier
  string-or-identifier ',' string-or-identifier-list

string-or-identifier:
  string-literal
  identifier

The require keyword must be followed by list of filenames. Each filename must be a Chapel source file (.chpl), a C source file (.c), a C header file (.h), a precompiled C object file (.o), or a precompiled library archive (lib*.a). When using precompiled library archives, remove the lib and .a parts of the filename and add -l to the beginning as if it were being specified on the command line.

require "foo.h", "-lfoo";

All require statements involving .chpl files must appear at the module-level and each .chpl file must be given by a string literal. For other types, each filename in the require statement must be given by a string literal or an identifier that is a param string expression, such as a param variable or a function returning a param string. Only require statements in code that the compiler considers executable will be processed. Thus, a require statement guarded by a param conditional that the compiler folds out, or in a module that does not appear in the program’s use statements will not be added to the program’s requirements.

Rationale.

Currently, the Chapel compiler parses all .chpl files early in compilation, prior to resolving param strings, calls, or control flow. This imposes more restrictions on .chpl-requiring statements than on other requirements that matter only during the backend compilation. We may consider relaxing these restrictions in the future.

For example, the following code either requires foo.h or whatever requirement is specified by defaultHeader (bar.h by default) depending on the value of requireFoo:

config param requireFoo=true,
             defaultHeader="bar.h";

if requireFoo then
  require "foo.h";
else
  require defaultHeader;

The Use Statement¶

The use statement provides access to the constants in an enumerated type or to the public symbols of a module without the need to use a fully qualified name. When using a module, the statement also ensures that the module symbol itself is visible within the current scope (top-level modules are not otherwise visible without a use).

Use statements can also restrict or rename the set of module symbols that are available within the scope. For further information about use statements, see Using Modules. For more information on enumerated types, please see Enumerated Types. For more information on modules in general, please see Modules.

The Import Statement¶

The import statement provides one of the two primary ways to access a module’s symbols from outside of the module, the other being the use statement. Import statements make either the module’s name or certain symbols within it available for reference within a given scope. For top-level modules, an import or use statement is required before referring to the module’s name or the symbols it contains within a given lexical scope.

Import statements can also rename the set of symbols that they make available within the scope. For further information about import statements, see Importing Modules.

For more information on modules in general, please see Modules.

The Defer Statement¶

A defer statement declares a clean-up action to be run when exiting a block. defer is useful because the clean-up action will be run no matter how the block is exited.

The syntax is:

defer-statement:
  'defer' statement

At each place where control flow exits a block, the compiler will add cleanup actions for the in-scope defer statements that have executed and for the local variables that have been initialized in that block.

The cleanup action for a defer statement is to run its body. The cleanup action for a variable is to run its deinitializer. See Variable Lifetimes.

When a block contains multiple defer statements, their cleanup actions will be run in reverse declaration order. Additionally, note that cleanup actions for defer statements may be interleaved among cleanup actions for variables. To understand the interleaving, imagine that the defer statement is declaring and initializing a local variable with a deinitializer that runs the body of the defer statement.

When an iterator contains a defer statement at the top level, the associated clean-up action will be executed when the loop running the iterator exits. defer actions inside a loop body are executed when that iteration completes.

The following program demonstrates a simple use of defer to create an action to be executed when returning from a function:

Example (defer1.chpl).

class Integer {
  var x:int;
}
proc deferInFunction() {
  var c = new unmanaged Integer(1);
  writeln("created ", c);
  defer {
    writeln("defer action: deleting ", c);
    delete c;
  }
  // ... (function body, possibly including return statements)
  // The defer action is executed no matter how this function returns.
}
deferInFunction();

produces the output

created {x = 1}
defer action: deleting {x = 1}

The following example uses a nested block to demonstrate that defer is handled when exiting the block in which it is contained:

Example (defer2.chpl).

class Integer {
  var x:int;
}
proc deferInNestedBlock() {
  var i = 1;
  writeln("before inner block");
  {
    var c = new unmanaged Integer(i);
    writeln("created ", c);
    defer {
      writeln("defer action: deleting ", c);
      delete c;
    }
    writeln("in inner block");
    // note, defer action is executed no matter how this block is exited
  }
  writeln("after inner block");
}
deferInNestedBlock();

produces the output

before inner block
created {x = 1}
in inner block
defer action: deleting {x = 1}
after inner block

The next example shows that when defer is used in a loop, the action will be executed for every loop iteration, whether or not loop body is exited early.

Example (defer3.chpl).

class Integer {
  var x:int;
}
proc deferInLoop() {
  for i in 1..10 {
    var c = new unmanaged Integer(i);
    writeln("created ", c);
    defer {
      writeln("defer action: deleting ", c);
      delete c;
    }
    writeln(c);
    if i == 2 then
      break;
  }
}
deferInLoop();

produces the output

created {x = 1}
{x = 1}
defer action: deleting {x = 1}
created {x = 2}
{x = 2}
defer action: deleting {x = 2}

Lastly, this example shows that defer statements that have not executed have no effect. Only a defer statement that has executed will have its cleanup action run.

Example (defer4.chpl).

proc deferControl(condition: bool) {
  if condition {
    defer {
      writeln("Inside if");
    }
  }
  return;
  defer {
    writeln("After return");
  }
}
writeln("Condition: false");
deferControl(false);
writeln("Condition: true");
deferControl(true);

produces the output

Condition: false
Condition: true
Inside if

The Empty Statement¶

An empty statement has no effect. The syntax of an empty statement is given by

empty-statement:
  ;

The Manage Statement¶

The manage statement enables participating types to be used as context managers. The syntax of the manage statement is given by

manage-statement:
  'manage' manager-expression-list 'do' statement
  'manage' manager-expression-list block-statement

manager-expression-list:
  manager-expression
  manager-expression-list ',' manager-expression

manager-expression:
  expression 'as' variable-kind identifier
  expression 'as' identifier
  expression

Classes or records that wish to be used as context managers must implement the contextManager interface. This is done by defining the methods enterContext and exitContext, and by adjusting the declaration of the class or record to say that it implements contextManager. The code sample below declares a context manager record IntWrapper and then uses it in a manage statement.

Example (manage1.chpl).

record IntWrapper : contextManager {
  var x: int;
}

proc ref IntWrapper.enterContext() ref: int {
  writeln('entering');
  writeln(this);
  return this.x;
}

proc IntWrapper.exitContext(in error: owned Error?) throws {
  if error then throw error;
  writeln('leaving');
  writeln(this);
}

proc manageIntWrapper() {
  var wrapper = new IntWrapper();
  manage wrapper as val do val = 8;
}
manageIntWrapper();

produces the output

entering
(x = 0)
leaving
(x = 8)

The enterContext() special method is called on the manager expression before executing the managed block (in the above example the manager expression is wrapper). The method may return a type or value, or it may return void.

The resource returned by enterContext() can be captured by name so that it can be referred to within the scope of the managed block (in the above example the captured resource is val).

Capturing a returned resource is optional, and the syntax may be omitted. It is an error to try to capture a resource if enterContext() returns void.

The storage of a captured resource may also be omitted, in which case it will be inferred from the return intent of the enterContext() method (in the above example the storage of val is inferred to be ref).

Resource storage may also be specified explicitly.

Example (manage2.chpl).

record IntWrapper : contextManager {
  var x: int;
}

proc ref IntWrapper.enterContext() ref: int {
  writeln('entering');
  writeln(this);
  return this.x;
}

proc IntWrapper.exitContext(in error: owned Error?) throws {
  if error then throw error;
  writeln('leaving');
  writeln(this);
}

proc manageIntWrapper() {
  var wrapper = new IntWrapper();

  // Here we explicitly declare the resource 'val' as 'var'.
  manage wrapper as var val {
    val = 8;
  }
}
manageIntWrapper();

produces the output

entering
(x = 0)
leaving
(x = 0)

Because the storage of val was specified as var, the integer field of wrapper was not modified even though enterContext() returns by ref.

Note

Open issue:

The enterContext() special method does not currently support the use of return intent overloading (see Return Intent Overloads) when the storage of a resource is omitted. Adding such support would require additional disambiguation rules, and the value of doing so is unclear at this time.

Participating types must also define the exitContext() method, which is called implicitly when the scope of the managed block is exited.

The exitContext() method takes an Error? by in intent. If the error is not nil, it may be handled within the method. It can also be propagated by annotating exitContext() with the throws tag and throwing the error.

Multiple manager expressions may be present in a single manage statement.

Example (manage3.chpl).

record IntWrapper : contextManager {
  var x: int;
}

proc ref IntWrapper.enterContext() ref: int {
  writeln('entering');
  writeln(this);
  return this.x;
}

proc IntWrapper.exitContext(in error: owned Error?) throws {
  if error then throw error;
  writeln('leaving');
  writeln(this);
}

proc manageIntWrapper() {
  var wrapper1 = new IntWrapper(1);
  var wrapper2 = new IntWrapper(2);

  // Here we invoke two managers within a single manage statement.
  manage wrapper1 as val1, wrapper2 as val2 {
    val1 *= -1;
    val2 *= -1;
  }
}
manageIntWrapper();

produces the output

entering
(x = 1)
entering
(x = 2)
leaving
(x = -2)
leaving
(x = -1)

Before executing the code in the body of the manage statement, the enterContext() method is called on each manager from left to right. Upon exiting the managed scope, the exitContext() method is called on each manager from right to left.