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