The locale Type and Variables¶

The Chapel language has a locale type and a number of built-in variables that permit a programmer to refer to, and reason about, the locales on which the program is running.

The locale Type¶

Locales are represented within Chapel programs using a built-in type named locale. The locale type supports a fixed number of unique values equal to the number of locales on which the program is executing, each value typically corresponding to one of the compute nodes on which the program is executing.

Locale values support methods that permit a programmer to make queries about the target architecture’s capabilities, such as the maximum amount of task parallelism supported or the amount of physical memory available on the locale. For details on this interface, refer to Locale Methods in the Chapel language specification.

As a simple example, each locale value supports an id method that reports its unique (0-based) ID. We’ll see the use of this method in subsequent program examples.

numLocales¶

The variable numLocales is a built-in integer constant indicating the number of locales on which the program is running. For example, when run on four locales, the following program:

examples/users-guide/locality/numLocalesVar.chpl¶

writeln("I'm running on ", numLocales, " locale(s)");

would generate:

I'm running on 4 locale(s)

The Locales Array¶

Chapel programs also have a built-in numLocales-element array, Locales, whose elements are the distinct locale values on which the program is running. This array is defined over a built-in domain, LocaleSpace. Both the domain and array are 1-dimensional and use dense, 0-based indexing.

Each locale value’s ID corresponds to its index in the Locales array. This is demonstrated by the following program which first prints the LocaleSpace domain and then iterates over it, showing that the ID of each value in Locales corresponds to its index:

examples/users-guide/locality/localesDomArr.chpl¶

writeln("LocaleSpace is: ", LocaleSpace);

for i in LocaleSpace do
  writeln("Locale #", i, "'s ID is: ", Locales[i].id);

Running on four locales, its output is:

LocaleSpace is: {0..3}
Locale #0's ID is: 0
Locale #1's ID is: 1
Locale #2's ID is: 2
Locale #3's ID is: 3

here¶

The final built-in locale variable that we’ll cover in this section is here. For any given task, this variable resolves to the locale value on which the task is running.

As an example, the following program demonstrates that Chapel programs begin their execution on locale 0:

examples/users-guide/locality/here-id.chpl¶

writeln("Chapel programs start as a single task running on locale ", here.id);

Running it on any number of locales generates:

Chapel programs start as a single task running on locale 0