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: /* first destroy things that could execute arbitrary code */
68: if (h->python_destroy) {
69: void *python_context = h->python_context;
70: PetscErrorCode (*python_destroy)(void*) = h->python_destroy;
71: h->python_context = 0;
72: h->python_destroy = 0;
73: (*python_destroy)(python_context);
74: }
75: PetscOListDestroy(h->olist);
76: PetscCommDestroy(&h->comm);
77: /* next destroy other things */
78: h->cookie = PETSCFREEDHEADER;
79: PetscFree(h->bops);
80: PetscFListDestroy(&h->qlist);
81: PetscStrfree(h->type_name);
82: PetscStrfree(h->name);
83: PetscStrfree(h->prefix);
84: PetscFree(h->fortran_func_pointers);
85: PetscFree(h->intcomposeddata);
86: PetscFree(h->intcomposedstate);
87: PetscFree(h->realcomposeddata);
88: PetscFree(h->realcomposedstate);
89: PetscFree(h->scalarcomposeddata);
90: PetscFree(h->scalarcomposedstate);
91: return(0);
92: }
96: /*@C
97: PetscObjectReference - Indicates to any PetscObject that it is being
98: referenced by another PetscObject. This increases the reference
99: count for that object by one.
101: Collective on PetscObject
103: Input Parameter:
104: . obj - the PETSc object. This must be cast with (PetscObject), for example,
105: PetscObjectReference((PetscObject)mat);
107: Level: advanced
109: .seealso: PetscObjectCompose(), PetscObjectDereference()
110: @*/
111: PetscErrorCode PetscObjectReference(PetscObject obj)
112: {
115: obj->refct++;
116: return(0);
117: }
121: /*@C
122: PetscObjectGetReference - Gets the current reference count for
123: any PETSc object.
125: Not Collective
127: Input Parameter:
128: . obj - the PETSc object; this must be cast with (PetscObject), for example,
129: PetscObjectGetReference((PetscObject)mat,&cnt);
131: Output Parameter:
132: . cnt - the reference count
134: Level: advanced
136: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
137: @*/
138: PetscErrorCode PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
139: {
143: *cnt = obj->refct;
144: return(0);
145: }
149: /*@
150: PetscObjectDereference - Indicates to any PetscObject that it is being
151: referenced by one less PetscObject. This decreases the reference
152: count for that object by one.
154: Collective on PetscObject
156: Input Parameter:
157: . obj - the PETSc object; this must be cast with (PetscObject), for example,
158: PetscObjectDereference((PetscObject)mat);
160: Level: advanced
162: .seealso: PetscObjectCompose(), PetscObjectReference()
163: @*/
164: PetscErrorCode PetscObjectDereference(PetscObject obj)
165: {
170: if (obj->bops->destroy) {
171: (*obj->bops->destroy)(obj);
172: } else if (!--obj->refct) {
173: SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
174: }
175: return(0);
176: }
178: /* ----------------------------------------------------------------------- */
179: /*
180: The following routines are the versions private to the PETSc object
181: data structures.
182: */
185: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
186: {
188: *comm = obj->comm;
189: return(0);
190: }
194: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
195: {
197: char *tname;
200: if (ptr) {
201: PetscOListReverseFind(ptr->olist,obj,&tname);
202: if (tname){
203: SETERRQ(PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was compose with it");
204: }
205: }
206: PetscOListAdd(&obj->olist,name,ptr);
207: return(0);
208: }
212: PetscErrorCode PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
213: {
217: PetscOListFind(obj->olist,name,ptr);
218: return(0);
219: }
223: PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
224: {
228: PetscFListAdd(&obj->qlist,name,fname,ptr);
229: return(0);
230: }
234: PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)(void))
235: {
239: PetscFListFind(obj->qlist,obj->comm,name,ptr);
240: return(0);
241: }
243: /*
244: These are the versions that are usable to any CCA compliant objects
245: */
248: /*@C
249: PetscObjectCompose - Associates another PETSc object with a given PETSc object.
250:
251: Not Collective
253: Input Parameters:
254: + obj - the PETSc object; this must be cast with (PetscObject), for example,
255: PetscObjectCompose((PetscObject)mat,...);
256: . name - name associated with the child object
257: - ptr - the other PETSc object to associate with the PETSc object; this must also be
258: cast with (PetscObject)
260: Level: advanced
262: Notes:
263: The second objects reference count is automatically increased by one when it is
264: composed.
266: Replaces any previous object that had the same name.
268: If ptr is null and name has previously been composed using an object, then that
269: entry is removed from the obj.
271: PetscObjectCompose() can be used with any PETSc object (such as
272: Mat, Vec, KSP, SNES, etc.) or any user-provided object. See
273: PetscContainerCreate() for info on how to create an object from a
274: user-provided pointer that may then be composed with PETSc objects.
275:
276: Concepts: objects^composing
277: Concepts: composing objects
279: .seealso: PetscObjectQuery(), PetscContainerCreate()
280: @*/
281: PetscErrorCode PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
282: {
289: (*obj->bops->compose)(obj,name,ptr);
290: return(0);
291: }
295: /*@C
296: PetscObjectQuery - Gets a PETSc object associated with a given object.
297:
298: Not Collective
300: Input Parameters:
301: + obj - the PETSc object
302: Thus must be cast with a (PetscObject), for example,
303: PetscObjectCompose((PetscObject)mat,...);
304: . name - name associated with child object
305: - ptr - the other PETSc object associated with the PETSc object, this must also be
306: cast with (PetscObject)
308: Level: advanced
310: Concepts: objects^composing
311: Concepts: composing objects
312: Concepts: objects^querying
313: Concepts: querying objects
315: .seealso: PetscObjectQuery()
316: @*/
317: PetscErrorCode PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
318: {
325: (*obj->bops->query)(obj,name,ptr);
326: return(0);
327: }
331: PetscErrorCode PetscObjectComposeFunction(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
332: {
339: (*obj->bops->composefunction)(obj,name,fname,ptr);
340: return(0);
341: }
345: /*@C
346: PetscObjectQueryFunction - Gets a function associated with a given object.
347:
348: Collective on PetscObject
350: Input Parameters:
351: + obj - the PETSc object; this must be cast with (PetscObject), for example,
352: PetscObjectQueryFunction((PetscObject)ksp,...);
353: - name - name associated with the child function
355: Output Parameter:
356: . ptr - function pointer
358: Level: advanced
360: Concepts: objects^composing functions
361: Concepts: composing functions
362: Concepts: functions^querying
363: Concepts: objects^querying
364: Concepts: querying objects
366: .seealso: PetscObjectComposeFunctionDynamic()
367: @*/
368: PetscErrorCode PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)(void))
369: {
375: (*obj->bops->queryfunction)(obj,name,ptr);
376: return(0);
377: }
379: struct _p_PetscContainer {
380: PETSCHEADER(int);
381: void *ptr;
382: PetscErrorCode (*userdestroy)(void*);
383: };
387: /*@C
388: PetscContainerGetPointer - Gets the pointer value contained in the container.
390: Collective on PetscContainer
392: Input Parameter:
393: . obj - the object created with PetscContainerCreate()
395: Output Parameter:
396: . ptr - the pointer value
398: Level: advanced
400: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
401: PetscContainerSetPointer()
402: @*/
403: PetscErrorCode PetscContainerGetPointer(PetscContainer obj,void **ptr)
404: {
408: *ptr = obj->ptr;
409: return(0);
410: }
415: /*@C
416: PetscContainerSetPointer - Sets the pointer value contained in the container.
418: Collective on PetscContainer
420: Input Parameters:
421: + obj - the object created with PetscContainerCreate()
422: - ptr - the pointer value
424: Level: advanced
426: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
427: PetscContainerGetPointer()
428: @*/
429: PetscErrorCode PetscContainerSetPointer(PetscContainer obj,void *ptr)
430: {
434: obj->ptr = ptr;
435: return(0);
436: }
440: /*@C
441: PetscContainerDestroy - Destroys a PETSc container object.
443: Collective on PetscContainer
445: Input Parameter:
446: . obj - an object that was created with PetscContainerCreate()
448: Level: advanced
450: .seealso: PetscContainerCreate()
451: @*/
452: PetscErrorCode PetscContainerDestroy(PetscContainer obj)
453: {
457: if (--((PetscObject)obj)->refct > 0) return(0);
458: if (obj->userdestroy) (*obj->userdestroy)(obj->ptr);
459: PetscHeaderDestroy(obj);
460: return(0);
461: }
465: /*@C
466: PetscContainerSetUserDestroy - Sets name of the user destroy function.
468: Collective on PetscContainer
470: Input Parameter:
471: + obj - an object that was created with PetscContainerCreate()
472: - des - name of the user destroy function
474: Level: advanced
476: .seealso: PetscContainerDestroy()
477: @*/
478: PetscErrorCode PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
479: {
482: obj->userdestroy = des;
483: return(0);
484: }
486: PetscCookie PETSC_CONTAINER_COOKIE;
490: /*@C
491: PetscContainerCreate - Creates a PETSc object that has room to hold
492: a single pointer. This allows one to attach any type of data (accessible
493: through a pointer) with the PetscObjectCompose() function to a PetscObject.
494: The data item itself is attached by a call to PetscContainerSetPointer.
496: Collective on MPI_Comm
498: Input Parameters:
499: . comm - MPI communicator that shares the object
501: Output Parameters:
502: . container - the container created
504: Level: advanced
506: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer()
507: @*/
508: PetscErrorCode PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
509: {
511: PetscContainer contain;
515: if (!PETSC_CONTAINER_COOKIE) {
516: PetscCookieRegister("Container",&PETSC_CONTAINER_COOKIE);
517: }
518: PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_COOKIE,0,"PetscContainer",comm,PetscContainerDestroy,0);
519: *container = contain;
520: return(0);
521: }
525: /*@
526: PetscObjectSetFromOptions - Sets generic parameters from user options.
528: Collective on obj
530: Input Parameter:
531: . obj - the PetscObjcet
533: Options Database Keys:
535: Notes:
536: We have no generic options at present, so this does nothing
538: Level: beginner
540: .keywords: set, options, database
541: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
542: @*/
543: PetscErrorCode PetscObjectSetFromOptions(PetscObject obj)
544: {
547: return(0);
548: }
552: /*@
553: PetscObjectSetUp - Sets up the internal data structures for the later use.
555: Collective on PetscObject
557: Input Parameters:
558: . obj - the PetscObject
560: Notes:
561: This does nothing at present.
563: Level: advanced
565: .keywords: setup
566: .seealso: PetscObjectDestroy()
567: @*/
568: PetscErrorCode PetscObjectSetUp(PetscObject obj)
569: {
572: return(0);
573: }