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:   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:   PetscFree(h->fortran_func_pointers);
 77:   PetscFree(h->intcomposeddata);
 78:   PetscFree(h->intcomposedstate);
 79:   PetscFree(h->realcomposeddata);
 80:   PetscFree(h->realcomposedstate);
 81:   PetscFree(h->scalarcomposeddata);
 82:   PetscFree(h->scalarcomposedstate);
 83:   return(0);
 84: }

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

 93:    Collective on PetscObject

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

 99:    Level: advanced

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

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

117:    Not Collective

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

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

126:    Level: advanced

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

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

146:    Collective on PetscObject

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

152:    Level: advanced

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

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

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

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

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

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

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

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

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

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

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

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

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

252:    Level: advanced

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

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

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

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

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

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

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

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

300:    Level: advanced

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

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

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

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

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

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

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

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

350:    Level: advanced

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

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

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

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

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

382:    Collective on PetscContainer

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

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

390:    Level: advanced

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


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

410:    Collective on PetscContainer

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

416:    Level: advanced

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

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

435:    Collective on PetscContainer

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

440:    Level: advanced

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

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

460:    Collective on PetscContainer

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

466:    Level: advanced

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

478: PetscCookie  PETSC_CONTAINER_COOKIE = 0;

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

488:    Collective on MPI_Comm

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

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

496:    Level: advanced

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

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

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

520:    Collective on obj

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

525:    Options Database Keys:

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

530:    Level: beginner

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

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

547:    Collective on PetscObject

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

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

555:    Level: advanced

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