Actual source code: inherit.c
1: #define PETSC_DLL
2: /*
3: Provides utility routines for manipulating any type of PETSc object.
4: */
5: #include petsc.h
6: #include petscsys.h
8: EXTERN PetscErrorCode PetscObjectGetComm_Petsc(PetscObject,MPI_Comm *);
9: EXTERN PetscErrorCode PetscObjectCompose_Petsc(PetscObject,const char[],PetscObject);
10: EXTERN PetscErrorCode PetscObjectQuery_Petsc(PetscObject,const char[],PetscObject *);
11: EXTERN PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject,const char[],const char[],void (*)(void));
12: EXTERN PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject,const char[],void (**)(void));
16: /*
17: PetscHeaderCreate_Private - Creates a base PETSc object header and fills
18: in the default values. Called by the macro PetscHeaderCreate().
19: */
20: PetscErrorCode PetscHeaderCreate_Private(PetscObject h,PetscCookie cookie,PetscInt type,const char class_name[],MPI_Comm comm,
21: PetscErrorCode (*des)(PetscObject),PetscErrorCode (*vie)(PetscObject,PetscViewer))
22: {
23: static PetscInt idcnt = 1;
24: PetscErrorCode ierr;
27: h->cookie = cookie;
28: h->type = type;
29: h->class_name = (char*)class_name;
30: h->prefix = 0;
31: h->refct = 1;
32: h->amem = -1;
33: h->id = idcnt++;
34: h->parentid = 0;
35: h->qlist = 0;
36: h->olist = 0;
37: h->bops->destroy = des;
38: h->bops->view = vie;
39: h->bops->getcomm = PetscObjectGetComm_Petsc;
40: h->bops->compose = PetscObjectCompose_Petsc;
41: h->bops->query = PetscObjectQuery_Petsc;
42: h->bops->composefunction = PetscObjectComposeFunction_Petsc;
43: h->bops->queryfunction = PetscObjectQueryFunction_Petsc;
44: PetscCommDuplicate(comm,&h->comm,&h->tag);
45: return(0);
46: }
53: /*
54: PetscHeaderDestroy_Private - Destroys a base PETSc object header. Called by
55: the macro PetscHeaderDestroy().
56: */
57: PetscErrorCode PetscHeaderDestroy_Private(PetscObject h)
58: {
62: if (PetscMemoryCollectMaximumUsage) {
63: PetscLogDouble usage;
64: PetscMemoryGetCurrentUsage(&usage);
65: if (usage > PetscMemoryMaximumUsage) PetscMemoryMaximumUsage = usage;
66: }
67: PetscCommDestroy(&h->comm);
68: PetscFree(h->bops);
69: PetscFree(h->ops);
70: PetscOListDestroy(h->olist);
71: PetscFListDestroy(&h->qlist);
72: PetscStrfree(h->type_name);
73: PetscStrfree(h->name);
74: h->cookie = PETSCFREEDHEADER;
75: PetscStrfree(h->prefix);
76: PetscFree(h->fortran_func_pointers);
77: PetscFree(h->intcomposeddata);
78: PetscFree(h->intcomposedstate);
79: PetscFree(h->realcomposeddata);
80: PetscFree(h->realcomposedstate);
81: PetscFree(h->scalarcomposeddata);
82: PetscFree(h->scalarcomposedstate);
83: return(0);
84: }
88: /*@C
89: PetscObjectReference - Indicates to any PetscObject that it is being
90: referenced by another PetscObject. This increases the reference
91: count for that object by one.
93: Collective on PetscObject
95: Input Parameter:
96: . obj - the PETSc object. This must be cast with (PetscObject), for example,
97: PetscObjectReference((PetscObject)mat);
99: Level: advanced
101: .seealso: PetscObjectCompose(), PetscObjectDereference()
102: @*/
103: PetscErrorCode PetscObjectReference(PetscObject obj)
104: {
107: obj->refct++;
108: return(0);
109: }
113: /*@C
114: PetscObjectGetReference - Gets the current reference count for
115: any PETSc object.
117: Not Collective
119: Input Parameter:
120: . obj - the PETSc object; this must be cast with (PetscObject), for example,
121: PetscObjectGetReference((PetscObject)mat,&cnt);
123: Output Parameter:
124: . cnt - the reference count
126: Level: advanced
128: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
129: @*/
130: PetscErrorCode PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
131: {
135: *cnt = obj->refct;
136: return(0);
137: }
141: /*@
142: PetscObjectDereference - Indicates to any PetscObject that it is being
143: referenced by one less PetscObject. This decreases the reference
144: count for that object by one.
146: Collective on PetscObject
148: Input Parameter:
149: . obj - the PETSc object; this must be cast with (PetscObject), for example,
150: PetscObjectDereference((PetscObject)mat);
152: Level: advanced
154: .seealso: PetscObjectCompose(), PetscObjectReference()
155: @*/
156: PetscErrorCode PetscObjectDereference(PetscObject obj)
157: {
162: if (obj->bops->destroy) {
163: (*obj->bops->destroy)(obj);
164: } else if (!--obj->refct) {
165: SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
166: }
167: return(0);
168: }
170: /* ----------------------------------------------------------------------- */
171: /*
172: The following routines are the versions private to the PETSc object
173: data structures.
174: */
177: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
178: {
180: *comm = obj->comm;
181: return(0);
182: }
186: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
187: {
189: char *tname;
192: if (ptr) {
193: PetscOListReverseFind(ptr->olist,obj,&tname);
194: if (tname){
195: SETERRQ(PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was compose with it");
196: }
197: }
198: PetscOListAdd(&obj->olist,name,ptr);
199: return(0);
200: }
204: PetscErrorCode PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
205: {
209: PetscOListFind(obj->olist,name,ptr);
210: return(0);
211: }
215: PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
216: {
220: PetscFListAdd(&obj->qlist,name,fname,ptr);
221: return(0);
222: }
226: PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)(void))
227: {
231: PetscFListFind(obj->qlist,obj->comm,name,ptr);
232: return(0);
233: }
235: /*
236: These are the versions that are usable to any CCA compliant objects
237: */
240: /*@C
241: PetscObjectCompose - Associates another PETSc object with a given PETSc object.
242:
243: Not Collective
245: Input Parameters:
246: + obj - the PETSc object; this must be cast with (PetscObject), for example,
247: PetscObjectCompose((PetscObject)mat,...);
248: . name - name associated with the child object
249: - ptr - the other PETSc object to associate with the PETSc object; this must also be
250: cast with (PetscObject)
252: Level: advanced
254: Notes:
255: The second objects reference count is automatically increased by one when it is
256: composed.
258: Replaces any previous object that had the same name.
260: If ptr is null and name has previously been composed using an object, then that
261: entry is removed from the obj.
263: PetscObjectCompose() can be used with any PETSc object (such as
264: Mat, Vec, KSP, SNES, etc.) or any user-provided object. See
265: PetscContainerCreate() for info on how to create an object from a
266: user-provided pointer that may then be composed with PETSc objects.
267:
268: Concepts: objects^composing
269: Concepts: composing objects
271: .seealso: PetscObjectQuery(), PetscContainerCreate()
272: @*/
273: PetscErrorCode PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
274: {
281: (*obj->bops->compose)(obj,name,ptr);
282: return(0);
283: }
287: /*@C
288: PetscObjectQuery - Gets a PETSc object associated with a given object.
289:
290: Not Collective
292: Input Parameters:
293: + obj - the PETSc object
294: Thus must be cast with a (PetscObject), for example,
295: PetscObjectCompose((PetscObject)mat,...);
296: . name - name associated with child object
297: - ptr - the other PETSc object associated with the PETSc object, this must also be
298: cast with (PetscObject)
300: Level: advanced
302: Concepts: objects^composing
303: Concepts: composing objects
304: Concepts: objects^querying
305: Concepts: querying objects
307: .seealso: PetscObjectQuery()
308: @*/
309: PetscErrorCode PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
310: {
317: (*obj->bops->query)(obj,name,ptr);
318: return(0);
319: }
323: PetscErrorCode PetscObjectComposeFunction(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
324: {
331: (*obj->bops->composefunction)(obj,name,fname,ptr);
332: return(0);
333: }
337: /*@C
338: PetscObjectQueryFunction - Gets a function associated with a given object.
339:
340: Collective on PetscObject
342: Input Parameters:
343: + obj - the PETSc object; this must be cast with (PetscObject), for example,
344: PetscObjectQueryFunction((PetscObject)ksp,...);
345: - name - name associated with the child function
347: Output Parameter:
348: . ptr - function pointer
350: Level: advanced
352: Concepts: objects^composing functions
353: Concepts: composing functions
354: Concepts: functions^querying
355: Concepts: objects^querying
356: Concepts: querying objects
358: .seealso: PetscObjectComposeFunctionDynamic()
359: @*/
360: PetscErrorCode PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)(void))
361: {
367: (*obj->bops->queryfunction)(obj,name,ptr);
368: return(0);
369: }
371: struct _p_PetscContainer {
372: PETSCHEADER(int);
373: void *ptr;
374: PetscErrorCode (*userdestroy)(void*);
375: };
379: /*@C
380: PetscContainerGetPointer - Gets the pointer value contained in the container.
382: Collective on PetscContainer
384: Input Parameter:
385: . obj - the object created with PetscContainerCreate()
387: Output Parameter:
388: . ptr - the pointer value
390: Level: advanced
392: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
393: PetscContainerSetPointer()
394: @*/
395: PetscErrorCode PetscContainerGetPointer(PetscContainer obj,void **ptr)
396: {
400: *ptr = obj->ptr;
401: return(0);
402: }
407: /*@C
408: PetscContainerSetPointer - Sets the pointer value contained in the container.
410: Collective on PetscContainer
412: Input Parameters:
413: + obj - the object created with PetscContainerCreate()
414: - ptr - the pointer value
416: Level: advanced
418: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
419: PetscContainerGetPointer()
420: @*/
421: PetscErrorCode PetscContainerSetPointer(PetscContainer obj,void *ptr)
422: {
426: obj->ptr = ptr;
427: return(0);
428: }
432: /*@C
433: PetscContainerDestroy - Destroys a PETSc container object.
435: Collective on PetscContainer
437: Input Parameter:
438: . obj - an object that was created with PetscContainerCreate()
440: Level: advanced
442: .seealso: PetscContainerCreate()
443: @*/
444: PetscErrorCode PetscContainerDestroy(PetscContainer obj)
445: {
449: if (--obj->refct > 0) return(0);
450: if (obj->userdestroy) (*obj->userdestroy)(obj->ptr);
451: PetscHeaderDestroy(obj);
452: return(0);
453: }
457: /*@C
458: PetscContainerSetUserDestroy - Sets name of the user destroy function.
460: Collective on PetscContainer
462: Input Parameter:
463: + obj - an object that was created with PetscContainerCreate()
464: - des - name of the user destroy function
466: Level: advanced
468: .seealso: PetscContainerDestroy()
469: @*/
470: PetscErrorCode PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
471: {
474: obj->userdestroy = des;
475: return(0);
476: }
478: PetscCookie PETSC_CONTAINER_COOKIE = 0;
482: /*@C
483: PetscContainerCreate - Creates a PETSc object that has room to hold
484: a single pointer. This allows one to attach any type of data (accessible
485: through a pointer) with the PetscObjectCompose() function to a PetscObject.
486: The data item itself is attached by a call to PetscContainerSetPointer.
488: Collective on MPI_Comm
490: Input Parameters:
491: . comm - MPI communicator that shares the object
493: Output Parameters:
494: . container - the container created
496: Level: advanced
498: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer()
499: @*/
500: PetscErrorCode PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
501: {
503: PetscContainer contain;
507: if (!PETSC_CONTAINER_COOKIE) {
508: PetscLogClassRegister(&PETSC_CONTAINER_COOKIE, "Container");
509: }
510: PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_COOKIE,0,"PetscContainer",comm,PetscContainerDestroy,0);
511: *container = contain;
512: return(0);
513: }
517: /*@
518: PetscObjectSetFromOptions - Sets generic parameters from user options.
520: Collective on obj
522: Input Parameter:
523: . obj - the PetscObjcet
525: Options Database Keys:
527: Notes:
528: We have no generic options at present, so this does nothing
530: Level: beginner
532: .keywords: set, options, database
533: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
534: @*/
535: PetscErrorCode PetscObjectSetFromOptions(PetscObject obj)
536: {
539: return(0);
540: }
544: /*@
545: PetscObjectSetUp - Sets up the internal data structures for the later use.
547: Collective on PetscObject
549: Input Parameters:
550: . obj - the PetscObject
552: Notes:
553: This does nothing at present.
555: Level: advanced
557: .keywords: setup
558: .seealso: PetscObjectDestroy()
559: @*/
560: PetscErrorCode PetscObjectSetUp(PetscObject obj)
561: {
564: return(0);
565: }