1: /*
  2:      Provides utility routines for manulating any type of PETSc object.
  3: */
  4: #include <petsc/private/petscimpl.h>
  5: #include <petscviewer.h>

  7: static PetscErrorCode DestroyComposedData(void ***composed_star, PetscObjectState **state_star, PetscInt *count_star, void **composed, PetscObjectState **state)
  8: {
  9:   void **tmp_star = *composed_star;

 11:   PetscFunctionBegin;
 12:   for (PetscInt i = 0, imax = *count_star; i < imax; ++i) PetscCall(PetscFree(tmp_star[i]));
 13:   PetscCall(PetscFree2(*composed_star, *state_star));
 14:   PetscCall(PetscFree2(*composed, *state));
 15:   *count_star = 0;
 16:   PetscFunctionReturn(PETSC_SUCCESS);
 17: }

 19: PetscErrorCode PetscComposedQuantitiesDestroy(PetscObject obj)
 20: {
 21:   PetscFunctionBegin;
 23:   PetscCall(DestroyComposedData((void ***)&obj->intstarcomposeddata, &obj->intstarcomposedstate, &obj->intstar_idmax, (void **)&obj->intcomposeddata, &obj->intcomposedstate));
 24:   PetscCall(DestroyComposedData((void ***)&obj->realstarcomposeddata, &obj->realstarcomposedstate, &obj->realstar_idmax, (void **)&obj->realcomposeddata, &obj->realcomposedstate));
 25: #if PetscDefined(USE_COMPLEX)
 26:   PetscCall(DestroyComposedData((void ***)&obj->scalarstarcomposeddata, &obj->scalarstarcomposedstate, &obj->scalarstar_idmax, (void **)&obj->scalarcomposeddata, &obj->scalarcomposedstate));
 27: #endif
 28:   PetscFunctionReturn(PETSC_SUCCESS);
 29: }

 31: /*@
 32:   PetscObjectDestroy - Destroys a `PetscObject`, regardless of the type.

 34:   Collective

 36:   Input Parameter:
 37: . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`\*), for example,
 38:         `PetscObjectDestroy`((`PetscObject`\*)&mat);

 40:   Level: beginner

 42: .seealso: `PetscObject`
 43: @*/
 44: PetscErrorCode PetscObjectDestroy(PetscObject *obj)
 45: {
 46:   PetscFunctionBegin;
 47:   if (!obj || !*obj) PetscFunctionReturn(PETSC_SUCCESS);
 49:   PetscCheck((*obj)->bops->destroy, PETSC_COMM_SELF, PETSC_ERR_PLIB, "This PETSc object of class %s does not have a generic destroy routine", (*obj)->class_name);
 50:   PetscCall((*(*obj)->bops->destroy)(obj));
 51:   PetscFunctionReturn(PETSC_SUCCESS);
 52: }

 54: /*@
 55:   PetscObjectView - Views a `PetscObject` regardless of the type.

 57:   Collective

 59:   Input Parameters:
 60: + obj    - any PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`), for example,
 61:            `PetscObjectView`((`PetscObject`)mat,`viewer`);
 62: - viewer - any PETSc viewer

 64:   Level: intermediate

 66: .seealso: `PetscObject`, `PetscObjectViewFromOptions()`, `PetscViewer`
 67: @*/
 68: PetscErrorCode PetscObjectView(PetscObject obj, PetscViewer viewer)
 69: {
 70:   PetscFunctionBegin;
 72:   PetscCheck(obj->bops->view, PETSC_COMM_SELF, PETSC_ERR_SUP, "This PETSc object does not have a generic viewer routine");
 73:   if (!viewer) PetscCall(PetscViewerASCIIGetStdout(obj->comm, &viewer));

 76:   PetscCall((*obj->bops->view)(obj, viewer));
 77:   PetscFunctionReturn(PETSC_SUCCESS);
 78: }

 80: /*@
 81:   PetscObjectViewFromOptions - Processes command line options to determine if/how a `PetscObject` is to be viewed.

 83:   Collective

 85:   Input Parameters:
 86: + obj        - the object
 87: . bobj       - optional other object that provides prefix (if `NULL` then the prefix in `obj` is used)
 88: - optionname - option string that is used to activate viewing

 90:   Options Database Key:
 91: . -optionname_view [viewertype]:... - option name and values. In actual usage this would be something like `-mat_coarse_view`

 93:   Level: developer

 95:   Notes:
 96:   The argument has the following form
 97: .vb
 98:     type:filename:format:filemode
 99: .ve
100:   where all parts are optional, but you need to include the colon to access the next part. For example, to read from an HDF5 file, use
101: .vb
102:     hdf5:sol.h5::read
103: .ve

105: .vb
106:     If no value is provided ascii:stdout is used
107:        ascii[:[filename][:[format][:append]]]    defaults to stdout - format can be one of ascii_info, ascii_info_detail, or ascii_matlab,
108:                                                   for example ascii::ascii_info prints just the information about the object not all details
109:                                                   unless :append is given filename opens in write mode, overwriting what was already there
110:        binary[:[filename][:[format][:append]]]   defaults to the file binaryoutput
111:        draw[:drawtype[:filename]]                for example, draw:tikz, draw:tikz:figure.tex  or draw:x
112:        socket[:port]                             defaults to the standard output port
113:        saws[:communicatorname]                    publishes object to the Scientific Application Webserver (SAWs)
114: .ve

116:   This is not called directly but is called by, for example, `MatViewFromOptions()`

118: .seealso: `PetscObject`, `PetscObjectView()`, `PetscOptionsCreateViewer()`
119: @*/
120: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj, PetscObject bobj, const char optionname[])
121: {
122:   PetscViewer       viewer;
123:   PetscBool         flg;
124:   static PetscBool  incall = PETSC_FALSE;
125:   PetscViewerFormat format;
126:   const char       *prefix;

128:   PetscFunctionBegin;
131:   if (incall) PetscFunctionReturn(PETSC_SUCCESS);
132:   incall = PETSC_TRUE;
133:   prefix = bobj ? bobj->prefix : obj->prefix;
134:   PetscCall(PetscOptionsCreateViewer(PetscObjectComm(obj), obj->options, prefix, optionname, &viewer, &format, &flg));
135:   if (flg) {
136:     PetscCall(PetscViewerPushFormat(viewer, format));
137:     PetscCall(PetscObjectView(obj, viewer));
138:     PetscCall(PetscViewerFlush(viewer));
139:     PetscCall(PetscViewerPopFormat(viewer));
140:     PetscCall(PetscViewerDestroy(&viewer));
141:   }
142:   incall = PETSC_FALSE;
143:   PetscFunctionReturn(PETSC_SUCCESS);
144: }

