Actual source code: inherit.c

petsc-3.6.1 2015-08-06
Report Typos and Errors
  2: /*
  3:      Provides utility routines for manipulating any type of PETSc object.
  4: */
  5: #include <petsc/private/petscimpl.h>  /*I   "petscsys.h"    I*/
  6: #include <petscviewer.h>

  8: #if defined(PETSC_USE_LOG)
  9: PetscObject *PetscObjects      = 0;
 10: PetscInt    PetscObjectsCounts = 0, PetscObjectsMaxCounts = 0;
 11: PetscBool   PetscObjectsLog    = PETSC_FALSE;
 12: #endif

 14: extern PetscErrorCode PetscObjectGetComm_Petsc(PetscObject,MPI_Comm*);
 15: extern PetscErrorCode PetscObjectCompose_Petsc(PetscObject,const char[],PetscObject);
 16: extern PetscErrorCode PetscObjectQuery_Petsc(PetscObject,const char[],PetscObject*);
 17: extern PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject,const char[],void (*)(void));
 18: extern PetscErrorCode PetscObjectQueryFunction_Petsc(PetscObject,const char[],void (**)(void));

 22: /*
 23:    PetscHeaderCreate_Private - Creates a base PETSc object header and fills
 24:    in the default values.  Called by the macro PetscHeaderCreate().
 25: */
 26: PetscErrorCode  PetscHeaderCreate_Private(PetscObject h,PetscClassId classid,const char class_name[],const char descr[],const char mansec[],
 27:                                           MPI_Comm comm,PetscObjectDestroyFunction destroy,PetscObjectViewFunction view)
 28: {
 29:   static PetscInt idcnt = 1;
 30:   PetscErrorCode  ierr;
 31: #if defined(PETSC_USE_LOG)
 32:   PetscObject     *newPetscObjects;
 33:   PetscInt         newPetscObjectsMaxCounts,i;
 34: #endif

 37:   h->classid               = classid;
 38:   h->type                  = 0;
 39:   h->class_name            = (char*)class_name;
 40:   h->description           = (char*)descr;
 41:   h->mansec                = (char*)mansec;
 42:   h->prefix                = 0;
 43:   h->refct                 = 1;
 44: #if defined(PETSC_HAVE_SAWS)
 45:   h->amsmem                = PETSC_FALSE;
 46: #endif
 47:   h->id                    = idcnt++;
 48:   h->parentid              = 0;
 49:   h->qlist                 = 0;
 50:   h->olist                 = 0;
 51:   h->precision             = (PetscPrecision) sizeof(PetscReal);
 52:   h->bops->destroy         = destroy;
 53:   h->bops->view            = view;
 54:   h->bops->getcomm         = PetscObjectGetComm_Petsc;
 55:   h->bops->compose         = PetscObjectCompose_Petsc;
 56:   h->bops->query           = PetscObjectQuery_Petsc;
 57:   h->bops->composefunction = PetscObjectComposeFunction_Petsc;
 58:   h->bops->queryfunction   = PetscObjectQueryFunction_Petsc;

 60:   PetscCommDuplicate(comm,&h->comm,&h->tag);

 62: #if defined(PETSC_USE_LOG)
 63:   /* Keep a record of object created */
 64:   if (PetscObjectsLog) {
 65:     PetscObjectsCounts++;
 66:     for (i=0; i<PetscObjectsMaxCounts; i++) {
 67:       if (!PetscObjects[i]) {
 68:         PetscObjects[i] = h;
 69:         return(0);
 70:       }
 71:     }
 72:     /* Need to increase the space for storing PETSc objects */
 73:     if (!PetscObjectsMaxCounts) newPetscObjectsMaxCounts = 100;
 74:     else                        newPetscObjectsMaxCounts = 2*PetscObjectsMaxCounts;
 75:     PetscMalloc1(newPetscObjectsMaxCounts,&newPetscObjects);
 76:     PetscMemcpy(newPetscObjects,PetscObjects,PetscObjectsMaxCounts*sizeof(PetscObject));
 77:     PetscMemzero(newPetscObjects+PetscObjectsMaxCounts,(newPetscObjectsMaxCounts - PetscObjectsMaxCounts)*sizeof(PetscObject));
 78:     PetscFree(PetscObjects);

 80:     PetscObjects                        = newPetscObjects;
 81:     PetscObjects[PetscObjectsMaxCounts] = h;
 82:     PetscObjectsMaxCounts               = newPetscObjectsMaxCounts;
 83:   }
 84: #endif
 85:   return(0);
 86: }

 88: extern PetscBool      PetscMemoryCollectMaximumUsage;
 89: extern PetscLogDouble PetscMemoryMaximumUsage;

 93: /*
 94:     PetscHeaderDestroy_Private - Destroys a base PETSc object header. Called by
 95:     the macro PetscHeaderDestroy().
 96: */
 97: PetscErrorCode  PetscHeaderDestroy_Private(PetscObject h)
 98: {

103:   PetscLogObjectDestroy(h);
104:   PetscComposedQuantitiesDestroy(h);
105:   if (PetscMemoryCollectMaximumUsage) {
106:     PetscLogDouble usage;
107:     PetscMemoryGetCurrentUsage(&usage);
108:     if (usage > PetscMemoryMaximumUsage) PetscMemoryMaximumUsage = usage;
109:   }
110:   /* first destroy things that could execute arbitrary code */
111:   if (h->python_destroy) {
112:     void           *python_context = h->python_context;
113:     PetscErrorCode (*python_destroy)(void*) = h->python_destroy;
114:     h->python_context = 0;
115:     h->python_destroy = 0;

117:     (*python_destroy)(python_context);
118:   }
119:   PetscObjectDestroyOptionsHandlers(h);
120:   PetscObjectListDestroy(&h->olist);
121:   PetscCommDestroy(&h->comm);
122:   /* next destroy other things */
123:   h->classid = PETSCFREEDHEADER;

125:   PetscFunctionListDestroy(&h->qlist);
126:   PetscFree(h->type_name);
127:   PetscFree(h->name);
128:   PetscFree(h->prefix);
129:   PetscFree(h->fortran_func_pointers);
130:   PetscFree(h->fortrancallback[PETSC_FORTRAN_CALLBACK_CLASS]);
131:   PetscFree(h->fortrancallback[PETSC_FORTRAN_CALLBACK_SUBTYPE]);

133: #if defined(PETSC_USE_LOG)
134:   if (PetscObjectsLog) {
135:     PetscInt i;
136:     /* Record object removal from list of all objects */
137:     for (i=0; i<PetscObjectsMaxCounts; i++) {
138:       if (PetscObjects[i] == h) {
139:         PetscObjects[i] = 0;
140:         PetscObjectsCounts--;
141:         break;
142:       }
143:     }
144:     if (!PetscObjectsCounts) {
145:       PetscFree(PetscObjects);
146:       PetscObjectsMaxCounts = 0;
147:     }
148:   }
149: #endif
150:   return(0);
151: }

