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:   /* first destroy things that could execute arbitrary code */
 68:   if (h->python_destroy) {
 69:     void           *python_context          = h->python_context;
 70:     PetscErrorCode (*python_destroy)(void*) = h->python_destroy;
 71:     h->python_context = 0;
 72:     h->python_destroy = 0;
 73:     (*python_destroy)(python_context);
 74:   }
 75:   PetscOListDestroy(h->olist);
 76:   PetscCommDestroy(&h->comm);
 77:   /* next destroy other things */
 78:   h->cookie = PETSCFREEDHEADER;
 79:   PetscFree(h->bops);
 80:   PetscFListDestroy(&h->qlist);
 81:   PetscStrfree(h->type_name);
 82:   PetscStrfree(h->name);
 83:   PetscStrfree(h->prefix);
 84:   PetscFree(h->fortran_func_pointers);
 85:   PetscFree(h->intcomposeddata);
 86:   PetscFree(h->intcomposedstate);
 87:   PetscFree(h->realcomposeddata);
 88:   PetscFree(h->realcomposedstate);
 89:   PetscFree(h->scalarcomposeddata);
 90:   PetscFree(h->scalarcomposedstate);
 91:   return(0);
 92: }

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

101:    Collective on PetscObject

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

107:    Level: advanced

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

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

125:    Not Collective

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

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

134:    Level: advanced

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

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

154:    Collective on PetscObject

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

160:    Level: advanced

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

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

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

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

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

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

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

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

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

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

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

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

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

260:    Level: advanced

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

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

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

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

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

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

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

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

308:    Level: advanced

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

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

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

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

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

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

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

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

358:    Level: advanced

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

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

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

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

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

390:    Collective on PetscContainer

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

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

398:    Level: advanced

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


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

418:    Collective on PetscContainer

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

424:    Level: advanced

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

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

443:    Collective on PetscContainer

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

448:    Level: advanced

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

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

468:    Collective on PetscContainer

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

474:    Level: advanced

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

486: PetscCookie  PETSC_CONTAINER_COOKIE;

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

496:    Collective on MPI_Comm

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

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

504:    Level: advanced

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

515:   if (!PETSC_CONTAINER_COOKIE) {
516:     PetscCookieRegister("Container",&PETSC_CONTAINER_COOKIE);
517:   }
518:   PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_COOKIE,0,"PetscContainer",comm,PetscContainerDestroy,0);
519:   *container = contain;
520:   return(0);
521: }

525: /*@
526:    PetscObjectSetFromOptions - Sets generic parameters from user options.

528:    Collective on obj

530:    Input Parameter:
531: .  obj - the PetscObjcet

533:    Options Database Keys:

535:    Notes:
536:    We have no generic options at present, so this does nothing

538:    Level: beginner

540: .keywords: set, options, database
541: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
542: @*/
543: PetscErrorCode  PetscObjectSetFromOptions(PetscObject obj)
544: {
547:   return(0);
548: }

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

555:    Collective on PetscObject

557:    Input Parameters:
558: .  obj - the PetscObject

560:    Notes:
561:    This does nothing at present.

563:    Level: advanced

565: .keywords: setup
566: .seealso: PetscObjectDestroy()
567: @*/
568: PetscErrorCode  PetscObjectSetUp(PetscObject obj)
569: {
572:   return(0);
573: }