146: /*@
147:   PetscObjectTypeCompare - Determines whether a PETSc object is of a particular type.

149:   Not Collective

151:   Input Parameters:
152: + obj       - a PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`), for example,
153:               `PetscObjectTypeCompare`((`PetscObject`)mat);
154: - type_name - string containing a type name

156:   Output Parameter:
157: . same - `PETSC_TRUE` if the type of `obj` and `type_name` are the same or both `NULL`, else `PETSC_FALSE`

159:   Level: intermediate

161: .seealso: `PetscObject`, `VecGetType()`, `KSPGetType()`, `PCGetType()`, `SNESGetType()`, `PetscObjectBaseTypeCompare()`, `PetscObjectTypeCompareAny()`, `PetscObjectBaseTypeCompareAny()`, `PetscObjectObjectTypeCompare()`
162: @*/
163: PetscErrorCode PetscObjectTypeCompare(PetscObject obj, const char type_name[], PetscBool *same)
164: {
165:   PetscFunctionBegin;
166:   PetscAssertPointer(same, 3);
167:   if (!obj) *same = (PetscBool)!type_name;
168:   else {
170:     if (!type_name || !obj->type_name) *same = (PetscBool)(!obj->type_name == !type_name);
171:     else {
172:       PetscAssertPointer(type_name, 2);
173:       PetscCall(PetscStrcmp(obj->type_name, type_name, same));
174:     }
175:   }
176:   PetscFunctionReturn(PETSC_SUCCESS);
177: }