155: /*@C
156:    PetscObjectCopyFortranFunctionPointers - Copy function pointers to another object

158:    Logically Collective on PetscObject

160:    Input Parameter:
161: +  src - source object
162: -  dest - destination object

164:    Level: developer

166:    Note:
167:    Both objects must have the same class.
168: @*/
169: PetscErrorCode PetscObjectCopyFortranFunctionPointers(PetscObject src,PetscObject dest)
170: {
172:   PetscInt       cbtype,numcb[PETSC_FORTRAN_CALLBACK_MAXTYPE];

177:   if (src->classid != dest->classid) SETERRQ(src->comm,PETSC_ERR_ARG_INCOMP,"Objects must be of the same class");

179:   PetscFree(dest->fortran_func_pointers);
180:   PetscMalloc(src->num_fortran_func_pointers*sizeof(void(*)(void)),&dest->fortran_func_pointers);
181:   PetscMemcpy(dest->fortran_func_pointers,src->fortran_func_pointers,src->num_fortran_func_pointers*sizeof(void(*)(void)));

183:   dest->num_fortran_func_pointers = src->num_fortran_func_pointers;

185:   PetscFortranCallbackGetSizes(src->classid,&numcb[PETSC_FORTRAN_CALLBACK_CLASS],&numcb[PETSC_FORTRAN_CALLBACK_SUBTYPE]);
186:   for (cbtype=PETSC_FORTRAN_CALLBACK_CLASS; cbtype<PETSC_FORTRAN_CALLBACK_MAXTYPE; cbtype++) {
187:     PetscFree(dest->fortrancallback[cbtype]);
188:     PetscCalloc1(numcb[cbtype],&dest->fortrancallback[cbtype]);
189:     PetscMemcpy(dest->fortrancallback[cbtype],src->fortrancallback[cbtype],src->num_fortrancallback[cbtype]*sizeof(PetscFortranCallback));
190:   }
191:   return(0);
192: }

