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 **);
18: /*
19: PetscHeaderCreate_Private - Creates a base PETSc object header and fills
20: in the default values. Called by the macro PetscHeaderCreate().
21: */
22: int PetscHeaderCreate_Private(PetscObject h,int cookie,int type,const char class_name[],MPI_Comm comm,
23: int (*des)(PetscObject),int (*vie)(PetscObject,PetscViewer))
24: {
25: static int idcnt = 1;
26: int ierr;
29: h->cookie = cookie;
30: h->type = type;
31: h->class_name = (char*)class_name;
32: h->prefix = 0;
33: h->refct = 1;
34: h->amem = -1;
35: h->id = idcnt++;
36: h->parentid = 0;
37: h->qlist = 0;
38: h->olist = 0;
39: h->bops->destroy = des;
40: h->bops->view = vie;
41: h->bops->getcomm = PetscObjectGetComm_Petsc;
42: h->bops->compose = PetscObjectCompose_Petsc;
43: h->bops->query = PetscObjectQuery_Petsc;
44: h->bops->composefunction = PetscObjectComposeFunction_Petsc;
45: h->bops->queryfunction = PetscObjectQueryFunction_Petsc;
46: h->bops->querylanguage = PetscObjectQueryLanguage_Petsc;
47: h->bops->composelanguage = PetscObjectComposeLanguage_Petsc;
48: PetscCommDuplicate(comm,&h->comm,&h->tag);
49: return(0);
50: }
54: /*
55: PetscHeaderDestroy_Private - Destroys a base PETSc object header. Called by
56: the macro PetscHeaderDestroy().
57: */
58: int PetscHeaderDestroy_Private(PetscObject h)
59: {
63: if (h->amem != -1) {
64: SETERRQ(1,"PETSc object destroyed before its AMS publication was destroyed");
65: }
67: PetscCommDestroy(&h->comm);
68: PetscFree(h->bops);
69: PetscFree(h->ops);
70: PetscOListDestroy(&h->olist);
71: PetscFListDestroy(&h->qlist);
72: PetscStrfree(h->type_name);
73: PetscStrfree(h->name);
74: h->cookie = PETSCFREEDHEADER;
75: PetscStrfree(h->prefix);
76: if (h->dict) {
77: ParameterDictDestroy(h->dict);
78: }
79: if (h->fortran_func_pointers) {
80: PetscFree(h->fortran_func_pointers);
81: }
82: if (h->intcomposeddata) {
83: PetscFree(h->intcomposeddata);
84: }
85: if (h->intcomposedstate) {
86: PetscFree(h->intcomposedstate);
87: }
88: if (h->realcomposeddata) {
89: PetscFree(h->realcomposeddata);
90: }
91: if (h->realcomposedstate) {
92: PetscFree(h->realcomposedstate);
93: }
94: if (h->scalarcomposeddata) {
95: PetscFree(h->scalarcomposeddata);
96: }
97: if (h->scalarcomposedstate) {
98: PetscFree(h->scalarcomposedstate);
99: }
100: PetscFree(h);
101: return(0);
102: }
106: /*@C
107: PetscObjectReference - Indicates to any PetscObject that it is being
108: referenced by another PetscObject. This increases the reference
109: count for that object by one.
111: Collective on PetscObject
113: Input Parameter:
114: . obj - the PETSc object. This must be cast with (PetscObject), for example,
115: PetscObjectReference((PetscObject)mat);
117: Level: advanced
119: .seealso: PetscObjectCompose(), PetscObjectDereference()
120: @*/
121: int PetscObjectReference(PetscObject obj)
122: {
125: obj->refct++;
126: return(0);
127: }
131: /*@C
132: PetscObjectGetReference - Gets the current reference count for
133: any PETSc object.
135: Not Collective
137: Input Parameter:
138: . obj - the PETSc object; this must be cast with (PetscObject), for example,
139: PetscObjectGetReference((PetscObject)mat,&cnt);
141: Output Parameter:
142: . cnt - the reference count
144: Level: advanced
146: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
147: @*/
148: int PetscObjectGetReference(PetscObject obj,int *cnt)
149: {
153: *cnt = obj->refct;
154: return(0);
155: }
159: /*@
160: PetscObjectDereference - Indicates to any PetscObject that it is being
161: referenced by one less PetscObject. This decreases the reference
162: count for that object by one.
164: Collective on PetscObject
166: Input Parameter:
167: . obj - the PETSc object; this must be cast with (PetscObject), for example,
168: PetscObjectDereference((PetscObject)mat);
170: Level: advanced
172: .seealso: PetscObjectCompose(), PetscObjectReference()
173: @*/
174: int PetscObjectDereference(PetscObject obj)
175: {
180: if (obj->bops->destroy) {
181: (*obj->bops->destroy)(obj);
182: } else if (!--obj->refct) {
183: SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
184: }
185: return(0);
186: }
188: /* ----------------------------------------------------------------------- */
189: /*
190: The following routines are the versions private to the PETSc object
191: data structures.
192: */
195: int PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
196: {
198: *comm = obj->comm;
199: return(0);
200: }
204: int PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
205: {
206: int ierr;
207: char *tname;
210: if (ptr) {
211: PetscOListReverseFind(ptr->olist,obj,&tname);
212: if (tname){
213: SETERRQ(1,"An object cannot be composed with an object that was compose with it");
214: }
215: }
216: PetscOListAdd(&obj->olist,name,ptr);
217: return(0);
218: }
222: int PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
223: {
227: PetscOListFind(obj->olist,name,ptr);
228: return(0);
229: }
233: int PetscObjectComposeLanguage_Petsc(PetscObject obj,PetscLanguage lang,void *vob)
234: {
236: if (lang == PETSC_LANGUAGE_CPP) {
237: obj->cpp = vob;
238: } else {
239: SETERRQ(1,"No support for this language yet");
240: }
241: return(0);
242: }
246: int PetscObjectQueryLanguage_Petsc(PetscObject obj,PetscLanguage lang,void **vob)
247: {
249: if (lang == PETSC_LANGUAGE_C) {
250: *vob = (void*)obj;
251: } else if (lang == PETSC_LANGUAGE_CPP) {
252: if (obj->cpp) {
253: *vob = obj->cpp;
254: } else {
255: SETERRQ(1,"No C++ wrapper generated");
256: }
257: } else {
258: SETERRQ(1,"No support for this language yet");
259: }
260: return(0);
261: }
265: int PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
266: {
270: PetscFListAdd(&obj->qlist,name,fname,ptr);
271: return(0);
272: }
276: int PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)(void))
277: {
281: PetscFListFind(obj->comm,obj->qlist,name,ptr);
282: return(0);
283: }
285: /*
286: These are the versions that are usable to any CCA compliant objects
287: */
290: /*@C
291: PetscObjectCompose - Associates another PETSc object with a given PETSc object.
292:
293: Not Collective
295: Input Parameters:
296: + obj - the PETSc object; this must be cast with (PetscObject), for example,
297: PetscObjectCompose((PetscObject)mat,...);
298: . name - name associated with the child object
299: - ptr - the other PETSc object to associate with the PETSc object; this must also be
300: cast with (PetscObject)
302: Level: advanced
304: Notes:
305: The second objects reference count is automatically increased by one when it is
306: composed.
308: Replaces any previous object that had the same name.
310: If ptr is null and name has previously been composed using an object, then that
311: entry is removed from the obj.
313: PetscObjectCompose() can be used with any PETSc object (such as
314: Mat, Vec, KSP, SNES, etc.) or any user-provided object. See
315: PetscObjectContainerCreate() for info on how to create an object from a
316: user-provided pointer that may then be composed with PETSc objects.
317:
318: Concepts: objects^composing
319: Concepts: composing objects
321: .seealso: PetscObjectQuery(), PetscObjectContainerCreate()
322: @*/
323: int PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
324: {
328: (*obj->bops->compose)(obj,name,ptr);
329: return(0);
330: }
334: /*@C
335: PetscObjectQuery - Gets a PETSc object associated with a given object.
336:
337: Not Collective
339: Input Parameters:
340: + obj - the PETSc object
341: Thus must be cast with a (PetscObject), for example,
342: PetscObjectCompose((PetscObject)mat,...);
343: . name - name associated with child object
344: - ptr - the other PETSc object associated with the PETSc object, this must also be
345: cast with (PetscObject)
347: Level: advanced
349: Concepts: objects^composing
350: Concepts: composing objects
351: Concepts: objects^querying
352: Concepts: querying objects
354: .seealso: PetscObjectQuery()
355: @*/
356: int PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
357: {
361: (*obj->bops->query)(obj,name,ptr);
362: return(0);
363: }
367: /*@C
368: PetscObjectQueryLanguage - Returns a language specific interface to the given object
369:
370: Not Collective
372: Input Parameters:
373: + obj - the PETSc object
374: Thus must be cast with a (PetscObject), for example,
375: PetscObjectCompose((PetscObject)mat,...);
376: - lang - one of PETSC_LANGUAGE_C, PETSC_LANGUAGE_F77, PETSC_LANGUAGE_CPP
378: Output Parameter:
379: . ptr - the language specific interface
381: Level: developer
383: .seealso: PetscObjectQuery()
384: @*/
385: int PetscObjectQueryLanguage(PetscObject obj,PetscLanguage lang,void **ptr)
386: {
390: (*obj->bops->querylanguage)(obj,lang,ptr);
391: return(0);
392: }
396: /*@C
397: PetscObjectComposeLanguage - Sets a language specific interface to the given object
398:
399: Not Collective
401: Input Parameters:
402: + obj - the PETSc object
403: Thus must be cast with a (PetscObject), for example,
404: PetscObjectCompose((PetscObject)mat,...);
405: . lang - one of PETSC_LANGUAGE_C, PETSC_LANGUAGE_F77, PETSC_LANGUAGE_CPP
406: - ptr - the language specific interface
408: Level: developer
410: .seealso: PetscObjectQuery()
411: @*/
412: int PetscObjectComposeLanguage(PetscObject obj,PetscLanguage lang,void *ptr)
413: {
417: (*obj->bops->composelanguage)(obj,lang,ptr);
418: return(0);
419: }
424: int PetscObjectComposeFunction(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
425: {
429: (*obj->bops->composefunction)(obj,name,fname,ptr);
430: return(0);
431: }
435: /*@C
436: PetscObjectQueryFunction - Gets a function associated with a given object.
437:
438: Collective on PetscObject
440: Input Parameters:
441: + obj - the PETSc object; this must be cast with (PetscObject), for example,
442: PetscObjectQueryFunction((PetscObject)ksp,...);
443: - name - name associated with the child function
445: Output Parameter:
446: . ptr - function pointer
448: Level: advanced
450: Concepts: objects^composing functions
451: Concepts: composing functions
452: Concepts: functions^querying
453: Concepts: objects^querying
454: Concepts: querying objects
456: .seealso: PetscObjectComposeFunctionDynamic()
457: @*/
458: int PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)(void))
459: {
463: (*obj->bops->queryfunction)(obj,name,ptr);
464: return(0);
465: }
469: /*@C
470: PetscObjectSetParameterDict - Sets a parameter dictionary for an object
472: Input Parameters:
473: + obj - The PetscObject
474: - dict - The ParameterDict
476: Level: intermediate
478: .seealso PetscObjectGetParameterDict()
479: @*/
480: int PetscObjectSetParameterDict(PetscObject obj, ParameterDict dict) {
485: if (obj->dict != PETSC_NULL) {
486: PetscObjectDereference((PetscObject) obj->dict);
487: }
488: if (dict != PETSC_NULL) {
489: PetscObjectReference((PetscObject) dict);
490: }
491: obj->dict = dict;
492: return(0);
493: }
497: /*@C
498: PetscObjectGetParameterDict - Gets the parameter dictionary for an object
500: Input Parameter:
501: . obj - The PetscObject
503: Output Parameter:
504: . dict - The ParameterDict
506: Level: intermediate
508: .seealso PetscObjectSetParameterDict()
509: @*/
510: int PetscObjectGetParameterDict(PetscObject obj, ParameterDict *dict) {
514: *dict = obj->dict;
515: return(0);
516: }
518: struct _p_PetscObjectContainer {
519: PETSCHEADER(int)
520: void *ptr;
521: };
525: /*@C
526: PetscObjectContainerGetPointer - Gets the pointer value contained in the container.
528: Collective on PetscObjectContainer
530: Input Parameter:
531: . obj - the object created with PetscObjectContainerCreate()
533: Output Parameter:
534: . ptr - the pointer value
536: Level: advanced
538: .seealso: PetscObjectContainerCreate(), PetscObjectContainerDestroy(),
539: PetscObjectContainerSetPointer()
540: @*/
541: int PetscObjectContainerGetPointer(PetscObjectContainer obj,void **ptr)
542: {
544: *ptr = obj->ptr;
545: return(0);
546: }
551: /*@C
552: PetscObjectContainerSetPointer - Sets the pointer value contained in the container.
554: Collective on PetscObjectContainer
556: Input Parameters:
557: + obj - the object created with PetscObjectContainerCreate()
558: - ptr - the pointer value
560: Level: advanced
562: .seealso: PetscObjectContainerCreate(), PetscObjectContainerDestroy(),
563: PetscObjectContainerGetPointer()
564: @*/
565: int PetscObjectContainerSetPointer(PetscObjectContainer obj,void *ptr)
566: {
568: obj->ptr = ptr;
569: return(0);
570: }
574: /*@C
575: PetscObjectContainerDestroy - Destroys a PETSc container object.
577: Collective on PetscObjectContainer
579: Input Parameter:
580: . obj - an object that was created with PetscObjectContainerCreate()
582: Level: advanced
584: .seealso: PetscObjectContainerCreate()
585: @*/
586: int PetscObjectContainerDestroy(PetscObjectContainer obj)
587: {
589: if (--obj->refct > 0) return(0);
590: PetscHeaderDestroy(obj);
591: return(0);
592: }
596: /*@C
597: PetscObjectContainerCreate - Creates a PETSc object that has room to hold
598: a single pointer. This allows one to attach any type of data (accessible
599: through a pointer) with the PetscObjectCompose() function to a PetscObject.
600: The data item itself is attached by a call to PetscObjectContainerSetPointer.
602: Collective on MPI_Comm
604: Input Parameters:
605: . comm - MPI communicator that shares the object
607: Output Parameters:
608: . container - the container created
610: Level: advanced
612: .seealso: PetscObjectContainerDestroy(), PetscObjectContainerSetPointer(), PetscObjectContainerSetPointer()
613: @*/
614: int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *container)
615: {
616: PetscObjectContainer contain;
619: PetscHeaderCreate(contain,_p_PetscObjectContainer,int,PETSC_COOKIE,0,"container",comm,PetscObjectContainerDestroy,0);
620: *container = contain;
621: return(0);
622: }