Actual source code: inherit.c

  1: #define PETSC_DLL
  2: /*
  3:      Provides utility routines for manipulating any type of PETSc object.
  4: */
 5:  #include petsc.h
 6:  #include petscsys.h

  8: EXTERN PetscErrorCode PetscObjectGetComm_Petsc(PetscObject,MPI_Comm *);
  9: EXTERN PetscErrorCode PetscObjectCompose_Petsc(PetscObject,const char[],PetscObject);
 10: EXTERN PetscErrorCode PetscObjectQuery_Petsc(PetscObject,const char[],PetscObject *);
 11: EXTERN PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject,const char[],const char[],void (*)(void));
 12: EXTERN PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject,const char[],void (**)(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: PetscErrorCode  PetscHeaderCreate_Private(PetscObject h,PetscCookie cookie,PetscInt type,const char class_name[],MPI_Comm comm,
 21:                                          PetscErrorCode (*des)(PetscObject),PetscErrorCode (*vie)(PetscObject,PetscViewer))
 22: {
 23:   static PetscInt idcnt = 1;
 24:   PetscErrorCode  ierr;

 27:   h->cookie                 = cookie;
 28:   h->type                   = type;
 29:   h->class_name             = (char*)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:   PetscCommDuplicate(comm,&h->comm,&h->tag);
 45:   return(0);
 46: }


 53: /*
 54:     PetscHeaderDestroy_Private - Destroys a base PETSc object header. Called by 
 55:     the macro PetscHeaderDestroy().
 56: */
 57: PetscErrorCode  PetscHeaderDestroy_Private(PetscObject h)
 58: {

 62:   if (PetscMemoryCollectMaximumUsage) {
 63:     PetscLogDouble usage;
 64:     PetscMemoryGetCurrentUsage(&usage);
 65:     if (usage > PetscMemoryMaximumUsage) PetscMemoryMaximumUsage = usage;
 66:   }
 67:   PetscCommDestroy(&h->comm);
 68:   PetscFree(h->bops);
 69:   PetscOListDestroy(h->olist);
 70:   PetscFListDestroy(&h->qlist);
 71:   PetscStrfree(h->type_name);
 72:   PetscStrfree(h->name);
 73:   h->cookie = PETSCFREEDHEADER;
 74:   PetscStrfree(h->prefix);
 75:   PetscFree(h->fortran_func_pointers);
 76:   PetscFree(h->intcomposeddata);
 77:   PetscFree(h->intcomposedstate);
 78:   PetscFree(h->realcomposeddata);
 79:   PetscFree(h->realcomposedstate);
 80:   PetscFree(h->scalarcomposeddata);
 81:   PetscFree(h->scalarcomposedstate);
 82:   return(0);
 83: }

 87: /*@C
 88:    PetscObjectReference - Indicates to any PetscObject that it is being
 89:    referenced by another PetscObject. This increases the reference
 90:    count for that object by one.

 92:    Collective on PetscObject

 94:    Input Parameter:
 95: .  obj - the PETSc object. This must be cast with (PetscObject), for example, 
 96:          PetscObjectReference((PetscObject)mat);

 98:    Level: advanced

100: .seealso: PetscObjectCompose(), PetscObjectDereference()
101: @*/
102: PetscErrorCode  PetscObjectReference(PetscObject obj)
103: {
106:   obj->refct++;
107:   return(0);
108: }

112: /*@C
113:    PetscObjectGetReference - Gets the current reference count for 
114:    any PETSc object.

116:    Not Collective

118:    Input Parameter:
119: .  obj - the PETSc object; this must be cast with (PetscObject), for example, 
120:          PetscObjectGetReference((PetscObject)mat,&cnt);

122:    Output Parameter:
123: .  cnt - the reference count

125:    Level: advanced

127: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
128: @*/
129: PetscErrorCode  PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
130: {
134:   *cnt = obj->refct;
135:   return(0);
136: }

140: /*@
141:    PetscObjectDereference - Indicates to any PetscObject that it is being
142:    referenced by one less PetscObject. This decreases the reference
143:    count for that object by one.

145:    Collective on PetscObject

147:    Input Parameter:
148: .  obj - the PETSc object; this must be cast with (PetscObject), for example, 
149:          PetscObjectDereference((PetscObject)mat);

151:    Level: advanced

153: .seealso: PetscObjectCompose(), PetscObjectReference()
154: @*/
155: PetscErrorCode  PetscObjectDereference(PetscObject obj)
156: {

161:   if (obj->bops->destroy) {
162:     (*obj->bops->destroy)(obj);
163:   } else if (!--obj->refct) {
164:     SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
165:   }
166:   return(0);
167: }

169: /* ----------------------------------------------------------------------- */
170: /*
171:      The following routines are the versions private to the PETSc object
172:      data structures.
173: */
176: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
177: {
179:   *comm = obj->comm;
180:   return(0);
181: }

185: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
186: {
188:   char           *tname;

191:   if (ptr) {
192:     PetscOListReverseFind(ptr->olist,obj,&tname);
193:     if (tname){
194:       SETERRQ(PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was compose with it");
195:     }
196:   }
197:   PetscOListAdd(&obj->olist,name,ptr);
198:   return(0);
199: }

203: PetscErrorCode PetscObjectQuery_Petsc(PetscObject obj,const char name[],PetscObject *ptr)
204: {

208:   PetscOListFind(obj->olist,name,ptr);
209:   return(0);
210: }

214: PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
215: {

219:   PetscFListAdd(&obj->qlist,name,fname,ptr);
220:   return(0);
221: }

225: PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject obj,const char name[],void (**ptr)(void))
226: {

230:   PetscFListFind(obj->qlist,obj->comm,name,ptr);
231:   return(0);
232: }

234: /*
235:         These are the versions that are usable to any CCA compliant objects
236: */
239: /*@C
240:    PetscObjectCompose - Associates another PETSc object with a given PETSc object. 
241:                        
242:    Not Collective

244:    Input Parameters:
245: +  obj - the PETSc object; this must be cast with (PetscObject), for example, 
246:          PetscObjectCompose((PetscObject)mat,...);
247: .  name - name associated with the child object 
248: -  ptr - the other PETSc object to associate with the PETSc object; this must also be 
249:          cast with (PetscObject)

251:    Level: advanced

253:    Notes:
254:    The second objects reference count is automatically increased by one when it is
255:    composed.

257:    Replaces any previous object that had the same name.

259:    If ptr is null and name has previously been composed using an object, then that
260:    entry is removed from the obj.

262:    PetscObjectCompose() can be used with any PETSc object (such as
263:    Mat, Vec, KSP, SNES, etc.) or any user-provided object.  See 
264:    PetscContainerCreate() for info on how to create an object from a 
265:    user-provided pointer that may then be composed with PETSc objects.
266:    
267:    Concepts: objects^composing
268:    Concepts: composing objects

270: .seealso: PetscObjectQuery(), PetscContainerCreate()
271: @*/
272: PetscErrorCode  PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
273: {

280:   (*obj->bops->compose)(obj,name,ptr);
281:   return(0);
282: }

286: /*@C
287:    PetscObjectQuery  - Gets a PETSc object associated with a given object.
288:                        
289:    Not Collective

291:    Input Parameters:
292: +  obj - the PETSc object
293:          Thus must be cast with a (PetscObject), for example, 
294:          PetscObjectCompose((PetscObject)mat,...);
295: .  name - name associated with child object 
296: -  ptr - the other PETSc object associated with the PETSc object, this must also be 
297:          cast with (PetscObject)

299:    Level: advanced

301:    Concepts: objects^composing
302:    Concepts: composing objects
303:    Concepts: objects^querying
304:    Concepts: querying objects

306: .seealso: PetscObjectQuery()
307: @*/
308: PetscErrorCode  PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
309: {

316:   (*obj->bops->query)(obj,name,ptr);
317:   return(0);
318: }

322: PetscErrorCode  PetscObjectComposeFunction(PetscObject obj,const char name[],const char fname[],void (*ptr)(void))
323: {

330:   (*obj->bops->composefunction)(obj,name,fname,ptr);
331:   return(0);
332: }

336: /*@C
337:    PetscObjectQueryFunction - Gets a function associated with a given object.
338:                        
339:    Collective on PetscObject

341:    Input Parameters:
342: +  obj - the PETSc object; this must be cast with (PetscObject), for example, 
343:          PetscObjectQueryFunction((PetscObject)ksp,...);
344: -  name - name associated with the child function

346:    Output Parameter:
347: .  ptr - function pointer

349:    Level: advanced

351:    Concepts: objects^composing functions
352:    Concepts: composing functions
353:    Concepts: functions^querying
354:    Concepts: objects^querying
355:    Concepts: querying objects

357: .seealso: PetscObjectComposeFunctionDynamic()
358: @*/
359: PetscErrorCode  PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)(void))
360: {

366:   (*obj->bops->queryfunction)(obj,name,ptr);
367:   return(0);
368: }