196: /*@C
197:    PetscObjectSetFortranCallback - set fortran callback function pointer and context

199:    Logically Collective

201:    Input Arguments:
202: +  obj - object on which to set callback
203: .  cbtype - callback type (class or subtype)
204: .  cid - address of callback Id, updated if not yet initialized (zero)
205: .  func - Fortran function
206: -  ctx - Fortran context

208:    Level: developer

210: .seealso: PetscObjectGetFortranCallback()
211: @*/
212: PetscErrorCode PetscObjectSetFortranCallback(PetscObject obj,PetscFortranCallbackType cbtype,PetscFortranCallbackId *cid,void (*func)(void),void *ctx)
213: {
215:   const char     *subtype = NULL;

219:   if (cbtype == PETSC_FORTRAN_CALLBACK_SUBTYPE) subtype = obj->type_name;
220:   if (!*cid) {PetscFortranCallbackRegister(obj->classid,subtype,cid);}
221:   if (*cid >= PETSC_SMALLEST_FORTRAN_CALLBACK+obj->num_fortrancallback[cbtype]) {
222:     PetscInt             oldnum = obj->num_fortrancallback[cbtype],newnum = PetscMax(1,2*oldnum);
223:     PetscFortranCallback *callback;
224:     PetscMalloc1(newnum,&callback);
225:     PetscMemcpy(callback,obj->fortrancallback[cbtype],oldnum*sizeof(*obj->fortrancallback[cbtype]));
226:     PetscFree(obj->fortrancallback[cbtype]);

228:     obj->fortrancallback[cbtype] = callback;
229:     obj->num_fortrancallback[cbtype] = newnum;
230:   }
231:   obj->fortrancallback[cbtype][*cid-PETSC_SMALLEST_FORTRAN_CALLBACK].func = func;
232:   obj->fortrancallback[cbtype][*cid-PETSC_SMALLEST_FORTRAN_CALLBACK].ctx = ctx;
233:   return(0);
234: }

238: /*@C
239:    PetscObjectGetFortranCallback - get fortran callback function pointer and context

241:    Logically Collective

243:    Input Arguments:
244: +  obj - object on which to get callback
245: .  cbtype - callback type
246: -  cid - address of callback Id

248:    Output Arguments:
249: +  func - Fortran function (or NULL if not needed)
250: -  ctx - Fortran context (or NULL if not needed)

252:    Level: developer

254: .seealso: PetscObjectSetFortranCallback()
255: @*/
256: PetscErrorCode PetscObjectGetFortranCallback(PetscObject obj,PetscFortranCallbackType cbtype,PetscFortranCallbackId cid,void (**func)(void),void **ctx)
257: {
258:   PetscFortranCallback *cb;

262:   if (PetscUnlikely(cid < PETSC_SMALLEST_FORTRAN_CALLBACK)) SETERRQ(obj->comm,PETSC_ERR_ARG_CORRUPT,"Fortran callback Id invalid");
263:   if (PetscUnlikely(cid >= PETSC_SMALLEST_FORTRAN_CALLBACK+obj->num_fortrancallback[cbtype])) SETERRQ(obj->comm,PETSC_ERR_ARG_CORRUPT,"Fortran callback not set on this object");
264:   cb = &obj->fortrancallback[cbtype][cid-PETSC_SMALLEST_FORTRAN_CALLBACK];
265:   if (func) *func = cb->func;
266:   if (ctx) *ctx = cb->ctx;
267:   return(0);
268: }

