Actual source code: inherit.c
petsc-3.13.6 2020-09-29
1: /*
2: Provides utility routines for manipulating any type of PETSc object.
3: */
4: #include <petsc/private/petscimpl.h>
5: #include <petscviewer.h>
7: #if defined(PETSC_USE_LOG)
8: PETSC_INTERN PetscObject *PetscObjects;
9: PETSC_INTERN PetscInt PetscObjectsCounts;
10: PETSC_INTERN PetscInt PetscObjectsMaxCounts;
11: PETSC_INTERN PetscBool PetscObjectsLog;
12: #endif
14: #if defined(PETSC_USE_LOG)
15: PetscObject *PetscObjects = NULL;
16: PetscInt PetscObjectsCounts = 0, PetscObjectsMaxCounts = 0;
17: PetscBool PetscObjectsLog = PETSC_FALSE;
18: #endif
20: PETSC_EXTERN PetscErrorCode PetscObjectGetComm_Petsc(PetscObject,MPI_Comm*);
21: PETSC_EXTERN PetscErrorCode PetscObjectCompose_Petsc(PetscObject,const char[],PetscObject);
22: PETSC_EXTERN PetscErrorCode PetscObjectQuery_Petsc(PetscObject,const char[],PetscObject*);
23: PETSC_EXTERN PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject,const char[],void (*)(void));
24: PETSC_EXTERN PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject,const char[],void (**)(void));
26: /*
27: PetscHeaderCreate_Private - Creates a base PETSc object header and fills
28: in the default values. Called by the macro PetscHeaderCreate().
29: */
30: PetscErrorCode PetscHeaderCreate_Private(PetscObject h,PetscClassId classid,const char class_name[],const char descr[],const char mansec[],
31: MPI_Comm comm,PetscObjectDestroyFunction destroy,PetscObjectViewFunction view)
32: {
33: static PetscInt idcnt = 1;
34: PetscErrorCode ierr;
35: #if defined(PETSC_USE_LOG)
36: PetscObject *newPetscObjects;
37: PetscInt newPetscObjectsMaxCounts,i;
38: #endif
41: h->classid = classid;
42: h->type = 0;
43: h->class_name = (char*)class_name;
44: h->description = (char*)descr;
45: h->mansec = (char*)mansec;
46: h->prefix = NULL;
47: h->refct = 1;
48: #if defined(PETSC_HAVE_SAWS)
49: h->amsmem = PETSC_FALSE;
50: #endif
51: h->id = idcnt++;
52: h->parentid = 0;
53: h->qlist = NULL;
54: h->olist = NULL;
55: h->bops->destroy = destroy;
56: h->bops->view = view;
57: h->bops->getcomm = PetscObjectGetComm_Petsc;
58: h->bops->compose = PetscObjectCompose_Petsc;
59: h->bops->query = PetscObjectQuery_Petsc;
60: h->bops->composefunction = PetscObjectComposeFunction_Petsc;
61: h->bops->queryfunction = PetscObjectQueryFunction_Petsc;
63: PetscCommDuplicate(comm,&h->comm,&h->tag);
65: #if defined(PETSC_USE_LOG)
66: /* Keep a record of object created */
67: if (PetscObjectsLog) {
68: PetscObjectsCounts++;
69: for (i=0; i<PetscObjectsMaxCounts; i++) {
70: if (!PetscObjects[i]) {
71: PetscObjects[i] = h;
72: return(0);
73: }
74: }
75: /* Need to increase the space for storing PETSc objects */
76: if (!PetscObjectsMaxCounts) newPetscObjectsMaxCounts = 100;
77: else newPetscObjectsMaxCounts = 2*PetscObjectsMaxCounts;
78: PetscCalloc1(newPetscObjectsMaxCounts,&newPetscObjects);
79: PetscArraycpy(newPetscObjects,PetscObjects,PetscObjectsMaxCounts);
80: PetscFree(PetscObjects);
82: PetscObjects = newPetscObjects;
83: PetscObjects[PetscObjectsMaxCounts] = h;
84: PetscObjectsMaxCounts = newPetscObjectsMaxCounts;
85: }
86: #endif
87: return(0);
88: }
90: PETSC_INTERN PetscBool PetscMemoryCollectMaximumUsage;
91: PETSC_INTERN PetscLogDouble PetscMemoryMaximumUsage;
93: /*
94: PetscHeaderDestroy_Private - Destroys a base PETSc object header. Called by
95: the macro PetscHeaderDestroy().
96: */
97: PetscErrorCode PetscHeaderDestroy_Private(PetscObject h)
98: {
103: PetscLogObjectDestroy(h);
104: PetscComposedQuantitiesDestroy(h);
105: if (PetscMemoryCollectMaximumUsage) {
106: PetscLogDouble usage;
107: PetscMemoryGetCurrentUsage(&usage);
108: if (usage > PetscMemoryMaximumUsage) PetscMemoryMaximumUsage = usage;
109: }
110: /* first destroy things that could execute arbitrary code */
111: if (h->python_destroy) {
112: void *python_context = h->python_context;
113: PetscErrorCode (*python_destroy)(void*) = h->python_destroy;
114: h->python_context = NULL;
115: h->python_destroy = NULL;
117: (*python_destroy)(python_context);
118: }
119: PetscObjectDestroyOptionsHandlers(h);
120: PetscObjectListDestroy(&h->olist);
121: PetscCommDestroy(&h->comm);
122: /* next destroy other things */
123: h->classid = PETSCFREEDHEADER;
125: PetscFunctionListDestroy(&h->qlist);
126: PetscFree(h->type_name);
127: PetscFree(h->name);
128: PetscFree(h->prefix);
129: PetscFree(h->fortran_func_pointers);
130: PetscFree(h->fortrancallback[PETSC_FORTRAN_CALLBACK_CLASS]);
131: PetscFree(h->fortrancallback[PETSC_FORTRAN_CALLBACK_SUBTYPE]);
133: #if defined(PETSC_USE_LOG)
134: if (PetscObjectsLog) {
135: PetscInt i;
136: /* Record object removal from list of all objects */
137: for (i=0; i<PetscObjectsMaxCounts; i++) {
138: if (PetscObjects[i] == h) {
139: PetscObjects[i] = NULL;
140: PetscObjectsCounts--;
141: break;
142: }
143: }
144: if (!PetscObjectsCounts) {
145: PetscFree(PetscObjects);
146: PetscObjectsMaxCounts = 0;
147: }
148: }
149: #endif
150: return(0);
151: }
153: /*@C
154: PetscObjectCopyFortranFunctionPointers - Copy function pointers to another object
156: Logically Collective on PetscObject
158: Input Parameter:
159: + src - source object
160: - dest - destination object
162: Level: developer
164: Note:
165: Both objects must have the same class.
166: @*/
167: PetscErrorCode PetscObjectCopyFortranFunctionPointers(PetscObject src,PetscObject dest)
168: {
170: PetscInt cbtype,numcb[PETSC_FORTRAN_CALLBACK_MAXTYPE];
175: if (src->classid != dest->classid) SETERRQ(src->comm,PETSC_ERR_ARG_INCOMP,"Objects must be of the same class");
177: PetscFree(dest->fortran_func_pointers);
178: PetscMalloc(src->num_fortran_func_pointers*sizeof(void(*)(void)),&dest->fortran_func_pointers);
179: PetscMemcpy(dest->fortran_func_pointers,src->fortran_func_pointers,src->num_fortran_func_pointers*sizeof(void(*)(void)));
181: dest->num_fortran_func_pointers = src->num_fortran_func_pointers;
183: PetscFortranCallbackGetSizes(src->classid,&numcb[PETSC_FORTRAN_CALLBACK_CLASS],&numcb[PETSC_FORTRAN_CALLBACK_SUBTYPE]);
184: for (cbtype=PETSC_FORTRAN_CALLBACK_CLASS; cbtype<PETSC_FORTRAN_CALLBACK_MAXTYPE; cbtype++) {
185: PetscFree(dest->fortrancallback[cbtype]);
186: PetscCalloc1(numcb[cbtype],&dest->fortrancallback[cbtype]);
187: PetscMemcpy(dest->fortrancallback[cbtype],src->fortrancallback[cbtype],src->num_fortrancallback[cbtype]*sizeof(PetscFortranCallback));
188: dest->num_fortrancallback[cbtype] = src->num_fortrancallback[cbtype];
189: }
190: return(0);
191: }
193: /*@C
194: PetscObjectSetFortranCallback - set fortran callback function pointer and context
196: Logically Collective
198: Input Arguments:
199: + obj - object on which to set callback
200: . cbtype - callback type (class or subtype)
201: . cid - address of callback Id, updated if not yet initialized (zero)
202: . func - Fortran function
203: - ctx - Fortran context
205: Level: developer
207: .seealso: PetscObjectGetFortranCallback()
208: @*/
209: PetscErrorCode PetscObjectSetFortranCallback(PetscObject obj,PetscFortranCallbackType cbtype,PetscFortranCallbackId *cid,void (*func)(void),void *ctx)
210: {
212: const char *subtype = NULL;
216: if (cbtype == PETSC_FORTRAN_CALLBACK_SUBTYPE) subtype = obj->type_name;
217: if (!*cid) {PetscFortranCallbackRegister(obj->classid,subtype,cid);}
218: if (*cid >= PETSC_SMALLEST_FORTRAN_CALLBACK+obj->num_fortrancallback[cbtype]) {
219: PetscInt oldnum = obj->num_fortrancallback[cbtype],newnum = PetscMax(1,2*oldnum);
220: PetscFortranCallback *callback;
221: PetscMalloc1(newnum,&callback);
222: PetscMemcpy(callback,obj->fortrancallback[cbtype],oldnum*sizeof(*obj->fortrancallback[cbtype]));
223: PetscFree(obj->fortrancallback[cbtype]);
225: obj->fortrancallback[cbtype] = callback;
226: obj->num_fortrancallback[cbtype] = newnum;
227: }
228: obj->fortrancallback[cbtype][*cid-PETSC_SMALLEST_FORTRAN_CALLBACK].func = func;
229: obj->fortrancallback[cbtype][*cid-PETSC_SMALLEST_FORTRAN_CALLBACK].ctx = ctx;
230: return(0);
231: }
233: /*@C
234: PetscObjectGetFortranCallback - get fortran callback function pointer and context
236: Logically Collective
238: Input Arguments:
239: + obj - object on which to get callback
240: . cbtype - callback type
241: - cid - address of callback Id
243: Output Arguments:
244: + func - Fortran function (or NULL if not needed)
245: - ctx - Fortran context (or NULL if not needed)
247: Level: developer
249: .seealso: PetscObjectSetFortranCallback()
250: @*/
251: PetscErrorCode PetscObjectGetFortranCallback(PetscObject obj,PetscFortranCallbackType cbtype,PetscFortranCallbackId cid,void (**func)(void),void **ctx)
252: {
253: PetscFortranCallback *cb;
257: if (PetscUnlikely(cid < PETSC_SMALLEST_FORTRAN_CALLBACK)) SETERRQ(obj->comm,PETSC_ERR_ARG_CORRUPT,"Fortran callback Id invalid");
258: if (PetscUnlikely(cid >= PETSC_SMALLEST_FORTRAN_CALLBACK+obj->num_fortrancallback[cbtype])) SETERRQ(obj->comm,PETSC_ERR_ARG_CORRUPT,"Fortran callback not set on this object");
259: cb = &obj->fortrancallback[cbtype][cid-PETSC_SMALLEST_FORTRAN_CALLBACK];
260: if (func) *func = cb->func;
261: if (ctx) *ctx = cb->ctx;
262: return(0);
263: }
265: #if defined(PETSC_USE_LOG)
266: /*@C
267: PetscObjectsDump - Prints the currently existing objects.
269: Logically Collective on PetscViewer
271: Input Parameter:
272: + fd - file pointer
273: - all - by default only tries to display objects created explicitly by the user, if all is PETSC_TRUE then lists all outstanding objects
275: Options Database:
276: . -objects_dump <all>
278: Level: advanced
280: @*/
281: PetscErrorCode PetscObjectsDump(FILE *fd,PetscBool all)
282: {
284: PetscInt i;
285: #if defined(PETSC_USE_DEBUG)
286: PetscInt j,k=0;
287: #endif
288: PetscObject h;
291: if (PetscObjectsCounts) {
292: PetscFPrintf(PETSC_COMM_WORLD,fd,"The following objects were never freed\n");
293: PetscFPrintf(PETSC_COMM_WORLD,fd,"-----------------------------------------\n");
294: for (i=0; i<PetscObjectsMaxCounts; i++) {
295: if ((h = PetscObjects[i])) {
296: PetscObjectName(h);
297: {
298: #if defined(PETSC_USE_DEBUG)
299: PetscStack *stack = NULL;
300: char *create,*rclass;
302: /* if the PETSc function the user calls is not a create then this object was NOT directly created by them */
303: PetscMallocGetStack(h,&stack);
304: if (stack) {
305: k = stack->currentsize-2;
306: if (!all) {
307: k = 0;
308: while (!stack->petscroutine[k]) k++;
309: PetscStrstr(stack->function[k],"Create",&create);
310: if (!create) {
311: PetscStrstr(stack->function[k],"Get",&create);
312: }
313: PetscStrstr(stack->function[k],h->class_name,&rclass);
314: if (!create) continue;
315: if (!rclass) continue;
316: }
317: }
318: #endif
320: PetscFPrintf(PETSC_COMM_WORLD,fd,"[%d] %s %s %s\n",PetscGlobalRank,h->class_name,h->type_name,h->name);
322: #if defined(PETSC_USE_DEBUG)
323: PetscMallocGetStack(h,&stack);
324: if (stack) {
325: for (j=k; j>=0; j--) {
326: fprintf(fd," [%d] %s() in %s\n",PetscGlobalRank,stack->function[j],stack->file[j]);
327: }
328: }
329: #endif
330: }
331: }
332: }
333: }
334: return(0);
335: }
336: #endif
338: #if defined(PETSC_USE_LOG)
340: /*@C
341: PetscObjectsView - Prints the currently existing objects.
343: Logically Collective on PetscViewer
345: Input Parameter:
346: . viewer - must be an PETSCVIEWERASCII viewer
348: Level: advanced
350: @*/
351: PetscErrorCode PetscObjectsView(PetscViewer viewer)
352: {
354: PetscBool isascii;
355: FILE *fd;
358: if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
359: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
360: if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");
361: PetscViewerASCIIGetPointer(viewer,&fd);
362: PetscObjectsDump(fd,PETSC_TRUE);
363: return(0);
364: }
366: /*@C
367: PetscObjectsGetObject - Get a pointer to a named object
369: Not collective
371: Input Parameter:
372: . name - the name of an object
374: Output Parameter:
375: . obj - the object or null if there is no object
377: Level: advanced
379: @*/
380: PetscErrorCode PetscObjectsGetObject(const char *name,PetscObject *obj,char **classname)
381: {
383: PetscInt i;
384: PetscObject h;
385: PetscBool flg;
388: *obj = NULL;
389: for (i=0; i<PetscObjectsMaxCounts; i++) {
390: if ((h = PetscObjects[i])) {
391: PetscObjectName(h);
392: PetscStrcmp(h->name,name,&flg);
393: if (flg) {
394: *obj = h;
395: if (classname) *classname = h->class_name;
396: return(0);
397: }
398: }
399: }
400: return(0);
401: }
402: #endif
404: /*@
405: PetscObjectSetPrintedOptions - indicate to an object that it should behave as if it has already printed the help for its options
407: Input Parameters:
408: . obj - the PetscObject
410: Level: developer
412: Developer Notes:
413: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
414: PCBJACOBI from all printing the same help messages to the screen
416: .seealso: PetscOptionsInsert()
417: @*/
418: PetscErrorCode PetscObjectSetPrintedOptions(PetscObject obj)
419: {
421: obj->optionsprinted = PETSC_TRUE;
422: return(0);
423: }
425: /*@
426: PetscObjectInheritPrintedOptions - If the child object is not on the rank 0 process of the parent object and the child is sequential then the child gets it set.
428: Input Parameters:
429: + pobj - the parent object
430: - obj - the PetscObject
432: Level: developer
434: Developer Notes:
435: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
436: PCBJACOBI from all printing the same help messages to the screen
438: This will not handle more complicated situations like with GASM where children may live on any subset of the parent's processes and overlap
440: .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions()
441: @*/
442: PetscErrorCode PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj)
443: {
445: PetscMPIInt prank,size;
448: MPI_Comm_rank(pobj->comm,&prank);
449: MPI_Comm_size(obj->comm,&size);
450: if (size == 1 && prank > 0) obj->optionsprinted = PETSC_TRUE;
451: return(0);
452: }
454: /*@C
455: PetscObjectAddOptionsHandler - Adds an additional function to check for options when XXXSetFromOptions() is called.
457: Not Collective
459: Input Parameter:
460: + obj - the PETSc object
461: . handle - function that checks for options
462: . destroy - function to destroy context if provided
463: - ctx - optional context for check function
465: Level: developer
468: .seealso: KSPSetFromOptions(), PCSetFromOptions(), SNESSetFromOptions(), PetscObjectProcessOptionsHandlers(), PetscObjectDestroyOptionsHandlers()
470: @*/
471: PetscErrorCode PetscObjectAddOptionsHandler(PetscObject obj,PetscErrorCode (*handle)(PetscOptionItems*,PetscObject,void*),PetscErrorCode (*destroy)(PetscObject,void*),void *ctx)
472: {
475: if (obj->noptionhandler >= PETSC_MAX_OPTIONS_HANDLER) SETERRQ(obj->comm,PETSC_ERR_ARG_OUTOFRANGE,"To many options handlers added");
476: obj->optionhandler[obj->noptionhandler] = handle;
477: obj->optiondestroy[obj->noptionhandler] = destroy;
478: obj->optionctx[obj->noptionhandler++] = ctx;
479: return(0);
480: }
482: /*@C
483: PetscObjectProcessOptionsHandlers - Calls all the options handlers attached to an object
485: Not Collective
487: Input Parameter:
488: . obj - the PETSc object
490: Level: developer
493: .seealso: KSPSetFromOptions(), PCSetFromOptions(), SNESSetFromOptions(), PetscObjectAddOptionsHandler(), PetscObjectDestroyOptionsHandlers()
495: @*/
496: PetscErrorCode PetscObjectProcessOptionsHandlers(PetscOptionItems *PetscOptionsObject,PetscObject obj)
497: {
498: PetscInt i;
503: for (i=0; i<obj->noptionhandler; i++) {
504: (*obj->optionhandler[i])(PetscOptionsObject,obj,obj->optionctx[i]);
505: }
506: return(0);
507: }
509: /*@C
510: PetscObjectDestroyOptionsHandlers - Destroys all the option handlers attached to an object
512: Not Collective
514: Input Parameter:
515: . obj - the PETSc object
517: Level: developer
520: .seealso: KSPSetFromOptions(), PCSetFromOptions(), SNESSetFromOptions(), PetscObjectAddOptionsHandler(), PetscObjectProcessOptionsHandlers()
522: @*/
523: PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject obj)
524: {
525: PetscInt i;
530: for (i=0; i<obj->noptionhandler; i++) {
531: if (obj->optiondestroy[i]) {
532: (*obj->optiondestroy[i])(obj,obj->optionctx[i]);
533: }
534: }
535: obj->noptionhandler = 0;
536: return(0);
537: }
540: /*@C
541: PetscObjectReference - Indicates to any PetscObject that it is being
542: referenced by another PetscObject. This increases the reference
543: count for that object by one.
545: Logically Collective on PetscObject
547: Input Parameter:
548: . obj - the PETSc object. This must be cast with (PetscObject), for example,
549: PetscObjectReference((PetscObject)mat);
551: Level: advanced
553: .seealso: PetscObjectCompose(), PetscObjectDereference()
554: @*/
555: PetscErrorCode PetscObjectReference(PetscObject obj)
556: {
558: if (!obj) return(0);
560: obj->refct++;
561: return(0);
562: }
564: /*@C
565: PetscObjectGetReference - Gets the current reference count for
566: any PETSc object.
568: Not Collective
570: Input Parameter:
571: . obj - the PETSc object; this must be cast with (PetscObject), for example,
572: PetscObjectGetReference((PetscObject)mat,&cnt);
574: Output Parameter:
575: . cnt - the reference count
577: Level: advanced
579: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
580: @*/
581: PetscErrorCode PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
582: {
586: *cnt = obj->refct;
587: return(0);
588: }
590: /*@C
591: PetscObjectDereference - Indicates to any PetscObject that it is being
592: referenced by one less PetscObject. This decreases the reference
593: count for that object by one.
595: Collective on PetscObject if reference reaches 0 otherwise Logically Collective
597: Input Parameter:
598: . obj - the PETSc object; this must be cast with (PetscObject), for example,
599: PetscObjectDereference((PetscObject)mat);
601: Notes:
602: PetscObjectDestroy(PetscObject *obj) sets the obj pointer to null after the call, this routine does not.
604: Level: advanced
606: .seealso: PetscObjectCompose(), PetscObjectReference()
607: @*/
608: PetscErrorCode PetscObjectDereference(PetscObject obj)
609: {
613: if (!obj) return(0);
615: if (obj->bops->destroy) {
616: (*obj->bops->destroy)(&obj);
617: } else if (!--obj->refct) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
618: return(0);
619: }
621: /* ----------------------------------------------------------------------- */
622: /*
623: The following routines are the versions private to the PETSc object
624: data structures.
625: */
626: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
627: {
630: *comm = obj->comm;
631: return(0);
632: }
634: PetscErrorCode PetscObjectRemoveReference(PetscObject obj,const char name[])
635: {
640: PetscObjectListRemoveReference(&obj->olist,name);
641: return(0);
642: }
644: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
645: {
647: char *tname;
648: PetscBool skipreference;
651: if (ptr) {
652: PetscObjectListReverseFind(ptr->olist,obj,&tname,&skipreference);
653: if (tname && !skipreference) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was composed with it");
654: }
655: PetscObjectListAdd(&obj->olist,name,ptr);
656: return(0);
657: }
659: PetscErrorCode PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
660: {
665: PetscObjectListFind(obj->olist,name,ptr);
666: return(0);
667: }
669: PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],void (*ptr)(void))
670: {
675: PetscFunctionListAdd(&obj->qlist,name,ptr);
676: return(0);
677: }
679: PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)(void))
680: {
685: PetscFunctionListFind(obj->qlist,name,ptr);
686: return(0);
687: }
689: /*@C
690: PetscObjectCompose - Associates another PETSc object with a given PETSc object.
692: Not Collective
694: Input Parameters:
695: + obj - the PETSc object; this must be cast with (PetscObject), for example,
696: PetscObjectCompose((PetscObject)mat,...);
697: . name - name associated with the child object
698: - ptr - the other PETSc object to associate with the PETSc object; this must also be
699: cast with (PetscObject)
701: Level: advanced
703: Notes:
704: The second objects reference count is automatically increased by one when it is
705: composed.
707: Replaces any previous object that had the same name.
709: If ptr is null and name has previously been composed using an object, then that
710: entry is removed from the obj.
712: PetscObjectCompose() can be used with any PETSc object (such as
713: Mat, Vec, KSP, SNES, etc.) or any user-provided object. See
714: PetscContainerCreate() for info on how to create an object from a
715: user-provided pointer that may then be composed with PETSc objects.
718: .seealso: PetscObjectQuery(), PetscContainerCreate(), PetscObjectComposeFunction(), PetscObjectQueryFunction()
719: @*/
720: PetscErrorCode PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
721: {
728: if (obj == ptr) SETERRQ(PetscObjectComm((PetscObject)obj),PETSC_ERR_SUP,"Cannot compose object with itself");
729: (*obj->bops->compose)(obj,name,ptr);
730: return(0);
731: }
733: /*@C
734: PetscObjectQuery - Gets a PETSc object associated with a given object.
736: Not Collective
738: Input Parameters:
739: + obj - the PETSc object
740: Thus must be cast with a (PetscObject), for example,
741: PetscObjectCompose((PetscObject)mat,...);
742: . name - name associated with child object
743: - ptr - the other PETSc object associated with the PETSc object, this must be
744: cast with (PetscObject*)
746: Level: advanced
748: The reference count of neither object is increased in this call
751: .seealso: PetscObjectCompose(), PetscObjectComposeFunction(), PetscObjectQueryFunction()
752: @*/
753: PetscErrorCode PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
754: {
761: (*obj->bops->query)(obj,name,ptr);
762: return(0);
763: }
765: /*MC
766: PetscObjectComposeFunction - Associates a function with a given PETSc object.
768: Synopsis:
769: #include <petscsys.h>
770: PetscErrorCode PetscObjectComposeFunction(PetscObject obj,const char name[],void (*fptr)(void))
772: Logically Collective on PetscObject
774: Input Parameters:
775: + obj - the PETSc object; this must be cast with a (PetscObject), for example,
776: PetscObjectCompose((PetscObject)mat,...);
777: . name - name associated with the child function
778: . fname - name of the function
779: - fptr - function pointer
781: Level: advanced
783: Notes:
784: To remove a registered routine, pass in NULL for fptr().
786: PetscObjectComposeFunction() can be used with any PETSc object (such as
787: Mat, Vec, KSP, SNES, etc.) or any user-provided object.
789: .seealso: PetscObjectQueryFunction(), PetscContainerCreate() PetscObjectCompose(), PetscObjectQuery()
790: M*/
792: PetscErrorCode PetscObjectComposeFunction_Private(PetscObject obj,const char name[],void (*fptr)(void))
793: {
799: (*obj->bops->composefunction)(obj,name,fptr);
800: return(0);
801: }
803: /*MC
804: PetscObjectQueryFunction - Gets a function associated with a given object.
806: Synopsis:
807: #include <petscsys.h>
808: PetscErrorCode PetscObjectQueryFunction(PetscObject obj,const char name[],void (**fptr)(void))
810: Logically Collective on PetscObject
812: Input Parameters:
813: + obj - the PETSc object; this must be cast with (PetscObject), for example,
814: PetscObjectQueryFunction((PetscObject)ksp,...);
815: - name - name associated with the child function
817: Output Parameter:
818: . fptr - function pointer
820: Level: advanced
822: .seealso: PetscObjectComposeFunction(), PetscFunctionListFind(), PetscObjectCompose(), PetscObjectQuery()
823: M*/
824: PETSC_EXTERN PetscErrorCode PetscObjectQueryFunction_Private(PetscObject obj,const char name[],void (**ptr)(void))
825: {
831: (*obj->bops->queryfunction)(obj,name,ptr);
832: return(0);
833: }
835: struct _p_PetscContainer {
836: PETSCHEADER(int);
837: void *ptr;
838: PetscErrorCode (*userdestroy)(void*);
839: };
841: /*@C
842: PetscContainerUserDestroyDefault - Default destroy routine for user-provided data that simply calls PetscFree().
844: Logically Collective on PetscContainer
846: Input Parameter:
847: . ctx - pointer to user-provided data
849: Level: advanced
851: .seealso: PetscContainerDestroy(), PetscContainterSetUserDestroy()
852: @*/
853: PetscErrorCode PetscContainerUserDestroyDefault(void* ctx)
854: {
858: PetscFree(ctx);
859: return(0);
860: }
862: /*@C
863: PetscContainerGetPointer - Gets the pointer value contained in the container.
865: Not Collective
867: Input Parameter:
868: . obj - the object created with PetscContainerCreate()
870: Output Parameter:
871: . ptr - the pointer value
873: Level: advanced
875: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
876: PetscContainerSetPointer()
877: @*/
878: PetscErrorCode PetscContainerGetPointer(PetscContainer obj,void **ptr)
879: {
883: *ptr = obj->ptr;
884: return(0);
885: }
888: /*@C
889: PetscContainerSetPointer - Sets the pointer value contained in the container.
891: Logically Collective on PetscContainer
893: Input Parameters:
894: + obj - the object created with PetscContainerCreate()
895: - ptr - the pointer value
897: Level: advanced
899: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
900: PetscContainerGetPointer()
901: @*/
902: PetscErrorCode PetscContainerSetPointer(PetscContainer obj,void *ptr)
903: {
907: obj->ptr = ptr;
908: return(0);
909: }
911: /*@C
912: PetscContainerDestroy - Destroys a PETSc container object.
914: Collective on PetscContainer
916: Input Parameter:
917: . obj - an object that was created with PetscContainerCreate()
919: Level: advanced
921: .seealso: PetscContainerCreate(), PetscContainerSetUserDestroy()
922: @*/
923: PetscErrorCode PetscContainerDestroy(PetscContainer *obj)
924: {
928: if (!*obj) return(0);
930: if (--((PetscObject)(*obj))->refct > 0) {*obj = NULL; return(0);}
931: if ((*obj)->userdestroy) { (*(*obj)->userdestroy)((*obj)->ptr); }
932: PetscHeaderDestroy(obj);
933: return(0);
934: }
936: /*@C
937: PetscContainerSetUserDestroy - Sets name of the user destroy function.
939: Logically Collective on PetscContainer
941: Input Parameter:
942: + obj - an object that was created with PetscContainerCreate()
943: - des - name of the user destroy function
945: Notes:
946: Use PetscContainerUserDestroyDefault() if the memory was obtained by calling PetscMalloc or one of its variants for single memory allocation.
948: Level: advanced
950: .seealso: PetscContainerDestroy(), PetscContainerUserDestroyDefault(), PetscMalloc(), PetscMalloc1(), PetscCalloc(), PetscCalloc1()
951: @*/
952: PetscErrorCode PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
953: {
956: obj->userdestroy = des;
957: return(0);
958: }
960: PetscClassId PETSC_CONTAINER_CLASSID;
962: /*@C
963: PetscContainerCreate - Creates a PETSc object that has room to hold
964: a single pointer. This allows one to attach any type of data (accessible
965: through a pointer) with the PetscObjectCompose() function to a PetscObject.
966: The data item itself is attached by a call to PetscContainerSetPointer().
968: Collective
970: Input Parameters:
971: . comm - MPI communicator that shares the object
973: Output Parameters:
974: . container - the container created
976: Level: advanced
978: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer(), PetscObjectCompose(), PetscObjectQuery()
979: @*/
980: PetscErrorCode PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
981: {
983: PetscContainer contain;
987: PetscSysInitializePackage();
988: PetscHeaderCreate(contain,PETSC_CONTAINER_CLASSID,"PetscContainer","Container","Sys",comm,PetscContainerDestroy,NULL);
989: *container = contain;
990: return(0);
991: }
993: /*@
994: PetscObjectSetFromOptions - Sets generic parameters from user options.
996: Collective on obj
998: Input Parameter:
999: . obj - the PetscObjcet
1001: Options Database Keys:
1003: Notes:
1004: We have no generic options at present, so this does nothing
1006: Level: beginner
1008: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
1009: @*/
1010: PetscErrorCode PetscObjectSetFromOptions(PetscObject obj)
1011: {
1014: return(0);
1015: }
1017: /*@
1018: PetscObjectSetUp - Sets up the internal data structures for the later use.
1020: Collective on PetscObject
1022: Input Parameters:
1023: . obj - the PetscObject
1025: Notes:
1026: This does nothing at present.
1028: Level: advanced
1030: .seealso: PetscObjectDestroy()
1031: @*/
1032: PetscErrorCode PetscObjectSetUp(PetscObject obj)
1033: {
1036: return(0);
1037: }