Docs: refer to illinois.edu, not uiuc.edu
[charm.git] / doc / charm++ / delegation.tex
1 {\em Delegation} is a means by which a library writer can 
2 intercept messages sent via a proxy.  This is typically
3 used to construct communication libraries.
4 A library creates a special kind of Group called a 
5 \kw{DelegationManager}, which receives the messages
6 sent via a delegated proxy.
7
8 There are two parts to the delegation interface-- a
9 very small client-side interface to enable delegation,
10 and a more complex manager-side interface to handle
11 the resulting redirected messages.
12
13 \section{Client Interface}
14
15 All proxies (Chare, Group, Array, ...) in \charmpp\ 
16 support the following delegation routines.
17
18 \function{void CProxy::ckDelegate(CkGroupID delMgr);}
19 Begin delegating messages sent via this proxy to the
20 given delegation manager. This only affects
21 the proxy it is called on-- other proxies for the
22 same object are {\em not} changed. If the proxy is 
23 already delegated, this call changes the delegation manager.
24
25 \function{CkGroupID CProxy::ckDelegatedIdx(void) const;}
26 Get this proxy's current delegation manager.
27
28 \function{void CProxy::ckUndelegate(void);}
29 Stop delegating messages sent via this proxy.  
30 This restores the proxy to normal operation.
31
32 One use of these routines might be:
33
34 \begin{alltt}
35   CkGroupID mgr=somebodyElsesCommLib(...);
36   CProxy_foo p=...;
37   p.someEntry1(...); //Sent to foo normally
38   p.ckDelegate(mgr);
39   p.someEntry2(...); //Handled by mgr, not foo!
40   p.someEntry3(...); //Handled by mgr again
41   p.ckUndelegate();
42   p.someEntry4(...); //Back to foo
43 \end{alltt}
44
45 The client interface is very simple; but it is often
46 not called by users directly.  Often the delegate 
47 manager library needs some other initialization,
48 so a more typical use would be:
49
50 \begin{alltt}
51   CProxy_foo p=...;
52   p.someEntry1(...); //Sent to foo normally
53   startCommLib(p,...); // Calls ckDelegate on proxy
54   p.someEntry2(...); //Handled by library, not foo!
55   p.someEntry3(...); //Handled by library again
56   finishCommLib(p,...); // Calls ckUndelegate on proxy
57   p.someEntry4(...); //Back to foo
58 \end{alltt}
59
60 Sync entry methods, group and nodegroup multicast messages,
61 and messages for virtual chares that have not yet been created
62 are never delegated.  Instead, these kinds of entry methods
63 execute as usual, even if the proxy is delegated.
64
65 \section{Manager Interface}
66
67 A delegation manager is a group which inherits from
68 \kw{CkDelegateMgr} and overrides certain virtual methods. 
69 Since \kw{CkDelegateMgr} does not do any communication itself, 
70 it need not be mentioned in the
71 .ci file; you can simply declare a group as usual and
72 inherit the C++ implementation from \kw{CkDelegateMgr}.
73
74 Your delegation manager will be called by \charmpp{}
75 any time a proxy delegated to it is used.  Since
76 any kind of proxy can be delegated, there are separate
77 virtual methods for delegated Chares, Groups, NodeGroups,
78 and Arrays.
79
80 \begin{alltt}
81 class CkDelegateMgr : public Group {
82 public:
83   virtual void ChareSend(int ep,void *m,const CkChareID *c,int onPE);
84
85   virtual void GroupSend(int ep,void *m,int onPE,CkGroupID g);
86   virtual void GroupBroadcast(int ep,void *m,CkGroupID g);
87
88   virtual void NodeGroupSend(int ep,void *m,int onNode,CkNodeGroupID g);
89   virtual void NodeGroupBroadcast(int ep,void *m,CkNodeGroupID g);
90
91   virtual void ArrayCreate(int ep,void *m,const CkArrayIndex &idx,int onPE,CkArrayID a);
92   virtual void ArraySend(int ep,void *m,const CkArrayIndex &idx,CkArrayID a);
93   virtual void ArrayBroadcast(int ep,void *m,CkArrayID a);
94   virtual void ArraySectionSend(int ep,void *m,CkArrayID a,CkSectionID &s);
95 };
96 \end{alltt}
97
98 These routines are called on the send side only.  They are called after 
99 parameter marshalling; but before the messages are packed.
100 The parameters passed in have the following descriptions.
101
102 \begin{enumerate}
103 \item{{\bf ep} The entry point begin called, passed as an index into the
104 \charmpp{} entry table.  This information is also stored in the message's
105 header; it is duplicated here for convenience.}
106 \item{{\bf m} The \charmpp{} message.  This is a pointer to the start of the
107 user data; use the system routine \kw{UsrToEnv} to get the corresponding envelope.
108 The messages are not necessarily packed; be sure to use \kw{CkPackMessage}.}
109 \item{{\bf c} The destination \kw{CkChareID}.  This information is already
110 stored in the message header.}
111 \item{{\bf onPE} The destination processor number. For chare messages, this
112 indicates the processor the chare lives on.  For group messages, this indicates
113 the destination processor.  For array create messages, this indicates the 
114 desired processor.}
115 \item{{\bf g} The destination \kw{CkGroupID}.  This is also stored in the 
116 message header.}
117 \item{{\bf onNode} The destination node.}
118 \item{{\bf idx} The destination array index.  This may be looked up using
119 the lastKnown method of the array manager, e.g., using:
120   \begin{alltt}
121   int lastPE=CProxy_CkArray(a).ckLocalBranch()->lastKnown(idx);
122   \end{alltt} }
123 \item{{\bf s} The destination array section.}
124 \end{enumerate}
125
126
127 The \kw{CkDelegateMgr} superclass implements all these methods; so
128 you only need to implement those you wish to optimize.  You can
129 also call the superclass to do the final delivery after you've
130 sent your messages.
131
132
133