270: #if defined(PETSC_USE_LOG)
273: /*@C
274:    PetscObjectsDump - Prints the currently existing objects.

276:    Logically Collective on PetscViewer

278:    Input Parameter:
279: +  fd - file pointer
280: -  all - by default only tries to display objects created explicitly by the user, if all is PETSC_TRUE then lists all outstanding objects

282:    Options Database:
283: .  -objects_dump <all>

285:    Level: advanced

287:    Concepts: options database^printing

289: @*/
290: PetscErrorCode  PetscObjectsDump(FILE *fd,PetscBool all)
291: {
293:   PetscInt       i;
294: #if defined(PETSC_USE_DEBUG)
295:   PetscInt       j,k=0;
296: #endif
297:   PetscObject    h;

300:   if (PetscObjectsCounts) {
301:     PetscFPrintf(PETSC_COMM_WORLD,fd,"The following objects were never freed\n");
302:     PetscFPrintf(PETSC_COMM_WORLD,fd,"-----------------------------------------\n");
303:     for (i=0; i<PetscObjectsMaxCounts; i++) {
304:       if ((h = PetscObjects[i])) {
305:         PetscObjectName(h);
306:         {
307: #if defined(PETSC_USE_DEBUG)
308:         PetscStack *stack = 0;
309:         char       *create,*rclass;

311:         /* if the PETSc function the user calls is not a create then this object was NOT directly created by them */
312:         PetscMallocGetStack(h,&stack);
313:         if (stack) {
314:           k = stack->currentsize-2;
315:           if (!all) {
316:             k = 0;
317:             while (!stack->petscroutine[k]) k++;
318:             PetscStrstr(stack->function[k],"Create",&create);
319:             if (!create) {
320:               PetscStrstr(stack->function[k],"Get",&create);
321:             }
322:             PetscStrstr(stack->function[k],h->class_name,&rclass);
323:             if (!create) continue;
324:             if (!rclass) continue;
325:           }
326:         }
327: #endif

329:         PetscFPrintf(PETSC_COMM_WORLD,fd,"[%d] %s %s %s\n",PetscGlobalRank,h->class_name,h->type_name,h->name);

331: #if defined(PETSC_USE_DEBUG)
332:         PetscMallocGetStack(h,&stack);
333:         if (stack) {
334:           for (j=k; j>=0; j--) {
335:             fprintf(fd,"      [%d]  %s() in %s\n",PetscGlobalRank,stack->function[j],stack->file[j]);
336:           }
337:         }
338: #endif
339:         }
340:       }
341:     }
342:   }
343:   return(0);
344: }
345: #endif

347: #if defined(PETSC_USE_LOG)

351: /*@C
352:    PetscObjectsView - Prints the currently existing objects.

354:    Logically Collective on PetscViewer

356:    Input Parameter:
357: .  viewer - must be an PETSCVIEWERASCII viewer

359:    Level: advanced

361:    Concepts: options database^printing

363: @*/
364: PetscErrorCode  PetscObjectsView(PetscViewer viewer)
365: {
367:   PetscBool      isascii;
368:   FILE           *fd;

371:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
372:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
373:   if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");
374:   PetscViewerASCIIGetPointer(viewer,&fd);
375:   PetscObjectsDump(fd,PETSC_TRUE);
376:   return(0);
377: }