179: /*@
180:   PetscObjectObjectTypeCompare - Determines whether two PETSc objects are of the same type

182:   Logically Collective

184:   Input Parameters:
185: + obj1 - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
186: - obj2 - another PETSc object

188:   Output Parameter:
189: . same - `PETSC_TRUE` if they are the same or both unset, else `PETSC_FALSE`

191:   Level: intermediate

193: .seealso: `PetscObjectTypeCompare()`, `VecGetType()`, `KSPGetType()`, `PCGetType()`, `SNESGetType()`, `PetscObjectBaseTypeCompare()`, `PetscObjectTypeCompareAny()`, `PetscObjectBaseTypeCompareAny()`
194: @*/
195: PetscErrorCode PetscObjectObjectTypeCompare(PetscObject obj1, PetscObject obj2, PetscBool *same)
196: {
197:   PetscFunctionBegin;
200:   PetscAssertPointer(same, 3);
201:   PetscCall(PetscStrcmp(obj1->type_name, obj2->type_name, same));
202:   PetscFunctionReturn(PETSC_SUCCESS);
203: }

205: /*@
206:   PetscObjectBaseTypeCompare - Determines whether a `PetscObject` is of a given base type. For example the base type of `MATSEQAIJPERM` is `MATSEQAIJ`

208:   Not Collective

210:   Input Parameters:
211: + obj       - the object
212: - type_name - string containing a type name

214:   Output Parameter:
215: . same - `PETSC_TRUE` if the object is of the same base type identified by `type_name` or both `NULL`, `PETSC_FALSE` otherwise

217:   Level: intermediate

219: .seealso: `PetscObject`, `PetscObjectTypeCompare()`, `PetscObjectTypeCompareAny()`, `PetscObjectBaseTypeCompareAny()`
220: @*/
221: PetscErrorCode PetscObjectBaseTypeCompare(PetscObject obj, const char type_name[], PetscBool *same)
222: {
223:   PetscFunctionBegin;
224:   PetscAssertPointer(same, 3);
225:   if (!obj) *same = (PetscBool)!type_name;
226:   else {
228:     if (!type_name || !obj->type_name) *same = (PetscBool)(!obj->type_name == !type_name);
229:     else {
230:       PetscAssertPointer(type_name, 2);
231:       PetscCall(PetscStrbeginswith(obj->type_name, type_name, same));
232:     }
233:   }
234:   PetscFunctionReturn(PETSC_SUCCESS);
235: }

237: /*@C
238:   PetscObjectTypeCompareAny - Determines whether a PETSc object is of any of a list of types.

240:   Not Collective

242:   Input Parameters:
243: + obj       - a PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`),
244:               for example, `PetscObjectTypeCompareAny`((`PetscObject`)mat,...);
245: - type_name - one or more string arguments containing type names, pass the empty string "" as the last argument

247:   Output Parameter:
248: . match - `PETSC_TRUE` if the type of `obj` matches any in the list, else `PETSC_FALSE`

250:   Level: intermediate

252: .seealso: `VecGetType()`, `KSPGetType()`, `PCGetType()`, `SNESGetType()`, `PetscObjectTypeCompare()`, `PetscObjectBaseTypeCompare()`
253: @*/
254: PetscErrorCode PetscObjectTypeCompareAny(PetscObject obj, PetscBool *match, const char type_name[], ...)
255: {
256:   va_list Argp;

258:   PetscFunctionBegin;
259:   PetscAssertPointer(match, 2);
260:   *match = PETSC_FALSE;
261:   if (!obj) PetscFunctionReturn(PETSC_SUCCESS);
262:   va_start(Argp, type_name);
263:   while (type_name && type_name[0]) {
264:     PetscBool found;
265:     PetscCall(PetscObjectTypeCompare(obj, type_name, &found));
266:     if (found) {
267:       *match = PETSC_TRUE;
268:       break;
269:     }
270:     type_name = va_arg(Argp, const char *);
271:   }
272:   va_end(Argp);
273:   PetscFunctionReturn(PETSC_SUCCESS);
274: }

276: /*@C
277:   PetscObjectBaseTypeCompareAny - Determines whether a PETSc object has the base type of any of a list of types.

279:   Not Collective

281:   Input Parameters:
282: + obj       - a PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`),
283:               for example, `PetscObjectBaseTypeCompareAny`((`PetscObject`)mat,...);
284: - type_name - one or more string arguments containing type names, pass the empty string "" as the last argument

286:   Output Parameter:
287: . match - `PETSC_TRUE` if the type of `obj` matches any in the list, else `PETSC_FALSE`

289:   Level: intermediate

291: .seealso: `VecGetType()`, `KSPGetType()`, `PCGetType()`, `SNESGetType()`, `PetscObjectTypeCompare()`, `PetscObjectBaseTypeCompare()`, `PetscObjectTypeCompareAny()`
292: @*/
293: PetscErrorCode PetscObjectBaseTypeCompareAny(PetscObject obj, PetscBool *match, const char type_name[], ...)
294: {
295:   va_list Argp;

297:   PetscFunctionBegin;
298:   PetscAssertPointer(match, 2);
299:   *match = PETSC_FALSE;
300:   va_start(Argp, type_name);
301:   while (type_name && type_name[0]) {
302:     PetscBool found;
303:     PetscCall(PetscObjectBaseTypeCompare(obj, type_name, &found));
304:     if (found) {
305:       *match = PETSC_TRUE;
306:       break;
307:     }
308:     type_name = va_arg(Argp, const char *);
309:   }
310:   va_end(Argp);
311:   PetscFunctionReturn(PETSC_SUCCESS);
312: }

