Actual source code: petscerror.h

  1: /*
  2:     Contains all error handling interfaces for PETSc.
  3: */


  9: /*
 10:    Defines the directory where the compiled source is located; used
 11:    in printing error messages. Each makefile has an entry 
 12:    LOCDIR          =  thedirectory
 13:    and bmake/common_variables includes in CCPPFLAGS -D__SDIR__=${LOCDIR}
 14:    which is a flag passed to the C/C++ compilers. This declaration below
 15:    is only needed if some code is compiled without the -D__SDIR__
 16: */
 19: #endif

 21: /*
 22:    Defines the function where the compiled source is located; used 
 23:    in printing error messages. This is defined here in case the user
 24:    does not declare it.
 25: */
 28: #endif

 30: /* 
 31:      These are the generic error codes. These error codes are used
 32:      many different places in the PETSc source code. The string versions are
 33:      at src/sys/error/err.c any changes here must also be made there
 34:      These are also define in include/finclude/petscerror.h any CHANGES here
 35:      must be also made there.

 37: */
 38: #define PETSC_ERR_MIN_VALUE        54   /* should always be one less then the smallest value */

 40: #define PETSC_ERR_MEM              55   /* unable to allocate requested memory */
 41: #define PETSC_ERR_SUP              56   /* no support for requested operation */
 42: #define PETSC_ERR_SUP_SYS          57   /* no support for requested operation on this computer system */
 43: #define PETSC_ERR_ORDER            58   /* operation done in wrong order */
 44: #define PETSC_ERR_SIG              59   /* signal received */
 45: #define PETSC_ERR_FP               72   /* floating point exception */
 46: #define PETSC_ERR_COR              74   /* corrupted PETSc object */
 47: #define PETSC_ERR_LIB              76   /* error in library called by PETSc */
 48: #define PETSC_ERR_PLIB             77   /* PETSc library generated inconsistent data */
 49: #define PETSC_ERR_MEMC             78   /* memory corruption */
 50: #define PETSC_ERR_CONV_FAILED      82   /* iterative method (KSP or SNES) failed */
 51: #define PETSC_ERR_USER             83   /* user has not provided needed function */
 52: #define PETSC_ERR_SYS              88   /* error in system call */

 54: #define PETSC_ERR_ARG_SIZ          60   /* nonconforming object sizes used in operation */
 55: #define PETSC_ERR_ARG_IDN          61   /* two arguments not allowed to be the same */
 56: #define PETSC_ERR_ARG_WRONG        62   /* wrong argument (but object probably ok) */
 57: #define PETSC_ERR_ARG_CORRUPT      64   /* null or corrupted PETSc object as argument */
 58: #define PETSC_ERR_ARG_OUTOFRANGE   63   /* input argument, out of range */
 59: #define PETSC_ERR_ARG_BADPTR       68   /* invalid pointer argument */
 60: #define PETSC_ERR_ARG_NOTSAMETYPE  69   /* two args must be same object type */
 61: #define PETSC_ERR_ARG_NOTSAMECOMM  80   /* two args must be same communicators */
 62: #define PETSC_ERR_ARG_WRONGSTATE   73   /* object in argument is in wrong state, e.g. unassembled mat */
 63: #define PETSC_ERR_ARG_TYPENOTSET   89   /* the type of the object has not yet been set */
 64: #define PETSC_ERR_ARG_INCOMP       75   /* two arguments are incompatible */
 65: #define PETSC_ERR_ARG_NULL         85   /* argument is null that should not be */
 66: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86   /* type name doesn't match any registered type */

 68: #define PETSC_ERR_FILE_OPEN        65   /* unable to open file */
 69: #define PETSC_ERR_FILE_READ        66   /* unable to read from file */
 70: #define PETSC_ERR_FILE_WRITE       67   /* unable to write to file */
 71: #define PETSC_ERR_FILE_UNEXPECTED  79   /* unexpected data in file */

 73: #define PETSC_ERR_MAT_LU_ZRPVT     71   /* detected a zero pivot during LU factorization */
 74: #define PETSC_ERR_MAT_CH_ZRPVT     81   /* detected a zero pivot during Cholesky factorization */

 76: #define PETSC_ERR_FLOP_COUNT       90
 77: #define PETSC_ERR_MAX_VALUE        91  /* this is always the one more than the largest error code */

 79: #define PetscStringizeArg(a) #a
 80: #define PetscStringize(a) PetscStringizeArg(a)

 83: #if defined(PETSC_USE_ERRORCHECKING)

 85: /*MC
 86:    SETERRQ - Macro that is called when an error has been detected, 

 88:    Synopsis:
 89:    PetscErrorCode SETERRQ(PetscErrorCode errorcode,char *message)

 91:    Not Collective

 93:    Input Parameters:
 94: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
 95: -  message - error message

 97:   Level: beginner

 99:    Notes:
100:     Once the error handler is called the calling function is then returned from with the given error code.

102:     See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments

104:     In Fortran MPI_Abort() is always called

106:     Experienced users can set the error handler with PetscPushErrorHandler().

108:    Concepts: error^setting condition

110: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
111: M*/
112: #define SETERRQ(n,s)              {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);}