381: /*@C
382:    PetscObjectsGetObject - Get a pointer to a named object

384:    Not collective

386:    Input Parameter:
387: .  name - the name of an object

389:    Output Parameter:
390: .   obj - the object or null if there is no object

392:    Level: advanced

394:    Concepts: options database^printing

396: @*/
397: PetscErrorCode  PetscObjectsGetObject(const char *name,PetscObject *obj,char **classname)
398: {
400:   PetscInt       i;
401:   PetscObject    h;
402:   PetscBool      flg;

405:   *obj = NULL;
406:   for (i=0; i<PetscObjectsMaxCounts; i++) {
407:     if ((h = PetscObjects[i])) {
408:       PetscObjectName(h);
409:       PetscStrcmp(h->name,name,&flg);
410:       if (flg) {
411:         *obj = h;
412:         if (classname) *classname = h->class_name;
413:         return(0);
414:       }
415:     }
416:   }
417:   return(0);
418: }
419: #endif

423: /*@C
424:     PetscObjectAddOptionsHandler - Adds an additional function to check for options when XXXSetFromOptions() is called.

426:     Not Collective

428:     Input Parameter:
429: +   obj - the PETSc object
430: .   handle - function that checks for options
431: .   destroy - function to destroy context if provided
432: -   ctx - optional context for check function

434:     Level: developer


437: .seealso: KSPSetFromOptions(), PCSetFromOptions(), SNESSetFromOptions(), PetscObjectProcessOptionsHandlers(), PetscObjectDestroyOptionsHandlers()

439: @*/
440: PetscErrorCode  PetscObjectAddOptionsHandler(PetscObject obj,PetscErrorCode (*handle)(PetscObject,void*),PetscErrorCode (*destroy)(PetscObject,void*),void *ctx)
441: {
444:   if (obj->noptionhandler >= PETSC_MAX_OPTIONS_HANDLER) SETERRQ(obj->comm,PETSC_ERR_ARG_OUTOFRANGE,"To many options handlers added");
445:   obj->optionhandler[obj->noptionhandler] = handle;
446:   obj->optiondestroy[obj->noptionhandler] = destroy;
447:   obj->optionctx[obj->noptionhandler++]   = ctx;
448:   return(0);
449: }

453: /*@C
454:     PetscObjectProcessOptionsHandlers - Calls all the options handlers attached to an object

456:     Not Collective

458:     Input Parameter:
459: .   obj - the PETSc object

461:     Level: developer


464: .seealso: KSPSetFromOptions(), PCSetFromOptions(), SNESSetFromOptions(), PetscObjectAddOptionsHandler(), PetscObjectDestroyOptionsHandlers()

466: @*/
467: PetscErrorCode  PetscObjectProcessOptionsHandlers(PetscObject obj)
468: {
469:   PetscInt       i;

474:   for (i=0; i<obj->noptionhandler; i++) {
475:     (*obj->optionhandler[i])(obj,obj->optionctx[i]);
476:   }
477:   return(0);
478: }

482: /*@C
483:     PetscObjectDestroyOptionsHandlers - Destroys all the option handlers attached to an object

485:     Not Collective

487:     Input Parameter:
488: .   obj - the PETSc object

490:     Level: developer


493: .seealso: KSPSetFromOptions(), PCSetFromOptions(), SNESSetFromOptions(), PetscObjectAddOptionsHandler(), PetscObjectProcessOptionsHandlers()

495: @*/
496: PetscErrorCode  PetscObjectDestroyOptionsHandlers(PetscObject obj)
497: {
498:   PetscInt       i;

503:   for (i=0; i<obj->noptionhandler; i++) {
504:     if (obj->optiondestroy[i]) {
505:       (*obj->optiondestroy[i])(obj,obj->optionctx[i]);
506:     }
507:   }
508:   obj->noptionhandler = 0;
509:   return(0);
510: }


515: /*@
516:    PetscObjectReference - Indicates to any PetscObject that it is being
517:    referenced by another PetscObject. This increases the reference
518:    count for that object by one.

520:    Logically Collective on PetscObject

522:    Input Parameter:
523: .  obj - the PETSc object. This must be cast with (PetscObject), for example,
524:          PetscObjectReference((PetscObject)mat);

526:    Level: advanced

528: .seealso: PetscObjectCompose(), PetscObjectDereference()
529: @*/
530: PetscErrorCode  PetscObjectReference(PetscObject obj)
531: {
533:   if (!obj) return(0);
535:   obj->refct++;
536:   return(0);
537: }