314: typedef struct {
315:   PetscErrorCode (*func)(void);
316: } PetscFinalizeFunction;

318: typedef struct {
319:   PetscErrorCode (*func)(void *);
320:   PetscCtx ctx;
321: } PetscFinalizeFunctionWithCtx;

323: typedef enum {
324:   PETSC_FINALIZE_EMPTY,
325:   PETSC_FINALIZE_OBJECT,
326:   PETSC_FINALIZE_FUNC,
327:   PETSC_FINALIZE_FUNC_WITH_CTX
328: } PetscFinalizeType;

330: static const char *const PetscFinalizeTypes[] = {"PETSC_FINALIZE_EMPTY", "PETSC_FINALIZE_OBJECT", "PETSC_FINALIZE_FUNC", "PETSC_FINALIZE_FUNC_WITH_CTX", PETSC_NULLPTR};

332: typedef struct {
333:   union ThunkUnion
334:   {
335:     PetscObject                  obj;
336:     PetscFinalizeFunction        fn;
337:     PetscFinalizeFunctionWithCtx fnctx;
338:   } thunk;
339:   PetscFinalizeType type;
340: } PetscFinalizerContainer;

342: #define PETSC_MAX_REGISTERED_FINALIZERS 256
343: static int                     reg_count = 0;
344: static PetscFinalizerContainer regfin[PETSC_MAX_REGISTERED_FINALIZERS];

346: static PetscErrorCode PetscRunRegisteredFinalizers(void)
347: {
348:   PetscFunctionBegin;
349:   while (reg_count) {
350:     PetscFinalizerContainer top = regfin[--reg_count];

352:     regfin[reg_count].type = PETSC_FINALIZE_EMPTY;
353:     PetscCall(PetscArrayzero(&regfin[reg_count].thunk, 1));
354:     switch (top.type) {
355:     case PETSC_FINALIZE_OBJECT:
356:       PetscCall(PetscObjectDestroy(&top.thunk.obj));
357:       break;
358:     case PETSC_FINALIZE_FUNC:
359:       PetscCall((*top.thunk.fn.func)());
360:       break;
361:     case PETSC_FINALIZE_FUNC_WITH_CTX:
362:       PetscCall((*top.thunk.fnctx.func)(top.thunk.fnctx.ctx));
363:       break;
364:     case PETSC_FINALIZE_EMPTY:
365:       SETERRQ(PETSC_COMM_SELF, PETSC_ERR_PLIB, "Finalizer at position %d is empty, yet registration count %d != 0", reg_count, reg_count);
366:       break;
367:     }
368:   }
369:   PetscFunctionReturn(PETSC_SUCCESS);
370: }

372: static int PetscFinalizerContainerEqual(const PetscFinalizerContainer *a, const PetscFinalizerContainer *b)
373: {
374:   if (a->type != b->type) return 0;
375:   switch (a->type) {
376:   case PETSC_FINALIZE_EMPTY:
377:     break;
378:   case PETSC_FINALIZE_OBJECT:
379:     return a->thunk.obj == b->thunk.obj;
380:   case PETSC_FINALIZE_FUNC:
381:     return a->thunk.fn.func == b->thunk.fn.func;
382:   case PETSC_FINALIZE_FUNC_WITH_CTX:
383:     return a->thunk.fnctx.func == b->thunk.fnctx.func && a->thunk.fnctx.ctx == b->thunk.fnctx.ctx;
384:   }
385:   return 1;
386: }

