Actual source code: inherit.c

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

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

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


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

 61:   if (PetscMemoryCollectMaximumUsage) {
 62:     PetscLogDouble usage;
 63:     PetscMemoryGetCurrentUsage(&usage);
 64:     if (usage > PetscMemoryMaximumUsage) PetscMemoryMaximumUsage = usage;
 65:   }
 66:   /* first destroy things that could execute arbitrary code */
 67:   if (h->python_destroy) {
 68:     void           *python_context          = h->python_context;
 69:     PetscErrorCode (*python_destroy)(void*) = h->python_destroy;
 70:     h->python_context = 0;
 71:     h->python_destroy = 0;
 72:     (*python_destroy)(python_context);
 73:   }
 74:   PetscOListDestroy(h->olist);
 75:   PetscCommDestroy(&h->comm);
 76:   /* next destroy other things */
 77:   h->cookie = PETSCFREEDHEADER;
 78:   PetscFree(h->bops);
 79:   PetscFListDestroy(&h->qlist);
 80:   PetscStrfree(h->type_name);
 81:   PetscStrfree(h->name);
 82:   PetscStrfree(h->prefix);
 83:   PetscFree(h->fortran_func_pointers);
 84:   PetscFree(h->intcomposeddata);
 85:   PetscFree(h->intcomposedstate);
 86:   PetscFree(h->realcomposeddata);
 87:   PetscFree(h->realcomposedstate);
 88:   PetscFree(h->scalarcomposeddata);
 89:   PetscFree(h->scalarcomposedstate);
 90:   return(0);
 91: }

 95: /*@C
 96:    PetscObjectReference - Indicates to any PetscObject that it is being
 97:    referenced by another PetscObject. This increases the reference
 98:    count for that object by one.

100:    Collective on PetscObject

102:    Input Parameter:
103: .  obj - the PETSc object. This must be cast with (PetscObject), for example, 
104:          PetscObjectReference((PetscObject)mat);

106:    Level: advanced

108: .seealso: PetscObjectCompose(), PetscObjectDereference()
109: @*/
110: PetscErrorCode  PetscObjectReference(PetscObject obj)
111: {
114:   obj->refct++;
115:   return(0);
116: }

120: /*@C
121:    PetscObjectGetReference - Gets the current reference count for 
122:    any PETSc object.

124:    Not Collective

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

130:    Output Parameter:
131: .  cnt - the reference count

133:    Level: advanced

135: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
136: @*/
137: PetscErrorCode  PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
138: {
142:   *cnt = obj->refct;
143:   return(0);
144: }

148: /*@
149:    PetscObjectDereference - Indicates to any PetscObject that it is being
150:    referenced by one less PetscObject. This decreases the reference
151:    count for that object by one.

153:    Collective on PetscObject

155:    Input Parameter:
156: .  obj - the PETSc object; this must be cast with (PetscObject), for example, 
157:          PetscObjectDereference((PetscObject)mat);

159:    Level: advanced

161: .seealso: PetscObjectCompose(), PetscObjectReference()
162: @*/
163: PetscErrorCode  PetscObjectDereference(PetscObject obj)
164: {

169:   if (obj->bops->destroy) {
170:     (*obj->bops->destroy)(obj);
171:   } else if (!--obj->refct) {
172:     SETERRQ(PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
173:   }
174:   return(0);
175: }

177: /* ----------------------------------------------------------------------- */
178: /*
179:      The following routines are the versions private to the PETSc object
180:      data structures.
181: */
184: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
185: {
187:   *comm = obj->comm;
188:   return(0);
189: }

193: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
194: {
196:   char           *tname;

199:   if (ptr) {
200:     PetscOListReverseFind(ptr->olist,obj,&tname);
201:     if (tname){
202:       SETERRQ(PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was compose with it");
203:     }
204:   }
205:   PetscOListAdd(&obj->olist,name,ptr);
206:   return(0);
207: }

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

216:   PetscOListFind(obj->olist,name,ptr);
217:   return(0);
218: }

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

227:   PetscFListAdd(&obj->qlist,name,fname,ptr);
228:   return(0);
229: }

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

238:   PetscFListFind(obj->qlist,obj->comm,name,ptr);
239:   return(0);
240: }

242: /*
243:         These are the versions that are usable to any CCA compliant objects
244: */
247: /*@C
248:    PetscObjectCompose - Associates another PETSc object with a given PETSc object. 
249:                        
250:    Not Collective

252:    Input Parameters:
253: +  obj - the PETSc object; this must be cast with (PetscObject), for example, 
254:          PetscObjectCompose((PetscObject)mat,...);
255: .  name - name associated with the child object 
256: -  ptr - the other PETSc object to associate with the PETSc object; this must also be 
257:          cast with (PetscObject)

259:    Level: advanced

261:    Notes:
262:    The second objects reference count is automatically increased by one when it is
263:    composed.

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

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

270:    PetscObjectCompose() can be used with any PETSc object (such as
271:    Mat, Vec, KSP, SNES, etc.) or any user-provided object.  See 
272:    PetscContainerCreate() for info on how to create an object from a 
273:    user-provided pointer that may then be composed with PETSc objects.
274:    
275:    Concepts: objects^composing
276:    Concepts: composing objects

278: .seealso: PetscObjectQuery(), PetscContainerCreate()
279: @*/
280: PetscErrorCode  PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
281: {

288:   (*obj->bops->compose)(obj,name,ptr);
289:   return(0);
290: }