541: /*@
542:    PetscObjectGetReference - Gets the current reference count for
543:    any PETSc object.

545:    Not Collective

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

551:    Output Parameter:
552: .  cnt - the reference count

554:    Level: advanced

556: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
557: @*/
558: PetscErrorCode  PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
559: {
563:   *cnt = obj->refct;
564:   return(0);
565: }

569: /*@
570:    PetscObjectDereference - Indicates to any PetscObject that it is being
571:    referenced by one less PetscObject. This decreases the reference
572:    count for that object by one.

574:    Collective on PetscObject if reference reaches 0 otherwise Logically Collective

576:    Input Parameter:
577: .  obj - the PETSc object; this must be cast with (PetscObject), for example,
578:          PetscObjectDereference((PetscObject)mat);

580:    Notes: PetscObjectDestroy(PetscObject *obj)  sets the obj pointer to null after the call, this routine does not.

582:    Level: advanced

584: .seealso: PetscObjectCompose(), PetscObjectReference()
585: @*/
586: PetscErrorCode  PetscObjectDereference(PetscObject obj)
587: {

591:   if (!obj) return(0);
593:   if (obj->bops->destroy) {
594:     (*obj->bops->destroy)(&obj);
595:   } else if (!--obj->refct) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
596:   return(0);
597: }

599: /* ----------------------------------------------------------------------- */
600: /*
601:      The following routines are the versions private to the PETSc object
602:      data structures.
603: */
606: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
607: {
610:   *comm = obj->comm;
611:   return(0);
612: }

616: PetscErrorCode PetscObjectRemoveReference(PetscObject obj,const char name[])
617: {

622:   PetscObjectListRemoveReference(&obj->olist,name);
623:   return(0);
624: }

628: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
629: {
631:   char           *tname;
632:   PetscBool      skipreference;

635:   if (ptr) {
636:     PetscObjectListReverseFind(ptr->olist,obj,&tname,&skipreference);
637:     if (tname && !skipreference) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was composed with it");
638:   }
639:   PetscObjectListAdd(&obj->olist,name,ptr);
640:   return(0);
641: }

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

651:   PetscObjectListFind(obj->olist,name,ptr);
652:   return(0);
653: }

657: PetscErrorCode PetscObjectComposeFunction_Petsc(PetscObject obj,const char name[],void (*ptr)(void))
658: {

663:   PetscFunctionListAdd(&obj->qlist,name,ptr);
664:   return(0);
665: }

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

675:   PetscFunctionListFind(obj->qlist,name,ptr);
676:   return(0);
677: }

681: /*@C
682:    PetscObjectCompose - Associates another PETSc object with a given PETSc object.

684:    Not Collective

686:    Input Parameters:
687: +  obj - the PETSc object; this must be cast with (PetscObject), for example,
688:          PetscObjectCompose((PetscObject)mat,...);
689: .  name - name associated with the child object
690: -  ptr - the other PETSc object to associate with the PETSc object; this must also be
691:          cast with (PetscObject)

693:    Level: advanced

695:    Notes:
696:    The second objects reference count is automatically increased by one when it is
697:    composed.

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

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

704:    PetscObjectCompose() can be used with any PETSc object (such as
705:    Mat, Vec, KSP, SNES, etc.) or any user-provided object.  See
706:    PetscContainerCreate() for info on how to create an object from a
707:    user-provided pointer that may then be composed with PETSc objects.

709:    Concepts: objects^composing
710:    Concepts: composing objects

712: .seealso: PetscObjectQuery(), PetscContainerCreate()
713: @*/
714: PetscErrorCode  PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
715: {

722:   (*obj->bops->compose)(obj,name,ptr);
723:   return(0);
724: }