114: /*MC
115:    SETERRQ1 - Macro that is called when an error has been detected, 

117:    Synopsis:
118:    PetscErrorCode SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg)

120:    Not Collective

122:    Input Parameters:
123: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
124: .  message - error message in the printf format
125: -  arg - argument (for example an integer, string or double)

127:   Level: beginner

129:    Notes:
130:     Once the error handler is called the calling function is then returned from with the given error code.

132:    Experienced users can set the error handler with PetscPushErrorHandler().

134:    Concepts: error^setting condition

136: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
137: M*/
138: #define SETERRQ1(n,s,a1)          {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1);}

140: /*MC
141:    SETERRQ2 - Macro that is called when an error has been detected, 

143:    Synopsis:
144:    PetscErrorCode SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)

146:    Not Collective

148:    Input Parameters:
149: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
150: .  message - error message in the printf format
151: .  arg1 - argument (for example an integer, string or double)
152: -  arg2 - argument (for example an integer, string or double)

154:   Level: beginner

156:    Notes:
157:     Once the error handler is called the calling function is then returned from with the given error code.

159:    Experienced users can set the error handler with PetscPushErrorHandler().

161:    Concepts: error^setting condition

163: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
164: M*/
165: #define SETERRQ2(n,s,a1,a2)       {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2);}

167: /*MC
168:    SETERRQ3 - Macro that is called when an error has been detected, 

170:    Synopsis:
171:    PetscErrorCode SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

173:    Not Collective

175:    Input Parameters:
176: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
177: .  message - error message in the printf format
178: .  arg1 - argument (for example an integer, string or double)
179: .  arg2 - argument (for example an integer, string or double)
180: -  arg3 - argument (for example an integer, string or double)

182:   Level: beginner

184:    Notes:
185:     Once the error handler is called the calling function is then returned from with the given error code.

187:     There are also versions for 4, 5, 6 and 7 arguments.

189:    Experienced users can set the error handler with PetscPushErrorHandler().

191:    Concepts: error^setting condition

193: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
194: M*/
195: #define SETERRQ3(n,s,a1,a2,a3)    {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3);}

197: #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);}
198: #define SETERRQ5(n,s,a1,a2,a3,a4,a5)       {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);}
199: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6)    {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5,a6);}
200: #define SETERRQ7(n,s,a1,a2,a3,a4,a5,a6,a7) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5,a6,a7);}
201: #define SETERRABORT(comm,n,s)     {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);}

203: /*MC
204:    CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns

206:    Synopsis:
207:    PetscErrorCode CHKERRQ(PetscErrorCode errorcode)

209:    Not Collective

211:    Input Parameters:
212: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h

214:   Level: beginner

216:    Notes:
217:     Once the error handler is called the calling function is then returned from with the given error code.

219:     Experienced users can set the error handler with PetscPushErrorHandler().

221:     CHKERRQ(n) is fundamentally a macro replacement for
222:          if (n) return(PetscError(...,n,...));

224:     Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
225:     highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
226:     it cannot be used in functions which return(void) or any other datatype.  In these types of functions,
227:     you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or
228:          if (n) {PetscError(....); return(YourReturnType);} 
229:     where you may pass back a PETSC_NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have
230:     MPI_Abort() returned immediately.

232:     In Fortran MPI_Abort() is always called

234:    Concepts: error^setting condition

236: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
237: M*/
238: #define CHKERRQ(n)             if (PetscUnlikely(n)) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}

240: #define CHKERRV(n)             if (PetscUnlikely(n)) {n = PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");return;}
241: #define CHKERRABORT(comm,n)    if (PetscUnlikely(n)) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);}
242: #define CHKERRCONTINUE(n)      if (PetscUnlikely(n)) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}

244: #ifdef PETSC_CLANGUAGE_CXX

