Actual source code: petscimpl.h


  2: /*
  3:     Defines the basic header of all PETSc objects.
  4: */
  5: #ifndef PETSCIMPL_H
  6: #define PETSCIMPL_H
  7: #include <petscsys.h>

  9: /* SUBMANSEC = Sys */

 11: #if defined(PETSC_CLANG_STATIC_ANALYZER)
 12:   #define PetscDisableStaticAnalyzerForExpressionUnderstandingThatThisIsDangerousAndBugprone(...)
 13: #else
 14:   #define PetscDisableStaticAnalyzerForExpressionUnderstandingThatThisIsDangerousAndBugprone(...) __VA_ARGS__
 15: #endif

 17: #if PetscDefined(USE_DEBUG) && !PetscDefined(HAVE_THREADSAFETY)
 18: PETSC_INTERN PetscErrorCode PetscStackSetCheck(PetscBool);
 19: PETSC_INTERN PetscErrorCode PetscStackView(FILE *);
 20: PETSC_INTERN PetscErrorCode PetscStackReset(void);
 21: PETSC_INTERN PetscErrorCode PetscStackCopy(PetscStack *, PetscStack *);
 22: PETSC_INTERN PetscErrorCode PetscStackPrint(PetscStack *, FILE *);
 23: #else
 24:   #define PetscStackSetCheck(check)         PETSC_SUCCESS
 25:   #define PetscStackView(file)              PETSC_SUCCESS
 26:   #define PetscStackReset()                 PETSC_SUCCESS
 27:   #define PetscStackCopy(stackin, stackout) PETSC_SUCCESS
 28:   #define PetscStackPrint(stack, file)      PETSC_SUCCESS
 29: #endif

 31: /* These are used internally by PETSc ASCII IO routines*/
 32: #include <stdarg.h>
 33: PETSC_EXTERN PetscErrorCode PetscVFPrintfDefault(FILE *, const char[], va_list);

 35: /*
 36:    All major PETSc data structures have a common core; this is defined
 37:    below by PETSCHEADER.

 39:    PetscHeaderCreate() should be used whenever creating a PETSc structure.
 40: */

 42: /*
 43:    PetscOps: structure of core operations that all PETSc objects support.

 45:       getcomm()         - Gets the object's communicator.
 46:       view()            - Is the routine for viewing the entire PETSc object; for
 47:                           example, MatView() is the general matrix viewing routine.
 48:                           This is used by PetscObjectView((PetscObject)obj) to allow
 49:                           viewing any PETSc object.
 50:       destroy()         - Is the routine for destroying the entire PETSc object;
 51:                           for example,MatDestroy() is the general matrix
 52:                           destruction routine.
 53:                           This is used by PetscObjectDestroy((PetscObject*)&obj) to allow
 54:                           destroying any PETSc object.
 55:       compose()         - Associates a PETSc object with another PETSc object with a name
 56:       query()           - Returns a different PETSc object that has been associated
 57:                           with the first object using a name.
 58:       composefunction() - Attaches an a function to a PETSc object with a name.
 59:       queryfunction()   - Requests a registered function that has been attached to a PETSc object.
 60: */

 62: typedef struct {
 63:   PetscErrorCode (*view)(PetscObject, PetscViewer);
 64:   PetscErrorCode (*destroy)(PetscObject *);
 65:   PetscErrorCode (*compose)(PetscObject, const char[], PetscObject);
 66:   PetscErrorCode (*query)(PetscObject, const char[], PetscObject *);
 67:   PetscErrorCode (*composefunction)(PetscObject, const char[], void (*)(void));
 68:   PetscErrorCode (*queryfunction)(PetscObject, const char[], void (**)(void));
 69: } PetscOps;

 71: typedef enum {
 72:   PETSC_FORTRAN_CALLBACK_CLASS,
 73:   PETSC_FORTRAN_CALLBACK_SUBTYPE,
 74:   PETSC_FORTRAN_CALLBACK_MAXTYPE
 75: } PetscFortranCallbackType;
 76: typedef size_t PetscFortranCallbackId;
 77: #define PETSC_SMALLEST_FORTRAN_CALLBACK ((PetscFortranCallbackId)1000)
 78: PETSC_EXTERN PetscErrorCode PetscFortranCallbackRegister(PetscClassId, const char *, PetscFortranCallbackId *);
 79: PETSC_EXTERN PetscErrorCode PetscFortranCallbackGetSizes(PetscClassId, PetscFortranCallbackId *, PetscFortranCallbackId *);

 81: typedef struct {
 82:   void (*func)(void);
 83:   void *ctx;
 84: } PetscFortranCallback;

 86: /*
 87:    All PETSc objects begin with the fields defined in PETSCHEADER.
 88:    The PetscObject is a way of examining these fields regardless of
 89:    the specific object. In C++ this could be a base abstract class
 90:    from which all objects are derived.
 91: */
 92: #define PETSC_MAX_OPTIONS_HANDLER 5
 93: typedef struct _p_PetscObject {
 94:   PetscOps      bops[1];
 95:   PetscClassId  classid;
 96:   MPI_Comm      comm;
 97:   PetscObjectId id; /* this is used to compare object for identity that may no longer exist since memory addresses get recycled for new objects */
 98:   PetscInt      refct;
 99:   PetscErrorCode (*non_cyclic_references)(PetscObject, PetscInt *);
100:   PetscInt64        cidx;
101:   PetscMPIInt       tag;
102:   PetscFunctionList qlist;
103:   PetscObjectList   olist;
104:   char             *class_name; /*  for example, "Vec" */
105:   char             *description;
106:   char             *mansec;
107:   char             *type_name; /*  this is the subclass, for example VECSEQ which equals "seq" */
108:   char             *name;
109:   char             *prefix;
110:   PetscInt          tablevel;
111:   void             *cpp;
112:   PetscObjectState  state;
113:   PetscInt          int_idmax, intstar_idmax;
114:   PetscObjectState *intcomposedstate, *intstarcomposedstate;
115:   PetscInt         *intcomposeddata, **intstarcomposeddata;
116:   PetscInt          real_idmax, realstar_idmax;
117:   PetscObjectState *realcomposedstate, *realstarcomposedstate;
118:   PetscReal        *realcomposeddata, **realstarcomposeddata;
119:   PetscInt          scalar_idmax, scalarstar_idmax;
120:   PetscObjectState *scalarcomposedstate, *scalarstarcomposedstate;
121:   PetscScalar      *scalarcomposeddata, **scalarstarcomposeddata;
122:   void (**fortran_func_pointers)(void);             /* used by Fortran interface functions to stash user provided Fortran functions */
123:   PetscFortranCallbackId num_fortran_func_pointers; /* number of Fortran function pointers allocated */
124:   PetscFortranCallback  *fortrancallback[PETSC_FORTRAN_CALLBACK_MAXTYPE];
125:   PetscFortranCallbackId num_fortrancallback[PETSC_FORTRAN_CALLBACK_MAXTYPE];
126:   void                  *python_context;
127:   PetscErrorCode (*python_destroy)(void *);

129:   PetscInt noptionhandler;
130:   PetscErrorCode (*optionhandler[PETSC_MAX_OPTIONS_HANDLER])(PetscObject, PetscOptionItems *, void *);
131:   PetscErrorCode (*optiondestroy[PETSC_MAX_OPTIONS_HANDLER])(PetscObject, void *);
132:   void *optionctx[PETSC_MAX_OPTIONS_HANDLER];
133: #if defined(PETSC_HAVE_SAWS)
134:   PetscBool amsmem;          /* if PETSC_TRUE then this object is registered with SAWs and visible to clients */
135:   PetscBool amspublishblock; /* if PETSC_TRUE and publishing objects then will block at PetscObjectSAWsBlock() */
136: #endif
137:   PetscOptions options; /* options database used, NULL means default */
138:   PetscBool    optionsprinted;
139:   PetscBool    donotPetscObjectPrintClassNamePrefixType;
140: } _p_PetscObject;

142: #define PETSCHEADER(ObjectOps) \
143:   _p_PetscObject hdr; \
144:   ObjectOps      ops[1]

146: #define PETSCFREEDHEADER -1

148: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*PetscObjectDestroyFunction)(PetscObject *); /* force cast in next macro to NEVER use extern "C" style */
149: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*PetscObjectViewFunction)(PetscObject, PetscViewer);

151: #define PetscHeaderInitialize_Private(h, classid, class_name, descr, mansec, comm, destroy, view) \
152:   ((PetscErrorCode)(PetscHeaderCreate_Private((PetscObject)(h), classid, class_name, descr, mansec, comm, (PetscObjectDestroyFunction)(destroy), (PetscObjectViewFunction)(view)) || PetscLogObjectCreate(h)))

