Debian Codegraph @

dune/uggrid/parallel/ddd/include/ddd.h

raw
1 // -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 // vi: set et ts=4 sw=2 sts=2:
3 // SPDX-FileCopyrightInfo: Copyright © DUNE Project contributors, see file LICENSE.md in module root
4 // SPDX-License-Identifier: LGPL-2.1-or-later
5 /****************************************************************************/
6 /* */
7 /* File: ddd.h */
8 /* */
9 /* Purpose: header file for ddd module */
10 /* */
11 /* Author: Klaus Birken */
12 /* Rechenzentrum Uni Stuttgart */
13 /* Universitaet Stuttgart */
14 /* Allmandring 30 */
15 /* 70550 Stuttgart */
16 /* internet: [email protected] */
17 /* */
18 /* */
19 /* History: 93/11/22 kb begin */
20 /* 94/06/27 kb revision for usage in C++ context */
21 /* 94/08/22 kb major revision, corresp. to Ref.Man. V1.0 */
22 /* 94/09/13 kb added DDD_Status */
23 /* 95/01/13 kb added range functionality */
24 /* 95/01/16 kb added Statistics features */
25 /* 95/01/18 kb moved Statistics to dddaddon.h */
26 /* 95/02/06 kb added extended Ifs */
27 /* 95/03/08 kb added UserData features */
28 /* 95/03/21 kb added variable-sized Objects */
29 /* 95/05/22 kb added var-sized AddData features */
30 /* 95/11/04 kb complete redesign of ObjMgr and Registering */
31 /* 95/11/06 kb changed parameters of DDD_Init() */
32 /* 95/11/15 kb ddd_hdr with arbitrary offset (started) */
33 /* 96/01/08 kb renamed range to attr */
34 /* 96/05/12 kb xfer-unpack rewritten */
35 /* 96/06/05 kb changed handler management */
36 /* 96/09/06 kb xfer-module completely rewritten */
37 /* 96/11/28 kb merged F_FRONTEND functionality from code branch */
38 /* 97/02/10 kb started with CPP_FRONTEND implementation */
39 /* 98/01/28 kb new ddd-environment: Join. */
40 /* 98/05/14 kb redesigned memory handling. */
41 /* 98/07/20 kb new ddd-environment: Prio. */
42 /* */
43 /* Remarks: */
44 /* */
45 /****************************************************************************/
46
47
48 #ifndef __DDD__
49 #define __DDD__
50
51 /* for size_t */
52 #include <cstddef>
53 #include <cinttypes>
54
55 #include <dune/uggrid/parallel/ddd/dddtypes.hh>
56 #include <dune/uggrid/parallel/ddd/dddtypes_impl.hh>
57
58 #include <dune/uggrid/low/namespace.h>
59
60 START_UGDIM_NAMESPACE
61
62 using namespace DDD;
63
64 #define DDD_VERSION "1.9"
65
66 /* F77SYM(lsym,usym) macro is defined in compiler.h. 961127 KB */
67
68 /****************************************************************************/
69 /* */
70 /* compile time constants defining static data size (i.e. arrays) */
71 /* other constants */
72 /* */
73 /****************************************************************************/
74
75
76
77 /* return types for DDD functions */
78 enum DDD_RET {
79 DDD_RET_OK = 0, /* function was executed ok */
80 DDD_RET_ERROR_UNKNOWN = 1, /* unknown error condition */
81 DDD_RET_ERROR_NOMEM = 2 /* function aborted due to mem shortage */
82 };
83
84
85 /* types of elements for StructRegister */
86 /* (use negative values for combination with positive DDD_TYPEs) */
87 enum DDD_ELEM_TYPE {
88 EL_DDDHDR = 0, /* element type: DDD header */
89 EL_GDATA = -1, /* element type: global data */
90 EL_LDATA = -2, /* element type: local data */
91 EL_GBITS = -3, /* element type: bitwise, 1=global */
92 EL_DATAPTR = -4, /* element type: data pointer */
93 EL_OBJPTR = -5, /* element type: object pointer */
94 EL_CONTINUE = -6, /* continued element definition list */
95 EL_END = -7 /* end of element definition list */
96 };
97
98
99
100
101
102
103 /* NOTE: changes must be also done in fddd.f */
104 enum OptConsts {
105 OPT_OFF = 0,
106 OPT_ON
107 };
108
109 enum OptConstIdent {
110 IDMODE_LISTS = 1, /* ordering of each identify-tupel is relevant */
111 IDMODE_SETS /* ordering of each identify-tupel is not sensitive */
112 };
113
114 enum OptConstXfer {
115 XFER_SHOW_NONE = 0x0000, /* show no statistical infos */
116 XFER_SHOW_OBSOLETE = 0x0001, /* show #obsolete xfer-commands */
117 XFER_SHOW_MEMUSAGE = 0x0002, /* show sizes of message buffers */
118 XFER_SHOW_MSGSALL = 0x0004 /* show message contents by LowComm stats */
119 };
120
121 enum OptConstJoin {
122 JOIN_SHOW_NONE = 0x0000, /* show no statistical infos */
123 JOIN_SHOW_OBSOLETE = 0x0001, /* show #obsolete join-commands */
124 JOIN_SHOW_MEMUSAGE = 0x0002, /* show sizes of message buffers */
125 JOIN_SHOW_MSGSALL = 0x0004 /* show message contents by LowComm stats */
126 };
127
128
129
130 /* direction of interface communication (DDD_IFOneway) */
131 /* NOTE: changes must be also done in fddd.f */
132 enum DDD_IF_DIR {
133 IF_FORWARD = 1, /* communicate from A to B */
134 IF_BACKWARD = 2 /* communicate from B to A */
135 };
136
137
138 /* ID of (predefined) standard interface */
139 enum IFConstants {
140 STD_INTERFACE = 0
141 };
142
143
144 /* DDD_TYPE DDD_USER_DATA: send stream of bytes with XferAddData */
145 enum XferConstants {
146 /* DDD_TYPE DDD_USER_DATA: send stream of bytes with XferAddData */
147 /* application may add small integers in order to get more
148 stream-of-byte channels, up to DDD_USER_DATA_MAX */
149 DDD_USER_DATA = 0x4000,
150 DDD_USER_DATA_MAX = 0x4fff,
151
152
153 /* additional parameter for user defined handlers in xfer */
154
155 /* object has been rejected due to RULE C3 */
156 XFER_REJECT = 0x9000,
157
158 /* object has been upgraded due to RULE C3 */
159 XFER_UPGRADE,
160
161 /* object has been downgraded due to PruneDel */
162 XFER_DOWNGRADE,
163
164 /* object is totally new */
165 XFER_NEW,
166
167
168 /* return value for DDD_XferIsPrunedDelete */
169 XFER_PRUNED_TRUE = 0x9100,
170 XFER_PRUNED_FALSE,
171 XFER_PRUNED_ERROR,
172
173
174 /* return value for DDD_XferObjIsResent */
175 XFER_RESENT_TRUE = 0x9200,
176 XFER_RESENT_FALSE,
177 XFER_RESENT_ERROR
178 };
179
180
181 /* several default modes for priority handling */
182 enum PrioMatrixDefaults {
183 PRIOMERGE_MAXIMUM = 0,
184 PRIOMERGE_MINIMUM
185 };
186
187
188
189 /* constants for management of temporary memory allocation/deletion */
190 enum TMemRequests {
191 TMEM_ANY = 0x0000,
192 TMEM_MSG,
193 TMEM_OBJLIST,
194 TMEM_CPL,
195
196 TMEM_XFER = 0x1000,
197 TMEM_LOWCOMM,
198
199 TMEM_JOIN = 0x2000,
200
201 TMEM_CONS = 0x3000,
202
203 TMEM_IDENT = 0x4000
204 };
205
206
207
208 /****************************************************************************/
209 /* */
210 /* data structures and new types */
211 /* */
212 /****************************************************************************/
213
214
215 /*
216 new DDD types, used during access of DDD functional interface
217 */
218 using DDD_GID = DDD::DDD_GID;
219 static_assert(
220 std::is_same<DDD::DDD_GID, std::uint_least64_t>::value,
221 "printf conversion specifier below expects DDD_GID to be uint_least64_t");
222 #define DDD_GID_FMT "%08" PRIxLEAST64
223 #define DDD_GID_TO_INT(A) (A)
224
225 using DDD_TYPE = DDD::DDD_TYPE;
226 using DDD_IF = DDD::DDD_IF;
227 using DDD_PROC = DDD::DDD_PROC;
228 using DDD_PRIO = DDD::DDD_PRIO;
229 using DDD_ATTR = DDD::DDD_ATTR;
230
231 using DDD_OBJ = DDD::DDD_OBJ;
232 using DDD_HEADER = DDD::DDD_HEADER;
233 using DDD_HDR = DDD::DDD_HDR;
234
235 /* NULL values for DDD types */
236 #define DDD_TYPE_NULL 0
237 #define DDD_PROC_NULL 0
238 #define DDD_PRIO_NULL 0
239 #define DDD_ATTR_NULL 0
240
241
242 /* special feature: hybrid reftype at TypeDefine-time */
243 #define DDD_TYPE_BY_HANDLER 127 /* must be > MAX_TYPEDESC */
244
245
246 /****************************************************************************/
247 /* */
248 /* macros */
249 /* */
250 /****************************************************************************/
251
252
253 /*
254 external access of elements in DDD_HEADER
255 */
256 #define DDD_InfoPriority(ddd_hdr) ((ddd_hdr)->prio)
257 #define DDD_InfoGlobalId(ddd_hdr) ((ddd_hdr)->gid)
258 #define DDD_InfoAttr(ddd_hdr) ((ddd_hdr)->attr)
259 #define DDD_InfoType(ddd_hdr) ((ddd_hdr)->typ)
260
261
262 /****************************************************************************/
263 /* */
264 /* declaration of DDD functional interface */
265 /* */
266 /****************************************************************************/
267
268 /*
269 General DDD Module
270 */
271 void DDD_Init(DDD::DDDContext& context);
272 void DDD_Exit(DDD::DDDContext& context);
273 void DDD_Status(const DDD::DDDContext& context);
274 void DDD_SetOption(DDD::DDDContext& context, DDD_OPTION, int);
275
276 /*
277 Redirect line-oriented output, new in V1.2
278 */
279 void DDD_LineOutRegister (void (*func)(const char *s));
280
281
282 /*
283 Type Manager Module
284 */
285
286 DDD_TYPE DDD_TypeDeclare(DDD::DDDContext& context, const char *name);
287 int DDD_InfoHdrOffset(const DDD::DDDContext& context, DDD_TYPE);
288 void DDD_TypeDefine(DDD::DDDContext& context, DDD_TYPE, ...);
289 void DDD_TypeDisplay(const DDD::DDDContext& context, DDD_TYPE);
290
291 int DDD_InfoTypes(const DDD::DDDContext& context);
292
293
294 /* newstyle, type-secure setting of handlers */
295 void DDD_SetHandlerLDATACONSTRUCTOR(DDD::DDDContext& context, DDD_TYPE, HandlerLDATACONSTRUCTOR);
296 void DDD_SetHandlerDESTRUCTOR (DDD::DDDContext& context, DDD_TYPE, HandlerDESTRUCTOR);
297 void DDD_SetHandlerDELETE (DDD::DDDContext& context, DDD_TYPE, HandlerDELETE);
298 void DDD_SetHandlerUPDATE (DDD::DDDContext& context, DDD_TYPE, HandlerUPDATE);
299 void DDD_SetHandlerOBJMKCONS (DDD::DDDContext& context, DDD_TYPE, HandlerOBJMKCONS);
300 void DDD_SetHandlerSETPRIORITY (DDD::DDDContext& context, DDD_TYPE, HandlerSETPRIORITY);
301 void DDD_SetHandlerXFERCOPY (DDD::DDDContext& context, DDD_TYPE, HandlerXFERCOPY);
302 void DDD_SetHandlerXFERDELETE (DDD::DDDContext& context, DDD_TYPE, HandlerXFERDELETE);
303 void DDD_SetHandlerXFERGATHER (DDD::DDDContext& context, DDD_TYPE, HandlerXFERGATHER);
304 void DDD_SetHandlerXFERSCATTER (DDD::DDDContext& context, DDD_TYPE, HandlerXFERSCATTER);
305 void DDD_SetHandlerXFERGATHERX (DDD::DDDContext& context, DDD_TYPE, HandlerXFERGATHERX);
306 void DDD_SetHandlerXFERSCATTERX (DDD::DDDContext& context, DDD_TYPE, HandlerXFERSCATTERX);
307 void DDD_SetHandlerXFERCOPYMANIP (DDD::DDDContext& context, DDD_TYPE, HandlerXFERCOPYMANIP);
308
309
310 void DDD_PrioMergeDefault (DDD::DDDContext& context, DDD_TYPE, int);
311 void DDD_PrioMergeDefine (DDD::DDDContext& context, DDD_TYPE, DDD_PRIO, DDD_PRIO, DDD_PRIO);
312 DDD_PRIO DDD_PrioMerge (DDD::DDDContext& context, DDD_TYPE, DDD_PRIO, DDD_PRIO);
313 void DDD_PrioMergeDisplay (DDD::DDDContext& context, DDD_TYPE);
314
315
316
317 /*
318 Object Properties
319 */
320
321 #ifndef DUNE_UGGRID_DDD_InfoProcListRange
322 /** \brief feature test macro for `DDD_InfoProcListRange` */
323 # define DUNE_UGGRID_DDD_InfoProcListRange 202209L
324 #endif
325
326 /**
327 * \brief entry in the list returned by `DDD_InfoProcListRange`
328 */
329 struct DDD_InfoProcListEntry
330 {
331 /** \brief processor */
332 DDD_PROC proc;
333 /** \brief priority */
334 DDD_PRIO prio;
335 };
336
337 /**
338 * \brief iterator for (process, priority) tuples for couplings
339 *
340 * See `DDD_InfoProcListRange` for more details.
341 */
342 class DDD_InfoProcListIterator
343 {
344 const COUPLING* cpl_;
345 public:
346 using value_type = DDD_InfoProcListEntry;
347
348 DDD_InfoProcListIterator(const COUPLING* cpl) noexcept
349 : cpl_(cpl)
350 { /* Nothing */ }
351
352 value_type operator*() const noexcept
353 { return { cpl_->_proc, cpl_->prio }; }
354
355 void operator++() noexcept
356 { cpl_ = cpl_->_next; }
357
358 explicit operator bool() const noexcept
359 { return static_cast<bool>(cpl_); }
360
361 #if __cplusplus >= 202002L
362 bool operator==(const DDD_InfoProcListIterator&) const noexcept = default;
363 #else
364 bool operator==(const DDD_InfoProcListIterator& other) const noexcept
365 { return cpl_ == other.cpl_; }
366 bool operator!=(const DDD_InfoProcListIterator& other) const noexcept
367 { return cpl_ != other.cpl_; }
368 #endif
369 };
370
371 /**
372 * \brief range with (process, priority) tuples for couplings of the given `hdr`
373 *
374 * This range provides access to the `process` and `priority` of all couplings
375 * for the object identified by `hdr`. In addition it provides an optional dummy
376 * coupling for the local process; this can be controlled with the `skipDummy`
377 * parameter.
378 */
379 class DDD_InfoProcListRange
380 {
381 COUPLING dummy_;
382 bool includeDummy_;
383 public:
384 /**
385 * \brief construct range with (process, priority) tuples for couplings of the given `hdr`
386 *
387 * \param context DDD context
388 * \param hdr parallel object whose couplings will be used
389 * \param includeDummy whether to include a dummy coupling for the local process
390 */
391 DDD_InfoProcListRange(DDDContext& context, const DDD_HDR hdr, bool includeDummy = true) noexcept;
392
393 /** \brief Returns iterator to the begin of the range */
394 DDD_InfoProcListIterator begin() const noexcept
395 { return {includeDummy_ ? &dummy_ : dummy_._next}; }
396
397 /** \brief Returns iterator to the end of the range */
398 DDD_InfoProcListIterator end() const noexcept
399 { return {nullptr}; }
400
401 /** \brief Return whether the range is empty. */
402 bool empty() const noexcept
403 { return begin() == end(); }
404 };
405
406 void DDD_PrioritySet(DDD::DDDContext& context, DDD_HDR, DDD_PRIO);
407 void DDD_AttrSet (DDD_HDR, DDD_ATTR); /* this shouldn't be allowed */
408 DDD_PROC DDD_InfoProcPrio(const DDD::DDDContext& context, DDD_HDR, DDD_PRIO);
409 bool DDD_InfoIsLocal(const DDD::DDDContext& context, DDD_HDR);
410 int DDD_InfoNCopies(const DDD::DDDContext& context, DDD_HDR);
411 size_t DDD_InfoCplMemory(const DDD::DDDContext& context);
412
413
414
415 /*
416 Identification Environment Module
417 */
418
419 void DDD_IdentifyBegin(DDD::DDDContext& context);
420 DDD_RET DDD_IdentifyEnd(DDD::DDDContext& context);
421 void DDD_IdentifyNumber(DDD::DDDContext& context, DDD_HDR, DDD_PROC, int);
422 void DDD_IdentifyString(DDD::DDDContext& context, DDD_HDR, DDD_PROC, char *);
423 void DDD_IdentifyObject(DDD::DDDContext& context, DDD_HDR, DDD_PROC, DDD_HDR);
424
425
426 /*
427 Interface Module
428 */
429
430 DDD_IF DDD_IFDefine (DDD::DDDContext& context, int, DDD_TYPE O[], int, DDD_PRIO A[], int, DDD_PRIO B[]);
431 void DDD_IFSetName (DDD::DDDContext& context, DDD_IF, const char *);
432
433 void DDD_IFDisplayAll(const DDD::DDDContext& context);
434 void DDD_IFDisplay(const DDD::DDDContext& context, DDD_IF);
435 size_t DDD_IFInfoMemoryAll(const DDD::DDDContext& context);
436 size_t DDD_IFInfoMemory(const DDD::DDDContext& context, DDD_IF);
437 void DDD_IFRefreshAll(DDD::DDDContext& context);
438
439 void DDD_IFExchange (DDD::DDDContext& context, DDD_IF, size_t, ComProcPtr2,ComProcPtr2);
440 void DDD_IFOneway (DDD::DDDContext& context, DDD_IF, DDD_IF_DIR,size_t, ComProcPtr2,ComProcPtr2);
441 void DDD_IFExecLocal (DDD::DDDContext& context, DDD_IF, ExecProcPtr);
442 void DDD_IFAExchange (DDD::DDDContext& context, DDD_IF,DDD_ATTR, size_t, ComProcPtr2,ComProcPtr2);
443 void DDD_IFAOneway (DDD::DDDContext& context, DDD_IF,DDD_ATTR,DDD_IF_DIR,size_t, ComProcPtr2,ComProcPtr2);
444 void DDD_IFAExecLocal (DDD::DDDContext& context, DDD_IF,DDD_ATTR, ExecProcPtr);
445 void DDD_IFExchangeX (DDD::DDDContext& context, DDD_IF, size_t, ComProcXPtr,ComProcXPtr);
446 void DDD_IFOnewayX (DDD::DDDContext& context, DDD_IF, DDD_IF_DIR,size_t, ComProcXPtr,ComProcXPtr);
447 void DDD_IFExecLocalX (DDD::DDDContext& context, DDD_IF, ExecProcXPtr);
448 void DDD_IFAExchangeX (DDD::DDDContext& context, DDD_IF,DDD_ATTR, size_t, ComProcXPtr,ComProcXPtr);
449 void DDD_IFAOnewayX (DDD::DDDContext& context, DDD_IF,DDD_ATTR,DDD_IF_DIR,size_t, ComProcXPtr,ComProcXPtr);
450 void DDD_IFAExecLocalX(DDD::DDDContext& context, DDD_IF,DDD_ATTR, ExecProcXPtr);
451
452 /*
453 Transfer Environment Module
454 */
455 bool DDD_XferWithAddData(const DDD::DDDContext& context);
456 void DDD_XferAddData(DDD::DDDContext& context, int, DDD_TYPE);
457 void DDD_XferAddDataX(DDD::DDDContext& context, int, DDD_TYPE, size_t sizes[]);
458 int DDD_XferIsPrunedDelete(const DDD::DDDContext& context, DDD_HDR);
459 int DDD_XferObjIsResent(const DDD::DDDContext& context, DDD_HDR);
460 void DDD_XferBegin(DDD::DDDContext& context);
461 DDD_RET DDD_XferEnd(DDD::DDDContext& context);
462 void DDD_XferCopyObj (DDD::DDDContext& context, DDD_HDR, DDD_PROC, DDD_PRIO);
463 void DDD_XferCopyObjX (DDD::DDDContext& context, DDD_HDR, DDD_PROC, DDD_PRIO, size_t);
464 void DDD_XferDeleteObj (DDD::DDDContext& context, DDD_HDR);
465 void DDD_XferPrioChange(DDD::DDDContext& context, DDD_HDR, DDD_PRIO);
466
467
468 /*
469 Prio Environment Module
470 */
471 void DDD_PrioBegin(DDD::DDDContext& context);
472 DDD_RET DDD_PrioEnd(DDD::DDDContext& context);
473 void DDD_PrioChange(const DDD::DDDContext& context, DDD_HDR, DDD_PRIO);
474
475
476
477 /*
478 Join Environment Module
479 */
480 void DDD_JoinBegin(DDD::DDDContext& context);
481 DDD_RET DDD_JoinEnd(DDD::DDDContext& context);
482 void DDD_JoinObj(DDD::DDDContext& context, DDD_HDR, DDD_PROC, DDD_GID);
483
484
485 /*
486 Object Manager
487 */
488
489 DDD_OBJ DDD_ObjNew (size_t, DDD_TYPE, DDD_PRIO, DDD_ATTR);
490 void DDD_ObjDelete (DDD_OBJ, size_t, DDD_TYPE);
491 void DDD_HdrConstructor(DDD::DDDContext& context, DDD_HDR, DDD_TYPE, DDD_PRIO, DDD_ATTR);
492 void DDD_HdrConstructorMove(DDD::DDDContext& context, DDD_HDR, DDD_HDR);
493 void DDD_HdrDestructor(DDD::DDDContext& context, DDD_HDR);
494 DDD_OBJ DDD_ObjGet (DDD::DDDContext& context, size_t, DDD_TYPE, DDD_PRIO, DDD_ATTR);
495 void DDD_ObjUnGet (DDD::DDDContext& context, DDD_HDR, size_t);
496
497
498
499 /*
500 Maintenance & Debugging
501 */
502
503 int DDD_ConsCheck(DDD::DDDContext& context); /* returns total #errors since V1.6.6 */
504 void DDD_ListLocalObjects(const DDD::DDDContext& context);
505 DDD_HDR DDD_SearchHdr(DDD::DDDContext&, DDD_GID);
506
507
508 /****************************************************************************/
509
510 END_UGDIM_NAMESPACE
511
512 #endif