Actual source code: inherit.c
1: #define PETSC_DLL
2: /*
3: Provides utility routines for manipulating any type of PETSc object.
4: */
5: #include petscsys.h
7: EXTERN PetscErrorCode PetscObjectGetComm_Petsc(PetscObject,MPI_Comm *);
8: EXTERN PetscErrorCode PetscObjectCompose_Petsc(PetscObject,const char[],PetscObject);
9: EXTERN PetscErrorCode PetscObjectQuery_Petsc(PetscObject,const char[],PetscObject *);
10: EXTERN PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject,const char[],const char[],void (*)(void));
11: EXTERN PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject,const char[],void (**)(void));
15: /*
16: PetscHeaderCreate_Private - Creates a base PETSc object header and fills
17: in the default values. Called by the macro PetscHeaderCreate().
18: */
19: PetscErrorCode PetscHeaderCreate_Private(PetscObject h,PetscCookie cookie,PetscInt type,const char class_name[],MPI_Comm comm,
20: PetscErrorCode (*des)(PetscObject),PetscErrorCode (*vie)(PetscObject,PetscViewer))
21: {
22: static PetscInt idcnt = 1;
23: PetscErrorCode ierr;
26: h->cookie = cookie;
27: h->type = type;
28: h->class_name = (char*)class_name;
29: h->prefix = 0;
30: h->refct = 1;
31: h->amem = -1;
32: h->id = idcnt++;
33: h->parentid = 0;
34: h->qlist = 0;
35: h->olist = 0;
36: h->bops->destroy = des;
37: h->bops->view = vie;
38: h->bops->getcomm = PetscObjectGetComm_Petsc;
39: h->bops->compose = PetscObjectCompose_Petsc;
40: h->bops->query = PetscObjectQuery_Petsc;
41: h->bops->composefunction = PetscObjectComposeFunction_Petsc;
42: h->bops->queryfunction = PetscObjectQueryFunction_Petsc;
43: PetscCommDuplicate(comm,&h->comm,&h->tag);
44: return(0);
45: }
52: /*
53: PetscHeaderDestroy_Private - Destroys a base PETSc object header. Called by
54: the macro PetscHeaderDestroy().
55: */
56: PetscErrorCode PetscHeaderDestroy_Private(PetscObject h)
57: {
61: if (PetscMemoryCollectMaximumUsage) {
62: PetscLogDouble usage;
63: PetscMemoryGetCurrentUsage(&usage);
64: if (usage > PetscMemoryMaximumUsage) PetscMemoryMaximumUsage = usage;
65: }
66: /* first destroy things that could execute arbitrary code */
67: if (h->python_destroy) {
68: void *python_context = h->python_context;
69: PetscErrorCode (*python_destroy)(void*) = h->python_destroy;
70: h->python_context = 0;
71: h->python_destroy = 0;
72: (*python_destroy)(python_context);
73: }
74: PetscOListDestroy(h->olist);
75: PetscCommDestroy(&h->comm);
76: /* next destroy other things */
77: h->cookie = PETSCFREEDHEADER;
78: PetscFree(h->bops);
79: PetscFListDestroy(&h->qlist);
80: PetscStrfree(h->type_name);
81: PetscStrfree(h->name);
82: PetscStrfree(h->prefix);
83: PetscFree(h->fortran_func_pointers);
84: PetscFree(h->intcomposeddata);
85: PetscFree(h->intcomposedstate);
86: PetscFree(h->realcomposeddata);
87: PetscFree(h->realcomposedstate);
88: PetscFree(h->scalarcomposeddata);
89: PetscFree(h->scalarcomposedstate);
90: return(0);
91: }
95: /*@C
96: PetscObjectReference - Indicates to any PetscObject that it is being
97: referenced by another PetscObject. This increases the reference
98: count for that object by one.
100: Collective on PetscObject
102: Input Parameter:
103: . obj - the PETSc object. This must be cast with (PetscObject), for example,
104: PetscObjectReference((PetscObject)mat);
106: Level: advanced
108: .seealso: PetscObjectCompose(), PetscObjectDereference()
109: @*/
110: PetscErrorCode PetscObjectReference(PetscObject obj)
111: {
114: obj->refct++;
115: return(0);
116: }
120: /*@C
121: PetscObjectGetReference - Gets the current reference count for
122: any PETSc object.
124: Not Collective
126: Input Parameter:
127: . obj - the PETSc object; this must be cast with (PetscObject), for example,
128: PetscObjectGetReference((PetscObject)mat,&cnt);
130: Output Parameter:
131: . cnt - the reference count
133: Level: advanced
135: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
136: @*/
137: PetscErrorCode PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
138: {
142: *cnt = obj->refct;
143: return(0);
144: }
148: /*@
149: PetscObjectDereference - Indicates to any PetscObject that it is being
150: referenced by one less PetscObject. This decreases the reference
151: count for that object by one.
153: Collective on PetscObject
155: Input Parameter:
156: . obj - the PETSc object; this must be cast with (PetscObject), for example,
157: PetscObjectDereference((PetscObject)mat);
159: Level: advanced
161: .seealso: PetscObjectCompose(), PetscObjectReference()
162: @*/
163: PetscErrorCode PetscObjectDereference(PetscObject obj)
164: {
169: if (obj->bops->destroy) {
170: (*obj->bops->destroy)(obj);
171: } else if (!--obj->refct) {
172: SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
173: }
174: return(0);
175: }
177: /* ----------------------------------------------------------------------- */
178: /*
179: The following routines are the versions private to the PETSc object
180: data structures.
181: */
184: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
185: {
187: *comm = obj->comm;
188: return(0);
189: }
193: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
194: {
196: char *tname;
199: if (ptr) {
200: PetscOListReverseFind(ptr->olist,obj,&tname);
201: if (tname){
202: SETERRQ(PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was compose with it");
203: }
204: }
205: PetscOListAdd(&obj->olist,name,ptr);
206: return(0);
207: }
211: PetscErrorCode PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
212: {
216: PetscOListFind(obj->olist,name,ptr);
217: return(0);
218: }
222: PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
223: {
227: PetscFListAdd(&obj->qlist,name,fname,ptr);
228: return(0);
229: }
233: PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)(void))
234: {
238: PetscFListFind(obj->qlist,obj->comm,name,ptr);
239: return(0);
240: }
242: /*
243: These are the versions that are usable to any CCA compliant objects
244: */
247: /*@C
248: PetscObjectCompose - Associates another PETSc object with a given PETSc object.
249:
250: Not Collective
252: Input Parameters:
253: + obj - the PETSc object; this must be cast with (PetscObject), for example,
254: PetscObjectCompose((PetscObject)mat,...);
255: . name - name associated with the child object
256: - ptr - the other PETSc object to associate with the PETSc object; this must also be
257: cast with (PetscObject)
259: Level: advanced
261: Notes:
262: The second objects reference count is automatically increased by one when it is
263: composed.
265: Replaces any previous object that had the same name.
267: If ptr is null and name has previously been composed using an object, then that
268: entry is removed from the obj.
270: PetscObjectCompose() can be used with any PETSc object (such as
271: Mat, Vec, KSP, SNES, etc.) or any user-provided object. See
272: PetscContainerCreate() for info on how to create an object from a
273: user-provided pointer that may then be composed with PETSc objects.
274:
275: Concepts: objects^composing
276: Concepts: composing objects
278: .seealso: PetscObjectQuery(), PetscContainerCreate()
279: @*/
280: PetscErrorCode PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
281: {
288: (*obj->bops->compose)(obj,name,ptr);
289: return(0);
290: }
296: /*@C
297: PetscObjectQuery - Gets a PETSc object associated with a given object.
298:
299: Not Collective
301: Input Parameters:
302: + obj - the PETSc object
303: Thus must be cast with a (PetscObject), for example,
304: PetscObjectCompose((PetscObject)mat,...);
305: . name - name associated with child object
306: - ptr - the other PETSc object associated with the PETSc object, this must also be
307: cast with (PetscObject)
309: Level: advanced
311: Concepts: objects^composing
312: Concepts: composing objects
313: Concepts: objects^querying
314: Concepts: querying objects
316: .seealso: PetscObjectQuery()
317: @*/
318: PetscErrorCode PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
319: {
326: (*obj->bops->query)(obj,name,ptr);
327: return(0);
328: }
332: PetscErrorCode PetscObjectComposeFunction(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
333: {
340: (*obj->bops->composefunction)(obj,name,fname,ptr);
341: return(0);
342: }
346: /*@C
347: PetscObjectQueryFunction - Gets a function associated with a given object.
348:
349: Collective on PetscObject
351: Input Parameters:
352: + obj - the PETSc object; this must be cast with (PetscObject), for example,
353: PetscObjectQueryFunction((PetscObject)ksp,...);
354: - name - name associated with the child function
356: Output Parameter:
357: . ptr - function pointer
359: Level: advanced
361: Concepts: objects^composing functions
362: Concepts: composing functions
363: Concepts: functions^querying
364: Concepts: objects^querying
365: Concepts: querying objects
367: .seealso: PetscObjectComposeFunctionDynamic()
368: @*/
369: PetscErrorCode PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)(void))
370: {
376: (*obj->bops->queryfunction)(obj,name,ptr);
377: return(0);
378: }
380: struct _p_PetscContainer {
381: PETSCHEADER(int);
382: void *ptr;
383: PetscErrorCode (*userdestroy)(void*);
384: };
388: /*@C
389: PetscContainerGetPointer - Gets the pointer value contained in the container.
391: Collective on PetscContainer
393: Input Parameter:
394: . obj - the object created with PetscContainerCreate()
396: Output Parameter:
397: . ptr - the pointer value
399: Level: advanced
401: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
402: PetscContainerSetPointer()
403: @*/
404: PetscErrorCode PetscContainerGetPointer(PetscContainer obj,void **ptr)
405: {
409: *ptr = obj->ptr;
410: return(0);
411: }
416: /*@C
417: PetscContainerSetPointer - Sets the pointer value contained in the container.
419: Collective on PetscContainer
421: Input Parameters:
422: + obj - the object created with PetscContainerCreate()
423: - ptr - the pointer value
425: Level: advanced
427: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
428: PetscContainerGetPointer()
429: @*/
430: PetscErrorCode PetscContainerSetPointer(PetscContainer obj,void *ptr)
431: {
435: obj->ptr = ptr;
436: return(0);
437: }
441: /*@C
442: PetscContainerDestroy - Destroys a PETSc container object.
444: Collective on PetscContainer
446: Input Parameter:
447: . obj - an object that was created with PetscContainerCreate()
449: Level: advanced
451: .seealso: PetscContainerCreate()
452: @*/
453: PetscErrorCode PetscContainerDestroy(PetscContainer obj)
454: {
458: if (--((PetscObject)obj)->refct > 0) return(0);
459: if (obj->userdestroy) (*obj->userdestroy)(obj->ptr);
460: PetscHeaderDestroy(obj);
461: return(0);
462: }
466: /*@C
467: PetscContainerSetUserDestroy - Sets name of the user destroy function.
469: Collective on PetscContainer
471: Input Parameter:
472: + obj - an object that was created with PetscContainerCreate()
473: - des - name of the user destroy function
475: Level: advanced
477: .seealso: PetscContainerDestroy()
478: @*/
479: PetscErrorCode PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
480: {
483: obj->userdestroy = des;
484: return(0);
485: }
487: PetscCookie PETSC_CONTAINER_COOKIE;
491: /*@C
492: PetscContainerCreate - Creates a PETSc object that has room to hold
493: a single pointer. This allows one to attach any type of data (accessible
494: through a pointer) with the PetscObjectCompose() function to a PetscObject.
495: The data item itself is attached by a call to PetscContainerSetPointer.
497: Collective on MPI_Comm
499: Input Parameters:
500: . comm - MPI communicator that shares the object
502: Output Parameters:
503: . container - the container created
505: Level: advanced
507: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer()
508: @*/
509: PetscErrorCode PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
510: {
512: PetscContainer contain;
516: PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_COOKIE,0,"PetscContainer",comm,PetscContainerDestroy,0);
517: *container = contain;
518: return(0);
519: }
523: /*@
524: PetscObjectSetFromOptions - Sets generic parameters from user options.
526: Collective on obj
528: Input Parameter:
529: . obj - the PetscObjcet
531: Options Database Keys:
533: Notes:
534: We have no generic options at present, so this does nothing
536: Level: beginner
538: .keywords: set, options, database
539: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
540: @*/
541: PetscErrorCode PetscObjectSetFromOptions(PetscObject obj)
542: {
545: return(0);
546: }
550: /*@
551: PetscObjectSetUp - Sets up the internal data structures for the later use.
553: Collective on PetscObject
555: Input Parameters:
556: . obj - the PetscObject
558: Notes:
559: This does nothing at present.
561: Level: advanced
563: .keywords: setup
564: .seealso: PetscObjectDestroy()
565: @*/
566: PetscErrorCode PetscObjectSetUp(PetscObject obj)
567: {
570: return(0);
571: }