728: /*@C
729:    PetscObjectSetPrecision - sets the precision used within a given object.

731:    Collective on the PetscObject

733:    Input Parameters:
734: +  obj - the PETSc object; this must be cast with (PetscObject), for example,
735:          PetscObjectCompose((PetscObject)mat,...);
736: -  precision - the precision

738:    Level: advanced

740: .seealso: PetscObjectQuery(), PetscContainerCreate()
741: @*/
742: PetscErrorCode  PetscObjectSetPrecision(PetscObject obj,PetscPrecision precision)
743: {
746:   obj->precision = precision;
747:   return(0);
748: }

752: /*@C
753:    PetscObjectQuery  - Gets a PETSc object associated with a given object.

755:    Not Collective

757:    Input Parameters:
758: +  obj - the PETSc object
759:          Thus must be cast with a (PetscObject), for example,
760:          PetscObjectCompose((PetscObject)mat,...);
761: .  name - name associated with child object
762: -  ptr - the other PETSc object associated with the PETSc object, this must be
763:          cast with (PetscObject*)

765:    Level: advanced

767:    The reference count of neither object is increased in this call

769:    Concepts: objects^composing
770:    Concepts: composing objects
771:    Concepts: objects^querying
772:    Concepts: querying objects

774: .seealso: PetscObjectCompose()
775: @*/
776: PetscErrorCode  PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
777: {

784:   (*obj->bops->query)(obj,name,ptr);
785:   return(0);
786: }

788: /*MC
789:    PetscObjectComposeFunction - Associates a function with a given PETSc object.

791:     Synopsis:
792:     #include <petscsys.h>
793:     PetscErrorCode PetscObjectComposeFunction(PetscObject obj,const char name[],void (*fptr)(void))

795:    Logically Collective on PetscObject

797:    Input Parameters:
798: +  obj - the PETSc object; this must be cast with a (PetscObject), for example,
799:          PetscObjectCompose((PetscObject)mat,...);
800: .  name - name associated with the child function
801: .  fname - name of the function
802: -  fptr - function pointer

804:    Level: advanced

806:    Notes:
807:    To remove a registered routine, pass in NULL for fptr().

809:    PetscObjectComposeFunction() can be used with any PETSc object (such as
810:    Mat, Vec, KSP, SNES, etc.) or any user-provided object.

812:    Concepts: objects^composing functions
813:    Concepts: composing functions
814:    Concepts: functions^querying
815:    Concepts: objects^querying
816:    Concepts: querying objects

818: .seealso: PetscObjectQueryFunction(), PetscContainerCreate()
819: M*/

823: PetscErrorCode  PetscObjectComposeFunction_Private(PetscObject obj,const char name[],void (*fptr)(void))
824: {

830:   (*obj->bops->composefunction)(obj,name,fptr);
831:   return(0);
832: }

834: /*MC
835:    PetscObjectQueryFunction - Gets a function associated with a given object.

837:     Synopsis:
838:     #include <petscsys.h>
839:     PetscErrorCode PetscObjectQueryFunction(PetscObject obj,const char name[],void (**fptr)(void))

841:    Logically Collective on PetscObject

843:    Input Parameters:
844: +  obj - the PETSc object; this must be cast with (PetscObject), for example,
845:          PetscObjectQueryFunction((PetscObject)ksp,...);
846: -  name - name associated with the child function

848:    Output Parameter:
849: .  fptr - function pointer

851:    Level: advanced

853:    Concepts: objects^composing functions
854:    Concepts: composing functions
855:    Concepts: functions^querying
856:    Concepts: objects^querying
857:    Concepts: querying objects

859: .seealso: PetscObjectComposeFunction(), PetscFunctionListFind()
860: M*/
863: PETSC_EXTERN PetscErrorCode PetscObjectQueryFunction_Private(PetscObject obj,const char name[],void (**ptr)(void))
864: {

870:   (*obj->bops->queryfunction)(obj,name,ptr);
871:   return(0);
872: }

