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: }