296: /*@C
297:    PetscObjectQuery  - Gets a PETSc object associated with a given object.
298:                        
299:    Not Collective

301:    Input Parameters:
302: +  obj - the PETSc object
303:          Thus must be cast with a (PetscObject), for example, 
304:          PetscObjectCompose((PetscObject)mat,...);
305: .  name - name associated with child object 
306: -  ptr - the other PETSc object associated with the PETSc object, this must also be 
307:          cast with (PetscObject)

309:    Level: advanced

311:    Concepts: objects^composing
312:    Concepts: composing objects
313:    Concepts: objects^querying
314:    Concepts: querying objects

316: .seealso: PetscObjectQuery()
317: @*/
318: PetscErrorCode  PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
319: {

326:   (*obj->bops->query)(obj,name,ptr);
327:   return(0);
328: }

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

340:   (*obj->bops->composefunction)(obj,name,fname,ptr);
341:   return(0);
342: }

346: /*@C
347:    PetscObjectQueryFunction - Gets a function associated with a given object.
348:                        
349:    Collective on PetscObject

351:    Input Parameters:
352: +  obj - the PETSc object; this must be cast with (PetscObject), for example, 
353:          PetscObjectQueryFunction((PetscObject)ksp,...);
354: -  name - name associated with the child function

356:    Output Parameter:
357: .  ptr - function pointer

359:    Level: advanced

361:    Concepts: objects^composing functions
362:    Concepts: composing functions
363:    Concepts: functions^querying
364:    Concepts: objects^querying
365:    Concepts: querying objects

367: .seealso: PetscObjectComposeFunctionDynamic()
368: @*/
369: PetscErrorCode  PetscObjectQueryFunction(PetscObject obj,const char name[],void (**ptr)(void))
370: {

376:   (*obj->bops->queryfunction)(obj,name,ptr);
377:   return(0);
378: }

380: struct _p_PetscContainer {
381:   PETSCHEADER(int);
382:   void   *ptr;
383:   PetscErrorCode (*userdestroy)(void*);
384: };

388: /*@C
389:    PetscContainerGetPointer - Gets the pointer value contained in the container.

391:    Collective on PetscContainer

393:    Input Parameter:
394: .  obj - the object created with PetscContainerCreate()

396:    Output Parameter:
397: .  ptr - the pointer value

399:    Level: advanced

401: .seealso: PetscContainerCreate(), PetscContainerDestroy(), 
402:           PetscContainerSetPointer()
403: @*/
404: PetscErrorCode  PetscContainerGetPointer(PetscContainer obj,void **ptr)
405: {
409:   *ptr = obj->ptr;
410:   return(0);
411: }


416: /*@C
417:    PetscContainerSetPointer - Sets the pointer value contained in the container.

419:    Collective on PetscContainer

421:    Input Parameters:
422: +  obj - the object created with PetscContainerCreate()
423: -  ptr - the pointer value

425:    Level: advanced

427: .seealso: PetscContainerCreate(), PetscContainerDestroy(), 
428:           PetscContainerGetPointer()
429: @*/
430: PetscErrorCode  PetscContainerSetPointer(PetscContainer obj,void *ptr)
431: {
435:   obj->ptr = ptr;
436:   return(0);
437: }

441: /*@C
442:    PetscContainerDestroy - Destroys a PETSc container object.

444:    Collective on PetscContainer

446:    Input Parameter:
447: .  obj - an object that was created with PetscContainerCreate()

449:    Level: advanced

451: .seealso: PetscContainerCreate()
452: @*/
453: PetscErrorCode  PetscContainerDestroy(PetscContainer obj)
454: {
458:   if (--((PetscObject)obj)->refct > 0) return(0);
459:   if (obj->userdestroy) (*obj->userdestroy)(obj->ptr);
460:   PetscHeaderDestroy(obj);
461:   return(0);
462: }

466: /*@C
467:    PetscContainerSetUserDestroy - Sets name of the user destroy function.

469:    Collective on PetscContainer

471:    Input Parameter:
472: +  obj - an object that was created with PetscContainerCreate()
473: -  des - name of the user destroy function

475:    Level: advanced

477: .seealso: PetscContainerDestroy()
478: @*/
479: PetscErrorCode  PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
480: {
483:   obj->userdestroy = des;
484:   return(0);
485: }

487: PetscCookie  PETSC_CONTAINER_COOKIE;

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

497:    Collective on MPI_Comm

499:    Input Parameters:
500: .  comm - MPI communicator that shares the object

502:    Output Parameters:
503: .  container - the container created

505:    Level: advanced

507: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer()
508: @*/
509: PetscErrorCode  PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
510: {
512:   PetscContainer contain;

516:   PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_COOKIE,0,"PetscContainer",comm,PetscContainerDestroy,0);
517:   *container = contain;
518:   return(0);
519: }

523: /*@
524:    PetscObjectSetFromOptions - Sets generic parameters from user options.

526:    Collective on obj

528:    Input Parameter:
529: .  obj - the PetscObjcet

531:    Options Database Keys:

533:    Notes:
534:    We have no generic options at present, so this does nothing

536:    Level: beginner

538: .keywords: set, options, database
539: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
540: @*/
541: PetscErrorCode  PetscObjectSetFromOptions(PetscObject obj)
542: {
545:   return(0);
546: }

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

553:    Collective on PetscObject

555:    Input Parameters:
556: .  obj - the PetscObject

558:    Notes:
559:    This does nothing at present.

561:    Level: advanced

563: .keywords: setup
564: .seealso: PetscObjectDestroy()
565: @*/
566: PetscErrorCode  PetscObjectSetUp(PetscObject obj)
567: {
570:   return(0);
571: }