370: struct _p_PetscContainer {
371:   PETSCHEADER(int);
372:   void   *ptr;
373:   PetscErrorCode (*userdestroy)(void*);
374: };

378: /*@C
379:    PetscContainerGetPointer - Gets the pointer value contained in the container.

381:    Collective on PetscContainer

383:    Input Parameter:
384: .  obj - the object created with PetscContainerCreate()

386:    Output Parameter:
387: .  ptr - the pointer value

389:    Level: advanced

391: .seealso: PetscContainerCreate(), PetscContainerDestroy(), 
392:           PetscContainerSetPointer()
393: @*/
394: PetscErrorCode  PetscContainerGetPointer(PetscContainer obj,void **ptr)
395: {
399:   *ptr = obj->ptr;
400:   return(0);
401: }


406: /*@C
407:    PetscContainerSetPointer - Sets the pointer value contained in the container.

409:    Collective on PetscContainer

411:    Input Parameters:
412: +  obj - the object created with PetscContainerCreate()
413: -  ptr - the pointer value

415:    Level: advanced

417: .seealso: PetscContainerCreate(), PetscContainerDestroy(), 
418:           PetscContainerGetPointer()
419: @*/
420: PetscErrorCode  PetscContainerSetPointer(PetscContainer obj,void *ptr)
421: {
425:   obj->ptr = ptr;
426:   return(0);
427: }

