Actual source code: inherit.c

petsc-dev 2014-02-02
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: +  viewer - must be an PETSCVIEWERASCII viewer
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:    Level: advanced

282:    Concepts: options database^printing

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

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

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

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

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

342: #if defined(PETSC_USE_LOG)

346: /*@C
347:    PetscObjectsView - Prints the currently existing objects.

349:    Logically Collective on PetscViewer

351:    Input Parameter:
352: .  viewer - must be an PETSCVIEWERASCII viewer

354:    Level: advanced

356:    Concepts: options database^printing

358: @*/
359: PetscErrorCode  PetscObjectsView(PetscViewer viewer)
360: {
362:   PetscBool      isascii;
363:   FILE           *fd;

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

376: /*@C
377:    PetscObjectsGetObject - Get a pointer to a named object

379:    Not collective

381:    Input Parameter:
382: .  name - the name of an object

384:    Output Parameter:
385: .   obj - the object or null if there is no object

387:    Level: advanced

389:    Concepts: options database^printing

391: @*/
392: PetscErrorCode  PetscObjectsGetObject(const char *name,PetscObject *obj,char **classname)
393: {
395:   PetscInt       i;
396:   PetscObject    h;
397:   PetscBool      flg;

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

417: char *PetscObjectsGetObjectMatlab(const char* name,PetscObject *obj)
418: {
420:   PetscInt       i;
421:   PetscObject    h;
422:   PetscBool      flg;

425:   *obj = NULL;
426:   for (i=0; i<PetscObjectsMaxCounts; i++) {
427:     if ((h = PetscObjects[i])) {
428:       PetscObjectName(h);if (ierr) return(0);
429:       PetscStrcmp(h->name,name,&flg);if (ierr) return(0);
430:       if (flg) {
431:         *obj = h;
432:         PetscFunctionReturn(h->class_name);
433:       }
434:     }
435:   }
436:   return(0);
437: }
438: #endif

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

445:     Not Collective

447:     Input Parameter:
448: +   obj - the PETSc object
449: .   handle - function that checks for options
450: .   destroy - function to destroy context if provided
451: -   ctx - optional context for check function

453:     Level: developer


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

458: @*/
459: PetscErrorCode  PetscObjectAddOptionsHandler(PetscObject obj,PetscErrorCode (*handle)(PetscObject,void*),PetscErrorCode (*destroy)(PetscObject,void*),void *ctx)
460: {
463:   if (obj->noptionhandler >= PETSC_MAX_OPTIONS_HANDLER) SETERRQ(obj->comm,PETSC_ERR_ARG_OUTOFRANGE,"To many options handlers added");
464:   obj->optionhandler[obj->noptionhandler] = handle;
465:   obj->optiondestroy[obj->noptionhandler] = destroy;
466:   obj->optionctx[obj->noptionhandler++]   = ctx;
467:   return(0);
468: }

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

475:     Not Collective

477:     Input Parameter:
478: .   obj - the PETSc object

480:     Level: developer


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

485: @*/
486: PetscErrorCode  PetscObjectProcessOptionsHandlers(PetscObject obj)
487: {
488:   PetscInt       i;

493:   for (i=0; i<obj->noptionhandler; i++) {
494:     (*obj->optionhandler[i])(obj,obj->optionctx[i]);
495:   }
496:   return(0);
497: }

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

504:     Not Collective

506:     Input Parameter:
507: .   obj - the PETSc object

509:     Level: developer


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

514: @*/
515: PetscErrorCode  PetscObjectDestroyOptionsHandlers(PetscObject obj)
516: {
517:   PetscInt       i;

522:   for (i=0; i<obj->noptionhandler; i++) {
523:     if (obj->optiondestroy[i]) {
524:       (*obj->optiondestroy[i])(obj,obj->optionctx[i]);
525:     }
526:   }
527:   obj->noptionhandler = 0;
528:   return(0);
529: }


534: /*@
535:    PetscObjectReference - Indicates to any PetscObject that it is being
536:    referenced by another PetscObject. This increases the reference
537:    count for that object by one.

539:    Logically Collective on PetscObject

541:    Input Parameter:
542: .  obj - the PETSc object. This must be cast with (PetscObject), for example,
543:          PetscObjectReference((PetscObject)mat);

545:    Level: advanced

547: .seealso: PetscObjectCompose(), PetscObjectDereference()
548: @*/
549: PetscErrorCode  PetscObjectReference(PetscObject obj)
550: {
552:   if (!obj) return(0);
554:   obj->refct++;
555:   return(0);
556: }

560: /*@
561:    PetscObjectGetReference - Gets the current reference count for
562:    any PETSc object.

564:    Not Collective

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

570:    Output Parameter:
571: .  cnt - the reference count

573:    Level: advanced

575: .seealso: PetscObjectCompose(), PetscObjectDereference(), PetscObjectReference()
576: @*/
577: PetscErrorCode  PetscObjectGetReference(PetscObject obj,PetscInt *cnt)
578: {
582:   *cnt = obj->refct;
583:   return(0);
584: }

588: /*@
589:    PetscObjectDereference - Indicates to any PetscObject that it is being
590:    referenced by one less PetscObject. This decreases the reference
591:    count for that object by one.

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

595:    Input Parameter:
596: .  obj - the PETSc object; this must be cast with (PetscObject), for example,
597:          PetscObjectDereference((PetscObject)mat);

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

601:    Level: advanced

603: .seealso: PetscObjectCompose(), PetscObjectReference()
604: @*/
605: PetscErrorCode  PetscObjectDereference(PetscObject obj)
606: {

611:   if (obj->bops->destroy) {
612:     (*obj->bops->destroy)(&obj);
613:   } else if (!--obj->refct) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SUP,"This PETSc object does not have a generic destroy routine");
614:   return(0);
615: }

617: /* ----------------------------------------------------------------------- */
618: /*
619:      The following routines are the versions private to the PETSc object
620:      data structures.
621: */
624: PetscErrorCode PetscObjectGetComm_Petsc(PetscObject obj,MPI_Comm *comm)
625: {
628:   *comm = obj->comm;
629:   return(0);
630: }

634: PetscErrorCode PetscObjectRemoveReference(PetscObject obj,const char name[])
635: {

640:   PetscObjectListRemoveReference(&obj->olist,name);
641:   return(0);
642: }

646: PetscErrorCode PetscObjectCompose_Petsc(PetscObject obj,const char name[],PetscObject ptr)
647: {
649:   char           *tname;
650:   PetscBool      skipreference;

653:   if (ptr) {
654:     PetscObjectListReverseFind(ptr->olist,obj,&tname,&skipreference);
655:     if (tname && !skipreference) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"An object cannot be composed with an object that was composed with it");
656:   }
657:   PetscObjectListAdd(&obj->olist,name,ptr);
658:   return(0);
659: }

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

