Actual source code: inherit.c
1: /*$Id: inherit.c,v 1.70 2001/06/21 21:15:31 bsmith Exp $*/
2: /*
3: Provides utility routines for manipulating any type of PETSc object.
4: */
5: #include petsc.h
6: #include petscsys.h
8: EXTERN int PetscObjectGetComm_Petsc(PetscObject,MPI_Comm *);
9: EXTERN int PetscObjectCompose_Petsc(PetscObject,const char[],PetscObject);
10: EXTERN int PetscObjectQuery_Petsc(PetscObject,const char[],PetscObject *);
11: EXTERN int PetscObjectComposeFunction_Petsc(PetscObject,const char[],const char[],void (*)(void));
12: EXTERN int PetscObjectQueryFunction_Petsc(PetscObject,const char[],void (**)(void));
13: EXTERN int PetscObjectComposeLanguage_Petsc(PetscObject,PetscLanguage,void *);
14: EXTERN int PetscObjectQueryLanguage_Petsc(PetscObject,PetscLanguage,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: int PetscHeaderCreate_Private(PetscObject h,int cookie,int type,char *class_name,MPI_Comm comm,
21: int (*des)(PetscObject),int (*vie)(PetscObject,PetscViewer))
22: {
23: static int idcnt = 1;
24: int ierr;
27: h->cookie = cookie;
28: h->type = type;
29: h->class_name = 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: h->bops->querylanguage = PetscObjectQueryLanguage_Petsc;
45: h->bops->composelanguage = PetscObjectComposeLanguage_Petsc;
46: PetscCommDuplicate_Private(comm,&h->comm,&h->tag);
47: return(0);
48: }
50: /*
51: PetscHeaderDestroy_Private - Destroys a base PETSc object header. Called by
52: the macro PetscHeaderDestroy().
53: */
54: int PetscHeaderDestroy_Private(PetscObject h)
55: {
59: if (h->amem != -1) {
60: SETERRQ(1,"PETSc object destroyed before its AMS publication was destroyed");
61: }
63: PetscCommDestroy_Private(&h->comm);
64: PetscFree(h->bops);
65: PetscFree(h->ops);
66: PetscOListDestroy(&h->olist);
67: PetscFListDestroy(&h->qlist);
68: PetscStrfree(h->type_name);
69: PetscStrfree(h->serialize_name);
70: PetscStrfree(h->name);
71: h->cookie = PETSCFREEDHEADER;
72: PetscStrfree(h->prefix);
73: if (h->dict) {
74: ParameterDictDestroy(h->dict);
75: }
76: if (h->fortran_func_pointers) {
77: PetscFree(h->fortran_func_pointers);
78: }
79: PetscFree(h);
80: return(0);
81: }
83: /*@C
84: PetscObjectReference - Indicates to any PetscObject that it is being
85: referenced by another PetscObject. This increases the reference
86: count for that object by one.
88: Collective on PetscObject
90: Input Parameter:
91: . obj - the PETSc object. This must be cast with (PetscObject), for example,
92: PetscObjectReference((PetscObject)mat);
94: Level: advanced
96: .seealso: PetscObjectCompose(), PetscObjectDereference()
97: @*/
98: int PetscObjectReference(PetscObject obj)
99: {
102: obj->refct++;
103: return(0);
104: }
106: /*@C
107: PetscObjectGetReference - Gets the current reference count for
108: any PETSc object.
110: Not Collective
112: Input Parameter:
113: . obj - the PETSc object; this must be cast with (PetscObject), for example,
114: PetscObjectGetReference((PetscObject)mat,&cnt);
116: Output Parameter:
117: . cnt - the reference count
119: Level: advanced
121: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
122: @*/
123: int PetscObjectGetReference(PetscObject obj,int *cnt)
124: {
127: *cnt = obj->refct;
128: return(0);
129: }
131: /*@
132: PetscObjectDereference - Indicates to any PetscObject that it is being
133: referenced by one less PetscObject. This decreases the reference
134: count for that object by one.
136: Collective on PetscObject
138: Input Parameter:
139: . obj - the PETSc object; this must be cast with (PetscObject), for example,
140: PetscObjectDereference((PetscObject)mat);
142: Level: advanced
144: .seealso: PetscObjectCompose(), PetscObjectReference()
145: @*/
146: int PetscObjectDereference(PetscObject obj)
147: {
152: if (obj->bops->destroy) {
153: (*obj->bops->destroy)(obj);
154: } else if (!--obj->refct) {
155: SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
156: }
157: return(0);
158: }
160: /* ----------------------------------------------------------------------- */
161: /*
162: The following routines are the versions private to the PETSc object
163: data structures.
164: */
165: int PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
166: {
168: *comm = obj->comm;
169: return(0);
170: }
172: int PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
173: {
174: int ierr;
175: char *tname;
178: if (ptr) {
179: PetscOListReverseFind(ptr->olist,obj,&tname);
180: if (tname){
181: SETERRQ(1,"An object cannot be composed with an object that was compose with it");
182: }
183: }
184: PetscOListAdd(&obj->olist,name,ptr);
185: return(0);
186: }
188: int PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
189: {
193: PetscOListFind(obj->olist,name,ptr);
194: return(0);
195: }
197: int PetscObjectComposeLanguage_Petsc(PetscObject obj,PetscLanguage lang,void *vob)
198: {
200: if (lang == PETSC_LANGUAGE_CPP) {
201: obj->cpp = vob;
202: } else {
203: SETERRQ(1,"No support for this language yet");
204: }
205: return(0);
206: }
208: int PetscObjectQueryLanguage_Petsc(PetscObject obj,PetscLanguage lang,void **vob)
209: {
211: if (lang == PETSC_LANGUAGE_C) {
212: *vob = (void*)obj;
213: } else if (lang == PETSC_LANGUAGE_CPP) {
214: if (obj->cpp) {
215: *vob = obj->cpp;
216: } else {
217: SETERRQ(1,"No C++ wrapper generated");
218: }
219: } else {
220: SETERRQ(1,"No support for this language yet");
221: }
222: return(0);
223: }
225: int PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
226: {
230: PetscFListAddDynamic(&obj->qlist,name,fname,ptr);
231: return(0);
232: }
234: int PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)(void))
235: {
239: PetscFListFind(obj->comm,obj->qlist,name,ptr);
240: return(0);
241: }
243: /*
244: These are the versions that are usable to any CCA compliant objects
245: */
246: /*@C
247: PetscObjectCompose - Associates another PETSc object with a given PETSc object.
248:
249: Not Collective
251: Input Parameters:
252: + obj - the PETSc object; this must be cast with (PetscObject), for example,
253: PetscObjectCompose((PetscObject)mat,...);
254: . name - name associated with the child object
255: - ptr - the other PETSc object to associate with the PETSc object; this must also be
256: cast with (PetscObject)
258: Level: advanced
260: Notes:
261: The second objects reference count is automatically increased by one when it is
262: composed.
264: Replaces any previous object that had the same name.
266: If ptr is null and name has previously been composed using an object, then that
267: entry is removed from the obj.
269: PetscObjectCompose() can be used with any PETSc object (such as
270: Mat, Vec, KSP, SNES, etc.) or any user-provided object. See
271: PetscObjectContainerCreate() for info on how to create an object from a
272: user-provided pointer that may then be composed with PETSc objects.
273:
274: Concepts: objects^composing
275: Concepts: composing objects
277: .seealso: PetscObjectQuery(), PetscObjectContainerCreate()
278: @*/
279: int PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
280: {
284: (*obj->bops->compose)(obj,name,ptr);
285: return(0);
286: }
288: /*@C
289: PetscObjectQuery - Gets a PETSc object associated with a given object.
290:
291: Not Collective
293: Input Parameters:
294: + obj - the PETSc object
295: Thus must be cast with a (PetscObject), for example,
296: PetscObjectCompose((PetscObject)mat,...);
297: . name - name associated with child object
298: - ptr - the other PETSc object associated with the PETSc object, this must also be
299: cast with (PetscObject)
301: Level: advanced
303: Concepts: objects^composing
304: Concepts: composing objects
305: Concepts: objects^querying
306: Concepts: querying objects
308: .seealso: PetscObjectQuery()
309: @*/
310: int PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
311: {
315: (*obj->bops->query)(obj,name,ptr);
316: return(0);
317: }
319: /*@C
320: PetscObjectQueryLanguage - Returns a language specific interface to the given object
321:
322: Not Collective
324: Input Parameters:
325: + obj - the PETSc object
326: Thus must be cast with a (PetscObject), for example,
327: PetscObjectCompose((PetscObject)mat,...);
328: - lang - one of PETSC_LANGUAGE_C, PETSC_LANGUAGE_F77, PETSC_LANGUAGE_CPP
330: Output Parameter:
331: . ptr - the language specific interface
333: Level: developer
335: .seealso: PetscObjectQuery()
336: @*/
337: int PetscObjectQueryLanguage(PetscObject obj,PetscLanguage lang,void **ptr)
338: {
342: (*obj->bops->querylanguage)(obj,lang,ptr);
343: return(0);
344: }
346: /*@C
347: PetscObjectComposeLanguage - Sets a language specific interface to the given object
348:
349: Not Collective
351: Input Parameters:
352: + obj - the PETSc object
353: Thus must be cast with a (PetscObject), for example,
354: PetscObjectCompose((PetscObject)mat,...);
355: . lang - one of PETSC_LANGUAGE_C, PETSC_LANGUAGE_F77, PETSC_LANGUAGE_CPP
356: - ptr - the language specific interface
358: Level: developer
360: .seealso: PetscObjectQuery()
361: @*/
362: int PetscObjectComposeLanguage(PetscObject obj,PetscLanguage lang,void *ptr)
363: {
367: (*obj->bops->composelanguage)(obj,lang,ptr);
368: return(0);
369: }
372: int PetscObjectComposeFunction(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
373: {
377: (*obj->bops->composefunction)(obj,name,fname,ptr);
378: return(0);
379: }
381: /*@C
382: PetscObjectQueryFunction - Gets a function associated with a given object.
383:
384: Collective on PetscObject
386: Input Parameters:
387: + obj - the PETSc object; this must be cast with (PetscObject), for example,
388: PetscObjectQueryFunction((PetscObject)ksp,...);
389: - name - name associated with the child function
391: Output Parameter:
392: . ptr - function pointer
394: Level: advanced
396: Concepts: objects^composing functions
397: Concepts: composing functions
398: Concepts: functions^querying
399: Concepts: objects^querying
400: Concepts: querying objects
402: .seealso: PetscObjectComposeFunctionDynamic()
403: @*/
404: int PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)(void))
405: {
409: (*obj->bops->queryfunction)(obj,name,ptr);
410: return(0);
411: }
413: /*@C
414: PetscObjectSetParameterDict - Sets a parameter dictionary for an object
416: Input Parameters:
417: + obj - The PetscObject
418: - dict - The ParameterDict
420: Level: intermediate
422: .seealso PetscObjectGetParameterDict()
423: @*/
424: int PetscObjectSetParameterDict(PetscObject obj, ParameterDict dict) {
429: if (obj->dict != PETSC_NULL) {
430: PetscObjectDereference((PetscObject) obj->dict);
431: }
432: if (dict != PETSC_NULL) {
433: PetscObjectReference((PetscObject) dict);
434: }
435: obj->dict = dict;
436: return(0);
437: }
439: /*@C
440: PetscObjectGetParameterDict - Gets the parameter dictionary for an object
442: Input Parameter:
443: . obj - The PetscObject
445: Output Parameter:
446: . dict - The ParameterDict
448: Level: intermediate
450: .seealso PetscObjectSetParameterDict()
451: @*/
452: int PetscObjectGetParameterDict(PetscObject obj, ParameterDict *dict) {
456: *dict = obj->dict;
457: return(0);
458: }
460: struct _p_PetscObjectContainer {
461: PETSCHEADER(int)
462: void *ptr;
463: };
465: /*@C
466: PetscObjectContainerGetPointer - Gets the pointer value contained in the container.
468: Collective on PetscObjectContainer
470: Input Parameter:
471: . obj - the object created with PetscObjectContainerCreate()
473: Output Parameter:
474: . ptr - the pointer value
476: Level: advanced
478: .seealso: PetscObjectContainerCreate(), PetscObjectContainerDestroy(),
479: PetscObjectContainerSetPointer()
480: @*/
481: int PetscObjectContainerGetPointer(PetscObjectContainer obj,void **ptr)
482: {
484: *ptr = obj->ptr;
485: return(0);
486: }
489: /*@C
490: PetscObjectContainerSetPointer - Sets the pointer value contained in the container.
492: Collective on PetscObjectContainer
494: Input Parameters:
495: + obj - the object created with PetscObjectContainerCreate()
496: - ptr - the pointer value
498: Level: advanced
500: .seealso: PetscObjectContainerCreate(), PetscObjectContainerDestroy(),
501: PetscObjectContainerGetPointer()
502: @*/
503: int PetscObjectContainerSetPointer(PetscObjectContainer obj,void *ptr)
504: {
506: obj->ptr = ptr;
507: return(0);
508: }
510: /*@C
511: PetscObjectContainerDestroy - Destroys a PETSc container object.
513: Collective on PetscObjectContainer
515: Input Parameter:
516: . obj - an object that was created with PetscObjectContainerCreate()
518: Level: advanced
520: .seealso: PetscObjectContainerCreate()
521: @*/
522: int PetscObjectContainerDestroy(PetscObjectContainer obj)
523: {
525: if (--obj->refct > 0) return(0);
526: PetscHeaderDestroy(obj);
527: return(0);
528: }
530: /*@C
531: PetscObjectContainerCreate - Creates a PETSc object that has room to hold
532: a single pointer. This allows one to attach any type of data (accessible
533: through a pointer) with the PetscObjectCompose() function to a PetscObject.
535: Collective on MPI_Comm
537: Input Parameters:
538: . comm - MPI communicator that shares the object
540: Level: advanced
542: .seealso: PetscObjectContainerDestroy()
543: @*/
544: int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *container)
545: {
546: PetscObjectContainer contain;
549: PetscHeaderCreate(contain,_p_PetscObjectContainer,int,PETSC_COOKIE,0,"container",comm,PetscObjectContainerDestroy,0);
550: *container = contain;
551: return(0);
552: }
554: /*MC
555: PetscObjectComposeFunctionDynamic - Associates a function with a given PETSc object.
556:
557: Collective on PetscObject
559: Input Parameters:
560: + obj - the PETSc object; this must be cast with a (PetscObject), for example,
561: PetscObjectCompose((PetscObject)mat,...);
562: . name - name associated with the child function
563: . fname - name of the function
564: - ptr - function pointer (or PETSC_NULL if using dynamic libraries)
566: Level: advanced
568: Synopsis:
569: int PetscObjectComposeFunctionDynamic(PetscObject obj,char *name,char *fname,void *ptr)
571: Notes:
572: PetscObjectComposeFunctionDynamic() can be used with any PETSc object (such as
573: Mat, Vec, KSP, SNES, etc.) or any user-provided object.
575: The composed function must be wrapped in a EXTERN_C_BEGIN/END for this to
576: work in C++/complex with dynamic link libraries (PETSC_USE_DYNAMIC_LIBRARIES)
577: enabled.
579: Concepts: objects^composing functions
580: Concepts: composing functions
581: Concepts: functions^querying
582: Concepts: objects^querying
583: Concepts: querying objects
585: .seealso: PetscObjectQueryFunction()
586: M*/