431: /*@C
432:    PetscContainerDestroy - Destroys a PETSc container object.

434:    Collective on PetscContainer

436:    Input Parameter:
437: .  obj - an object that was created with PetscContainerCreate()

439:    Level: advanced

441: .seealso: PetscContainerCreate()
442: @*/
443: PetscErrorCode  PetscContainerDestroy(PetscContainer obj)
444: {
448:   if (--((PetscObject)obj)->refct > 0) return(0);
449:   if (obj->userdestroy) (*obj->userdestroy)(obj->ptr);
450:   PetscHeaderDestroy(obj);
451:   return(0);
452: }

456: /*@C
457:    PetscContainerSetUserDestroy - Sets name of the user destroy function.

459:    Collective on PetscContainer

461:    Input Parameter:
462: +  obj - an object that was created with PetscContainerCreate()
463: -  des - name of the user destroy function

465:    Level: advanced

467: .seealso: PetscContainerDestroy()
468: @*/
469: PetscErrorCode  PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
470: {
473:   obj->userdestroy = des;
474:   return(0);
475: }

477: PetscCookie  PETSC_CONTAINER_COOKIE = 0;

481: /*@C
482:    PetscContainerCreate - Creates a PETSc object that has room to hold
483:    a single pointer. This allows one to attach any type of data (accessible
484:    through a pointer) with the PetscObjectCompose() function to a PetscObject.
485:    The data item itself is attached by a call to PetscContainerSetPointer.

487:    Collective on MPI_Comm

489:    Input Parameters:
490: .  comm - MPI communicator that shares the object

492:    Output Parameters:
493: .  container - the container created

495:    Level: advanced

497: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer()
498: @*/
499: PetscErrorCode  PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
500: {
502:   PetscContainer contain;

506:   if (!PETSC_CONTAINER_COOKIE) {
507:     PetscLogClassRegister(&PETSC_CONTAINER_COOKIE, "Container");
508:   }
509:   PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_COOKIE,0,"PetscContainer",comm,PetscContainerDestroy,0);
510:   *container = contain;
511:   return(0);
512: }

516: /*@
517:    PetscObjectSetFromOptions - Sets generic parameters from user options.

519:    Collective on obj

521:    Input Parameter:
522: .  obj - the PetscObjcet

524:    Options Database Keys:

526:    Notes:
527:    We have no generic options at present, so this does nothing

529:    Level: beginner

531: .keywords: set, options, database
532: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
533: @*/
534: PetscErrorCode  PetscObjectSetFromOptions(PetscObject obj)
535: {
538:   return(0);
539: }

543: /*@
544:    PetscObjectSetUp - Sets up the internal data structures for the later use.

546:    Collective on PetscObject

548:    Input Parameters:
549: .  obj - the PetscObject

551:    Notes:
552:    This does nothing at present.

554:    Level: advanced

556: .keywords: setup
557: .seealso: PetscObjectDestroy()
558: @*/
559: PetscErrorCode  PetscObjectSetUp(PetscObject obj)
560: {
563:   return(0);
564: }