669:   PetscObjectListFind(obj->olist,name,ptr);
670:   return(0);
671: }

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

681:   PetscFunctionListAdd(&obj->qlist,name,ptr);
682:   return(0);
683: }

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

693:   PetscFunctionListFind(obj->qlist,name,ptr);
694:   return(0);
695: }

699: /*@C
700:    PetscObjectCompose - Associates another PETSc object with a given PETSc object.

702:    Not Collective

704:    Input Parameters:
705: +  obj - the PETSc object; this must be cast with (PetscObject), for example,
706:          PetscObjectCompose((PetscObject)mat,...);
707: .  name - name associated with the child object
708: -  ptr - the other PETSc object to associate with the PETSc object; this must also be
709:          cast with (PetscObject)

711:    Level: advanced

713:    Notes:
714:    The second objects reference count is automatically increased by one when it is
715:    composed.

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

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

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

727:    Concepts: objects^composing
728:    Concepts: composing objects

730: .seealso: PetscObjectQuery(), PetscContainerCreate()
731: @*/
732: PetscErrorCode  PetscObjectCompose(PetscObject obj,const char name[],PetscObject ptr)
733: {

740:   (*obj->bops->compose)(obj,name,ptr);
741:   return(0);
742: }

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

749:    Collective on the PetscObject

