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*/