246: /*MC
247:    CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception

249:    Synopsis:
250:    void CHKERRXX(PetscErrorCode errorcode)

252:    Not Collective

254:    Input Parameters:
255: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h

257:   Level: beginner

259:    Notes:
260:     Once the error handler throws a ??? exception.

262:     You can use CHKERRV() which returns without an error code (bad idea since the error is ignored)
263:     or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately.

265:    Concepts: error^setting condition

267: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ
268: M*/
269: #define CHKERRXX(n)            if (PetscUnlikely(n)) {PetscErrorCxx(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0);}

271: #endif

273: /*MC
274:    CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected

276:    Synopsis:
277:    CHKMEMQ;

279:    Not Collective

281:   Level: beginner

283:    Notes:
284:     Must run with the option -malloc_debug to enable this option

286:     Once the error handler is called the calling function is then returned from with the given error code.

288:     By defaults prints location where memory that is corrupted was allocated.

290:     Use CHKMEMA for functions that return void

292:    Concepts: memory corruption

294: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
295:           PetscMallocValidate()
296: M*/
297: #define CHKMEMQ {PetscErrorCode _7_PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}

299: #define CHKMEMA {PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);}

301: #if defined(PETSC_UNDERSCORE_CHKERR)
303: #define _   __g
305: #endif

307: #define               PETSC_EXCEPTIONS_MAX  256

313: EXTERN PetscErrorCode  PetscExceptionPush(PetscErrorCode);
314: EXTERN PetscErrorCode  PetscExceptionPop(PetscErrorCode);

316: EXTERN PetscErrorCode  PetscErrorSetCatchable(PetscErrorCode,PetscTruth);
317: EXTERN PetscTruth  PetscErrorIsCatchable(PetscErrorCode);
318: /*MC
319:    PetscExceptionCaught - Indicates if a specific exception zierr was caught.

321:    Synopsis:
322:      PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr);

324:    Not Collective

326:   Input Parameters:
327:   + xierr - error code returned from PetscExceptionTry1() or other PETSc routine
328:   - zierr - error code you want it to be

330:   Level: advanced

332:    Notes:
333:     PETSc must not be configured using the option --with-errorchecking=0 for this to work

335:     Use PetscExceptionValue() to see if an error code is being "tried"

337:   Concepts: exceptions, exception handling

339: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
340:           CHKERRQ(), PetscExceptionTry1(), PetscExceptionValue()
341: M*/
342: PETSC_STATIC_INLINE PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr)
343: {
344:   PetscInt i;
345:   if (xierr != zierr) return PETSC_FALSE;
346:   for (i=0; i<PetscErrorUncatchableCount; i++) {
347:     if (PetscErrorUncatchable[i] == zierr) {
348:       return PETSC_FALSE;
349:     }
350:   }
351:   return PETSC_TRUE;
352: }

354: /*MC
355:    PetscExceptionValue - Indicates if the error code is one that is currently being tried

357:    Synopsis:
358:      PetscTruth PetscExceptionValue(PetscErrorCode xierr);

360:    Not Collective

362:   Input Parameters:
363:   . xierr - error code 

365:   Level: developer

367:    Notes:
368:     PETSc must not be configured using the option --with-errorchecking=0 for this to work

370:     Use PetscExceptionCaught() to see if the current error code is EXACTLY the one you want

372:   Concepts: exceptions, exception hanlding

374: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
375:           CHKERRQ(), PetscExceptionTry1(), PetscExceptionCaught()
376: M*/
377: PETSC_STATIC_INLINE PetscTruth PetscExceptionValue(PetscErrorCode zierr)
378: {
379:   PetscInt i;
380:   for (i=0; i<PetscExceptionsCount; i++) {
381:     if (PetscExceptions[i] == zierr) {
382:       return PETSC_TRUE;
383:     }
384:   }
385:   return PETSC_FALSE;
386: }

388: /*MC
389:    PetscExceptionTry1 - Runs the routine, causing a particular error code to be treated as an exception,
390:          rather than an error. That is if that error code is treated the program returns to this level,
391:          but does not call the error handlers

393:    Synopsis:
394:      PetscErrorCode PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode);

396:    Not Collective

398:   Level: advanced

400:    No Fortran Equivalent (see PetscExceptionPush() for Fortran)

402:    Notes:
403:     PETSc must not be configured using the option --with-errorchecking=0 for this to work

405:   Note: In general, the outer most try on an exception is the one that will be caught (that is trys down in 
406:         PETSc code will not usually handle an exception that was issued above). See SNESSolve() for an example
407:         of how the local try is ignored if a higher (in the stack) one is also in effect.

409:   Concepts: exceptions, exception hanlding

411: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
412:           CHKERRQ(), PetscExceptionCaught(), PetscExceptionPush(), PetscExceptionPop()
413: M*/
415: #define PetscExceptionTry1(a,b) (PetscExceptionTmp1 = PetscExceptionPush(b)) ? PetscExceptionTmp1 : (PetscExceptionTmp1 = a, (PetscExceptionTmp = PetscExceptionPop(b)) ? PetscExceptionTmp : PetscExceptionTmp1)

