doc: attempt to chapterize the advanced topics
[charm.git] / doc / charm++ / advancedarrays.tex
1 The basic array features described before (creation, messaging,
2 broadcasts, and reductions) are needed in almost every
3 \charmpp{} program.  The more advanced techniques that follow
4 are not universally needed; but are still often useful.
5
6 \subsubsection{Local Access}
7
8 \index{ckLocal for arrays}
9 \label{ckLocal for arrays}
10 You can get direct access to a local array element using the
11 proxy's \kw{ckLocal} method, which returns an ordinary \CC\ pointer
12 to the element if it exists on the local processor; and NULL if
13 the element does not exist or is on another processor.
14
15 \begin{alltt}
16 A1 *a=a1[i].ckLocal();
17 if (a==NULL) //...is remote-- send message
18 else //...is local-- directly use members and methods of a
19 \end{alltt}
20
21 Note that if the element migrates or is deleted, any pointers 
22 obtained with \kw{ckLocal} are no longer valid.  It is best,
23 then, to either avoid \kw{ckLocal} or else call \kw{ckLocal} 
24 each time the element may have migrated; e.g., at the start 
25 of each entry method.
26
27 \subsubsection{Advanced Array Creation}
28
29 \label{advanced array create}
30 There are several ways to control the array creation process.
31 You can adjust the map and bindings before creation, change
32 the way the initial array elements are created, create elements
33 explicitly during the computation, and create elements implicitly,
34 ``on demand''.  
35
36 You can create all your elements using any one of these methods,
37 or create different elements using different methods.  
38 An array element has the same syntax and semantics no matter
39 how it was created.  
40
41 \subsubsection{Advanced Array Creation: CkArrayOptions}
42
43 \index{CkArrayOptions}
44 \label{CkArrayOptions}
45
46 The array creation method \kw{ckNew} actually takes a parameter
47 of type \kw{CkArrayOptions}.  This object describes several
48 optional attributes of the new array.
49
50 The most common form of \kw{CkArrayOptions} is to set the number
51 of initial array elements.  A \kw{CkArrayOptions} object will be 
52 constructed automatically in this special common case.  Thus
53 the following code segments all do exactly the same thing:
54
55 \begin{alltt}
56 //Implicit CkArrayOptions
57   a1=CProxy_A1::ckNew(\uw{parameters},nElements);
58
59 //Explicit CkArrayOptions
60   a1=CProxy_A1::ckNew(\uw{parameters},CkArrayOptions(nElements));
61
62 //Separate CkArrayOptions
63   CkArrayOptions opts(nElements);
64   a1=CProxy_A1::ckNew(\uw{parameters},opts);
65 \end{alltt}
66
67 Note that the ``numElements'' in an array element is simply the
68 numElements passed in when the array was created.  The true number of
69 array elements may grow or shrink during the course of the
70 computation, so numElements can become out of date.  This ``bulk''
71 constructor approach should be preferred where possible, especially
72 for large arrays.  Bulk construction is handled via a broadcast which
73 will be significantly more efficient in the number of messages
74 required than inserting each element individually which will require
75 one message send per element.
76
77 \kw{CkArrayOptions} contains a few flags that the runtime can use to
78 optimize handling of a given array. If the array elements will only
79 migrate at controlled points (such as periodic load balancing with
80 {\tt AtASync()}), this is signalled to the runtime by calling {\tt
81   opts.setAnytimeMigration(false)}\footnote{At present, this optimizes
82 broadcasts to not save old messages for immigrating chares.}. If all
83 array elements will be inserted by bulk creation or by {\tt
84   fooArray[x].insert()} calls, signal this by calling {\tt
85   opts.setStaticInsertion(true)} \footnote{This can enable a slightly
86   faster default mapping scheme.}.
87
88 \subsubsection{Advanced Array Creation: Map Object}
89
90 \index{array map}
91 \label{array map}
92
93 You can use \kw{CkArrayOptions} to specify a ``map object''
94 for an array.  The map object is used by the array manager
95 to determine the ``home'' processor of each element.  The
96 home processor is the processor responsible for maintaining
97 the location of the element.
98
99 There is a default map object, which maps 1D array indices
100 in a block fashion to processors, and maps other array
101 indices based on a hash function. Some other mappings such as round-robin
102 (\kw{RRMap}) also exist, which can be used
103 similar to custom ones described below.
104
105 A custom map object is implemented as a group which inherits from
106 \kw{CkArrayMap} and defines these virtual methods:
107
108 \begin{alltt}
109 class CkArrayMap : public Group
110 \{
111 public:
112   //...
113   
114   //Return an ``arrayHdl'', given some information about the array
115   virtual int registerArray(CkArrayIndex& numElements,CkArrayID aid);
116   //Return the home processor number for this element of this array
117   virtual int procNum(int arrayHdl,const CkArrayIndex &element);
118 \}
119 \end{alltt}
120
121 For example, a simple 1D blockmapping scheme.  Actual mapping is
122 handled in the procNum function.
123
124 \begin{alltt}
125 class BlockMap : public CkArrayMap 
126 \{
127  public:
128   BlockMap(void) \{\}
129   BlockMap(CkMigrateMessage *m)\{\}
130   int registerArray(CkArrayIndex& numElements,CkArrayID aid) \{
131     return 0;
132   \}
133   int procNum(int /*arrayHdl*/,const CkArrayIndex &idx) \{
134     int elem=*(int *)idx.data();
135     int penum =  (elem/(32/CkNumPes()));
136     return penum;
137   \}
138 \};
139
140 \end{alltt}
141 Once you've instantiated a custom map object, you can use it to
142 control the location of a new array's elements using the
143 \kw{setMap} method of the \kw{CkArrayOptions} object described above.
144 For example, if you've declared a map object named ``BlockMap'':
145
146 \begin{alltt}
147 //Create the map group
148   CProxy_BlockMap myMap=CProxy_BlockMap::ckNew();
149 //Make a new array using that map
150   CkArrayOptions opts(nElements);
151   opts.setMap(myMap);
152   a1=CProxy_A1::ckNew(\uw{parameters},opts);
153 \end{alltt}
154
155
156
157 \subsubsection{Advanced Array Creation: Initial Elements}
158
159 \index{array initial}
160 \label{array initial}
161
162 The map object described above can also be used to create
163 the initial set of array elements in a distributed fashion.
164 An array's initial elements are created by its map object,
165 by making a call to \kw{populateInitial} on each processor.
166
167 You can create your own set of elements by creating your
168 own map object and overriding this virtual function of \kw{CkArrayMap}:
169
170 \begin{alltt}
171   virtual void populateInitial(int arrayHdl,int numInitial,
172         void *msg,CkArrMgr *mgr)
173 \end{alltt}
174
175 In this call, \kw{arrayHdl} is the value returned by \kw{registerArray},
176 \kw{numInitial} is the number of elements passed to \kw{CkArrayOptions},
177 \kw{msg} is the constructor message to pass, and \kw{mgr} is the
178 array to create.
179
180 \kw{populateInitial} creates new array elements using the method
181 \kw{void CkArrMgr::insertInitial(CkArrayIndex idx,void *ctorMsg)}.
182 For example, to create one row of 2D array elements on each processor,
183 you would write:
184
185 \begin{alltt}
186 void xyElementMap::populateInitial(int arrayHdl,int numInitial,
187         void *msg,CkArrMgr *mgr)
188 \{
189   if (numInitial==0) return; //No initial elements requested
190         
191   //Create each local element
192   int y=CkMyPe();
193   for (int x=0;x<numInitial;x++) \{
194     mgr->insertInitial(CkArrayIndex2D(x,y),CkCopyMsg(&msg));
195   \}
196   mgr->doneInserting();
197   CkFreeMsg(msg);
198 \}
199 \end{alltt}
200
201 Thus calling \kw{ckNew(10)} on a 3-processor machine would result in
202 30 elements being created.
203
204
205 \subsubsection{Advanced Array Creation: Bound Arrays}
206
207 \index{bound arrays} \index{bindTo}
208 \label{bound arrays}
209 You can ``bind'' a new array to an existing array
210 using the \kw{bindTo} method of \kw{CkArrayOptions}.  Bound arrays
211 act like separate arrays in all ways except for migration--
212 corresponding elements of bound arrays always migrate together.
213 For example, this code creates two arrays A and B which are
214 bound together-- A[i] and B[i] will always be on the same processor.
215
216 \begin{alltt}
217 //Create the first array normally
218   aProxy=CProxy_A::ckNew(\uw{parameters},nElements);
219 //Create the second array bound to the first
220   CkArrayOptions opts(nElements);
221   opts.bindTo(aProxy);
222   bProxy=CProxy_B::ckNew(\uw{parameters},opts);
223 \end{alltt}
224
225 An arbitrary number of arrays can be bound together--
226 in the example above, we could create yet another array
227 C and bind it to A or B.  The result would be the same
228 in either case-- A[i], B[i], and C[i] will always be
229 on the same processor.
230
231 There is no relationship between the types of bound arrays--
232 it is permissible to bind arrays of different types or of the
233 same type.  It is also permissible to have different numbers
234 of elements in the arrays, although elements of A which have
235 no corresponding element in B obey no special semantics.
236 Any method may be used to create the elements of any bound
237 array.
238
239 Bound arrays are often useful if A[i] and B[i] perform different 
240 aspects of the same computation, and thus will run most efficiently 
241 if they lie on the same processor.  Bound array elements are guaranteed
242 to always be able to interact using \kw{ckLocal} (see 
243 section~\ref{ckLocal for arrays}), although the local pointer must
244 be refreshed after any migration. This should be done during the \kw{pup}
245 routine. When migrated, all elements that are bound together will be created
246 at the new processor before \kw{pup} is called on any of them, ensuring that
247 a valid local pointer to any of the bound objects can be obtained during the
248 \kw{pup} routine of any of the others.
249
250 For example, an array {\it Alibrary} is implemented as a library module.
251 It implements a certain functionality by operating on a data array {\it dest}
252 which is just a pointer to some user provided data.
253 A user defined array {\it UserArray} is created and bound to 
254 the array {\it Alibrary} to take advanatage of the functionality provided 
255 by the library.
256 When bound array element migrated, the {\it data} pointer in {\it UserArray}
257 is re-allocated in {\it pup()}, thus {\it UserArray} is responsible to refresh
258 the pointer {\it dest} stored in {\it Alibrary}.
259
260 \begin{alltt}
261 class Alibrary: public CProxy_Alibrary \{
262 public:
263   ...
264   void set_ptr(double *ptr) \{ dest = ptr; \}
265   virtual void pup(PUP::er &p);
266 private:
267   double *dest;           // point to user data in user defined bound array
268 \};
269
270 class UserArray: public CProxy_UserArray \{
271 public:
272   virtual void pup(PUP::er &p) \{
273                 p|len;
274                 if(p.isUnpacking()) \{ 
275                   data = new double[len];
276                   Alibrary *myfellow = AlibraryProxy(thisIndex).ckLocal();
277                   myfellow->set_ptr(data);    // refresh data in bound array
278                 \}
279                 p(data, len);
280   \}
281 private:
282   CProxy_Alibrary  AlibraryProxy;   // proxy to my bound array
283   double *data;          // user allocated data pointer
284   int len;
285 \};
286 \end{alltt}
287
288
289 \subsubsection{Advanced Array Creation: Dynamic Insertion}
290
291 \label{dynamic_insertion}
292
293 In addition to creating initial array elements using ckNew,
294 you can also
295 create array elements during the computation.
296
297 You insert elements into the array by indexing the proxy
298 and calling insert.  The insert call optionally takes 
299 parameters, which are passed to the constructor; and a
300 processor number, where the element will be created.
301 Array elements can be inserted in any order from 
302 any processor at any time.  Array elements need not 
303 be contiguous.
304
305 If using \kw{insert} to create all the elements of the array,
306 you must call \kw{CProxy\_Array::doneInserting} before using
307 the array.
308
309 \begin{alltt}
310 //In the .C file:
311 int x,y,z;
312 CProxy_A1 a1=CProxy_A1::ckNew();  //Creates a new, empty 1D array
313 for (x=...) \{
314    a1[x  ].insert(\uw{parameters});  //Bracket syntax
315    a1(x+1).insert(\uw{parameters});  // or equivalent parenthesis syntax
316 \}
317 a1.doneInserting();
318
319 CProxy_A2 a2=CProxy_A2::ckNew();   //Creates 2D array
320 for (x=...) for (y=...)
321    a2(x,y).insert(\uw{parameters});  //Can't use brackets!
322 a2.doneInserting();
323
324 CProxy_A3 a3=CProxy_A3::ckNew();   //Creates 3D array
325 for (x=...) for (y=...) for (z=...)
326    a3(x,y,z).insert(\uw{parameters});
327 a3.doneInserting();
328
329 CProxy_AF aF=CProxy_AF::ckNew();   //Creates user-defined index array
330 for (...) \{
331    aF[CkArrayIndexFoo(...)].insert(\uw{parameters}); //Use brackets...
332    aF(CkArrayIndexFoo(...)).insert(\uw{parameters}); //  ...or parenthesis
333 \}
334 aF.doneInserting();
335
336 \end{alltt}
337
338 The \kw{doneInserting} call starts the reduction manager (see ``Array
339 Reductions'') and load balancer (see ~\ref{lbFramework})-- since
340 these objects need to know about all the array's elements, they
341 must be started after the initial elements are inserted.
342 You may call \kw{doneInserting} multiple times, but only the first
343 call actually does anything.  You may even \kw{insert} or \kw{destroy}
344 elements after a call to \kw{doneInserting}, with different semantics-- 
345 see the reduction manager and load balancer sections for details.
346
347 If you do not specify one, the system will choose a processor to 
348 create an array element on based on the current map object.
349
350
351
352 \subsubsection{Advanced Array Creation: Demand Creation}
353
354 Normally, invoking an entry method on a nonexistant array
355 element is an error.  But if you add the attribute
356 \index{createhere} \index{createhome}
357 \kw{[createhere]} or \kw{[createhome]} to an entry method,
358  the array manager will 
359 ``demand create'' a new element to handle the message.  
360
361 With \kw{[createhome]}, the new element
362 will be created on the home processor, which is most efficient when messages for
363 the element may arrive from anywhere in the machine. With \kw{[createhere]},
364 the new element is created on the sending processor, which is most efficient
365 if when messages will often be sent from that same processor.
366
367 The new element is created by calling its default (taking no
368 parameters) constructor, which must exist and be listed in the .ci file.
369 A single array can have a mix of demand-creation and
370 classic entry methods; and demand-created and normally 
371 created elements.
372
373
374
375 \subsubsection{User-defined Array Index Type}
376 \label{user-defined array index type}
377
378 \index{Array index type, user-defined}
379 \charmpp{} array indices are arbitrary collections of integers.
380 To define a new array index, you create an ordinary C++ class 
381 which inherits from \kw{CkArrayIndex} and sets the ``nInts'' member
382 to the length, in integers, of the array index.
383
384 For example, if you have a structure or class named ``Foo'', you 
385 can use a \uw{Foo} object as an array index by defining the class:
386
387 \begin{alltt}
388 #include <charm++.h>
389 class CkArrayIndexFoo:public CkArrayIndex \{
390     Foo f;
391 public:
392     CkArrayIndexFoo(const Foo \&in) 
393     \{
394         f=in;
395         nInts=sizeof(f)/sizeof(int);
396     \}
397     //Not required, but convenient: cast-to-foo operators
398     operator Foo &() \{return f;\}
399     operator const Foo &() const \{return f;\}
400 \};
401 \end{alltt}
402
403 Note that \uw{Foo}'s size must be an integral number of integers--
404 you must pad it with zero bytes if this is not the case.
405 Also, \uw{Foo} must be a simple class-- it cannot contain 
406 pointers, have virtual functions, or require a destructor.
407 Finally, there is a \charmpp\ configuration-time option called
408 CK\_ARRAYINDEX\_MAXLEN \index{CK\_ARRAYINDEX\_MAXLEN} 
409 which is the largest allowable number of 
410 integers in an array index.  The default is 3; but you may 
411 override this to any value by passing ``-DCK\_ARRAYINDEX\_MAXLEN=n'' 
412 to the \charmpp\ build script as well as all user code. Larger 
413 values will increase the size of each message.
414
415 You can then declare an array indexed by \uw{Foo} objects with
416
417 \begin{alltt}
418 //in the .ci file:
419 array [Foo] AF \{ entry AF(); ... \}
420
421 //in the .h file:
422 class AF : public CBase\_AF
423 \{ public: AF() \{\} ... \}
424
425 //in the .C file:
426     Foo f;
427     CProxy_AF a=CProxy_AF::ckNew();
428     a[CkArrayIndexFoo(f)].insert();
429     ...
430 \end{alltt}
431
432 Note that since our CkArrayIndexFoo constructor is not declared
433 with the explicit keyword, we can equivalently write the last line as:
434
435 \begin{alltt}
436     a[f].insert();
437 \end{alltt}
438
439 When you implement your array element class, as shown above you 
440 can inherit from \kw{CBase}\_\uw{ClassName}, 
441 a class templated by the index type \uw{Foo}. In the old syntax,
442 you could also inherit directly from \kw{ArrayElementT}.
443 The array index (an object of type \uw{Foo}) is then accessible as 
444 ``thisIndex''. For example:
445
446 \begin{alltt}
447
448 //in the .C file:
449 AF::AF()
450 \{
451     Foo myF=thisIndex;
452     functionTakingFoo(myF);
453 \}
454 \end{alltt}
455
456 %\subsubsection{Load Balancing Chare Arrays}
457
458 %see section~\ref{lbFramework}
459
460 \subsubsection{Array Section}
461
462 \label{array section}
463
464 \charmpp{} supports the array section operation, the section operation identifies a subset of array 
465 elements from a chare array for access via a single section proxy. \charmpp{} also supports array sections
466 which are a subset of array elements in multiple chare arrays of the
467 same type \ref{cross array section}.
468 A special proxy for an array section can be created given a list of array
469 indexes of elements.
470 Multicast operations, a broadcast to all members of a section, are directly supported in array section proxy with
471 an unoptimized direct-sending implementation.
472 Section reduction is not directly supported by the section proxy. 
473 However, an optimized section multicast/reduction 
474 library called ''CkMulticast'' is provided as a separate library module,
475 which can be plugged in as a delegation of a section proxy for performing
476 section-based multicasts and reductions using optimized spanning trees. 
477
478 For each chare array "A" declared in a ci file, a section proxy 
479 of type "CProxySection\_A" is automatically generated in the decl and def 
480 header files. 
481 In order to create an array section, the user needs to provide array indexes 
482 of all the array section members through either explicit enumeration, or an index range expression.
483 You can create an array section proxy in your application by 
484 invoking ckNew() function of the CProxySection.
485 For example, for a 3D array:
486
487 \begin{alltt}
488   CkVec<CkArrayIndex3D> elems;    // add array indices
489   for (int i=0; i<10; i++)
490     for (int j=0; j<20; j+=2)
491       for (int k=0; k<30; k+=2)
492          elems.push_back(CkArrayIndex3D(i, j, k));
493   CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, elems.getVec(), elems.size());
494 \end{alltt}
495
496 Alternatively, one can do the same thing by providing the index range [lbound:ubound:stride] 
497 for each dimension:
498
499 \begin{alltt}
500   CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, 0, 9, 1, 0, 19, 2, 0, 29, 2);
501 \end{alltt}
502
503 The above codes create a section proxy that contains array elements of 
504 [0:9, 0:19:2, 0:29:2].
505
506 For user-defined array index other than CkArrayIndex1D to CkArrayIndex6D,
507 one needs to use the generic array index type: CkArrayIndex.
508
509 \begin{alltt}
510   CkArrayIndex *elems;    // add array indices
511   int numElems;
512   CProxySection_Hello proxy = CProxySection_Hello::ckNew(helloArrayID, elems, numElems);
513 \end{alltt}
514
515 Once you have the array section proxy, you can broadcast to all the 
516 section members, or send messages to one member using its offset index within the section, like these:
517
518 \begin{alltt}
519   CProxySection_Hello proxy;
520   proxy.someEntry(...)          // section broadcast
521   proxy[0].someEntry(...)       // send to the first element in the section.
522 \end{alltt}
523
524 You can send the section proxy in a message to another processor, and still 
525 safely invoke the entry functions on the section proxy.
526
527 In the broadcast example above, for a section with k members, a total
528 number of k messages will be sent, one to each member, which is
529 inefficient when several members are on a same processor, in which
530 case only one message needs to be sent to that processor and delivered
531 to all section members on that processor locally. To support this
532 optimization, a separate library called CkMulticast is provided as a
533 target for delegation to an optimized implementation. This library
534 also supports section based reduction.
535
536 Note: Use of the bulk array constructor (dimensions given in the CkNew
537 or CkArrayOptions rather than individual insertion) will allow
538 construction to race ahead of several other startup procedures, this
539 creates some limitation on the construction delegation and use of
540 array section proxies.  For safety, array sections should be
541 created in a post constructor entry method.
542
543
544 \label {array_section_multicast}
545
546
547 To use the library, you need to compile and install CkMulticast library and 
548 link your applications against the library using -module:
549
550 \begin{alltt}
551   # compile and install the CkMulticast library, do this only once
552   # assuming a net-linux-x86\_64 build
553   cd charm/net-linux-x86\_64/tmp
554   make multicast
555
556   # link CkMulticast library using -module when compiling application
557   charmc  -o hello hello.o -module CkMulticast -language charm++ 
558 \end{alltt}
559
560 The CkMulticast library is implemented using delegation(Sec. ~\ref{delegation}). 
561 A special ''CkMulticastMgr'' Chare Group is created as a 
562 delegation for section multicast/reduction - all the messages sent
563 by the section proxy will be passed to the local delegation branch.
564
565 To use the CkMulticast delegation, one needs to create the CkMulticastMgr Group 
566 first, and then setup the delegation relationship between the section proxy and 
567 CkMulticastMgr Group. 
568 One only needs to create one CkMulticastMgr Group globally.
569 CkMulticastMgr group can serve all multicast/reduction delegations
570 for different array sections in an application:
571
572 \begin{alltt}
573   CProxySection_Hello sectProxy = CProxySection_Hello::ckNew(...);
574   CkGroupID mCastGrpId = CProxy_CkMulticastMgr::ckNew();
575   CkMulticastMgr *mCastGrp = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
576
577   sectProxy.ckSectionDelegate(mCastGrp);  // initialize section proxy
578
579   sectProxy.someEntry(...)           //multicast via delegation library as before
580 \end{alltt}
581
582 By default, CkMulticastMgr group builds a spanning tree for multicast/reduction
583 with a factor of 2 (binary tree).
584 One can specify a different factor when creating a CkMulticastMgr group.
585 For example,
586
587 \begin{alltt}
588   CkGroupID mCastGrpId = CProxy_CkMulticastMgr::ckNew(3);   // factor is 3
589 \end{alltt}
590
591 Note, to use CkMulticast library, all multicast messages must inherit from 
592 CkMcastBaseMsg, as the following.
593 Note that CkMcastBaseMsg must come first, this is IMPORTANT for CkMulticast 
594 library to retrieve section information out of the message.
595
596
597 \begin{alltt}
598 class HiMsg : public CkMcastBaseMsg, public CMessage_HiMsg
599 \{
600 public:
601   int *data;
602 \};
603 \end{alltt}
604
605 Due to this restriction, you must define message explicitly for multicast 
606 entry functions and no parameter marshalling can be used for multicast with 
607 CkMulticast library.
608
609 \paragraph{Array Section Reduction} 
610
611 Since an array element can be a member of multiple array sections, 
612 it is necessary to disambiguate between which array
613 section reduction it is participating in each time it contributes to one. For this purpose, a data structure 
614 called ''CkSectionInfo'' is created by CkMulticastMgr for each 
615 array section that the array element belongs to.
616 During a section reduction, the array element must pass the 
617 \kw{CkSectionInfo} as a parameter in the \kw{contribute()}. 
618 The \kw{CkSectionInfo} for a section can be retrieved
619 from a message in a multicast entry point using function call 
620 \kw{CkGetSectionInfo}:
621
622 \begin{alltt}
623   CkSectionInfo cookie;
624
625   void SayHi(HiMsg *msg)
626   \{
627     CkGetSectionInfo(cookie, msg);     // update section cookie every time
628     int data = thisIndex;
629     mcastGrp->contribute(sizeof(int), &data, CkReduction::sum_int, cookie);
630   \}
631 \end{alltt}
632
633 Note that the cookie cannot be used as a one-time local variable in the 
634 function, the same cookie is needed for the next contribute. This is 
635 because the cookie includes some context sensive information (e.g., the 
636 reduction counter). Subsequent invocations of \kw{CkGetSectionInfo()} only updates part of the data in the cookie, rather than creating a brand new one.
637
638 Similar to array reduction, to use section based reduction, a
639 reduction client CkCallback object must be created. You may pass the
640 client callback as an additional parameter to \kw{contribute}. If
641 different contribute calls to the same reduction operation pass
642 different callbacks, some (unspecified, unreliable) callback will be
643 chosen for use. 
644
645 See the following example:
646
647 \begin{alltt}
648     CkCallback cb(CkIndex_myArrayType::myReductionEntry(NULL),thisProxy); 
649     mcastGrp->contribute(sizeof(int), &data, CkReduction::sum_int, cookie, cb);
650 \end{alltt}
651
652 If no member passes a callback to contribute, the reduction will use the 
653 default callback. You set the default callback for an array section using the 
654 \kw{setReductionClient} call in the section root member. A 
655 {\bf CkReductionMsg} message will be passed to this callback, which 
656 must delete the message when done.
657
658 \begin{alltt}
659   CProxySection_Hello sectProxy;
660   CkMulticastMgr *mcastGrp = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
661   mcastGrp->setReductionClient(sectProxy, new CkCallback(...));
662 \end{alltt}
663
664 As in an array reduction, users can use built-in reduction 
665 types(Section~\ref{builtin_reduction}) or define his/her own reducer functions
666 (Section~\ref{new_type_reduction}).
667
668 \paragraph{Array section multicast/reduction when migration happens}
669
670 Using multicast/reduction, you don't need to worry about array migrations.
671 When migration happens, array element in the array section can still use 
672 the \kw{CkSectionInfo} it stored previously for doing reduction. 
673 Reduction messages will be correctly delivered but may not be as efficient 
674 until a new multicast spanning tree is rebuilt internally 
675 in \kw{CkMulticastMgr} library. 
676 When a new spanning tree is rebuilt, a updated \kw{CkSectionInfo} is 
677 passed along with a multicast message, 
678 so it is recommended that 
679 \kw{CkGetSectionInfo()} function is always called when a multicast 
680 message arrives (as shown in the above SayHi example).
681
682 In case when a multicast root migrates, the library must reconstruct the 
683 spanning tree to get optimal performance. One will get the following
684 warning message if not doing so:
685 "Warning: Multicast not optimized after multicast root migrated."
686 In current implementation, user needs to initiate the rebuilding process
687 using \kw{resetSection}.
688
689 \begin{alltt}
690 void Foo::pup(PUP::er & p) {
691     // if I am multicast root and it is unpacking
692    if (ismcastroot && p.isUnpacking()) {
693       CProxySection_Foo   fooProxy;    // proxy for the section
694       CkMulticastMgr *mg = CProxy_CkMulticastMgr(mCastGrpId).ckLocalBranch();
695       mg->resetSection(fooProxy);
696         // you may want to reset reduction client to root
697       CkCallback *cb = new CkCallback(...);
698       mg->setReductionClient(mcp, cb);
699    }
700 }
701 \end{alltt}
702
703 \paragraph{Cross Array Sections}
704
705
706 \experimental{}
707 \label{cross array section}
708
709 Cross array sections contain elements from multiple arrays.
710 Construction and use of cross array sections is similar to normal
711 array sections with the following restrictions.  
712
713 \begin{itemize}
714
715 \item Arrays in a section my all be of the same type.
716
717 \item Each array must be enumerated by array ID
718
719 \item The elements within each array must be enumerated explicitly
720
721 \item No existing modules currently support delegation of cross
722   section proxies.  Therefore reductions are not currently supported.
723
724 \end{itemize}
725
726 Note: cross section logic also works for groups with analogous characteristics.
727
728 Given three arrays declared thusly:
729
730 \begin{alltt}
731           CkArrayID *aidArr= new CkArrayID[3];
732           CProxy\_multisectiontest\_array1d *Aproxy= new CProxy\_multisectiontest\_array1d[3];
733           for(int i=0;i<3;i++)
734             \{
735               Aproxy[i]=CProxy\_multisectiontest\_array1d::ckNew(masterproxy.ckGetGroupID(),ArraySize);   
736               aidArr[i]=Aproxy[i].ckGetArrayID();
737             \}
738 \end{alltt}
739
740 One can make a section including the  lower half elements of all three
741 arrays as follows:
742
743 \begin{alltt}
744           int aboundary=ArraySize/2;
745           int afloor=aboundary;
746           int aceiling=ArraySize-1;
747           int asectionSize=aceiling-afloor+1;
748           // cross section lower half of each array
749           CkArrayIndex **aelems= new CkArrayIndex*[3];
750           aelems[0]= new CkArrayIndex[asectionSize];
751           aelems[1]= new CkArrayIndex[asectionSize];
752           aelems[2]= new CkArrayIndex[asectionSize];
753           int *naelems=new int[3];
754           for(int k=0;k<3;k++)
755             \{
756               naelems[k]=asectionSize;
757               for(int i=afloor,j=0;i<=aceiling;i++,j++)
758                 aelems[k][j]=CkArrayIndex1D(i);
759             \}
760           CProxySection\_multisectiontest\_array1d arrayLowProxy(3,aidArr,aelems,naelems);
761 \end{alltt}
762
763
764
765 The resulting cross section proxy, as in the example \uw{arrayLowProxy},
766 can then be used for multicasts in the same way as a normal array
767 section.
768
769 Note: For simplicity the example has all arrays and sections of uniform
770 size.  The size of each array and the number of elements in each array
771 within a section can all be set independently.
772
773