3.7 Basic Arrays

Arrays are arbitrarily-sized collections of chares. The entire array has a globally unique identifier of type CkArrayID, and each element has a unique index of type CkArrayIndex. A CkArrayIndex can be a single integer (i.e. 1D array), several integers (i.e. a multidimensional array), or an arbitrary string of bytes (e.g. a binary tree index).

Array elements can be dynamically created and destroyed on any processor, and messages for the elements will still arrive properly. Array elements can be migrated at any time, allowing arrays to be efficiently load balanced. Array elements can also receive array broadcasts and contribute to array reductions.

3.7.1 Declaring a 1D Array

You can declare a one-dimensional chare array as:

//In the .ci file:
array [1D] A {
  entry A(parameters1);
  entry void someEntry(parameters2);
};

Just as every Chare inherits from the system class CBase_ClassName, every array element inherits from the system class CBase_ClassName. Just as a Chare inherits ``thishandle'', each array element inherits ``thisArrayID'', the CkArrayID of its array, and ``thisIndex'', the element's array index. As well as chares are allowed to inherit directly from class Chare, array elements are allowed to inherit from ArrayElement1D if 1D array, ArrayElement2D if 2D array, and so on up to 6D.

class A : public CBase_A {
  public:
    A(parameters1);
    A(CkMigrateMessage *);

    void someEntry(parameters2);
};

Note A's odd migration constructor, which is normally empty:

//In the .C file:
A::A(void)
{
  //...your constructor code...
}
A::A(CkMigrateMessage *m) { }

Read the section ``Migratable Array Elements'' for more information on the CkMigrateMessage constructor.

3.7.2 Creating a Simple Array

You always create an array using the CProxy_Array::ckNew routine. This returns a proxy object, which can be kept, copied, or sent in messages. To create a 1D array containing elements indexed (0, 1, ..., num_elements-1), use:

CProxy_A1 a1 = CProxy_A1::ckNew(parameters,num_elements);

The constructor is invoked on each array element. For creating higher-dimensional arrays, or for more options when creating the array, see section 3.8.2.

3.7.3 Messages

An array proxy responds to the appropriate index call- for 1D arrays, use [i] or (i); for 2D use (x,y); for 3D use (x,y,z); and for user-defined types use [f] or (f).

To send a message to an array element, index the proxy and call the method name:

a1[i].doSomething(parameters);
a3(x,y,z).doAnother(parameters);
aF[CkArrayIndexFoo(...)].doAgain(parameters);

You may invoke methods on array elements that have not yet been created- by default, the system will buffer the message until the element is created¹³.

Messages are not guarenteed to be delivered in order. For example, if I invoke a method A, then method B; it is possible for B to be executed before A.

a1[i].A();
a1[i].B();

Messages sent to migrating elements will be delivered after the migrating element arrives. It is an error to send a message to a deleted array element.

3.7.4 Broadcasts

To broadcast a message to all the current elements of an array, simply omit the index, as:

a1.doIt(parameters); //<- invokes doIt on each array element

The broadcast message will be delivered to every existing array element exactly once. Broadcasts work properly even with ongoing migrations, insertions, and deletions.

3.7.5 Reductions on Chare Arrays

A reduction applies a single operation (e.g. add, max, min, ...) to data items scattered across many processors and collects the result in one place. CHARM++ supports reductions on the elements of a Chare array.

The data to be reduced comes from each array element, which must call the contribute method:

ArrayElement::contribute(int nBytes,const void *data,CkReduction::reducerType type);

Reductions are described in more detail in Section 3.14.

3.7.6 Destroying Arrays

To destroy an array element- detach it from the array, call its destructor, and release its memory-invoke its Array destroy method, as:

a1[i].ckDestroy();

You must ensure that no messages are sent to a deleted element. After destroying an element, you may insert a new element at its index.