154: /*MC
155:     PetscHeaderCreate - Creates a PETSc object of a particular class

157:   Synopsis:
158: #include <petsc/private/petscimpl.h>
159:   PetscErrorCode PetscHeaderCreate(PetscObject h, PetscClassId classid, const char class_name[], const char descr[], const char mansec[], MPI_Comm comm, PetscObjectDestroyFunction destroy, PetscObjectViewFunction view)

161:   Input Parameters:
162: + classid    - The classid associated with this object (for example `VEC_CLASSID`)
163: . class_name - String name of class; should be static (for example "Vec"), may be
164:                `PETSC_NULLPTR`
165: . descr      - String containing short description; should be static (for example "Vector"),
166:                may be `PETSC_NULLPTR`
167: . mansec     - String indicating section in manual pages; should be static (for example "Vec"),
168:                may be `PETSC_NULLPTR`
169: . comm       - The MPI Communicator
170: . destroy    - The destroy routine for this object (for example `VecDestroy()`)
171: - view       - The view routine for this object (for example `VecView()`), may be
172:                `PETSC_NULLPTR`

174:   Output Parameter:
175: . h - The newly created `PetscObject`

177:   Notes:
178:   Can only be used to create a `PetscObject`. A `PetscObject` is defined as a pointer to a
179:   C/C++ structure which satisfies all of the following\:

181:   1. The first member of the structure must be a `_p_PetscObject`.
182:   2. C++ structures must be "Standard Layout". Generally speaking a standard layout class\:
183:      - Has no virtual functions or base classes.
184:      - Has only standard layout non-static members (if any).
185:      - Has only standard layout base classes (if any).

187:      See https://en.cppreference.com/w/cpp/language/classes#Standard-layout_class for further
188:      information.

190:   Example Usage:
191:   Existing `PetscObject`s may be easily created as shown. Unless otherwise stated, a particular
192:   objects `destroy` and `view` functions are exactly `<OBJECT_TYPE>Destroy()` and
193:   `<OBJECT_TYPE>View()`.
194: .vb
195:   Vec v;

197:   PetscHeaderCreate(v, VEC_CLASSID, "Vec", "A distributed vector class", "Vec", PETSC_COMM_WORLD, VecDestroy, VecView);
198: .ve

200:   It is possible to create custom `PetscObject`s, note however that they must abide by the
201:   restrictions set forth above.
202: .vb
203:   // OK, first member of C structure is _p_PetscObject
204:   struct MyCPetscObject_s
205:   {
206:     _p_PetscObject header;
207:     int            some_data;
208:   };
209:   typedef struct *MyCPetscObject_s MyCPetscObject;

211:   PetscErrorCode MyObjectDestroy(MyObject *);
212:   PetscErrorCode MyObjectView(MyObject);

214:   MyCPetscObject obj;

216:   // assume MY_PETSC_CLASSID is already registered
217:   PetscHeaderCreate(obj, MY_PETSC_CLASSID, "MyObject", "A custom PetscObject", PETSC_NULLPTR, PETSC_COMM_SELF, MyObjectDestroy, MyObjectView);

219:   // OK, only destroy function must be given, all others may be NULL
220:   PetscHeaderCreate(obj, MY_PETSC_CLASSID, PETSC_NULLPTR, PETSC_NULLPTR, PETSC_NULLPTR, PETSC_COMM_SELF, MyObjectDestroy, PETSC_NULLPTR);

222:   // ERROR must be a single-level pointer
223:   PetscHeaderCreate(&obj, ...);
224: .ve

226:   Illustrating proper construction from C++\:
227: .vb
228:   // ERROR, class is not standard layout, first member must be publicly accessible
229:   class BadCppPetscObject
230:   {
231:     _p_PetscObject header;
232:   };

234:   // ERROR, class is not standard layout, has a virtual function and virtual inheritance
235:   class BadCppPetscObject2 : virtual BaseClass
236:   {
237:   public:
238:     _p_PetscObject header;

240:     virtual void foo();
241:   };

243:   // ERROR, class is not standard layout! Has non-standard layout member
244:   class BadCppPetscObject2
245:   {
246:   public:
247:     _p_PetscObject    header;
248:     BadCppPetscObject non_standard_layout;
249:   };

251:   // OK, class is standard layout!
252:   class GoodCppPetscObject;
253:   using MyCppObject = GoodCppPetscObject *;

255:   // OK, non-virtual inheritance of other standard layout class does not affect layout
256:   class GoodCppPetscObject : StandardLayoutClass
257:   {
258:   public:
259:     // OK, non standard layout member is static, does not affect layout
260:     static BadCppPetscObject non_standard_layout;

262:     // OK, first non-static member is _p_PetscObject
263:     _p_PetscObject header;

265:      // OK, non-virtual member functions do not affect class layout
266:     void foo();

268:     // OK, may use "member" functions for destroy and view so long as they are static
269:     static PetscErrorCode destroy(MyCppObject *);
270:     static PetscErrorCode view(MyCppObject);
271:   };

273:   // OK, usage via pointer
274:   MyObject obj;

276:   PetscHeaderCreate(obj, MY_PETSC_CLASSID, "MyObject", "A custom C++ PetscObject", nullptr, PETSC_COMM_SELF, GoodCppPetscObject::destroy, GoodCppPetscObject::view);
277: .ve

279:   Level: developer

281: .seealso: `PetscHeaderDestroy()`, `PetscClassIdRegister()`
282: M*/
283: #define PetscHeaderCreate(h, classid, class_name, descr, mansec, comm, destroy, view) ((PetscErrorCode)(PetscNew(&(h)) || PetscHeaderInitialize_Private((h), (classid), (class_name), (descr), (mansec), (comm), (destroy), (view))))

285: PETSC_EXTERN PetscErrorCode PetscComposedQuantitiesDestroy(PetscObject obj);
286: PETSC_EXTERN PetscErrorCode PetscHeaderCreate_Private(PetscObject, PetscClassId, const char[], const char[], const char[], MPI_Comm, PetscObjectDestroyFunction, PetscObjectViewFunction);
287: PETSC_INTERN PetscObjectId  PetscObjectNewId_Internal(void);

289: /*MC
290:   PetscHeaderDestroy - Final step in destroying a `PetscObject`

292:   Synopsis:
293: #include <petsc/private/petscimpl.h>
294:   PetscErrorCode PetscHeaderDestroy(PetscObject *obj)

296:   Input Parameter:
297: . h - A pointer to the header created with `PetscHeaderCreate()`

299:   Notes:
300:   `h` is freed and set to `PETSC_NULLPTR` when this routine returns.

302:   Example Usage:
303: .vb
304:   PetscObject obj;

306:   PetscHeaderCreate(obj, ...);
307:   // use obj...

309:   // note pointer to obj is used
310:   PetscHeaderDestroy(&obj);
311: .ve

313:   Note that this routine is the _last_ step when destroying higher-level `PetscObject`s as it
314:   deallocates the memory for the structure itself\:
315: .vb
316:   typedef struct MyPetscObject_s *MyPetscObject;
317:   struct MyPetscObject_s
318:   {
319:     _p_PetscObject  hdr;
320:     PetscInt       *foo;
321:     PetscScalar    *bar;
322:   };

324:   // assume obj is created/initialized elsewhere...
325:   MyPetscObject obj;

327:   // OK, should dispose of all dynamically allocated resources before calling
328:   // PetscHeaderDestroy()
329:   PetscFree(obj->foo);

331:   // OK, dispose of obj
332:   PetscHeaderDestroy(&obj);

334:   // ERROR, obj points to NULL here, accessing obj->bar may result in segmentation violation!
335:   // obj->bar is potentially leaked!
336:   PetscFree(obj->bar);
337: .ve

339:   Level: developer

341: .seealso: `PetscHeaderCreate()`
342: M*/
343: #define PetscHeaderDestroy(h) ((PetscErrorCode)(PetscHeaderDestroy_Private((PetscObject)(*(h)), PETSC_FALSE) || PetscFree(*(h))))

345: PETSC_EXTERN PetscErrorCode                PetscHeaderDestroy_Private(PetscObject, PetscBool);
346: PETSC_SINGLE_LIBRARY_INTERN PetscErrorCode PetscHeaderReset_Internal(PetscObject);
347: PETSC_EXTERN PetscErrorCode                PetscObjectCopyFortranFunctionPointers(PetscObject, PetscObject);
348: PETSC_EXTERN PetscErrorCode                PetscObjectSetFortranCallback(PetscObject, PetscFortranCallbackType, PetscFortranCallbackId *, void (*)(void), void *ctx);
349: PETSC_EXTERN PetscErrorCode                PetscObjectGetFortranCallback(PetscObject, PetscFortranCallbackType, PetscFortranCallbackId, void (**)(void), void **ctx);

