Cleanup custom array index example and fix bad documentation 57/5057/3
authorEric Mikida <epmikida@hpccharm.com>
Wed, 3 Apr 2019 21:29:21 +0000 (17:29 -0400)
committerEvan Ramos <evan@hpccharm.com>
Fri, 5 Apr 2019 03:34:56 +0000 (22:34 -0500)
Change-Id: I3a152278b6717d8887cca87b207a95b28f134580

doc/charm++/manual.rst
examples/charm++/hello/fancyarray/hello.C
examples/charm++/hello/fancyarray/hello.ci

index 9556ac0f6ae38207d5473c7637d5b862534b09ee..6baf57e625baae045032ae685725dcfc4ae3ef85 100644 (file)
@@ -5976,79 +5976,73 @@ User-defined Array Indices
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Charm++ array indices are arbitrary collections of integers. To define a
-new array index, you create an ordinary C++ class which inherits from
-CkArrayIndex and sets the “nInts” member to the length, in integers, of
-the array index.
+new array index type, you create an ordinary C++ class which inherits from
+CkArrayIndex, allocates custom data in the space it has set aside for index
+data, and sets the “nInts” member to the length, in integers, of the custom
+index data.
 
 For example, if you have a structure or class named “Foo”, you can use a
 Foo object as an array index by defining the class:
 
 ::
 
-   #include <charm++.h>
+    // Include to inherit from CkArrayIndex
+    #include <charm++.h>
 
-   class CkArrayIndexFoo : public CkArrayIndex {
-       Foo f;
-   public:
-       CkArrayIndexFoo(const Foo &in)
-       {
-           f=in;
-           nInts=sizeof(f)/sizeof(int);
-       }
-       // Not required, but convenient: cast-to-foo operators
-       operator Foo &() {return f;}
-       operator const Foo &() const {return f;}
-   };
+    class CkArrayIndexFoo : public CkArrayIndex {
+    private:
+      Foo* f;
+    public:
+      CkArrayIndexFoo(const Foo &in) {
+        f = new (index) Foo(in);
+        nInts = sizeof(Foo)/sizeof(int);
+      }
+    };
 
-Note that Foo’s size must be an integral number of integers- you must
-pad it with zero bytes if this is not the case. Also, Foo must be a
-simple class- it cannot contain pointers, have virtual functions, or
-require a destructor. Finally, there is a Charm++ configuration-time
-option called CK_ARRAYINDEX_MAXLEN which is the largest allowable number
-of integers in an array index. The default is 3; but you may override
-this to any value by passing “-DCK_ARRAYINDEX_MAXLEN=n” to the
-Charm++ build script as well as all user code. Larger values will
-increase the size of each message.
+Note that Foo must be allocated using placement new pointing to the "index"
+member of CkArrayIndex. Furthermore, its size must be an integral number of
+integers- you must pad it with zero bytes if this is not the case. Also, Foo
+must be a simple class- it cannot contain pointers, have virtual functions, or
+require a destructor. Finally, there is a Charm++ configuration-time option
+called CK_ARRAYINDEX_MAXLEN which is the largest allowable number of integers
+in an array index. The default is 3; but you may override this to any value by
+passing “-DCK_ARRAYINDEX_MAXLEN=n” to the Charm++ build script as well as all
+user code. Larger values will increase the size of each message.
 
 You can then declare an array indexed by Foo objects with
 
 ::
 
-   // in the .ci file:
-   array [Foo] AF { entry AF(); ... }
+    // in the .ci file:
+    array [Foo] AF { entry AF(); ... }
 
-   // in the .h file:
-   class AF : public CBase_AF
-   { public: AF() {} ... }
+    // in the .h file:
+    class AF : public CBase_AF
+    { public: AF() {} ... }
 
-   // in the .C file:
-   Foo f;
-   CProxy_AF a=CProxy_AF::ckNew();
-   a[CkArrayIndexFoo(f)].insert();
-   ...
+    // in the .C file:
+    Foo f;
+    CProxy_AF a=CProxy_AF::ckNew();
+    a[CkArrayIndexFoo(f)].insert();
+    ...
 
 Note that since our CkArrayIndexFoo constructor is not declared with the
 explicit keyword, we can equivalently write the last line as:
 
 ::
 
-       a[f].insert();
+    a[f].insert();
 
-When you implement your array element class, as shown above you can
-inherit from CBase_ClassName, a class templated by the index type Foo.
-In the old syntax, you could also inherit directly from ArrayElementT.
-The array index (an object of type Foo) is then accessible as
-“thisIndex”. For example:
+The array index (an object of type Foo) is then accessible as “thisIndex”. For
+example:
 
 ::
 
-
-   // in the .C file:
-   AF::AF()
-   {
-       Foo myF=thisIndex;
-       functionTakingFoo(myF);
-   }
+    // in the .C file:
+    AF::AF() {
+      Foo myF=thisIndex;
+      functionTakingFoo(myF);
+    }
 
 A demonstration of user defined indices can be seen in
 ``examples/charm++/hello/fancyarray``.
index 535fd991af6999a3643dd00f579c1bea78dfdaaa..f659898a8e578d2a24dcbe708b282a7c2ee6536a 100644 (file)
@@ -1,43 +1,46 @@
 #include <stdio.h>
+
+// *MUST* include "charm++.h" to inherit from CkArrayIndex
 #include "charm++.h"
 
-//*MUST* declare index type *BEFORE* we include hello.decl.h!
+// *MUST* declare index type *BEFORE* we include hello.decl.h!
 