751:    Input Parameters:
752: +  obj - the PETSc object; this must be cast with (PetscObject), for example,
753:          PetscObjectCompose((PetscObject)mat,...);
754: -  precision - the precision

756:    Level: advanced

758: .seealso: PetscObjectQuery(), PetscContainerCreate()
759: @*/
760: PetscErrorCode  PetscObjectSetPrecision(PetscObject obj,PetscPrecision precision)
761: {
764:   obj->precision = precision;
765:   return(0);
766: }

770: /*@C
771:    PetscObjectQuery  - Gets a PETSc object associated with a given object.

773:    Not Collective

775:    Input Parameters:
776: +  obj - the PETSc object
777:          Thus must be cast with a (PetscObject), for example,
778:          PetscObjectCompose((PetscObject)mat,...);
779: .  name - name associated with child object
780: -  ptr - the other PETSc object associated with the PETSc object, this must be
781:          cast with (PetscObject*)

783:    Level: advanced

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

787:    Concepts: objects^composing
788:    Concepts: composing objects
789:    Concepts: objects^querying
790:    Concepts: querying objects

792: .seealso: PetscObjectCompose()
793: @*/
794: PetscErrorCode  PetscObjectQuery(PetscObject obj,const char name[],PetscObject *ptr)
795: {

802:   (*obj->bops->query)(obj,name,ptr);
803:   return(0);
804: }

806: /*MC
807:    PetscObjectComposeFunction - Associates a function with a given PETSc object.

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

813:    Logically Collective on PetscObject

815:    Input Parameters:
816: +  obj - the PETSc object; this must be cast with a (PetscObject), for example,
817:          PetscObjectCompose((PetscObject)mat,...);
818: .  name - name associated with the child function
819: .  fname - name of the function
820: -  fptr - function pointer

822:    Level: advanced

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

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

830:    Concepts: objects^composing functions
831:    Concepts: composing functions
832:    Concepts: functions^querying
833:    Concepts: objects^querying
834:    Concepts: querying objects

836: .seealso: PetscObjectQueryFunction(), PetscContainerCreate()
837: M*/

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

848:   (*obj->bops->composefunction)(obj,name,fptr);
849:   return(0);
850: }

852: /*MC
853:    PetscObjectQueryFunction - Gets a function associated with a given object.

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

859:    Logically Collective on PetscObject

861:    Input Parameters:
862: +  obj - the PETSc object; this must be cast with (PetscObject), for example,
863:          PetscObjectQueryFunction((PetscObject)ksp,...);
864: -  name - name associated with the child function

866:    Output Parameter:
867: .  fptr - function pointer

869:    Level: advanced

871:    Concepts: objects^composing functions
872:    Concepts: composing functions
873:    Concepts: functions^querying
874:    Concepts: objects^querying
875:    Concepts: querying objects

877: .seealso: PetscObjectComposeFunction(), PetscFunctionListFind()
878: M*/
881: PETSC_EXTERN PetscErrorCode PetscObjectQueryFunction_Private(PetscObject obj,const char name[],void (**ptr)(void))
882: {

888:   (*obj->bops->queryfunction)(obj,name,ptr);
889:   return(0);
890: }

892: struct _p_PetscContainer {
893:   PETSCHEADER(int);
894:   void           *ptr;
895:   PetscErrorCode (*userdestroy)(void*);
896: };

900: /*@C
901:    PetscContainerGetPointer - Gets the pointer value contained in the container.

903:    Not Collective

905:    Input Parameter:
906: .  obj - the object created with PetscContainerCreate()

908:    Output Parameter:
909: .  ptr - the pointer value

911:    Level: advanced

913: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
914:           PetscContainerSetPointer()
915: @*/
916: PetscErrorCode  PetscContainerGetPointer(PetscContainer obj,void **ptr)
917: {
921:   *ptr = obj->ptr;
922:   return(0);
923: }