351: PETSC_INTERN PetscErrorCode PetscCitationsInitialize(void);
352: PETSC_INTERN PetscErrorCode PetscFreeMPIResources(void);
353: PETSC_INTERN PetscErrorCode PetscOptionsHasHelpIntro_Internal(PetscOptions, PetscBool *);

355: /* Code shared between C and Fortran */
356: PETSC_INTERN PetscErrorCode PetscInitialize_Common(const char *, const char *, const char *, PetscBool, PetscBool, PetscInt);

358: #if PetscDefined(HAVE_SETJMP_H)
359: PETSC_EXTERN PetscBool PetscCheckPointer(const void *, PetscDataType);
360: #else
361:   #define PetscCheckPointer(ptr, data_type) (ptr ? PETSC_TRUE : PETSC_FALSE)
362: #endif
363: #if !defined(PETSC_CLANG_STATIC_ANALYZER)
364:   /*
365:     Macros to test if a PETSc object is valid and if pointers are valid
366: */
367:   #if !defined(PETSC_USE_DEBUG)

370:       do { \
371:         (void)(h); \
372:       } while (0)
374:       do { \
375:         (void)(h); \
376:       } while (0)
378:       do { \
379:         (void)(h); \
380:       } while (0)
382:       do { \
383:         (void)(h); \
384:       } while (0)
386:       do { \
387:         (void)(h); \
388:       } while (0)
390:       do { \
391:         (void)(h); \
392:       } while (0)
394:       do { \
395:         (void)(h); \
396:       } while (0)
398:       do { \
399:         (void)(h); \
400:       } while (0)
402:       do { \
403:         (void)(h); \
404:       } while (0)
406:       do { \
407:         (void)(h); \
408:       } while (0)
410:       do { \
411:         (void)(h); \
412:       } while (0)
414:       do { \
415:         (void)(h); \
416:       } while (0)

418:   #else