874: struct _p_PetscContainer {
875:   PETSCHEADER(int);
876:   void           *ptr;
877:   PetscErrorCode (*userdestroy)(void*);
878: };

882: /*@C
883:    PetscContainerGetPointer - Gets the pointer value contained in the container.

885:    Not Collective

887:    Input Parameter:
888: .  obj - the object created with PetscContainerCreate()

890:    Output Parameter:
891: .  ptr - the pointer value

893:    Level: advanced

895: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
896:           PetscContainerSetPointer()
897: @*/
898: PetscErrorCode  PetscContainerGetPointer(PetscContainer obj,void **ptr)
899: {
903:   *ptr = obj->ptr;
904:   return(0);
905: }


910: /*@C
911:    PetscContainerSetPointer - Sets the pointer value contained in the container.

913:    Logically Collective on PetscContainer

915:    Input Parameters:
916: +  obj - the object created with PetscContainerCreate()
917: -  ptr - the pointer value

919:    Level: advanced

921: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
922:           PetscContainerGetPointer()
923: @*/
924: PetscErrorCode  PetscContainerSetPointer(PetscContainer obj,void *ptr)
925: {
929:   obj->ptr = ptr;
930:   return(0);
931: }

935: /*@C
936:    PetscContainerDestroy - Destroys a PETSc container object.

938:    Collective on PetscContainer

940:    Input Parameter:
941: .  obj - an object that was created with PetscContainerCreate()

943:    Level: advanced

945: .seealso: PetscContainerCreate(), PetscContainerSetUserDestroy()
946: @*/
947: PetscErrorCode  PetscContainerDestroy(PetscContainer *obj)
948: {

952:   if (!*obj) return(0);
954:   if (--((PetscObject)(*obj))->refct > 0) {*obj = 0; return(0);}
955:   if ((*obj)->userdestroy) (*(*obj)->userdestroy)((*obj)->ptr);
956:   PetscHeaderDestroy(obj);
957:   return(0);
958: }

962: /*@C
963:    PetscContainerSetUserDestroy - Sets name of the user destroy function.

965:    Logically Collective on PetscContainer

967:    Input Parameter:
968: +  obj - an object that was created with PetscContainerCreate()
969: -  des - name of the user destroy function

971:    Level: advanced

973: .seealso: PetscContainerDestroy()
974: @*/
975: PetscErrorCode  PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
976: {
979:   obj->userdestroy = des;
980:   return(0);
981: }

983: PetscClassId PETSC_CONTAINER_CLASSID;

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

993:    Collective on MPI_Comm

995:    Input Parameters:
996: .  comm - MPI communicator that shares the object

998:    Output Parameters:
999: .  container - the container created

1001:    Level: advanced

1003: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer()
1004: @*/
1005: PetscErrorCode  PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
1006: {
1008:   PetscContainer contain;

1012:   PetscSysInitializePackage();
1013:   PetscHeaderCreate(contain,PETSC_CONTAINER_CLASSID,"PetscContainer","Container","Sys",comm,PetscContainerDestroy,NULL);
1014:   *container = contain;
1015:   return(0);
1016: }

1020: /*@
1021:    PetscObjectSetFromOptions - Sets generic parameters from user options.

1023:    Collective on obj

1025:    Input Parameter:
1026: .  obj - the PetscObjcet

1028:    Options Database Keys:

1030:    Notes:
1031:    We have no generic options at present, so this does nothing

1033:    Level: beginner

1035: .keywords: set, options, database
1036: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
1037: @*/
1038: PetscErrorCode  PetscObjectSetFromOptions(PetscObject obj)
1039: {
1042:   return(0);
1043: }

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

1050:    Collective on PetscObject

1052:    Input Parameters:
1053: .  obj - the PetscObject

1055:    Notes:
1056:    This does nothing at present.

1058:    Level: advanced

1060: .keywords: setup
1061: .seealso: PetscObjectDestroy()
1062: @*/
1063: PetscErrorCode  PetscObjectSetUp(PetscObject obj)
1064: {
1067:   return(0);
1068: }