Adding some user events to trace the multicasts.
[charm.git] / src / ck-com / MulticastStrategy.h
1 /**
2    @addtogroup ComlibCharmStrategy
3    @{
4    
5    @file 
6    @brief Contains the abstract parent class for all multicast strategies
7    
8 */
9
10 #ifndef MULTICAST_STRATEGY
11 #define MULTICAST_STRATEGY
12
13 #include "ComlibManager.h"
14 #include "ComlibSectionInfo.h"
15
16 /**
17  * Abstract parent class for multicast strategies. All multicast strategies mush inherit
18  * from this.
19  *
20  * The definition of the array section, as well as the location of all the elements in
21  * the processors is determined by the sending processor. All recipient processors will 
22  * deliver messages locally to any array elements whose destination PE in the message is
23  * the local PE. If the element is not located locally, the array manager will handle 
24  * the delivery to the actual location of the element.
25  *
26  */
27 class MulticastStrategy: public Strategy, public CharmStrategy {
28  protected:
29     /// Helper that generates unique ids for successive uses of the strategy.
30     ComlibSectionInfo sinfo;
31     
32     /// A container to hold persistent information about the previously used array sections. 
33     /// The strategy could refer to information here instead of decoding the section info
34     /// from the message.
35     CkHashtableT<ComlibSectionHashKey, ComlibSectionHashObject *> sec_ht; 
36     
37     /// Add this section to the hash table locally.
38     /// This used to be a void function, but to maintain some sanity checking, it now returns the object
39     ComlibSectionHashObject * insertSectionID(CkSectionID *sid, int npes, ComlibMulticastIndexCount *pelist);
40
41     ///Called when a new section multicast is called by the user locally.
42     ///The strategy should then create a topology for it and return a hash
43     ///object to store that topology.
44     virtual void createObjectOnSrcPe(ComlibSectionHashObject *obj, int npes, ComlibMulticastIndexCount *pelist)=0;
45
46     /**   
47      * Similar to createHashObjectOnSrcPe, but that this call is made on the
48      * destination or intermediate processor. It receives all the information in
49      * the parameters, and it does not use ComlibLastKnown, since in some cases
50      * it can be incoherent.
51
52      * @param nindices number of local elements to multicast
53      * @param idxlist list of local elements
54      * @param npes number of processors involved in the multicast
55      * @param counts list of all the processors involved int the multicast
56      * @param srcpe processor which started the multicast
57      * @return a hash object describing the section
58      */
59     virtual void createObjectOnIntermediatePe(ComlibSectionHashObject *obj, int npes, ComlibMulticastIndexCount *counts, int srcpe)=0;
60         
61     /// Needed for getNewMulticastMessage, to specify if the list of processors
62     /// need to be ordered. By default it doesn't.
63     virtual int needSorting() { return 0; }
64
65     /// Called to multicast the message to local array elements.
66     virtual void localMulticast(envelope *env, ComlibSectionHashObject *obj, CkMcastBaseMsg *msg);
67     
68     /// Called to send to message out to the remote destinations.
69     /// This method can be overridden to call converse level strategies.
70     virtual void remoteMulticast(envelope *env, ComlibSectionHashObject *obj);
71
72     /// This function is called when a multicast is received with a new section
73     /// definition. Process the new message by extracting the array elements
74     /// from it and creating a new hash object by calling
75     /// createObjectOnIntermediatePe(). Objects are deleting from the hashtable
76     /// only during spring cleaning.
77     void handleNewMulticastMessage(envelope *env);
78
79  public:
80
81     MulticastStrategy(CkMigrateMessage *m): Strategy(m), CharmStrategy(m){}
82     
83     ///Array constructor
84     MulticastStrategy();
85     
86     //Destuctor
87     ~MulticastStrategy();
88
89     void insertMessage(MessageHolder *msg) {insertMessage((CharmMessageHolder*)msg);}
90     void insertMessage(CharmMessageHolder *msg);
91
92     //    void doneInserting();        // Not needed because this is not a bracketed strategy
93
94     ///Called by the converse handler function
95     void handleMessage(void *msg);    
96
97     virtual void pup(PUP::er &p);
98     
99     PUPable_abstract(MulticastStrategy);
100 };
101 #endif
102
103 /*@}*/