Actual source code: inherit.c
1: /*$Id: inherit.c,v 1.69 2001/04/10 19:34:33 bsmith Exp $*/
2: /*
3: Provides utility routines for manipulating any type of PETSc object.
4: */
5: #include "petsc.h" /*I "petsc.h" I*/
7: EXTERN int PetscObjectGetComm_Petsc(PetscObject,MPI_Comm *);
8: EXTERN int PetscObjectCompose_Petsc(PetscObject,const char[],PetscObject);
9: EXTERN int PetscObjectQuery_Petsc(PetscObject,const char[],PetscObject *);
10: EXTERN int PetscObjectComposeFunction_Petsc(PetscObject,const char[],const char[],void (*)());
11: EXTERN int PetscObjectQueryFunction_Petsc(PetscObject,const char[],void (**)());
12: EXTERN int PetscObjectComposeLanguage_Petsc(PetscObject,PetscLanguage,void *);
13: EXTERN int PetscObjectQueryLanguage_Petsc(PetscObject,PetscLanguage,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: int PetscHeaderCreate_Private(PetscObject h,int cookie,int type,char *class_name,MPI_Comm comm,
20: int (*des)(PetscObject),int (*vie)(PetscObject,PetscViewer))
21: {
22: static int idcnt = 1;
23: int ierr;
26: h->cookie = cookie;
27: h->type = type;
28: h->class_name = 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: h->bops->querylanguage = PetscObjectQueryLanguage_Petsc;
44: h->bops->composelanguage = PetscObjectComposeLanguage_Petsc;
45: PetscCommDuplicate_Private(comm,&h->comm,&h->tag);
46: return(0);
47: }
49: /*
50: PetscHeaderDestroy_Private - Destroys a base PETSc object header. Called by
51: the macro PetscHeaderDestroy().
52: */
53: int PetscHeaderDestroy_Private(PetscObject h)
54: {
58: if (h->amem != -1) {
59: SETERRQ(1,"PETSc object destroyed before its AMS publication was destroyed");
60: }
62: PetscCommDestroy_Private(&h->comm);
63: PetscFree(h->bops);
64: PetscFree(h->ops);
65: PetscOListDestroy(&h->olist);
66: PetscFListDestroy(&h->qlist);
67: PetscStrfree(h->type_name);
68: PetscStrfree(h->name);
69: h->cookie = PETSCFREEDHEADER;
70: PetscStrfree(h->prefix);
71: if (h->fortran_func_pointers) {
72: PetscFree(h->fortran_func_pointers);
73: }
74: PetscFree(h);
75: return(0);
76: }
78: /*@C
79: PetscObjectReference - Indicates to any PetscObject that it is being
80: referenced by another PetscObject. This increases the reference
81: count for that object by one.
83: Collective on PetscObject
85: Input Parameter:
86: . obj - the PETSc object. This must be cast with (PetscObject), for example,
87: PetscObjectReference((PetscObject)mat);
89: Level: advanced
91: .seealso: PetscObjectCompose(), PetscObjectDereference()
92: @*/
93: int PetscObjectReference(PetscObject obj)
94: {
97: obj->refct++;
98: return(0);
99: }
101: /*@C
102: PetscObjectGetReference - Gets the current reference count for
103: any PETSc object.
105: Not Collective
107: Input Parameter:
108: . obj - the PETSc object; this must be cast with (PetscObject), for example,
109: PetscObjectGetReference((PetscObject)mat,&cnt);
111: Output Parameter:
112: . cnt - the reference count
114: Level: advanced
116: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
117: @*/
118: int PetscObjectGetReference(PetscObject obj,int *cnt)
119: {
122: *cnt = obj->refct;
123: return(0);
124: }
126: /*@
127: PetscObjectDereference - Indicates to any PetscObject that it is being
128: referenced by one less PetscObject. This decreases the reference
129: count for that object by one.
131: Collective on PetscObject
133: Input Parameter:
134: . obj - the PETSc object; this must be cast with (PetscObject), for example,
135: PetscObjectDereference((PetscObject)mat);
137: Level: advanced
139: .seealso: PetscObjectCompose(), PetscObjectReference()
140: @*/
141: int PetscObjectDereference(PetscObject obj)
142: {
147: if (obj->bops->destroy) {
148: (*obj->bops->destroy)(obj);
149: } else if (!--obj->refct) {
150: SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
151: }
152: return(0);
153: }
155: /* ----------------------------------------------------------------------- */
156: /*
157: The following routines are the versions private to the PETSc object
158: data structures.
159: */
160: int PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
161: {
163: *comm = obj->comm;
164: return(0);
165: }
167: int PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
168: {
169: int ierr;
170: char *tname;
173: if (ptr) {
174: PetscOListReverseFind(ptr->olist,obj,&tname);
175: if (tname){
176: SETERRQ(1,"An object cannot be composed with an object that was compose with it");
177: }
178: }
179: PetscOListAdd(&obj->olist,name,ptr);
180: return(0);
181: }
183: int PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
184: {
188: PetscOListFind(obj->olist,name,ptr);
189: return(0);
190: }
192: int PetscObjectComposeLanguage_Petsc(PetscObject obj,PetscLanguage lang,void *vob)
193: {
195: if (lang == PETSC_LANGUAGE_CPP) {
196: obj->cpp = vob;
197: } else {
198: SETERRQ(1,"No support for this language yet");
199: }
200: return(0);
201: }
203: int PetscObjectQueryLanguage_Petsc(PetscObject obj,PetscLanguage lang,void **vob)
204: {
206: if (lang == PETSC_LANGUAGE_C) {
207: *vob = (void*)obj;
208: } else if (lang == PETSC_LANGUAGE_CPP) {
209: if (obj->cpp) {
210: *vob = obj->cpp;
211: } else {
212: SETERRQ(1,"No C++ wrapper generated");
213: }
214: } else {
215: SETERRQ(1,"No support for this language yet");
216: }
217: return(0);
218: }
220: int PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],const char fname[],void (*ptr)())
221: {
225: PetscFListAddDynamic(&obj->qlist,name,fname,ptr);
226: return(0);
227: }
229: int PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)())
230: {
234: PetscFListFind(obj->comm,obj->qlist,name,ptr);
235: return(0);
236: }
238: /*
239: These are the versions that are usable to any CCA compliant objects
240: */
241: /*@C
242: PetscObjectCompose - Associates another PETSc object with a given PETSc object.
243:
244: Not Collective
246: Input Parameters:
247: + obj - the PETSc object; this must be cast with (PetscObject), for example,
248: PetscObjectCompose((PetscObject)mat,...);
249: . name - name associated with the child object
250: - ptr - the other PETSc object to associate with the PETSc object; this must also be
251: cast with (PetscObject)
253: Level: advanced
255: Notes:
256: The second objects reference count is automatically increased by one when it is
257: composed.
259: Replaces any previous object that had the same name.
261: If ptr is null and name has previously been composed using an object, then that
262: entry is removed from the obj.
264: PetscObjectCompose() can be used with any PETSc object (such as
265: Mat, Vec, KSP, SNES, etc.) or any user-provided object. See
266: PetscObjectContainerCreate() for info on how to create an object from a
267: user-provided pointer that may then be composed with PETSc objects.
268:
269: Concepts: objects^composing
270: Concepts: composing objects
272: .seealso: PetscObjectQuery(), PetscObjectContainerCreate()
273: @*/
274: int PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
275: {
279: (*obj->bops->compose)(obj,name,ptr);
280: return(0);
281: }
283: /*@C
284: PetscObjectQuery - Gets a PETSc object associated with a given object.
285:
286: Not Collective
288: Input Parameters:
289: + obj - the PETSc object
290: Thus must be cast with a (PetscObject), for example,
291: PetscObjectCompose((PetscObject)mat,...);
292: . name - name associated with child object
293: - ptr - the other PETSc object associated with the PETSc object, this must also be
294: cast with (PetscObject)
296: Level: advanced
298: Concepts: objects^composing
299: Concepts: composing objects
300: Concepts: objects^querying
301: Concepts: querying objects
303: .seealso: PetscObjectQuery()
304: @*/
305: int PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
306: {
310: (*obj->bops->query)(obj,name,ptr);
311: return(0);
312: }
314: /*@C
315: PetscObjectQueryLanguage - Returns a language specific interface to the given object
316:
317: Not Collective
319: Input Parameters:
320: + obj - the PETSc object
321: Thus must be cast with a (PetscObject), for example,
322: PetscObjectCompose((PetscObject)mat,...);
323: - lang - one of PETSC_LANGUAGE_C, PETSC_LANGUAGE_F77, PETSC_LANGUAGE_CPP
325: Output Parameter:
326: . ptr - the language specific interface
328: Level: developer
330: .seealso: PetscObjectQuery()
331: @*/
332: int PetscObjectQueryLanguage(PetscObject obj,PetscLanguage lang,void **ptr)
333: {
337: (*obj->bops->querylanguage)(obj,lang,ptr);
338: return(0);
339: }
341: /*@C
342: PetscObjectComposeLanguage - Sets a language specific interface to the given object
343:
344: Not Collective
346: Input Parameters:
347: + obj - the PETSc object
348: Thus must be cast with a (PetscObject), for example,
349: PetscObjectCompose((PetscObject)mat,...);
350: . lang - one of PETSC_LANGUAGE_C, PETSC_LANGUAGE_F77, PETSC_LANGUAGE_CPP
351: - ptr - the language specific interface
353: Level: developer
355: .seealso: PetscObjectQuery()
356: @*/
357: int PetscObjectComposeLanguage(PetscObject obj,PetscLanguage lang,void *ptr)
358: {
362: (*obj->bops->composelanguage)(obj,lang,ptr);
363: return(0);
364: }
367: int PetscObjectComposeFunction(PetscObject obj,const char name[],const char fname[],void (*ptr)())
368: {
372: (*obj->bops->composefunction)(obj,name,fname,ptr);
373: return(0);
374: }
376: /*@C
377: PetscObjectQueryFunction - Gets a function associated with a given object.
378:
379: Collective on PetscObject
381: Input Parameters:
382: + obj - the PETSc object; this must be cast with (PetscObject), for example,
383: PetscObjectQueryFunction((PetscObject)ksp,...);
384: - name - name associated with the child function
386: Output Parameter:
387: . ptr - function pointer
389: Level: advanced
391: Concepts: objects^composing functions
392: Concepts: composing functions
393: Concepts: functions^querying
394: Concepts: objects^querying
395: Concepts: querying objects
397: .seealso: PetscObjectComposeFunctionDynamic()
398: @*/
399: int PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)())
400: {
404: (*obj->bops->queryfunction)(obj,name,ptr);
405: return(0);
406: }
408: struct _p_PetscObjectContainer {
409: PETSCHEADER(int)
410: void *ptr;
411: };
413: /*@C
414: PetscObjectContainerGetPointer - Gets the pointer value contained in the container.
416: Collective on PetscObjectContainer
418: Input Parameter:
419: . obj - the object created with PetscObjectContainerCreate()
421: Output Parameter:
422: . ptr - the pointer value
424: Level: advanced
426: .seealso: PetscObjectContainerCreate(), PetscObjectContainerDestroy(),
427: PetscObjectContainerSetPointer()
428: @*/
429: int PetscObjectContainerGetPointer(PetscObjectContainer obj,void **ptr)
430: {
432: *ptr = obj->ptr;
433: return(0);
434: }
437: /*@C
438: PetscObjectContainerSetPointer - Sets the pointer value contained in the container.
440: Collective on PetscObjectContainer
442: Input Parameters:
443: + obj - the object created with PetscObjectContainerCreate()
444: - ptr - the pointer value
446: Level: advanced
448: .seealso: PetscObjectContainerCreate(), PetscObjectContainerDestroy(),
449: PetscObjectContainerGetPointer()
450: @*/
451: int PetscObjectContainerSetPointer(PetscObjectContainer obj,void *ptr)
452: {
454: obj->ptr = ptr;
455: return(0);
456: }
458: /*@C
459: PetscObjectContainerDestroy - Destroys a PETSc container object.
461: Collective on PetscObjectContainer
463: Input Parameter:
464: . obj - an object that was created with PetscObjectContainerCreate()
466: Level: advanced
468: .seealso: PetscObjectContainerCreate()
469: @*/
470: int PetscObjectContainerDestroy(PetscObjectContainer obj)
471: {
473: if (--obj->refct > 0) return(0);
474: PetscHeaderDestroy(obj);
475: return(0);
476: }
478: /*@C
479: PetscObjectContainerCreate - Creates a PETSc object that has room to hold
480: a single pointer. This allows one to attach any type of data (accessible
481: through a pointer) with the PetscObjectCompose() function to a PetscObject.
483: Collective on MPI_Comm
485: Input Parameters:
486: . comm - MPI communicator that shares the object
488: Level: advanced
490: .seealso: PetscObjectContainerDestroy()
491: @*/
492: int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *container)
493: {
494: PetscObjectContainer contain;
497: PetscHeaderCreate(contain,_p_PetscObjectContainer,int,PETSC_COOKIE,0,"container",comm,PetscObjectContainerDestroy,0);
498: *container = contain;
499: return(0);
500: }
502: /*MC
503: PetscObjectComposeFunction - Associates a function with a given PETSc object.
504:
505: Collective on PetscObject
507: Input Parameters:
508: + obj - the PETSc object; this must be cast with a (PetscObject), for example,
509: PetscObjectCompose((PetscObject)mat,...);
510: . name - name associated with the child function
511: . fname - name of the function
512: - ptr - function pointer (or PETSC_NULL if using dynamic libraries)
514: Level: advanced
516: Synopsis:
517: PetscObjectComposeFunctionDynamic(PetscObject obj,char *name,char *fname,void *ptr)
519: Notes:
520: PetscObjectComposeFunctionDynamic() can be used with any PETSc object (such as
521: Mat, Vec, KSP, SNES, etc.) or any user-provided object.
523: The composed function must be wrapped in a EXTERN_C_BEGIN/END for this to
524: work in C++/complex with dynamic link libraries (PETSC_USE_DYNAMIC_LIBRARIES)
525: enabled.
527: Concepts: objects^composing functions
528: Concepts: composing functions
529: Concepts: functions^querying
530: Concepts: objects^querying
531: Concepts: querying objects
533: .seealso: PetscObjectQueryFunction()
534: M*/