928: /*@C
929:    PetscContainerSetPointer - Sets the pointer value contained in the container.

931:    Logically Collective on PetscContainer

933:    Input Parameters:
934: +  obj - the object created with PetscContainerCreate()
935: -  ptr - the pointer value

937:    Level: advanced

939: .seealso: PetscContainerCreate(), PetscContainerDestroy(),
940:           PetscContainerGetPointer()
941: @*/
942: PetscErrorCode  PetscContainerSetPointer(PetscContainer obj,void *ptr)
943: {
947:   obj->ptr = ptr;
948:   return(0);
949: }

953: /*@C
954:    PetscContainerDestroy - Destroys a PETSc container object.

956:    Collective on PetscContainer

958:    Input Parameter:
959: .  obj - an object that was created with PetscContainerCreate()

961:    Level: advanced

963: .seealso: PetscContainerCreate(), PetscContainerSetUserDestroy()
964: @*/
965: PetscErrorCode  PetscContainerDestroy(PetscContainer *obj)
966: {

970:   if (!*obj) return(0);
972:   if (--((PetscObject)(*obj))->refct > 0) {*obj = 0; return(0);}
973:   if ((*obj)->userdestroy) (*(*obj)->userdestroy)((*obj)->ptr);
974:   PetscHeaderDestroy(obj);
975:   return(0);
976: }

980: /*@C
981:    PetscContainerSetUserDestroy - Sets name of the user destroy function.

983:    Logically Collective on PetscContainer

985:    Input Parameter:
986: +  obj - an object that was created with PetscContainerCreate()
987: -  des - name of the user destroy function

989:    Level: advanced

991: .seealso: PetscContainerDestroy()
992: @*/
993: PetscErrorCode  PetscContainerSetUserDestroy(PetscContainer obj, PetscErrorCode (*des)(void*))
994: {
997:   obj->userdestroy = des;
998:   return(0);
999: }

1001: PetscClassId PETSC_CONTAINER_CLASSID;

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

1011:    Collective on MPI_Comm

1013:    Input Parameters:
1014: .  comm - MPI communicator that shares the object

1016:    Output Parameters:
1017: .  container - the container created

1019:    Level: advanced

1021: .seealso: PetscContainerDestroy(), PetscContainerSetPointer(), PetscContainerGetPointer()
1022: @*/
1023: PetscErrorCode  PetscContainerCreate(MPI_Comm comm,PetscContainer *container)
1024: {
1026:   PetscContainer contain;

1030:   PetscSysInitializePackage();
1031:   PetscHeaderCreate(contain,_p_PetscContainer,PetscInt,PETSC_CONTAINER_CLASSID,"PetscContainer","Container","Sys",comm,PetscContainerDestroy,0);
1032:   *container = contain;
1033:   return(0);
1034: }

1038: /*@
1039:    PetscObjectSetFromOptions - Sets generic parameters from user options.

1041:    Collective on obj

1043:    Input Parameter:
1044: .  obj - the PetscObjcet

1046:    Options Database Keys:

1048:    Notes:
1049:    We have no generic options at present, so this does nothing

1051:    Level: beginner

1053: .keywords: set, options, database
1054: .seealso: PetscObjectSetOptionsPrefix(), PetscObjectGetOptionsPrefix()
1055: @*/
1056: PetscErrorCode  PetscObjectSetFromOptions(PetscObject obj)
1057: {
1060:   return(0);
1061: }

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

1068:    Collective on PetscObject

1070:    Input Parameters:
1071: .  obj - the PetscObject

1073:    Notes:
1074:    This does nothing at present.

1076:    Level: advanced

1078: .keywords: setup
1079: .seealso: PetscObjectDestroy()
1080: @*/
1081: PetscErrorCode  PetscObjectSetUp(PetscObject obj)
1082: {
1085:   return(0);
1086: }