417: /*
418:    Used by PetscExceptionTrySync(). Returns zierr on ALL processes in comm iff xierr is zierr on at least one process and zero on all others.
419: */
420: PETSC_STATIC_INLINE PetscErrorCode PetscExceptionTrySync_Private(MPI_Comm comm,PetscErrorCode xierr,PetscErrorCode zierr)
421: {
422:   PetscReal      in[2],out[2];

425:   if (xierr != zierr) return xierr;

427:   in[0] = xierr;
428:   in[1] = 0.0;   /* dummy value */

430:   MPI_Allreduce(in,out,2,MPIU_REAL,0,comm); if (ierr) {;}
431:   return xierr;
432: }

434: /*MC
435:    PetscExceptionTrySyncNorm - Runs the routine, causing a particular error code to be treated as an exception,
436:          rather than an error. That is if that error code is treated the program returns to this level,
437:          but does not call the error handlers

439:    Synopsis:
440:      PetscExceptionTrySyncNorm(MPI_Comm comm,PetscErrorCode routine(....),PetscErrorCode);

442:      Collective on Comm

444:   Level: advanced

446:    Notes: This synchronizes the error code across all processes in the communicator IF the code matches PetscErrorCode. The next
447:      call with an MPI_Reduce()/MPI_Allreduce() MUST be VecNorm() [We can added VecDot() and maybe others as needed].

449:     PETSc must not be configured using the option --with-errorchecking=0 for this to work

451:   Note: In general, the outer most try on an exception is the one that will be caught (that is trys down in 
452:         PETSc code will not usually handle an exception that was issued above). See SNESSolve() for an example
453:         of how the local try is ignored if a higher (in the stack) one is also in effect.

455:   Concepts: exceptions, exception hanlding

457: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
458:           CHKERRQ(), PetscExceptionCaught(), PetscExceptionPush(), PetscExceptionPop(), PetscExceptionTry1()
459: M*/
460: #define PetscExceptionTrySyncNorm(comm,a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : \
461:                                         (PetscExceptionTmp = a , PetscExceptionPop(b),PetscExceptionTrySyncNorm_Private(comm,PetscExceptionTmp,b))

463: #else

465: /* 
466:     These are defined to be empty for when error checking is turned off, with config/configure.py --with-errorchecking=0
467: */

469: #define SETERRQ(n,s) ;
470: #define SETERRQ1(n,s,a1) ;
471: #define SETERRQ2(n,s,a1,a2) ;
472: #define SETERRQ3(n,s,a1,a2,a3) ;
473: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
474: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ;
475: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ;
476: #define SETERRABORT(comm,n,s) ;

478: #define CHKERRQ(n)     ;
479: #define CHKERRABORT(comm,n) ;
480: #define CHKERRCONTINUE(n) ;
481: #define CHKMEMQ        ;

483: #ifdef PETSC_CLANGUAGE_CXX
484: #define CHKERRXX(n) ;
485: #endif

487: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
488: #define _   
490: #endif 

492: #define PetscExceptionPush(a)                0
493: #define PetscExceptionPop(a)                 0
494: #define PetscErrorSetCatchable(a,b)          0
495: #define PetscErrorIsCatchable(a)             PETSC_FALSE

497: #define PetscExceptionCaught(a,b)            PETSC_FALSE
498: #define PetscExceptionValue(a)               PETSC_FALSE
499: #define PetscExceptionTry1(a,b)              a
500: #define PetscExceptionTrySyncNorm(comm,a,b)  a

502: #endif

