Querying a Local Subdomain

While writing a distributed program, one might need to know the index set that a certain locale owns in a given distributed array, domain, or distribution. This README describes the initial support for this functionality.

For code examples using these features, see the distributions.chpl primer.

Functions Supported on Array and Domain Types

hasSingleLocalSubdomain

proc array.hasSingleLocalSubdomain() : bool;
proc domain.hasSingleLocalSubdomain() : bool;

This is a param function which returns a boolean. If true, then the index set owned by a locale can be represented by a single domain. For example:

Distribution	hasSingleLocalSubdomain()
Block	true
Cyclic	true
BlockCyclic	false
Replicated	true

This function always returns true for non-distributed arrays and domains.

To support this function on a custom domain map, write a param function named dsiHasSingleLocalSubdomain.

localSubdomain

proc array.localSubdomain(loc: locale = here) : domain;
proc domain.localSubdomain(loc: locale = here) : domain;

This function only operates on arrays and domains whose hasSingleLocalSubdomain() result is true. Otherwise, a compile-time error is issued.

This function returns a single domain that represents the index set owned by the given locale, which defaults to here. This returned domain cannot be used to modify the index set owned by the locale.

To support this function on a custom domain map, write a function named dsiLocalSubdomain. For example:

proc BlockArr.dsiLocalSubdomain(loc: locale) : domain;

localSubdomains

iter array.localSubdomains(loc: locale = here) : domain;
iter domain.localSubdomains(loc: locale = here) : domain;

This iterator yields the subdomain(s) that represent the index set owned by the given locale, which defaults to here

If the locale’s index set can be represented by a single domain, then the result of localSubdomain is yielded.

Currently, this is a serial iterator.

To support this iterator on a custom domain map, write an iterator named dsiLocalSubdomains. For example:

iter BlockCyclicArr.dsiLocalSubdomains(loc: locale) : domain;

Functions Supported on Arrays, Domains, and Distributions

targetLocales

proc array.targetLocales() : [] locale;
proc domain.targetLocales() : [] locale;
proc distribution.targetLocales() : [] locale;

This function returns an array of locales that the distribution uses as the locale grid.