doc: Add serial to list of ci file reserved words
[charm.git] / src / ck-ldb / lbdb.h
1 /**
2  * \addtogroup CkLdb
3 */
4 /*@{*/
5
6 #ifndef LBDBH_H
7 #define LBDBH_H
8
9 #include "converse.h"
10 #include "charm.h"
11 #include "middle.h"
12
13 class LBDatabase;//Forward declaration
14
15 //typedef float floatType;
16 // type defined by build option
17 #ifndef CMK_LBTIME_TYPE
18 #define CMK_LBTIME_TYPE double
19 #endif
20 typedef CMK_LBTIME_TYPE LBRealType;
21
22 #define COMPRESS_LDB    1
23
24 extern int _lb_version;
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 typedef void* cvoid; /* To eliminate warnings, because a C void* is not
31                         the same as a C++ void* */
32
33   /*  User-defined object ID is 4 ints long (as defined in converse.h) */
34   /*  as OBJ_ID_SZ */
35
36 #if CMK_LBDB_ON
37 typedef struct {
38   void *handle;            // pointer to LBDB
39 } LDHandle;
40 #else
41 typedef int LDHandle;
42 #endif
43
44 typedef struct _LDOMid {
45   CkGroupID id;
46   CmiBool operator==(const struct _LDOMid& omId) const {
47     return id == omId.id?CmiTrue:CmiFalse;
48   }
49   CmiBool operator<(const struct _LDOMid& omId) const {
50     return id < omId.id?CmiTrue:CmiFalse;
51   }
52   CmiBool operator!=(const struct _LDOMid& omId) const {
53     return id == omId.id?CmiFalse:CmiTrue;
54   }
55   inline void pup(PUP::er &p);
56 } LDOMid;
57
58 typedef struct {
59   LDHandle ldb;
60 //  void *user_ptr;
61   LDOMid id;
62   int handle;           // index to LBOM
63   inline void pup(PUP::er &p);
64 } LDOMHandle;
65
66 typedef struct _LDObjid {
67   int id[OBJ_ID_SZ];
68 #if CMK_GLOBAL_LOCATION_UPDATE
69   char dimension;
70   char nInts;
71   char isArrayElement;
72   char locMgrGid; 
73 #endif
74   CmiBool operator==(const struct _LDObjid& objid) const {
75     for (int i=0; i<OBJ_ID_SZ; i++) if (id[i] != objid.id[i]) return CmiFalse;
76     return CmiTrue;
77   }
78   CmiBool operator<(const struct _LDObjid& objid) const {
79     for (int i=0; i<OBJ_ID_SZ; i++) {
80       if (id[i] < objid.id[i]) return CmiTrue;
81       else if (id[i] > objid.id[i]) return CmiFalse;
82     }
83     return CmiFalse;
84   }
85   inline void pup(PUP::er &p);
86 } LDObjid;
87
88 /* LDObjKey uniquely identify one object */
89 typedef struct _LDObjKey {
90   /// Id of the location manager for this object
91   LDOMid omId;
92   LDObjid objId;
93 public:
94   CmiBool operator==(const _LDObjKey& obj) const {
95     return (CmiBool)(omId == obj.omId && objId == obj.objId);
96   }
97   CmiBool operator<(const _LDObjKey& obj) const {
98     if (omId < obj.omId) return CmiTrue;
99     else if (omId == obj.omId) return objId < obj.objId;
100     else return CmiFalse;
101   }
102   inline LDOMid &omID() { return omId; }
103   inline LDObjid &objID() { return objId; }
104   inline const LDOMid &omID() const { return omId; }
105   inline const LDObjid &objID() const { return objId; }
106   inline void pup(PUP::er &p);
107 } LDObjKey;
108
109 typedef int LDObjIndex;
110 typedef int LDOMIndex;
111
112 typedef struct {
113   LDOMHandle omhandle;
114   LDObjid id;
115   LDObjIndex  handle;
116   inline const LDOMid &omID() const { return omhandle.id; }
117   inline const LDObjid &objID() const { return id; }
118   inline void pup(PUP::er &p);
119 } LDObjHandle;
120
121 typedef struct {
122   LDObjHandle handle;
123   LBRealType wallTime;
124 #if CMK_LB_CPUTIMER
125   LBRealType cpuTime;
126 #endif
127 #if ! COMPRESS_LDB
128   LBRealType minWall, maxWall;
129 #endif
130   CmiBool migratable;
131   CmiBool asyncArrival;
132   inline const LDOMHandle &omHandle() const { return handle.omhandle; }
133   inline const LDOMid &omID() const { return handle.omhandle.id; }
134   inline const LDObjid &objID() const { return handle.id; }
135   inline const LDObjid &id() const { return handle.id; }
136   inline void pup(PUP::er &p);
137 } LDObjData;
138
139 /* used by load balancer */
140 typedef struct {
141   int index;
142   LDObjData data;
143   int from_proc;
144   int to_proc;
145   inline void pup(PUP::er &p);
146 } LDObjStats;
147
148 #define LD_PROC_MSG      1
149 #define LD_OBJ_MSG       2
150 #define LD_OBJLIST_MSG   3
151
152 typedef struct _LDCommDesc {
153   char type;
154   union {
155     int destProc;               /* 1:   processor level message */
156     struct{
157       LDObjKey  destObj;                /* 2:   object based message    */
158       int destObjProc;
159     } destObj;
160     struct {
161       LDObjKey  *objs;
162       int len;
163     } destObjs;                 /* 3:   one to many message     */
164   } dest;
165   char &get_type() { return type; }
166   char get_type() const { return type; }
167   int proc() const { return type==LD_PROC_MSG?dest.destProc:-1; }
168   void setProc(int pe) { CmiAssert(type==LD_PROC_MSG); dest.destProc = pe; }
169   int lastKnown() const { 
170     if (type==LD_OBJ_MSG) return dest.destObj.destObjProc;
171     if (type==LD_PROC_MSG) return dest.destProc;
172     return -1;
173   }
174   LDObjKey &get_destObj() 
175         { CmiAssert(type==LD_OBJ_MSG); return dest.destObj.destObj; }
176   LDObjKey const &get_destObj() const 
177         { CmiAssert(type==LD_OBJ_MSG); return dest.destObj.destObj; }
178   LDObjKey * get_destObjs(int &len) 
179         { CmiAssert(type==LD_OBJLIST_MSG); len=dest.destObjs.len; return dest.destObjs.objs; }
180   void init_objmsg(LDOMid &omid, LDObjid &objid, int destObjProc) { 
181         type=LD_OBJ_MSG; 
182         dest.destObj.destObj.omID()=omid;
183         dest.destObj.destObj.objID() =objid;
184         dest.destObj.destObjProc = destObjProc;
185   }
186   void init_mcastmsg(LDOMid &omid, LDObjid *objid, int len) { 
187         type=LD_OBJLIST_MSG; 
188         dest.destObjs.len = len;
189         dest.destObjs.objs = new LDObjKey[len];
190         for (int i=0; i<len; i++) {
191           dest.destObjs.objs[i].omID()=omid;
192           dest.destObjs.objs[i].objID() =objid[i];
193         }
194   }
195   inline CmiBool operator==(const _LDCommDesc &obj) const;
196   inline _LDCommDesc &operator=(const _LDCommDesc &c);
197   inline void pup(PUP::er &p);
198 } LDCommDesc;
199
200 typedef struct {
201   int src_proc;                 // sender can either be a proc or an obj
202   LDObjKey  sender;             // 
203   LDCommDesc   receiver;
204   int  sendHash, recvHash;
205   int messages;
206   int bytes;
207   inline int from_proc() const { return (src_proc != -1); }
208   inline int recv_type() const { return receiver.get_type(); }
209   inline void pup(PUP::er &p);
210   inline void clearHash() { sendHash = recvHash = -1; }
211 } LDCommData;
212
213 /*
214  * Requests to load balancer
215  *   FIXME: these routines don't seem to exist anywhere-- are they obsolete?
216  *   Are the official versions now in LBDatabase.h?
217  */
218 void LBBalance(void *param);
219 void LBCollectStatsOn(void);
220 void LBCollectStatsOff(void);
221
222 /*
223  * Callbacks from database to object managers
224  */
225 typedef void (*LDMigrateFn)(LDObjHandle handle, int dest);
226 typedef void (*LDStatsFn)(LDOMHandle h, int state);
227 typedef void (*LDQueryEstLoadFn)(LDOMHandle h);
228 typedef void (*LDMetaLBResumeWaitingCharesFn) (LDObjHandle handle, int lb_ideal_period);
229 typedef void (*LDMetaLBCallLBOnCharesFn) (LDObjHandle handle);
230
231 typedef struct {
232   LDMigrateFn migrate;
233   LDStatsFn setStats;
234   LDQueryEstLoadFn queryEstLoad;
235   LDMetaLBResumeWaitingCharesFn metaLBResumeWaitingChares;
236   LDMetaLBCallLBOnCharesFn metaLBCallLBOnChares;
237 } LDCallbacks;
238
239 /*
240  * Calls from object managers to load database
241  */
242 #if CMK_LBDB_ON
243 LDHandle LDCreate(void);
244 #else
245 #define LDCreate() 0
246 #endif
247
248 LDOMHandle LDRegisterOM(LDHandle _lbdb, LDOMid userID, 
249                         void *userptr, LDCallbacks cb);
250
251 void LDOMMetaLBResumeWaitingChares(LDHandle _h, int lb_ideal_period);
252 void LDOMMetaLBCallLBOnChares(LDHandle _h);
253 void * LDOMUserData(LDOMHandle &_h);
254 void LDRegisteringObjects(LDOMHandle _h);
255 void LDDoneRegisteringObjects(LDOMHandle _h);
256
257 LDObjHandle LDRegisterObj(LDOMHandle h, LDObjid id, void *userptr,
258                           int migratable);
259 void LDUnregisterObj(LDObjHandle h);
260
261 void * LDObjUserData(LDObjHandle &_h);
262 void LDObjTime(LDObjHandle &h, LBRealType walltime, LBRealType cputime);
263 int  CLDRunningObject(LDHandle _h, LDObjHandle* _o );
264 void LDObjectStart(const LDObjHandle &_h);
265 void LDObjectStop(const LDObjHandle &_h);
266 void LDSend(const LDOMHandle &destOM, const LDObjid &destid, unsigned int bytes, int destObjProc, int force);
267 void LDMulticastSend(const LDOMHandle &destOM, LDObjid *destids, int ndests, unsigned int bytes, int nMsgs);
268
269 void LDMessage(LDObjHandle from, 
270                LDOMid toOM, LDObjid *toID, int bytes);
271
272 void LDEstObjLoad(LDObjHandle h, double load);
273 void LDNonMigratable(const LDObjHandle &h);
274 void LDMigratable(const LDObjHandle &h);
275 void LDAsyncMigrate(const LDObjHandle &h, CmiBool);
276 void LDDumpDatabase(LDHandle _lbdb);
277
278 /*
279  * Calls from load balancer to load database
280  */  
281 typedef void (*LDMigratedFn)(void* data, LDObjHandle handle, int waitBarrier);
282 void LDNotifyMigrated(LDHandle _lbdb, LDMigratedFn fn, void* data);
283
284 typedef void (*LDStartLBFn)(void *user_ptr);
285 void LDAddStartLBFn(LDHandle _lbdb, LDStartLBFn fn, void* data);
286 void LDRemoveStartLBFn(LDHandle _lbdb, LDStartLBFn fn);
287 void LDStartLB(LDHandle _db);
288 void LDTurnManualLBOn(LDHandle _lbdb);
289 void LDTurnManualLBOff(LDHandle _lbdb);
290
291 typedef void (*LDMigrationDoneFn)(void *user_ptr);
292 int LDAddMigrationDoneFn(LDHandle _lbdb, LDMigrationDoneFn fn,  void* data);
293 void  LDRemoveMigrationDoneFn(LDHandle _lbdb, LDMigrationDoneFn fn);
294 void LDMigrationDone(LDHandle _lbdb);
295
296 typedef void (*LDPredictFn)(void* user_ptr);
297 typedef void (*LDPredictModelFn)(void* user_ptr, void* model);
298 typedef void (*LDPredictWindowFn)(void* user_ptr, void* model, int wind);
299 void LDTurnPredictorOn(LDHandle _lbdb, void *model);
300 void LDTurnPredictorOnWin(LDHandle _lbdb, void *model, int wind);
301 void LDTurnPredictorOff(LDHandle _lbdb);
302 void LDChangePredictor(LDHandle _lbdb, void *model);
303 void LDCollectStatsOn(LDHandle _lbdb);
304 void LDCollectStatsOff(LDHandle _lbdb);
305 int  CLDCollectingStats(LDHandle _lbdb);
306 void LDQueryEstLoad(LDHandle bdb);
307 void LDGetObjLoad(LDObjHandle &h, LBRealType *wallT, LBRealType *cpuT);
308 void LDQueryKnownObjLoad(LDObjHandle &h, LBRealType *wallT, LBRealType *cpuT);
309
310 int LDGetObjDataSz(LDHandle _lbdb);
311 void LDGetObjData(LDHandle _lbdb, LDObjData *data);
312
313 int LDGetCommDataSz(LDHandle _lbdb);
314 void LDGetCommData(LDHandle _lbdb, LDCommData *data);
315
316 void LDBackgroundLoad(LDHandle _lbdb, LBRealType *walltime, LBRealType *cputime);
317 void LDIdleTime(LDHandle _lbdb, LBRealType *walltime);
318 void LDTotalTime(LDHandle _lbdb, LBRealType *walltime, LBRealType *cputime);
319 void LDGetTime(LDHandle _db, LBRealType *total_walltime,LBRealType *total_cputime,
320                    LBRealType *idletime, LBRealType *bg_walltime, LBRealType *bg_cputime);
321
322 void LDClearLoads(LDHandle _lbdb);
323 int  LDMigrate(LDObjHandle h, int dest);
324 void LDMigrated(LDObjHandle h, int waitBarrier);
325
326 /*
327  * Local Barrier calls
328  */
329 typedef void (*LDBarrierFn)(void *user_ptr);
330 typedef void (*LDResumeFn)(void *user_ptr);
331
332 typedef struct {
333   int serial;
334 } LDBarrierClient;
335
336 typedef struct {
337   int serial;
338 } LDBarrierReceiver;
339
340 LDBarrierClient LDAddLocalBarrierClient(LDHandle _lbdb,LDResumeFn fn,
341                                         void* data);
342 void LDRemoveLocalBarrierClient(LDHandle _lbdb, LDBarrierClient h);
343 LDBarrierReceiver LDAddLocalBarrierReceiver(LDHandle _lbdb,LDBarrierFn fn,
344                                             void* data);
345 void LDRemoveLocalBarrierReceiver(LDHandle _lbdb,LDBarrierReceiver h);
346 void LDAtLocalBarrier(LDHandle _lbdb, LDBarrierClient h);
347 void LDLocalBarrierOn(LDHandle _db);
348 void LDLocalBarrierOff(LDHandle _db);
349 void LDResumeClients(LDHandle _lbdb);
350 int LDProcessorSpeed();
351 CmiBool LDOMidEqual(const LDOMid &i1, const LDOMid &i2);
352 CmiBool LDObjIDEqual(const LDObjid &i1, const LDObjid &i2);
353
354 /*
355  *  LBDB Configuration calls
356  */
357 void LDSetLBPeriod(LDHandle _db, double s);
358 double LDGetLBPeriod(LDHandle _db);
359
360 int LDMemusage(LDHandle _db);
361
362 #ifdef __cplusplus
363 }
364 #endif /* _cplusplus */
365
366 const LDObjHandle &LDGetObjHandle(LDHandle h, int idx);
367
368 #if CMK_LBDB_ON
369 PUPbytes(LDHandle)
370 #endif
371
372 inline void LDOMid::pup(PUP::er &p) {
373   id.pup(p);
374 }
375 PUPmarshall(LDOMid)
376
377 inline void LDObjid::pup(PUP::er &p) {
378   for (int i=0; i<OBJ_ID_SZ; i++) p|id[i];
379 #if CMK_GLOBAL_LOCATION_UPDATE
380   p|dimension;
381   p|nInts;
382   p|isArrayElement;
383   p|locMgrGid;
384 #endif
385 }
386 PUPmarshall(LDObjid)
387
388 inline void LDObjKey::pup(PUP::er &p) {
389   p|omId;
390   p|objId;
391 }
392 PUPmarshall(LDObjKey)
393
394 inline void LDObjStats::pup(PUP::er &p) {
395   p|index;
396   p|data;
397   p|from_proc;
398   p|to_proc;
399 }
400 PUPmarshall(LDObjStats)
401 inline void LDOMHandle::pup(PUP::er &p) {
402   // skip ldb since it is a pointer
403   int ptrSize = sizeof(void *);
404   p|ptrSize;
405   // if pointer size is not expected, must be in simulation mode
406   // ignore this field
407   if (p.isUnpacking() && ptrSize != sizeof(void *)) {  
408     char dummy;
409     for (int i=0; i<ptrSize; i++) p|dummy;
410   }
411   else
412     p|ldb;
413   p|id;
414   p|handle;
415 }
416 PUPmarshall(LDOMHandle)
417
418 inline void LDObjHandle::pup(PUP::er &p) {
419   p|omhandle;
420   p|id;
421   p|handle;
422 }
423 PUPmarshall(LDObjHandle)
424
425 inline void LDObjData::pup(PUP::er &p) {
426   p|handle;
427   p|wallTime;
428 #if CMK_LB_CPUTIMER
429   p|cpuTime;
430 #endif
431 #if ! COMPRESS_LDB
432   p|minWall;
433   p|maxWall;
434 #endif
435   p|migratable;
436   if (_lb_version > -1) p|asyncArrival;
437 }
438 PUPmarshall(LDObjData)
439
440 inline CmiBool LDCommDesc::operator==(const LDCommDesc &obj) const {
441     if (type != obj.type) return CmiFalse;
442     switch (type) {
443     case LD_PROC_MSG: return (CmiBool)(dest.destProc == obj.dest.destProc);
444     case LD_OBJ_MSG:  return (CmiBool)(dest.destObj.destObj == obj.dest.destObj.destObj);
445     case LD_OBJLIST_MSG: { if (dest.destObjs.len != obj.dest.destObjs.len) 
446                                return CmiFalse;
447                            for (int i=0; i<dest.destObjs.len; i++)
448                              if (!(dest.destObjs.objs[i] == obj.dest.destObjs.objs[i])) return CmiFalse;
449                            return CmiTrue; }
450     }
451     return CmiFalse;
452 }
453 inline LDCommDesc & LDCommDesc::operator=(const LDCommDesc &c) {
454     type = c.type;
455     switch (type) {
456     case LD_PROC_MSG: dest.destProc = c.dest.destProc; break;
457     case LD_OBJ_MSG:  dest.destObj.destObj = c.dest.destObj.destObj; break;
458     case LD_OBJLIST_MSG: { dest.destObjs.len = c.dest.destObjs.len;
459                            dest.destObjs.objs = new LDObjKey[dest.destObjs.len];
460                            for (int i=0; i<dest.destObjs.len; i++)
461                              dest.destObjs.objs[i] = c.dest.destObjs.objs[i]; 
462                            break; }
463     }
464     return *this;
465 }
466 inline void LDCommDesc::pup(PUP::er &p) {
467   p|type;
468   switch (type) {
469   case LD_PROC_MSG:  p|dest.destProc; break;
470   case LD_OBJ_MSG:   p|dest.destObj.destObj; 
471                      if (_lb_version == -1 && p.isUnpacking()) 
472                        dest.destObj.destObjProc = -1;
473                      else
474                        p|dest.destObj.destObjProc; 
475                      break;
476   case LD_OBJLIST_MSG:  {  p|dest.destObjs.len; 
477                            if (p.isUnpacking()) 
478                                dest.destObjs.objs = new LDObjKey[dest.destObjs.len];
479                            for (int i=0; i<dest.destObjs.len; i++) p|dest.destObjs.objs[i];
480                            break; }
481   }   // end of switch
482 }
483 PUPmarshall(LDCommDesc)
484
485 inline void LDCommData::pup(PUP::er &p) {
486     p|src_proc;
487     p|sender;
488     p|receiver;
489     p|messages;
490     p|bytes;
491     if (p.isUnpacking()) {
492       sendHash = recvHash = -1;
493     }
494 }
495 PUPmarshall(LDCommData)
496
497 #endif /* LBDBH_H */
498
499 /*@}*/