Actual source code: inherit.c

petsc-master 2015-03-26
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: #endif

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

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

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

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

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

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

 85: extern PetscBool      PetscMemoryCollectMaximumUsage;
 86: extern PetscLogDouble PetscMemoryMaximumUsage;

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

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

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

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

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

153: /*@C
154:    PetscObjectCopyFortranFunctionPointers - Copy function pointers to another object

156:    Logically Collective on PetscObject

158:    Input Parameter:
159: +  src - source object
160: -  dest - destination object

162:    Level: developer

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

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

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

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

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

194: /*@C
195:    PetscObjectSetFortranCallback - set fortran callback function pointer and context

197:    Logically Collective

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

206:    Level: developer

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

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

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

236: /*@C
237:    PetscObjectGetFortranCallback - get fortran callback function pointer and context

239:    Logically Collective

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

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

250:    Level: developer

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

260:   if (PetscUnlikely(cid < PETSC_SMALLEST_FORTRAN_CALLBACK)) SETERRQ(obj->comm,PETSC_ERR_ARG_CORRUPT,"Fortran callback Id invalid");
261:   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");
262:   cb = &obj->fortrancallback[cbtype][cid-PETSC_SMALLEST_FORTRAN_CALLBACK];
263:   if (func) *func = cb->func;
264:   if (ctx) *ctx = cb->ctx;
265:   return(0);
266: }

268: #if defined(PETSC_USE_LOG)
271: /*@C
272:    PetscObjectsDump - Prints the currently existing objects.

274:    Logically Collective on PetscViewer

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

280:    Options Database:
281: .  -objects_dump <all>

283:    Level: advanced

285:    Concepts: options database^printing

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

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

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

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

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

345: #if defined(PETSC_USE_LOG)

349: /*@C
350:    PetscObjectsView - Prints the currently existing objects.

352:    Logically Collective on PetscViewer

354:    Input Parameter:
355: .  viewer - must be an PETSCVIEWERASCII viewer

357:    Level: advanced

359:    Concepts: options database^printing

361: @*/
362: PetscErrorCode  PetscObjectsView(PetscViewer viewer)
363: {
365:   PetscBool      isascii;
366:   FILE           *fd;

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

379: /*@C
380:    PetscObjectsGetObject - Get a pointer to a named object

382:    Not collective

384:    Input Parameter:
385: .  name - the name of an object

387:    Output Parameter:
388: .   obj - the object or null if there is no object

390:    Level: advanced

392:    Concepts: options database^printing

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

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

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

424:     Not Collective

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

432:     Level: developer


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

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

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

454:     Not Collective

456:     Input Parameter:
457: .   obj - the PETSc object

459:     Level: developer


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

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

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

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

483:     Not Collective

485:     Input Parameter:
486: .   obj - the PETSc object

488:     Level: developer


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

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

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


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

518:    Logically Collective on PetscObject

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

524:    Level: advanced

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

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

543:    Not Collective

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

549:    Output Parameter:
550: .  cnt - the reference count

552:    Level: advanced

554: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
555: @*/
556: PetscErrorCode  PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
557: {
561:   *cnt = obj->refct;
562:   return(0);
563: }

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

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

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

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

580:    Level: advanced

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

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

597: /* ----------------------------------------------------------------------- */
598: /*
599:      The following routines are the versions private to the PETSc object
600:      data structures.
601: */
604: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
605: {
608:   *comm = obj->comm;
609:   return(0);
610: }

614: PetscErrorCode PetscObjectRemoveReference(PetscObject obj,const char name[])
615: {

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

626: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
627: {
629:   char           *tname;
630:   PetscBool      skipreference;

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

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

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

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

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

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

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

679: /*@C
680:    PetscObjectCompose - Associates another PETSc object with a given PETSc object.

682:    Not Collective

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

691:    Level: advanced

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

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

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

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

707:    Concepts: objects^composing
708:    Concepts: composing objects

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

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

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

729:    Collective on the PetscObject

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

736:    Level: advanced

738: .seealso: PetscObjectQuery(), PetscContainerCreate()
739: @*/
740: PetscErrorCode  PetscObjectSetPrecision(PetscObject obj,PetscPrecision precision)
741: {
744:   obj->precision = precision;
745:   return(0);
746: }

750: /*@C
751:    PetscObjectQuery  - Gets a PETSc object associated with a given object.

753:    Not Collective

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

763:    Level: advanced

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

767:    Concepts: objects^composing
768:    Concepts: composing objects
769:    Concepts: objects^querying
770:    Concepts: querying objects

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

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

786: /*MC
787:    PetscObjectComposeFunction - Associates a function with a given PETSc object.

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

793:    Logically Collective on PetscObject

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

802:    Level: advanced

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

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

810:    Concepts: objects^composing functions
811:    Concepts: composing functions
812:    Concepts: functions^querying
813:    Concepts: objects^querying
814:    Concepts: querying objects

816: .seealso: PetscObjectQueryFunction(), PetscContainerCreate()
817: M*/

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

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

832: /*MC
833:    PetscObjectQueryFunction - Gets a function associated with a given object.

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

839:    Logically Collective on PetscObject

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

846:    Output Parameter:
847: .  fptr - function pointer

849:    Level: advanced

851:    Concepts: objects^composing functions
852:    Concepts: composing functions
853:    Concepts: functions^querying
854:    Concepts: objects^querying
855:    Concepts: querying objects

857: .seealso: PetscObjectComposeFunction(), PetscFunctionListFind()
858: M*/
861: PETSC_EXTERN PetscErrorCode PetscObjectQueryFunction_Private(PetscObject obj,const char name[],void (**ptr)(void))
862: {

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

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

880: /*@C
881:    PetscContainerGetPointer - Gets the pointer value contained in the container.

883:    Not Collective

885:    Input Parameter:
886: .  obj - the object created with PetscContainerCreate()

888:    Output Parameter:
889: .  ptr - the pointer value

891:    Level: advanced

893: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
894:           PetscContainerSetPointer()
895: @*/
896: PetscErrorCode  PetscContainerGetPointer(PetscContainer obj,void **ptr)
897: {
901:   *ptr = obj->ptr;
902:   return(0);
903: }


908: /*@C
909:    PetscContainerSetPointer - Sets the pointer value contained in the container.

911:    Logically Collective on PetscContainer

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

917:    Level: advanced

919: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
920:           PetscContainerGetPointer()
921: @*/
922: PetscErrorCode  PetscContainerSetPointer(PetscContainer obj,void *ptr)
923: {
927:   obj->ptr = ptr;
928:   return(0);
929: }

933: /*@C
934:    PetscContainerDestroy - Destroys a PETSc container object.

936:    Collective on PetscContainer

938:    Input Parameter:
939: .  obj - an object that was created with PetscContainerCreate()

941:    Level: advanced

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

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

960: /*@C
961:    PetscContainerSetUserDestroy - Sets name of the user destroy function.

963:    Logically Collective on PetscContainer

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

969:    Level: advanced

971: .seealso: PetscContainerDestroy()
972: @*/
973: PetscErrorCode  PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
974: {
977:   obj->userdestroy = des;
978:   return(0);
979: }

981: PetscClassId PETSC_CONTAINER_CLASSID;

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

991:    Collective on MPI_Comm

993:    Input Parameters:
994: .  comm - MPI communicator that shares the object

996:    Output Parameters:
997: .  container - the container created

999:    Level: advanced

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

1010:   PetscSysInitializePackage();
1011:   PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_CLASSID,"PetscContainer","Container","Sys",comm,PetscContainerDestroy,0);
1012:   *container = contain;
1013:   return(0);
1014: }

1018: /*@
1019:    PetscObjectSetFromOptions - Sets generic parameters from user options.

1021:    Collective on obj

1023:    Input Parameter:
1024: .  obj - the PetscObjcet

1026:    Options Database Keys:

1028:    Notes:
1029:    We have no generic options at present, so this does nothing

1031:    Level: beginner

1033: .keywords: set, options, database
1034: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
1035: @*/
1036: PetscErrorCode  PetscObjectSetFromOptions(PetscObject obj)
1037: {
1040:   return(0);
1041: }

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

1048:    Collective on PetscObject

1050:    Input Parameters:
1051: .  obj - the PetscObject

1053:    Notes:
1054:    This does nothing at present.

1056:    Level: advanced

1058: .keywords: setup
1059: .seealso: PetscObjectDestroy()
1060: @*/
1061: PetscErrorCode  PetscObjectSetUp(PetscObject obj)
1062: {
1065:   return(0);
1066: }