420:     /*  This check is for subtype methods such as DMDAGetCorners() that do not use the PetscTryMethod() or PetscUseMethod() paradigm */
422:       do { \
423:         PetscBool _7_same; \
425:         PetscCall(PetscObjectTypeCompare((PetscObject)(h), t, &_7_same)); \
426:         PetscCheck(_7_same, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Wrong subtype object:Parameter # %d must have implementation %s it is %s", arg, t, ((PetscObject)(h))->type_name); \
427:       } while (0)

430:       do { \
431:         PetscCheck(ptr, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Null Pointer: Parameter # %d", arg); \
432:         PetscCheck(PetscCheckPointer(ptr, ptype), PETSC_COMM_SELF, PETSC_ERR_ARG_BADPTR, "Invalid Pointer to " PetscStringize(ptrtype) ": Argument '" PetscStringize(ptr) "' (parameter # %d)", arg); \
433:       } while (0)

436:       do { \
438:         if (((PetscObject)(h))->classid != ck) { \
439:           PetscCheck(((PetscObject)(h))->classid != PETSCFREEDHEADER, PETSC_COMM_SELF, PETSC_ERR_ARG_CORRUPT, "Object already free: Parameter # %d", arg); \
440:           SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Wrong type of object: Parameter # %d", arg); \
441:         } \
442:       } while (0)

445:       do { \
447:         PetscCheck(((PetscObject)(h))->classid != PETSCFREEDHEADER, PETSC_COMM_SELF, PETSC_ERR_ARG_CORRUPT, "Object already free: Parameter # %d", arg); \
448:         PetscCheck(((PetscObject)(h))->classid >= PETSC_SMALLEST_CLASSID && ((PetscObject)(h))->classid <= PETSC_LARGEST_CLASSID, PETSC_COMM_SELF, PETSC_ERR_ARG_CORRUPT, "Invalid type of object: Parameter # %d", arg); \
449:       } while (0)


461:       do { \
462:         PetscCheck((f), PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Null Function Pointer: Parameter # %d", arg); \
463:       } while (0)
464:   #endif
465: #else  /* PETSC_CLANG_STATIC_ANALYZER */
466: template <typename T>
468: template <typename T>
470: template <typename T>
472: template <typename T>
474: template <typename T>
476: template <typename T>
478: template <typename T>
480: template <typename T>
482: template <typename T>
484: template <typename T>
486: template <typename T>
488: template <typename T>
490: template <typename T>
492: #endif /* PETSC_CLANG_STATIC_ANALYZER */

494: #define PetscSorted(n, idx, sorted) \
495:   do { \
496:     (sorted) = PETSC_TRUE; \
497:     for (PetscInt _i_ = 1; _i_ < (n); ++_i_) { \
498:       if ((idx)[_i_] < (idx)[_i_ - 1]) { \
499:         (sorted) = PETSC_FALSE; \
500:         break; \
501:       } \
502:     } \
503:   } while (0)

505: #if !defined(PETSC_CLANG_STATIC_ANALYZER)
506:   #if !defined(PETSC_USE_DEBUG)

508:     #define PetscCheckSameType(a, arga, b, argb) \
509:       do { \
510:         (void)(a); \
511:         (void)(b); \
512:       } while (0)
513:     #define PetscCheckTypeName(a, type) \
514:       do { \
515:         (void)(a); \
516:       } while (0)
517:     #define PetscCheckTypeNames(a, type1, type2) \
518:       do { \
519:         (void)(a); \
520:       } while (0)
522:       do { \
523:         (void)(a); \
524:       } while (0)
525:     #define PetscCheckSameComm(a, arga, b, argb) \
526:       do { \
527:         (void)(a); \
528:         (void)(b); \
529:       } while (0)
530:     #define PetscCheckSameTypeAndComm(a, arga, b, argb) \
531:       do { \
532:         (void)(a); \
533:         (void)(b); \
534:       } while (0)
536:       do { \
537:         (void)(a); \
538:         (void)(b); \
539:       } while (0)
541:       do { \
542:         (void)(a); \
543:         (void)(b); \
544:       } while (0)
546:       do { \
547:         (void)(a); \
548:         (void)(b); \
549:       } while (0)
551:       do { \
552:         (void)(a); \
553:         (void)(b); \
554:       } while (0)
556:       do { \
557:         (void)(a); \
558:         (void)(b); \
559:       } while (0)
561:       do { \
562:         (void)(a); \
563:         (void)(b); \
564:       } while (0)
565:     #define PetscCheckSorted(n, idx) \
566:       do { \
567:         (void)(n); \
568:         (void)(idx); \
569:       } while (0)

571:   #else

573:     /*
574:   This macro currently does nothing, the plan is for each PetscObject to have a PetscInt "type"
575:   member associated with the string type_name that can be quickly compared.

577:   **Do not swap this macro to compare string type_name!**

579:   This macro is used incorrectly in the code. Many places that do not need identity of the
580:   types incorrectly call this check and would need to be fixed if this macro is enabled.
581: */
582:     #if 0
583:       #define PetscCheckSameType(a, arga, b, argb) \
584:         do { \
585:           PetscBool pcst_type_eq_ = PETSC_TRUE; \
586:           PetscCall(PetscStrcmp(((PetscObject)(a))->type_name, (((PetscObject)(b)))->type_name, &pcst_type_eq_)); \
587:           PetscCheck(pcst_type_eq_, PETSC_COMM_SELF, PETSC_ERR_ARG_NOTSAMETYPE, "Objects not of same type : Argument # % d and % d, % s != % s ", arga, argb, ((PetscObject)(a))->type_name, ((PetscObject)(b))->type_name); \
588:         } while (0)
589:     #else
590:       #define PetscCheckSameType(a, arga, b, argb) \
591:         do { \
592:           (void)(a); \
593:           (void)(b); \
594:         } while (0)
595:     #endif

597:     /*
598:     Check type_name
599: */
600:     #define PetscCheckTypeName(a, type) \
601:       do { \
602:         PetscBool _7_match; \
603:         PetscCall(PetscObjectTypeCompare(((PetscObject)(a)), (type), &_7_match)); \
604:         PetscCheck(_7_match, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Object (%s) is not %s", (char *)(((PetscObject)(a))->type_name), type); \
605:       } while (0)

607:     #define PetscCheckTypeNames(a, type1, type2) \
608:       do { \
609:         PetscBool _7_match; \
610:         PetscCall(PetscObjectTypeCompareAny(((PetscObject)(a)), &_7_match, (type1), (type2), "")); \
611:         PetscCheck(_7_match, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Object (%s) is not %s or %s", (char *)(((PetscObject)(a))->type_name), type1, type2); \
612:       } while (0)

614:     /*
615:    Use this macro to check if the type is set
616: */

619:     /*
620:    Sometimes object must live on same communicator to inter-operate
621: */
622:     #define PetscCheckSameComm(a, arga, b, argb) \
623:       do { \
624:         PetscMPIInt _7_flag; \
625:         PetscCallMPI(MPI_Comm_compare(PetscObjectComm((PetscObject)(a)), PetscObjectComm((PetscObject)(b)), &_7_flag)); \
626:         PetscCheck(_7_flag == MPI_CONGRUENT || _7_flag == MPI_IDENT, PETSC_COMM_SELF, PETSC_ERR_ARG_NOTSAMECOMM, "Different communicators in the two objects: Argument # %d and %d flag %d", arga, argb, _7_flag); \
627:       } while (0)

629:     #define PetscCheckSameTypeAndComm(a, arga, b, argb) \
630:       do { \
631:         PetscCheckSameType(a, arga, b, argb); \
632:         PetscCheckSameComm(a, arga, b, argb); \
633:       } while (0)

636:       do { \
637:         PetscScalar b0 = (b); \
638:         PetscReal   b1[5], b2[5]; \
639:         if (PetscIsNanScalar(b0)) { \
640:           b1[4] = 1; \
641:         } else { \
642:           b1[4] = 0; \
643:         }; \
644:         b1[0] = -PetscRealPart(b0); \
645:         b1[1] = PetscRealPart(b0); \
646:         b1[2] = -PetscImaginaryPart(b0); \
647:         b1[3] = PetscImaginaryPart(b0); \
648:         PetscCall(MPIU_Allreduce(b1, b2, 5, MPIU_REAL, MPIU_MAX, PetscObjectComm((PetscObject)(a)))); \
649:         PetscCheck(b2[4] > 0 || (PetscEqualReal(-b2[0], b2[1]) && PetscEqualReal(-b2[2], b2[3])), PetscObjectComm((PetscObject)(a)), PETSC_ERR_ARG_WRONG, "Scalar value must be same on all processes, argument # %d", arg); \
650:       } while (0)

653:       do { \
654:         PetscReal b0 = (b), b1[3], b2[3]; \
655:         if (PetscIsNanReal(b0)) { \
656:           b1[2] = 1; \
657:         } else { \
658:           b1[2] = 0; \
659:         }; \
660:         b1[0] = -b0; \
661:         b1[1] = b0; \
662:         PetscCall(MPIU_Allreduce(b1, b2, 3, MPIU_REAL, MPIU_MAX, PetscObjectComm((PetscObject)(a)))); \
663:         PetscCheck(b2[2] > 0 || PetscEqualReal(-b2[0], b2[1]), PetscObjectComm((PetscObject)(a)), PETSC_ERR_ARG_WRONG, "Real value must be same on all processes, argument # %d", arg); \
664:       } while (0)

667:       do { \
668:         PetscInt b0 = (b), b1[2], b2[2]; \
669:         b1[0]       = -b0; \
670:         b1[1]       = b0; \
671:         PetscCall(MPIU_Allreduce(b1, b2, 2, MPIU_INT, MPI_MAX, PetscObjectComm((PetscObject)(a)))); \
672:         PetscCheck(-b2[0] == b2[1], PetscObjectComm((PetscObject)(a)), PETSC_ERR_ARG_WRONG, "Int value must be same on all processes, argument # %d", arg); \
673:       } while (0)

676:       do { \
677:         PetscMPIInt b0 = (b), b1[2], b2[2]; \
678:         b1[0]          = -b0; \
679:         b1[1]          = b0; \
680:         PetscCall(MPIU_Allreduce(b1, b2, 2, MPI_INT, MPI_MAX, PetscObjectComm((PetscObject)(a)))); \
681:         PetscCheck(-b2[0] == b2[1], PetscObjectComm((PetscObject)(a)), PETSC_ERR_ARG_WRONG, "PetscMPIInt value must be same on all processes, argument # %d", arg); \
682:       } while (0)

685:       do { \
686:         PetscMPIInt b0 = (PetscMPIInt)(b), b1[2], b2[2]; \
687:         b1[0]          = -b0; \
688:         b1[1]          = b0; \
689:         PetscCall(MPIU_Allreduce(b1, b2, 2, MPI_INT, MPI_MAX, PetscObjectComm((PetscObject)(a)))); \
690:         PetscCheck(-b2[0] == b2[1], PetscObjectComm((PetscObject)(a)), PETSC_ERR_ARG_WRONG, "Bool value must be same on all processes, argument # %d", arg); \
691:       } while (0)

694:       do { \
695:         PetscMPIInt b0 = (PetscMPIInt)(b), b1[2], b2[2]; \
696:         b1[0]          = -b0; \
697:         b1[1]          = b0; \
698:         PetscCall(MPIU_Allreduce(b1, b2, 2, MPI_INT, MPI_MAX, PetscObjectComm((PetscObject)(a)))); \
699:         PetscCheck(-b2[0] == b2[1], PetscObjectComm((PetscObject)(a)), PETSC_ERR_ARG_WRONG, "Enum value must be same on all processes, argument # %d", arg); \
700:       } while (0)

702:     #define PetscCheckSorted(n, idx) \
703:       do { \
704:         PetscBool _1_flg; \
705:         PetscSorted(n, idx, _1_flg); \
706:         PetscCheck(_1_flg, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Input array needs to be sorted"); \
707:       } while (0)

709:   #endif
710: #else  /* PETSC_CLANG_STATIC_ANALYZER */
711: template <typename Ta, typename Tb>
712: void PetscCheckSameType(Ta, int, Tb, int);
713: template <typename Ta, typename Tb>
714: void PetscCheckTypeName(Ta, Tb);
715: template <typename Ta, typename Tb, typename Tc>
716: void PetscCheckTypeName(Ta, Tb, Tc);
717: template <typename T>
719: template <typename Ta, typename Tb>
720: void PetscCheckSameComm(Ta, int, Tb, int);
721: template <typename Ta, typename Tb>
722: void PetscCheckSameTypeAndComm(Ta, int, Tb, int);
723: template <typename Ta, typename Tb>
725: template <typename Ta, typename Tb>
727: template <typename Ta, typename Tb>
729: template <typename Ta, typename Tb>
731: template <typename Ta, typename Tb>
733: template <typename Ta, typename Tb>
735: template <typename T>
736: void PetscCheckSorted(PetscInt, T);
737: #endif /* PETSC_CLANG_STATIC_ANALYZER */

739: /*MC
740:    PetscTryMethod - Queries an object for a method added with `PetscObjectComposeFunction()`, if it exists then calls it.

742:   Synopsis:
743:    #include "petsc/private/petscimpl.h"
744:    PetscTryMethod(PetscObject obj,const char *name,(arg_types),(arg_value))

746:    Input Parameters:
747: +   obj - the object
748: .   name - the name of the method, for example, "KSPGMRESSetRestart_C" for the function `KSPGMRESSetRestart()`
749: .   arg_types - the argument types for the method, for example, (KSP,PetscInt)
750: -   args - the arguments for the method, for example, (ksp,restart))

752:    Level: developer

754:    Notes:
755:    This does not return an error code, it is a macro that returns with an error code on error.

757:    Use `PetscUseTypeMethod()` or `PetscTryTypeMethod()` to call functions that are included in the objects function table, the `ops` array
758:    in the object.

760: .seealso: `PetscUseMethod()`, `PetscCall()`, `PetscUseTypeMethod()`, `PetscTryTypeMethod()`, `PetscCheck()`
761: M*/
762: #define PetscTryMethod(obj, A, B, C) \
763:   do { \
764:     PetscErrorCode(*_7_f) B; \
765:     PetscCall(PetscObjectQueryFunction((PetscObject)(obj), A, &_7_f)); \
766:     if (_7_f) PetscCall((*_7_f)C); \
767:   } while (0)

769: /*MC
770:    PetscUseMethod - Queries an object for a method added with `PetscObjectComposeFunction()`, if it exists then calls it, otherwise generates an error.

772:   Synopsis:
773:    #include "petsc/private/petscimpl.h"
774:    PetscUseMethod(PetscObject obj,const char *name,(arg_types),(arg_value))

776:    Input Parameters:
777: +   obj - the object
778: .   name - the name of the method, for example, "KSPGMRESSetRestart_C" for the function `KSPGMRESSetRestart()`
779: .   arg_types - the argument types for the method, for example, (KSP,PetscInt)
780: -   args - the arguments for the method, for example, (ksp,restart))

782:    Level: developer

784:    Notes:
785:    This does not return an error code, it is a macro that returns with an error code on error.

787:    Use `PetscUseTypeMethod()` or `PetscTryTypeMethod()` to call functions that are included in the objects function table, the `ops` array
788:    in the object.

790: .seealso: `PetscTryMethod()`, `PetscCall()`, `PetscUseTypeMethod()`, `PetscTryTypeMethod()`, `PetscCheck()`
791: M*/
792: #define PetscUseMethod(obj, A, B, C) \
793:   do { \
794:     PetscErrorCode(*_7_f) B; \
795:     PetscCall(PetscObjectQueryFunction((PetscObject)(obj), A, &_7_f)); \
796:     PetscCheck(_7_f, PetscObjectComm((PetscObject)(obj)), PETSC_ERR_SUP, "Cannot locate function %s in object", A); \
797:     PetscCall((*_7_f)C); \
798:   } while (0)

800: /*
801:   Use Microsoft traditional preprocessor.

803:   The Microsoft compiler option -Zc:preprocessor available in recent versions of the compiler
804:   sets  _MSVC_TRADITIONAL to zero so this code path is not used.

806:   It appears the Intel Windows compiler icl does not have an equaivalent of  -Zc:preprocessor

808:   These macros use the trick that Windows compilers remove the , before the __VA_ARGS__ if __VA_ARGS__ does not exist

810:   PetscCall() cannot be used in the macros because the remove the , trick does not work in a macro in a macro
811: */
812: #if (defined(_MSC_VER) && (!defined(_MSVC_TRADITIONAL) || _MSVC_TRADITIONAL)) || defined(__ICL)

814:   #define PetscUseTypeMethod(obj, OP, ...) \
815:     do { \
816:       PetscErrorCode ierr_p_; \
817:       PetscStackUpdateLine; \
818:       PetscCheck((obj)->ops->OP, PetscObjectComm((PetscObject)obj), PETSC_ERR_SUP, "No method %s for %s of type %s", PetscStringize(OP), ((PetscObject)obj)->class_name, ((PetscObject)obj)->type_name); \
819:       ierr_p_ = (*(obj)->ops->OP)(obj, __VA_ARGS__); \
820:       PetscCall(ierr_p_); \
821:     } while (0)

823:   #define PetscTryTypeMethod(obj, OP, ...) \
824:     do { \
825:       if ((obj)->ops->OP) { \
826:         PetscErrorCode ierr_p_; \
827:         PetscStackUpdateLine; \
828:         ierr_p_ = (*(obj)->ops->OP)(obj, __VA_ARGS__); \
829:         PetscCall(ierr_p_); \
830:       } \
831:     } while (0)

833: #else

835:   /*MC
836:    PetscUseTypeMethod - Call a method on a PETSc object, that is a function in the objects function table obj->ops, error if the method does not exist

838:   Synopsis:
839:    #include "petsc/private/petscimpl.h"
840:    PetscUseTypeMethod(obj,method,other_args)

842:    Input Parameters:
843: +   obj - the object the method is called on
844: .   method - the name of the method, for example, mult for the PETSc routine MatMult()
845: -   other_args - the other arguments for the method, obj is the first argument

847:    Level: developer

849:    Note:
850:    This does not return an error code, it is a macro that returns with an error code on error.

852:    Use `PetscUseMethod()` or `PetscTryMethod()` to call functions that have been composed to an object with `PetscObjectComposeFunction()`

854: .seealso: `PetscTryMethod()`, `PetscUseMethod()`, `PetscCall()`, `PetscCheck()`, `PetscTryTypeMethod()`
855: M*/
856:   #define PetscUseTypeMethod(obj, ...) \
857:     do { \
858:       PetscCheck((obj)->ops->PETSC_FIRST_ARG((__VA_ARGS__, unused)), PetscObjectComm((PetscObject)obj), PETSC_ERR_SUP, "No method %s for %s of type %s", \
859:                  PetscStringize(PETSC_FIRST_ARG((__VA_ARGS__,unused))), ((PetscObject)obj)->class_name, ((PetscObject)obj)->type_name); \
860:       PetscCall((*(obj)->ops->PETSC_FIRST_ARG((__VA_ARGS__, unused)))(obj PETSC_REST_ARG(__VA_ARGS__))); \
861:     } while (0)

863:   /*MC
864:    PetscTryTypeMethod - Call a method on a PETSc object, that is a function in the objects function table obj->ops, skip if the method does not exist

866:   Synopsis:
867:    #include "petsc/private/petscimpl.h"
868:    PetscTryTtype(obj,method,other_args)

870:    Input Parameters:
871: +   obj - the object the method is called on
872: .   method - the name of the method, for example, mult for the PETSc routine MatMult()
873: -   other_args - the other arguments for the method, obj is the first argument

875:    Level: developer

877:    Note:
878:    This does not return an error code, it is a macro that returns with an error code on error.

880:    Use `PetscUseMethod()` or `PetscTryMethod()` to call functions that have been composed to an object with `PetscObjectComposeFunction()`

882: .seealso: `PetscTryMethod()`, `PetscUseMethod()`, `PetscCall()`, `PetscCheck()`, `PetscUseTypeMethod()`
883: M*/
884:   #define PetscTryTypeMethod(obj, ...) \
885:     do { \
886:       if ((obj)->ops->PETSC_FIRST_ARG((__VA_ARGS__, unused))) PetscCall((*(obj)->ops->PETSC_FIRST_ARG((__VA_ARGS__, unused)))(obj PETSC_REST_ARG(__VA_ARGS__))); \
887:     } while (0)

889: #endif

891: /*MC
892:    PetscObjectStateIncrease - Increases the state of any `PetscObject`

894:    Synopsis:
895:    #include "petsc/private/petscimpl.h"
896:    PetscErrorCode PetscObjectStateIncrease(PetscObject obj)

898:    Logically Collective

900:    Input Parameter:
901: .  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. This must be
902:          cast with a (PetscObject), for example,
903:          `PetscObjectStateIncrease`((`PetscObject`)mat);

905:    Level: developer

907:    Notes:
908:    Object state is a 64 bit integer which gets increased every time
909:    the object is changed internally. By saving and later querying the object state
910:    one can determine whether information about the object is still current.
911:    Currently, state is maintained for `Vec` and `Mat` objects.

913:    This routine is mostly for internal use by PETSc; a developer need only
914:    call it after explicit access to an object's internals. Routines such
915:    as `VecSet()` or `MatScale()` already call this routine. It is also called, as a
916:    precaution, in `VecRestoreArray()`, `MatRestoreRow()`, `MatDenseRestoreArray()`.

918:    Routines such as `VecNorm()` can by-pass the computation if the norm has already been computed and the vector's state has not changed.

920:    This routine is logically collective because state equality comparison needs to be possible without communication.

922:    `Mat` also has `MatGetNonzeroState()` for tracking changes to the nonzero structure.

924: .seealso: `PetscObjectStateGet()`, `PetscObject`
925: M*/
926: #define PetscObjectStateIncrease(obj) ((obj)->state++, PETSC_SUCCESS)

928: PETSC_EXTERN PetscErrorCode PetscObjectStateGet(PetscObject, PetscObjectState *);
929: PETSC_EXTERN PetscErrorCode PetscObjectStateSet(PetscObject, PetscObjectState);
930: PETSC_EXTERN PetscErrorCode PetscObjectComposedDataRegister(PetscInt *);
931: PETSC_EXTERN PetscErrorCode PetscObjectComposedDataIncreaseInt(PetscObject);
932: PETSC_EXTERN PetscErrorCode PetscObjectComposedDataIncreaseIntstar(PetscObject);
933: PETSC_EXTERN PetscErrorCode PetscObjectComposedDataIncreaseReal(PetscObject);
934: PETSC_EXTERN PetscErrorCode PetscObjectComposedDataIncreaseRealstar(PetscObject);
935: PETSC_EXTERN PetscErrorCode PetscObjectComposedDataIncreaseScalar(PetscObject);
936: PETSC_EXTERN PetscErrorCode PetscObjectComposedDataIncreaseScalarstar(PetscObject);
937: PETSC_EXTERN PetscInt       PetscObjectComposedDataMax;

939: /*MC
940:    PetscObjectComposedDataSetInt - attach integer data to a `PetscObject` that may be accessed with `PetscObjectComposedDataGetInt()`

942:    Synopsis:
943:    #include "petsc/private/petscimpl.h"
944:    PetscErrorCode PetscObjectComposedDataSetInt(PetscObject obj,int id,int data)

946:    Not Collective

948:    Input parameters:
949: +  obj - the object to which data is to be attached
950: .  id - the identifier for the data
951: -  data - the data to  be attached

953:    Level: developer

955:    Notes:
956:    The `data` identifier can be created through a call to  `PetscObjectComposedDataRegister()`

958:    This allows the efficient composition of a single integer value with a `PetscObject`. Complex data may be
959:    attached with `PetscObjectCompose()`

961: .seealso: `PetscObjectComposedDataGetInt()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetReal()`,
962:           `PetscObjectComposedDataGetIntstar()`, `PetscObjectComposedDataSetIntstar()`, `PetscObject`,
963:           `PetscObjectCompose()`, `PetscObjectQuery()`
964: M*/
965: #define PetscObjectComposedDataSetInt(obj, id, data) \
966:   ((PetscErrorCode)((((obj)->int_idmax < PetscObjectComposedDataMax) && PetscObjectComposedDataIncreaseInt(obj)) || ((obj)->intcomposeddata[id] = data, (obj)->intcomposedstate[id] = (obj)->state, PETSC_SUCCESS)))

968: /*MC
969:    PetscObjectComposedDataGetInt - retrieve integer data attached to an object with `PetscObjectComposedDataSetInt()`

971:    Synopsis:
972:    #include "petsc/private/petscimpl.h"
973:    PetscErrorCode PetscObjectComposedDataGetInt(PetscObject obj,int id,int data,PetscBool  flag)

975:    Not Collective

977:    Input parameters:
978: +  obj - the object from which data is to be retrieved
979: -  id - the identifier for the data

981:    Output parameters:
982: +  data - the data to be retrieved
983: -  flag - `PETSC_TRUE` if the data item exists and is valid, `PETSC_FALSE` otherwise

985:    Level: developer

987:    Notes:
988:    The `data` and `flag` variables are inlined, so they are not pointers.

990:    The length of the array accessed must be known.

992: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetReal()`,
993:           `PetscObjectComposedDataGetIntstar()`, `PetscObjectComposedDataSetIntstar()`, `PetscObject`,
994:           `PetscObjectCompose()`, `PetscObjectQuery()`
995: M*/
996: #define PetscObjectComposedDataGetInt(obj, id, data, flag) (((obj)->intcomposedstate ? (data = (obj)->intcomposeddata[id], flag = (PetscBool)((obj)->intcomposedstate[id] == (obj)->state)) : (flag = PETSC_FALSE)), PETSC_SUCCESS)

998: /*MC
999:    PetscObjectComposedDataSetIntstar - attach an integer array data to a `PetscObject` that may be accessed with `PetscObjectComposedDataGetIntstar()`

1001:    Synopsis:
1002:    #include "petsc/private/petscimpl.h"
1003:    PetscErrorCode PetscObjectComposedDataSetIntstar(PetscObject obj,int id,int *data)

1005:    Not Collective

1007:    Input parameters:
1008: +  obj - the object to which data is to be attached
1009: .  id - the identifier for the data
1010: -  data - the data to  be attached

1012:    Level: developer

1014:    Notes:
1015:    The `data` identifier can be determined through a call to `PetscObjectComposedDataRegister()`

1017:    The length of the array accessed must be known, it is not available through this API.

1019: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetReal()`,
1020:           `PetscObjectComposedDataGetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1021:           `PetscObjectCompose()`, `PetscObjectQuery()`
1022: M*/
1023: #define PetscObjectComposedDataSetIntstar(obj, id, data) \
1024:   ((PetscErrorCode)((((obj)->intstar_idmax < PetscObjectComposedDataMax) && PetscObjectComposedDataIncreaseIntstar(obj)) || ((obj)->intstarcomposeddata[id] = data, (obj)->intstarcomposedstate[id] = (obj)->state, PETSC_SUCCESS)))

1026: /*MC
1027:    PetscObjectComposedDataGetIntstar - retrieve integer array data attached to an object with `PetscObjectComposedDataSetIntstar()`

1029:    Synopsis:
1030:    #include "petsc/private/petscimpl.h"
1031:    PetscErrorCode PetscObjectComposedDataGetIntstar(PetscObject obj,int id,int *data,PetscBool  flag)

1033:    Not Collective

1035:    Input parameters:
1036: +  obj - the object from which data is to be retrieved
1037: -  id - the identifier for the data

1039:    Output parameters:
1040: +  data - the data to be retrieved
1041: -  flag - `PETSC_TRUE` if the data item exists and is valid, `PETSC_FALSE` otherwise

1043:    Level: developer

1045:    Notes:
1046:    The `data` and `flag` variables are inlined, so they are not pointers.

1048:    The length of the array accessed must be known, it is not available through this API.

1050: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetReal()`,
1051:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1052:           `PetscObjectCompose()`, `PetscObjectQuery()`
1053: M*/
1054: #define PetscObjectComposedDataGetIntstar(obj, id, data, flag) \
1055:   ((PetscErrorCode)(((obj)->intstarcomposedstate ? (data = (obj)->intstarcomposeddata[id], flag = (PetscBool)((obj)->intstarcomposedstate[id] == (obj)->state)) : (flag = PETSC_FALSE)), PETSC_SUCCESS))

1057: /*MC
1058:    PetscObjectComposedDataSetReal - attach real data to a `PetscObject` that may be accessed with `PetscObjectComposedDataGetReal()`

1060:    Synopsis:
1061:    #include "petsc/private/petscimpl.h"
1062:    PetscErrorCode PetscObjectComposedDataSetReal(PetscObject obj,int id,PetscReal data)

1064:    Not Collective

1066:    Input parameters:
1067: +  obj - the object to which data is to be attached
1068: .  id - the identifier for the data
1069: -  data - the data to  be attached

1071:    Level: developer

1073:    Note:
1074:    The `data` identifier can be determined through a call to  `PetscObjectComposedDataRegister()`

1076: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetIntstar()`,
1077:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1078:           `PetscObjectCompose()`, `PetscObjectQuery()`
1079: M*/
1080: #define PetscObjectComposedDataSetReal(obj, id, data) \
1081:   ((PetscErrorCode)((((obj)->real_idmax < PetscObjectComposedDataMax) && PetscObjectComposedDataIncreaseReal(obj)) || ((obj)->realcomposeddata[id] = data, (obj)->realcomposedstate[id] = (obj)->state, PETSC_SUCCESS)))

1083: /*MC
1084:    PetscObjectComposedDataGetReal - retrieve real data attached to an object set with `PetscObjectComposedDataSetReal()`

1086:    Synopsis:
1087:    #include "petsc/private/petscimpl.h"
1088:    PetscErrorCode PetscObjectComposedDataGetReal(PetscObject obj,int id,PetscReal data,PetscBool  flag)

1090:    Not Collective

1092:    Input parameters:
1093: +  obj - the object from which data is to be retrieved
1094: -  id - the identifier for the data

1096:    Output parameters:
1097: +  data - the data to be retrieved
1098: -  flag - `PETSC_TRUE` if the data item exists and is valid, `PETSC_FALSE` otherwise

1100:    Level: developer

1102:    Note:
1103:    The `data` and `flag` variables are inlined, so they are not pointers.

1105: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataSetReal()`, `PetscObjectComposedDataSetIntstar()`,
1106:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1107:           `PetscObjectCompose()`, `PetscObjectQuery()`
1108: M*/
1109: #define PetscObjectComposedDataGetReal(obj, id, data, flag) ((PetscErrorCode)(((obj)->realcomposedstate ? (data = (obj)->realcomposeddata[id], flag = (PetscBool)((obj)->realcomposedstate[id] == (obj)->state)) : (flag = PETSC_FALSE)), PETSC_SUCCESS))

1111: /*MC
1112:    PetscObjectComposedDataSetRealstar - attach real array data to a `PetscObject` that may be retrieved with `PetscObjectComposedDataGetRealstar()`

1114:    Synopsis:
1115:    #include "petsc/private/petscimpl.h"
1116:    PetscErrorCode PetscObjectComposedDataSetRealstar(PetscObject obj,int id,PetscReal *data)

1118:    Not Collective

1120:    Input parameters:
1121: +  obj - the object to which data is to be attached
1122: .  id - the identifier for the data
1123: -  data - the data to  be attached

1125:    Level: developer

1127:    Notes:
1128:    The `data` identifier can be determined through a call to `PetscObjectComposedDataRegister()`

1130:    The length of the array accessed must be known, it is not available through this API.

1132: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataSetReal()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetIntstar()`,
1133:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1134:           `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscObjectComposedDataGetRealstar()`
1135: M*/
1136: #define PetscObjectComposedDataSetRealstar(obj, id, data) \
1137:   ((PetscErrorCode)((((obj)->realstar_idmax < PetscObjectComposedDataMax) && PetscObjectComposedDataIncreaseRealstar(obj)) || ((obj)->realstarcomposeddata[id] = data, (obj)->realstarcomposedstate[id] = (obj)->state, PETSC_SUCCESS)))

1139: /*MC
1140:    PetscObjectComposedDataGetRealstar - retrieve real array data attached to an object with `PetscObjectComposedDataSetRealstar()`

1142:    Synopsis:
1143:    #include "petsc/private/petscimpl.h"
1144:    PetscErrorCode PetscObjectComposedDataGetRealstar(PetscObject obj,int id,PetscReal *data,PetscBool  flag)

1146:    Not Collective

1148:    Input parameters:
1149: +  obj - the object from which data is to be retrieved
1150: -  id - the identifier for the data

1152:    Output parameters:
1153: +  data - the data to be retrieved
1154: -  flag - `PETSC_TRUE` if the data item exists and is valid, `PETSC_FALSE` otherwise

1156:    Notes:
1157:    Level: developer

1159:    The `data` and `flag` variables are inlined, so they are not pointers.

1161:    The length of the array accessed must be known, it is not available through this API.

1163: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataSetReal()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetIntstar()`,
1164:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1165:           `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscObjectComposedDataSetRealstar()`
1166: M*/
1167: #define PetscObjectComposedDataGetRealstar(obj, id, data, flag) \
1168:   ((PetscErrorCode)(((obj)->realstarcomposedstate ? (data = (obj)->realstarcomposeddata[id], flag = (PetscBool)((obj)->realstarcomposedstate[id] == (obj)->state)) : (flag = PETSC_FALSE)), PETSC_SUCCESS))

1170: /*MC
1171:    PetscObjectComposedDataSetScalar - attach scalar data to a PetscObject that may be retrieved with `PetscObjectComposedDataGetScalar()`

1173:    Synopsis:
1174:    #include "petsc/private/petscimpl.h"
1175:    PetscErrorCode PetscObjectComposedDataSetScalar(PetscObject obj,int id,PetscScalar data)

1177:    Not Collective

1179:    Input parameters:
1180: +  obj - the object to which data is to be attached
1181: .  id - the identifier for the data
1182: -  data - the data to  be attached

1184:    Level: developer

1186:    Note:
1187:    The `data` identifier can be determined through a call to `PetscObjectComposedDataRegister()`

1189: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataSetReal()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetIntstar()`,
1190:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1191:           `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscObjectComposedDataSetRealstar()`, `PetscObjectComposedDataGetScalar()`
1192: M*/
1193: #if defined(PETSC_USE_COMPLEX)
1194:   #define PetscObjectComposedDataSetScalar(obj, id, data) \
1195:     ((PetscErrorCode)((((obj)->scalar_idmax < PetscObjectComposedDataMax) && PetscObjectComposedDataIncreaseScalar(obj)) || ((obj)->scalarcomposeddata[id] = data, (obj)->scalarcomposedstate[id] = (obj)->state, PETSC_SUCCESS)))
1196: #else
1197:   #define PetscObjectComposedDataSetScalar(obj, id, data) PetscObjectComposedDataSetReal(obj, id, data)
1198: #endif
1199: /*MC
1200:    PetscObjectComposedDataGetScalar - retrieve scalar data attached to an object that was set with `PetscObjectComposedDataSetScalar()`

1202:    Synopsis:
1203:    #include "petsc/private/petscimpl.h"
1204:    PetscErrorCode PetscObjectComposedDataGetScalar(PetscObject obj,int id,PetscScalar data,PetscBool  flag)

1206:    Not Collective

1208:    Input parameters:
1209: +  obj - the object from which data is to be retrieved
1210: -  id - the identifier for the data

1212:    Output parameters:
1213: +  data - the data to be retrieved
1214: -  flag - `PETSC_TRUE` if the data item exists and is valid, `PETSC_FALSE` otherwise

1216:    Level: developer

1218:    Note:
1219:    The `data` and `flag` variables are inlined, so they are not pointers.

1221: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataSetReal()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetIntstar()`,
1222:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1223:           `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscObjectComposedDataSetRealstar()`, `PetscObjectComposedDataSetScalar()`
1224: M*/
1225: #if defined(PETSC_USE_COMPLEX)
1226:   #define PetscObjectComposedDataGetScalar(obj, id, data, flag) \
1227:     ((PetscErrorCode)(((obj)->scalarcomposedstate ? (data = (obj)->scalarcomposeddata[id], flag = (PetscBool)((obj)->scalarcomposedstate[id] == (obj)->state)) : (flag = PETSC_FALSE)), PETSC_SUCCESS))
1228: #else
1229:   #define PetscObjectComposedDataGetScalar(obj, id, data, flag) PetscObjectComposedDataGetReal(obj, id, data, flag)
1230: #endif

1232: /*MC
1233:    PetscObjectComposedDataSetScalarstar - attach scalar array data to a `PetscObject` that may be retrieved with `PetscObjectComposedDataSetScalarstar()`

1235:    Synopsis:
1236:    #include "petsc/private/petscimpl.h"
1237:    PetscErrorCode PetscObjectComposedDataSetScalarstar(PetscObject obj,int id,PetscScalar *data)

1239:    Not Collective

1241:    Input parameters:
1242: +  obj - the object to which data is to be attached
1243: .  id - the identifier for the data
1244: -  data - the data to  be attached

1246:    Level: developer

1248:    Notes:
1249:    The `data` identifier can be determined through a call to `PetscObjectComposedDataRegister()`

1251:    The length of the array accessed must be known, it is not available through this API.

1253: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataSetReal()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetIntstar()`,
1254:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1255:           `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscObjectComposedDataSetRealstar()`, `PetscObjectComposedDataGetScalarstar()`
1256: M*/
1257: #if defined(PETSC_USE_COMPLEX)
1258:   #define PetscObjectComposedDataSetScalarstar(obj, id, data) \
1259:     ((PetscErrorCode)((((obj)->scalarstar_idmax < PetscObjectComposedDataMax) && PetscObjectComposedDataIncreaseScalarstar(obj)) || ((obj)->scalarstarcomposeddata[id] = data, (obj)->scalarstarcomposedstate[id] = (obj)->state, PETSC_SUCCESS)))
1260: #else
1261:   #define PetscObjectComposedDataSetScalarstar(obj, id, data) PetscObjectComposedDataSetRealstar(obj, id, data)
1262: #endif
1263: /*MC
1264:    PetscObjectComposedDataGetScalarstar - retrieve scalar array data set with `PetscObjectComposedDataSetScalarstar()`
1265:    attached to an object

1267:    Synopsis:
1268:    #include "petsc/private/petscimpl.h"
1269:    PetscErrorCode PetscObjectComposedDataGetScalarstar(PetscObject obj,int id,PetscScalar *data,PetscBool  flag)

1271:    Not Collective

1273:    Input parameters:
1274: +  obj - the object from which data is to be retrieved
1275: -  id - the identifier for the data

1277:    Output parameters:
1278: +  data - the data to be retrieved
1279: -  flag - `PETSC_TRUE` if the data item exists and is valid, `PETSC_FALSE` otherwise

1281:    Level: developer

1283:    Notes:
1284:    The `data` and `flag` variables are inlined, so they are not pointers.

1286:    The length of the array accessed must be known, it is not available through this API.

1288: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataSetReal()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetIntstar()`,
1289:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
1290:           `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscObjectComposedDataSetRealstar()`, `PetscObjectComposedDataSetScalarstar()`
1291: M*/
1292: #if defined(PETSC_USE_COMPLEX)
1293:   #define PetscObjectComposedDataGetScalarstar(obj, id, data, flag) \
1294:     ((PetscErrorCode)(((obj)->scalarstarcomposedstate ? (data = (obj)->scalarstarcomposeddata[id], flag = (PetscBool)((obj)->scalarstarcomposedstate[id] == (obj)->state)) : (flag = PETSC_FALSE)), PETSC_SUCCESS))
1295: #else
1296:   #define PetscObjectComposedDataGetScalarstar(obj, id, data, flag) PetscObjectComposedDataGetRealstar(obj, id, data, flag)
1297: #endif

1299: PETSC_EXTERN PetscMPIInt Petsc_Counter_keyval;
1300: PETSC_EXTERN PetscMPIInt Petsc_InnerComm_keyval;
1301: PETSC_EXTERN PetscMPIInt Petsc_OuterComm_keyval;
1302: PETSC_EXTERN PetscMPIInt Petsc_Seq_keyval;
1303: PETSC_EXTERN PetscMPIInt Petsc_ShmComm_keyval;
1304: PETSC_EXTERN PetscMPIInt Petsc_CreationIdx_keyval;
1305: PETSC_EXTERN PetscMPIInt Petsc_Garbage_HMap_keyval;

1307: PETSC_EXTERN PetscMPIInt Petsc_SharedWD_keyval;
1308: PETSC_EXTERN PetscMPIInt Petsc_SharedTmp_keyval;

1310: struct PetscCommStash {
1311:   struct PetscCommStash *next;
1312:   MPI_Comm               comm;
1313: };

1315: /*
1316:   PETSc communicators have this attribute, see
1317:   PetscCommDuplicate(), PetscCommDestroy(), PetscCommGetNewTag(), PetscObjectGetName()
1318: */
1319: typedef struct {
1320:   PetscMPIInt            tag;       /* next free tag value */
1321:   PetscInt               refcount;  /* number of references, communicator can be freed when this reaches 0 */
1322:   PetscInt               namecount; /* used to generate the next name, as in Vec_0, Mat_1, ... */
1323:   PetscMPIInt           *iflags;    /* length of comm size, shared by all calls to PetscCommBuildTwoSided_Allreduce/RedScatter on this comm */
1324:   struct PetscCommStash *comms;     /* communicators available for PETSc to pass off to other packages */
1325: } PetscCommCounter;

1327: typedef enum {
1328:   STATE_BEGIN,
1329:   STATE_PENDING,
1330:   STATE_END
1331: } SRState;

1333: typedef enum {
1334:   PETSC_SR_REDUCE_SUM = 0,
1335:   PETSC_SR_REDUCE_MAX = 1,
1336:   PETSC_SR_REDUCE_MIN = 2
1337: } PetscSRReductionType;

1339: typedef struct {
1340:   MPI_Comm     comm;
1341:   MPI_Request  request;
1342:   PetscBool    mix;
1343:   PetscBool    async;
1344:   PetscScalar *lvalues;    /* this are the reduced values before call to MPI_Allreduce() */
1345:   PetscScalar *gvalues;    /* values after call to MPI_Allreduce() */
1346:   void       **invecs;     /* for debugging only, vector/memory used with each op */
1347:   PetscInt    *reducetype; /* is particular value to be summed or maxed? */
1348:   struct {
1349:     PetscScalar v;
1350:     PetscInt    i;
1351:   }       *lvalues_mix, *gvalues_mix; /* used when mixing reduce operations */
1352:   SRState  state;                     /* are we calling xxxBegin() or xxxEnd()? */
1353:   PetscInt maxops;                    /* total amount of space we have for requests */
1354:   PetscInt numopsbegin;               /* number of requests that have been queued in */
1355:   PetscInt numopsend;                 /* number of requests that have been gotten by user */
1356: } PetscSplitReduction;

1358: PETSC_EXTERN PetscErrorCode PetscSplitReductionGet(MPI_Comm, PetscSplitReduction **);
1359: PETSC_EXTERN PetscErrorCode PetscSplitReductionEnd(PetscSplitReduction *);
1360: PETSC_EXTERN PetscErrorCode PetscSplitReductionExtend(PetscSplitReduction *);

1362: #if defined(PETSC_HAVE_THREADSAFETY)
1363:   #if defined(PETSC_HAVE_CONCURRENCYKIT)
1364:     #if defined(__cplusplus)
1365: /*  CK does not have extern "C" protection in their include files */
1366: extern "C" {
1367:     #endif
1368:     #include <ck_spinlock.h>
1369:     #if defined(__cplusplus)
1370: }
1371:     #endif
1372: typedef ck_spinlock_t PetscSpinlock;

1374: static inline PetscErrorCode PetscSpinlockCreate(PetscSpinlock *ck_spinlock)
1375: {
1376:   ck_spinlock_init(ck_spinlock);
1377:   return PETSC_SUCCESS;
1378: }
1379: static inline PetscErrorCode PetscSpinlockLock(PetscSpinlock *ck_spinlock)
1380: {
1381:   ck_spinlock_lock(ck_spinlock);
1382:   return PETSC_SUCCESS;
1383: }
1384: static inline PetscErrorCode PetscSpinlockUnlock(PetscSpinlock *ck_spinlock)
1385: {
1386:   ck_spinlock_unlock(ck_spinlock);
1387:   return PETSC_SUCCESS;
1388: }
1389: static inline PetscErrorCode PetscSpinlockDestroy(PetscSpinlock *ck_spinlock)
1390: {
1391:   return PETSC_SUCCESS;
1392: }
1393:   #elif (defined(__cplusplus) && defined(PETSC_HAVE_CXX_ATOMIC)) || (!defined(__cplusplus) && defined(PETSC_HAVE_STDATOMIC_H))
1394:     #if defined(__cplusplus)
1395:       #include <atomic>
1396:       #define petsc_atomic_flag                 std::atomic_flag
1397:       #define petsc_atomic_flag_test_and_set(p) std::atomic_flag_test_and_set_explicit(p, std::memory_order_relaxed)
1398:       #define petsc_atomic_flag_clear(p)        std::atomic_flag_clear_explicit(p, std::memory_order_relaxed)
1399:     #else
1400:       #include <stdatomic.h>
1401:       #define petsc_atomic_flag                 atomic_flag
1402:       #define petsc_atomic_flag_test_and_set(p) atomic_flag_test_and_set_explicit(p, memory_order_relaxed)
1403:       #define petsc_atomic_flag_clear(p)        atomic_flag_clear_explicit(p, memory_order_relaxed)
1404:     #endif

1406: typedef petsc_atomic_flag PetscSpinlock;

1408: static inline PetscErrorCode PetscSpinlockCreate(PetscSpinlock *spinlock)
1409: {
1410:   petsc_atomic_flag_clear(spinlock);
1411:   return PETSC_SUCCESS;
1412: }
1413: static inline PetscErrorCode PetscSpinlockLock(PetscSpinlock *spinlock)
1414: {
1415:   do {
1416:   } while (petsc_atomic_flag_test_and_set(spinlock));
1417:   return PETSC_SUCCESS;
1418: }
1419: static inline PetscErrorCode PetscSpinlockUnlock(PetscSpinlock *spinlock)
1420: {
1421:   petsc_atomic_flag_clear(spinlock);
1422:   return PETSC_SUCCESS;
1423: }
1424: static inline PetscErrorCode PetscSpinlockDestroy(PetscSpinlock *spinlock)
1425: {
1426:   return PETSC_SUCCESS;
1427: }
1428:     #undef petsc_atomic_flag_test_and_set
1429:     #undef petsc_atomic_flag_clear
1430:     #undef petsc_atomic_flag

1432:   #elif defined(PETSC_HAVE_OPENMP)

1434:     #include <omp.h>
1435: typedef omp_lock_t PetscSpinlock;

1437: static inline PetscErrorCode PetscSpinlockCreate(PetscSpinlock *omp_lock)
1438: {
1439:   omp_init_lock(omp_lock);
1440:   return PETSC_SUCCESS;
1441: }
1442: static inline PetscErrorCode PetscSpinlockLock(PetscSpinlock *omp_lock)
1443: {
1444:   omp_set_lock(omp_lock);
1445:   return PETSC_SUCCESS;
1446: }
1447: static inline PetscErrorCode PetscSpinlockUnlock(PetscSpinlock *omp_lock)
1448: {
1449:   omp_unset_lock(omp_lock);
1450:   return PETSC_SUCCESS;
1451: }
1452: static inline PetscErrorCode PetscSpinlockDestroy(PetscSpinlock *omp_lock)
1453: {
1454:   omp_destroy_lock(omp_lock);
1455:   return PETSC_SUCCESS;
1456: }
1457:   #else
1458:     #if defined(__cplusplus)
1459:       #error "Thread safety requires either --download-concurrencykit, std::atomic, or --with-openmp"
1460:     #else
1461:       #error "Thread safety requires either --download-concurrencykit, stdatomic.h, or --with-openmp"
1462:     #endif
1463:   #endif

1465: #else
1466: typedef int PetscSpinlock;
1467:   #define PetscSpinlockCreate(a)  PETSC_SUCCESS
1468:   #define PetscSpinlockLock(a)    PETSC_SUCCESS
1469:   #define PetscSpinlockUnlock(a)  PETSC_SUCCESS
1470:   #define PetscSpinlockDestroy(a) PETSC_SUCCESS
1471: #endif

1473: #if defined(PETSC_HAVE_THREADSAFETY)
1474: PETSC_INTERN PetscSpinlock PetscViewerASCIISpinLockOpen;
1475: PETSC_INTERN PetscSpinlock PetscViewerASCIISpinLockStdout;
1476: PETSC_INTERN PetscSpinlock PetscViewerASCIISpinLockStderr;
1477: PETSC_INTERN PetscSpinlock PetscCommSpinLock;
1478: #endif

1480: PETSC_EXTERN PetscLogEvent PETSC_Barrier;
1481: PETSC_EXTERN PetscLogEvent PETSC_BuildTwoSided;
1482: PETSC_EXTERN PetscLogEvent PETSC_BuildTwoSidedF;
1483: PETSC_EXTERN PetscBool     use_gpu_aware_mpi;
1484: PETSC_EXTERN PetscBool     PetscPrintFunctionList;

1486: #if defined(PETSC_HAVE_ADIOS)
1487: PETSC_EXTERN int64_t Petsc_adios_group;
1488: #endif

1490: #if defined(PETSC_HAVE_KOKKOS)
1491: PETSC_INTERN PetscBool      PetscBeganKokkos;
1492: PETSC_EXTERN PetscBool      PetscKokkosInitialized;
1493: PETSC_INTERN PetscErrorCode PetscKokkosIsInitialized_Private(PetscBool *);
1494: PETSC_INTERN PetscErrorCode PetscKokkosFinalize_Private(void);
1495: #endif

1497: #if defined(PETSC_HAVE_OPENMP)
1498: PETSC_EXTERN PetscInt PetscNumOMPThreads;
1499: #endif

1501: #endif /* PETSCIMPL_H */