388: static PetscErrorCode RegisterFinalizer(PetscFinalizerContainer container)
389: {
390:   PetscFunctionBegin;
391:   PetscAssert(reg_count < (int)PETSC_STATIC_ARRAY_LENGTH(regfin), PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "No more room in array, limit %zu, recompile %s with larger value for " PetscStringize(regfin), PETSC_STATIC_ARRAY_LENGTH(regfin), __FILE__);
392:   PetscAssert(regfin[reg_count].type == PETSC_FINALIZE_EMPTY, PETSC_COMM_SELF, PETSC_ERR_PLIB, "Finalizer type (%s) at position %d is not PETSC_FINALIZE_EMPTY!", PetscFinalizeTypes[regfin[reg_count].type], reg_count);
393:   if (PetscDefined(USE_DEBUG)) {
394:     for (int i = 0; i < reg_count; ++i) PetscCheck(!PetscFinalizerContainerEqual(regfin + i, &container), PETSC_COMM_SELF, PETSC_ERR_ORDER, "Finalizer (of type %s) already registered!", PetscFinalizeTypes[container.type]);
395:   }
396:   regfin[reg_count++] = container;
397:   PetscFunctionReturn(PETSC_SUCCESS);
398: }

400: /*@
401:   PetscObjectRegisterDestroy - Registers a PETSc object to be destroyed when
402:   `PetscFinalize()` is called.

404:   Logically Collective

406:   Input Parameter:
407: . obj - a PETSc object, for example a `Vec`, `Mat` or `KSP`. It must be cast with a (`PetscObject`), for example,
408:         `PetscObjectRegisterDestroy`((`PetscObject`)mat);

410:   Level: developer

412:   Note:
413:   This is used by, for example, `PETSC_VIEWER_XXX_()` routines to free the viewer
414:   when PETSc ends.

416: .seealso: `PetscObjectRegisterDestroyAll()`
417: @*/
418: PetscErrorCode PetscObjectRegisterDestroy(PetscObject obj)
419: {
420:   PetscFinalizerContainer container;

422:   PetscFunctionBegin;
424:   container.thunk.obj = obj;
425:   container.type      = PETSC_FINALIZE_OBJECT;
426:   PetscCall(RegisterFinalizer(container));
427:   PetscFunctionReturn(PETSC_SUCCESS);
428: }

430: /*@C
431:   PetscObjectRegisterDestroyAll - Frees all the PETSc objects that have been registered
432:   with `PetscObjectRegisterDestroy()`. Called by `PetscFinalize()`

434:   Logically Collective on the individual `PetscObject`s that are being processed

436:   Level: developer

438: .seealso: `PetscObjectRegisterDestroy()`
439: @*/
440: PetscErrorCode PetscObjectRegisterDestroyAll(void)
441: {
442:   PetscFunctionBegin;
443:   PetscCall(PetscRunRegisteredFinalizers());
444:   PetscFunctionReturn(PETSC_SUCCESS);
445: }

447: /*@C
448:   PetscRegisterFinalize - Registers a function that is to be called in `PetscFinalize()`

450:   Not Collective

452:   Input Parameter:
453: . f - function to be called

455:   Level: developer

457:   Notes:
458:   This is used by, for example, `DMInitializePackage()` to have `DMFinalizePackage()` called

460:   Use `PetscObjectRegisterDestroy()` to register the destruction of an object in `PetscFinalize()`

462: .seealso: `PetscRegisterFinalizeAll()`, `PetscObjectRegisterDestroy()`
463: @*/
464: PetscErrorCode PetscRegisterFinalize(PetscErrorCode (*f)(void))
465: {
466:   PetscFinalizerContainer container;

468:   PetscFunctionBegin;
470:   container.thunk.fn.func = f;
471:   container.type          = PETSC_FINALIZE_FUNC;
472:   PetscCall(RegisterFinalizer(container));
473:   PetscFunctionReturn(PETSC_SUCCESS);
474: }

476: /*@C
477:   PetscRegisterFinalizeAll - Runs all the finalize functions set with `PetscRegisterFinalize()`

479:   Not Collective unless registered functions are collective

481:   Level: developer

483: .seealso: `PetscRegisterFinalize()`, `PetscObjectRegisterDestroyAll()`
484: @*/
485: PetscErrorCode PetscRegisterFinalizeAll(void)
486: {
487:   PetscFunctionBegin;
488:   PetscCall(PetscRunRegisteredFinalizers());
489:   PetscFunctionReturn(PETSC_SUCCESS);
490: }