504: EXTERN PetscErrorCode  PetscErrorPrintfInitialize(void);
505: EXTERN PetscErrorCode  PetscErrorMessage(int,const char*[],char **);
506: EXTERN PetscErrorCode  PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
508: #include <sstream>
509: EXTERN void            PetscTraceBackErrorHandlerCxx(int,const char *,const char *,const char *,PetscErrorCode,int, std::ostringstream&);
510: #endif
511: EXTERN PetscErrorCode  PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
512: EXTERN PetscErrorCode  PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
513: EXTERN PetscErrorCode  PetscMPIAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
514: EXTERN PetscErrorCode  PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
515: EXTERN PetscErrorCode  PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
516: EXTERN PetscErrorCode  PetscReturnErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
517: EXTERN PetscErrorCode  PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
518: EXTERN void            PetscErrorCxx(int,const char*,const char*,const char*,PetscErrorCode,int);
519: EXTERN PetscErrorCode  PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*);
520: EXTERN PetscErrorCode  PetscPopErrorHandler(void);
521: EXTERN PetscErrorCode  PetscDefaultSignalHandler(int,void*);
522: EXTERN PetscErrorCode  PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
523: EXTERN PetscErrorCode  PetscPopSignalHandler(void);

525: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
526: EXTERN PetscErrorCode   PetscSetFPTrap(PetscFPTrap);

528: /*
529:       Allows the code to build a stack frame as it runs
530: */
531: #if defined(PETSC_USE_DEBUG)

533: #define PETSCSTACKSIZE 15

535: typedef struct  {
536:   const char *function[PETSCSTACKSIZE];
537:   const char *file[PETSCSTACKSIZE];
538:   const char *directory[PETSCSTACKSIZE];
539:         int  line[PETSCSTACKSIZE];
540:         int currentsize;
541: } PetscStack;

544: EXTERN PetscErrorCode   PetscStackCopy(PetscStack*,PetscStack*);
545: EXTERN PetscErrorCode   PetscStackPrint(PetscStack*,FILE* fp);

547: #define PetscStackActive (petscstack != 0)


550: /*MC
552:         used for error handling.

554:    Synopsis:

557:    Not Collective

559:    Usage:
560: .vb
561:      int something;

564: .ve

566:    Notes:
567:      Not available in Fortran

569:    Level: developer

571: .seealso: PetscFunctionReturn()

573: .keywords: traceback, error handling
574: M*/
576:   {\
577:    if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
578:     petscstack->function[petscstack->currentsize]  = __FUNCT__; \
579:     petscstack->file[petscstack->currentsize]      = __FILE__; \
580:     petscstack->directory[petscstack->currentsize] = __SDIR__; \
581:     petscstack->line[petscstack->currentsize]      = __LINE__; \
582:     petscstack->currentsize++; \
583:   }}

585: #define PetscStackPush(n) \
586:   {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
587:     petscstack->function[petscstack->currentsize]  = n; \
588:     petscstack->file[petscstack->currentsize]      = "unknown"; \
589:     petscstack->directory[petscstack->currentsize] = "unknown"; \
590:     petscstack->line[petscstack->currentsize]      = 0; \
591:     petscstack->currentsize++; \
592:   }}

594: #define PetscStackPop \
595:   {if (petscstack && petscstack->currentsize > 0) {     \
596:     petscstack->currentsize--; \
597:     petscstack->function[petscstack->currentsize]  = 0; \
598:     petscstack->file[petscstack->currentsize]      = 0; \
599:     petscstack->directory[petscstack->currentsize] = 0; \
600:     petscstack->line[petscstack->currentsize]      = 0; \
601:   }};

603: /*MC
604:    PetscFunctionReturn - Last executable line of each PETSc function
605:         used for error handling. Replaces return()

607:    Synopsis:
608:    void return(0);

610:    Not Collective

612:    Usage:
613: .vb
614:     ....
615:      return(0);
616:    }
617: .ve

619:    Notes:
620:      Not available in Fortran

622:    Level: developer


626: .keywords: traceback, error handling
627: M*/
628: #define PetscFunctionReturn(a) \
629:   {\
630:   PetscStackPop; \
631:   return(a);}

633: #define PetscFunctionReturnVoid() \
634:   {\
635:   PetscStackPop; \
636:   return;}


639: #else

642: #define PetscFunctionReturn(a)  return(a)
643: #define PetscFunctionReturnVoid() return
644: #define PetscStackPop 
645: #define PetscStackPush(f) 
646: #define PetscStackActive        0

648: #endif

650: EXTERN PetscErrorCode   PetscStackCreate(void);
651: EXTERN PetscErrorCode   PetscStackView(PetscViewer);
652: EXTERN PetscErrorCode   PetscStackDestroy(void);
653: EXTERN PetscErrorCode   PetscStackPublish(void);
654: EXTERN PetscErrorCode   PetscStackDepublish(void);


658: #endif