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: PetscOListDestroy(h->olist);
70: PetscFListDestroy(&h->qlist);
71: PetscStrfree(h->type_name);
72: PetscStrfree(h->name);
73: h->cookie = PETSCFREEDHEADER;
74: PetscStrfree(h->prefix);
75: PetscFree(h->fortran_func_pointers);
76: PetscFree(h->intcomposeddata);
77: PetscFree(h->intcomposedstate);
78: PetscFree(h->realcomposeddata);
79: PetscFree(h->realcomposedstate);
80: PetscFree(h->scalarcomposeddata);
81: PetscFree(h->scalarcomposedstate);
82: return(0);
83: }
87: /*@C
88: PetscObjectReference - Indicates to any PetscObject that it is being
89: referenced by another PetscObject. This increases the reference
90: count for that object by one.
92: Collective on PetscObject
94: Input Parameter:
95: . obj - the PETSc object. This must be cast with (PetscObject), for example,
96: PetscObjectReference((PetscObject)mat);
98: Level: advanced
100: .seealso: PetscObjectCompose(), PetscObjectDereference()
101: @*/
102: PetscErrorCode PetscObjectReference(PetscObject obj)
103: {
106: obj->refct++;
107: return(0);
108: }
112: /*@C
113: PetscObjectGetReference - Gets the current reference count for
114: any PETSc object.
116: Not Collective
118: Input Parameter:
119: . obj - the PETSc object; this must be cast with (PetscObject), for example,
120: PetscObjectGetReference((PetscObject)mat,&cnt);
122: Output Parameter:
123: . cnt - the reference count
125: Level: advanced
127: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
128: @*/
129: PetscErrorCode PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
130: {
134: *cnt = obj->refct;
135: return(0);
136: }
140: /*@
141: PetscObjectDereference - Indicates to any PetscObject that it is being
142: referenced by one less PetscObject. This decreases the reference
143: count for that object by one.
145: Collective on PetscObject
147: Input Parameter:
148: . obj - the PETSc object; this must be cast with (PetscObject), for example,
149: PetscObjectDereference((PetscObject)mat);
151: Level: advanced
153: .seealso: PetscObjectCompose(), PetscObjectReference()
154: @*/
155: PetscErrorCode PetscObjectDereference(PetscObject obj)
156: {
161: if (obj->bops->destroy) {
162: (*obj->bops->destroy)(obj);
163: } else if (!--obj->refct) {
164: SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
165: }
166: return(0);
167: }
169: /* ----------------------------------------------------------------------- */
170: /*
171: The following routines are the versions private to the PETSc object
172: data structures.
173: */
176: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
177: {
179: *comm = obj->comm;
180: return(0);
181: }
185: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
186: {
188: char *tname;
191: if (ptr) {
192: PetscOListReverseFind(ptr->olist,obj,&tname);
193: if (tname){
194: SETERRQ(PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was compose with it");
195: }
196: }
197: PetscOListAdd(&obj->olist,name,ptr);
198: return(0);
199: }
203: PetscErrorCode PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
204: {
208: PetscOListFind(obj->olist,name,ptr);
209: return(0);
210: }
214: PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
215: {
219: PetscFListAdd(&obj->qlist,name,fname,ptr);
220: return(0);
221: }
225: PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)(void))
226: {
230: PetscFListFind(obj->qlist,obj->comm,name,ptr);
231: return(0);
232: }
234: /*
235: These are the versions that are usable to any CCA compliant objects
236: */
239: /*@C
240: PetscObjectCompose - Associates another PETSc object with a given PETSc object.
241:
242: Not Collective
244: Input Parameters:
245: + obj - the PETSc object; this must be cast with (PetscObject), for example,
246: PetscObjectCompose((PetscObject)mat,...);
247: . name - name associated with the child object
248: - ptr - the other PETSc object to associate with the PETSc object; this must also be
249: cast with (PetscObject)
251: Level: advanced
253: Notes:
254: The second objects reference count is automatically increased by one when it is
255: composed.
257: Replaces any previous object that had the same name.
259: If ptr is null and name has previously been composed using an object, then that
260: entry is removed from the obj.
262: PetscObjectCompose() can be used with any PETSc object (such as
263: Mat, Vec, KSP, SNES, etc.) or any user-provided object. See
264: PetscContainerCreate() for info on how to create an object from a
265: user-provided pointer that may then be composed with PETSc objects.
266:
267: Concepts: objects^composing
268: Concepts: composing objects
270: .seealso: PetscObjectQuery(), PetscContainerCreate()
271: @*/
272: PetscErrorCode PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
273: {
280: (*obj->bops->compose)(obj,name,ptr);
281: return(0);
282: }
286: /*@C
287: PetscObjectQuery - Gets a PETSc object associated with a given object.
288:
289: Not Collective
291: Input Parameters:
292: + obj - the PETSc object
293: Thus must be cast with a (PetscObject), for example,
294: PetscObjectCompose((PetscObject)mat,...);
295: . name - name associated with child object
296: - ptr - the other PETSc object associated with the PETSc object, this must also be
297: cast with (PetscObject)
299: Level: advanced
301: Concepts: objects^composing
302: Concepts: composing objects
303: Concepts: objects^querying
304: Concepts: querying objects
306: .seealso: PetscObjectQuery()
307: @*/
308: PetscErrorCode PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
309: {
316: (*obj->bops->query)(obj,name,ptr);
317: return(0);
318: }
322: PetscErrorCode PetscObjectComposeFunction(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
323: {
330: (*obj->bops->composefunction)(obj,name,fname,ptr);
331: return(0);
332: }
336: /*@C
337: PetscObjectQueryFunction - Gets a function associated with a given object.
338:
339: Collective on PetscObject
341: Input Parameters:
342: + obj - the PETSc object; this must be cast with (PetscObject), for example,
343: PetscObjectQueryFunction((PetscObject)ksp,...);
344: - name - name associated with the child function
346: Output Parameter:
347: . ptr - function pointer
349: Level: advanced
351: Concepts: objects^composing functions
352: Concepts: composing functions
353: Concepts: functions^querying
354: Concepts: objects^querying
355: Concepts: querying objects
357: .seealso: PetscObjectComposeFunctionDynamic()
358: @*/
359: PetscErrorCode PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)(void))
360: {
366: (*obj->bops->queryfunction)(obj,name,ptr);
367: return(0);
368: }
370: struct _p_PetscContainer {
371: PETSCHEADER(int);
372: void *ptr;
373: PetscErrorCode (*userdestroy)(void*);
374: };
378: /*@C
379: PetscContainerGetPointer - Gets the pointer value contained in the container.
381: Collective on PetscContainer
383: Input Parameter:
384: . obj - the object created with PetscContainerCreate()
386: Output Parameter:
387: . ptr - the pointer value
389: Level: advanced
391: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
392: PetscContainerSetPointer()
393: @*/
394: PetscErrorCode PetscContainerGetPointer(PetscContainer obj,void **ptr)
395: {
399: *ptr = obj->ptr;
400: return(0);
401: }
406: /*@C
407: PetscContainerSetPointer - Sets the pointer value contained in the container.
409: Collective on PetscContainer
411: Input Parameters:
412: + obj - the object created with PetscContainerCreate()
413: - ptr - the pointer value
415: Level: advanced
417: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
418: PetscContainerGetPointer()
419: @*/
420: PetscErrorCode PetscContainerSetPointer(PetscContainer obj,void *ptr)
421: {
425: obj->ptr = ptr;
426: return(0);
427: }
431: /*@C
432: PetscContainerDestroy - Destroys a PETSc container object.
434: Collective on PetscContainer
436: Input Parameter:
437: . obj - an object that was created with PetscContainerCreate()
439: Level: advanced
441: .seealso: PetscContainerCreate()
442: @*/
443: PetscErrorCode PetscContainerDestroy(PetscContainer obj)
444: {
448: if (--((PetscObject)obj)->refct > 0) return(0);
449: if (obj->userdestroy) (*obj->userdestroy)(obj->ptr);
450: PetscHeaderDestroy(obj);
451: return(0);
452: }
456: /*@C
457: PetscContainerSetUserDestroy - Sets name of the user destroy function.
459: Collective on PetscContainer
461: Input Parameter:
462: + obj - an object that was created with PetscContainerCreate()
463: - des - name of the user destroy function
465: Level: advanced
467: .seealso: PetscContainerDestroy()
468: @*/
469: PetscErrorCode PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
470: {
473: obj->userdestroy = des;
474: return(0);
475: }
477: PetscCookie PETSC_CONTAINER_COOKIE = 0;
481: /*@C
482: PetscContainerCreate - Creates a PETSc object that has room to hold
483: a single pointer. This allows one to attach any type of data (accessible
484: through a pointer) with the PetscObjectCompose() function to a PetscObject.
485: The data item itself is attached by a call to PetscContainerSetPointer.
487: Collective on MPI_Comm
489: Input Parameters:
490: . comm - MPI communicator that shares the object
492: Output Parameters:
493: . container - the container created
495: Level: advanced
497: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer()
498: @*/
499: PetscErrorCode PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
500: {
502: PetscContainer contain;
506: if (!PETSC_CONTAINER_COOKIE) {
507: PetscLogClassRegister(&PETSC_CONTAINER_COOKIE, "Container");
508: }
509: PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_COOKIE,0,"PetscContainer",comm,PetscContainerDestroy,0);
510: *container = contain;
511: return(0);
512: }
516: /*@
517: PetscObjectSetFromOptions - Sets generic parameters from user options.
519: Collective on obj
521: Input Parameter:
522: . obj - the PetscObjcet
524: Options Database Keys:
526: Notes:
527: We have no generic options at present, so this does nothing
529: Level: beginner
531: .keywords: set, options, database
532: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
533: @*/
534: PetscErrorCode PetscObjectSetFromOptions(PetscObject obj)
535: {
538: return(0);
539: }
543: /*@
544: PetscObjectSetUp - Sets up the internal data structures for the later use.
546: Collective on PetscObject
548: Input Parameters:
549: . obj - the PetscObject
551: Notes:
552: This does nothing at present.
554: Level: advanced
556: .keywords: setup
557: .seealso: PetscObjectDestroy()
558: @*/
559: PetscErrorCode PetscObjectSetUp(PetscObject obj)
560: {
563: return(0);
564: }