-//This is our application-specific index type.  It's a
-//  completely ordinary C++ class (or even C struct)-- the
-//  only requirement is that all the data be allocated
-//  locally (no pointers, no virtual methods).
+// This is our application-specific index type. It's a completely ordinary C++
+// class (or even C struct) -- the only requirement is that all the data be
+// allocated locally (no pointers, no virtual methods).
 class Fancy {
-       int a,b;
+private:
+  int a,b;
 public:
-       Fancy() :a(0), b(0) {}
-       Fancy(int a_,int b_) :a(a_), b(b_) {}
-       Fancy next(void) const 
-               {return Fancy(b-a,b+1);}
-       int cardinality(void) const 
-               {return b;}
-       int getA(void) const {return a;}
-       int getB(void) const {return b;}        
+  Fancy() : a(0), b(0) {}
+  Fancy(int a_,int b_) : a(a_), b(b_) {}
+  Fancy next(void) const  { return Fancy(b-a,b+1); }
+  int cardinality(void) const { return b; }
+  int getA(void) const { return a; }
+  int getB(void) const { return b; }
 };
 
-//This adapts the application's index for use by the array
-// manager.  This class is only used by the translator--
-// you never need to refer to it again!
+// This adapts the application's index for use by the array manager. This class
+// is only used by the translator -- you never need to refer to it again!
 class CkArrayIndexFancy : public CkArrayIndex {
-       Fancy *idx;
+private:
+  Fancy* idx;
 public:
-    CkArrayIndexFancy() 
-    {
-        /// Use placement new to ensure that the custom index object is placed in the memory reserved for it in the base class
-        idx = new(index) Fancy(); 
-    }
+  CkArrayIndexFancy() {
+    // Use placement new to ensure that the custom index object is placed in the
+    // memory reserved for it in the base class.
+    idx = new(index) Fancy();
+    // Set nInts in CkArrayIndex to the size of our custom index data (in ints)
+    nInts = sizeof(Fancy) / sizeof(int);
+  }
 
-       CkArrayIndexFancy(const Fancy &f)
-       {
-        /// Use placement new to ensure that the custom index object is placed in the memory reserved for it in the base class
-        idx = new(index) Fancy(f);
-               nInts=2;
-       }
+  CkArrayIndexFancy(const Fancy& f) {
+    // Use placement new to ensure that the custom index object is placed in the
+    // memory reserved for it in the base class.
+    idx = new(index) Fancy(f);
+    // Set nInts in CkArrayIndex to the size of our custom index data (in ints)
+    nInts = sizeof(Fancy) / sizeof(int);
+  }
 };
 
 #include "hello.decl.h"
@@ -46,62 +49,57 @@ public:
 /*readonly*/ int nElements;
 
 /*mainchare*/
-class Main : public CBase_Main
-{
+class Main : public CBase_Main {
 public:
-  Main(CkArgMsg* m)
-  {
+  Main(CkArgMsg* m) {
     //Process command-line arguments
-    nElements=5;
-    if(m->argc >1 ) nElements=atoi(m->argv[1]);
+    nElements = 5;
+    if (m->argc >1 ) nElements=atoi(m->argv[1]);
     delete m;
 
     //Start the computation
     CkPrintf("Running Hello on %d processors for %d elements\n",
-            CkNumPes(),nElements);
-    mainProxy = thisProxy;
+        CkNumPes(), nElements);
 
+    mainProxy = thisProxy;
     CProxy_Hello arr = CProxy_Hello::ckNew();
     const Fancy startIndex(23,0);
-    Fancy f=startIndex;
-    for (int i=0;i<nElements;i++) {
+    Fancy f = startIndex;
+    for (int i = 0; i < nElements; i++) {
       arr[f].insert();
-      f=f.next();
+      f = f.next();
     }
     arr.doneInserting();
 
     arr[startIndex].SayHi(17);
   };
 
-  void done(void)
-  {
+  void done(void) {
     CkPrintf("All done\n");
     CkExit();
   };
 };
 
 /*array [Fancy]*/
-class Hello : public CBase_Hello
-{
+class Hello : public CBase_Hello {
 public:
-  Hello()
-  {
-    //Note how thisIndex is of type fancyIndex:
+  Hello() {
+    // Note how thisIndex is of type fancyIndex:
     CkPrintf("Hello (%d,%d) created on %d\n",
-       thisIndex.getA(),thisIndex.getB(),CkMyPe());
+        thisIndex.getA(), thisIndex.getB(), CkMyPe());
   }
 
   Hello(CkMigrateMessage *m) {}
-  
-  void SayHi(int hiNo)
-  {
+
+  void SayHi(int hiNo) {
     CkPrintf("Hi[%d] from element %d\n",hiNo,thisIndex.cardinality());
-    if (thisIndex.cardinality() < nElements-1)
+    if (thisIndex.cardinality() < nElements-1) {
       //Pass the hello on:
       thisProxy[thisIndex.next()].SayHi(hiNo+1);
-    else 
+    } else {
       //We've been around once-- we're done.
       mainProxy.done();
+    }
   }
 };
 
index 0391078b57eaf264c2221e69de366f4a823be00e..bef8a3c1aa450d08dbc7732e0f81f07446db156c 100644 (file)
@@ -3,12 +3,12 @@ mainmodule hello {
   readonly int nElements;
 
   mainchare Main {
-    entry Main(CkArgMsg *);
-    entry void done(void);
+    entry Main(CkArgMsg*);
+    entry void done();
   };
 
   array [Fancy] Hello {
-    entry Hello(void);
+    entry Hello();
     entry void SayHi(int hiNo);
-  };           
+  };
 };