Actual source code: petscerror.h

  1: /*
  2:     Contains all error handling interfaces for PETSc.
  3: */
 6:  #include petsc.h

  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 */

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

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

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

 75: #define PETSC_ERR_MAX_VALUE        88   /* this is always the one more than the largest error code */

 77: #if defined(PETSC_USE_ERRORCHECKING)

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

 82:    Not Collective

 84:    Synopsis:
 85:    void SETERRQ(PetscErrorCode errorcode,char *message)


 88:    Input Parameters:
 89: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
 90: -  message - error message

 92:   Level: beginner

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

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


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

102:    Concepts: error^setting condition

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

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

111:    Not Collective

113:    Synopsis:
114:    void SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg)


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

122:   Level: beginner

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

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

129:    Concepts: error^setting condition

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

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

138:    Not Collective

140:    Synopsis:
141:    void SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)


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

150:   Level: beginner

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

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

157:    Concepts: error^setting condition

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

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

166:    Not Collective

168:    Synopsis:
169:    void SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)


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

179:   Level: beginner

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

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

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

188:    Concepts: error^setting condition

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

194: #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);}
195: #define SETERRQ5(n,s,a1,a2,a3,a4,a5)       {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);}
196: #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);}
197: #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);}
198: #define SETERRABORT(comm,n,s)     {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);}

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

203:    Not Collective

205:    Synopsis:
206:    void CHKERRQ(PetscErrorCode errorcode)


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

212:   Level: beginner

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

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

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

222:     Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
223:     highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
224:     it cannot be used in functions which return(void) or any other datatype.  In these types of functions,
225:     a more appropriate construct for using PETSc Error Handling would be
226:          if (n) {PetscError(....); return(YourReturnType);}

228:    Concepts: error^setting condition

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

234: #define CHKERRV(n)             if (n) {n = PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");return;}
235: #define CHKERRABORT(comm,n)    if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);}
236: #define CHKERRCONTINUE(n)      if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}

238: #define CHKFPQ(f) if (f != f) {SETERRQ(PETSC_ERR_FP, "Invalid value: NaN");}

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

243:    Not Collective

245:    Synopsis:
246:    CHKMEMQ;

248:   Level: beginner

250:    Notes:
251:     Must run with the option -malloc_debug to enable this option

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

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

257:     Use CHKMEMA for functions that return void

259:    Concepts: memory corruption

261: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
262:           PetscMallocValidate()
263: M*/
264: #define CHKMEMQ {PetscErrorCode _7_PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}

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

268: #if defined(PETSC_UNDERSCORE_CHKERR)
270: #define _   __g
272: #endif

274: #define               PETSC_EXCEPTIONS_MAX  256

280: EXTERN PetscErrorCode  PetscExceptionPush(PetscErrorCode);
281: EXTERN void  PetscExceptionPop(PetscErrorCode);

283: EXTERN PetscErrorCode  PetscErrorSetCatchable(PetscErrorCode,PetscTruth);
284: EXTERN PetscTruth  PetscErrorIsCatchable(PetscErrorCode);
285: /*MC
286:    PetscExceptionCaught - Indicates if a specific exception zierr was caught.

288:    Not Collective

290:    Synopsis:
291:      PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr);

293:   Input Parameters:
294:   + xierr - error code returned from PetscExceptionTry1() 
295:   - zierr - error code you want it to be

297:   Level: advanced

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

302:     Use PetscExceptionValue() to see if the current error code is one that has been "tried"

304:   Concepts: exceptions, exception hanlding

306: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
307:           CHKERRQ(), PetscExceptionTry1(), PetscExceptionValue()
308: M*/
309: PETSC_STATIC_INLINE PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr) {
310:   PetscInt i;
311:   if (xierr != zierr) return PETSC_FALSE;
312:   for (i=0; i<PetscErrorUncatchableCount; i++) {
313:     if (PetscErrorUncatchable[i] == zierr) {
314:       return PETSC_FALSE;
315:     }
316:   }
317:   return PETSC_TRUE;
318: }

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

323:    Not Collective

325:    Synopsis:
326:      PetscTruth PetscExceptionValue(PetscErrorCode xierr);

328:   Input Parameters:
329:   . xierr - error code 

331:   Level: developer

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

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

338:   Concepts: exceptions, exception hanlding

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

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

358:    Not Collective

360:    Synopsis:
361:      PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode);

363:   Level: advanced

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

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

372:   Concepts: exceptions, exception hanlding

374: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
375:           CHKERRQ(), PetscExceptionCaught(), PetscExceptionPush(), PetscExceptionPop()
376: M*/
378: #define PetscExceptionTry1(a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : (PetscExceptionTmp = a , PetscExceptionPop(b),PetscExceptionTmp)

380: #else

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

386: #define SETERRQ(n,s) ;
387: #define SETERRQ1(n,s,a1) ;
388: #define SETERRQ2(n,s,a1,a2) ;
389: #define SETERRQ3(n,s,a1,a2,a3) ;
390: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
391: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ;
392: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ;
393: #define SETERRABORT(comm,n,s) ;

395: #define CHKERRQ(n)     ;
396: #define CHKERRABORT(comm,n) ;
397: #define CHKERRCONTINUE(n) ;

399: #define CHKMEMQ        ;

401: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
402: #define _   
404: #endif 

406: #define PetscErrorSetCatchable(a,b) 0
407: #define PetscExceptionCaught(a,b)   PETSC_FALSE
408: #define PetscExceptionValue(a)      PETSC_FALSE
409: #define PetscExceptionTry1(a,b)     a
410: #endif

412: EXTERN PetscErrorCode  PetscErrorPrintfInitialize(void);
413: EXTERN PetscErrorCode  PetscErrorMessage(int,const char*[],char **);
414: EXTERN PetscErrorCode  PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
415: EXTERN PetscErrorCode  PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
416: EXTERN PetscErrorCode  PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
417: EXTERN PetscErrorCode  PetscMPIAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
418: EXTERN PetscErrorCode  PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
419: EXTERN PetscErrorCode  PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
420: EXTERN PetscErrorCode  PetscReturnErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
421: EXTERN PetscErrorCode  PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
422: EXTERN PetscErrorCode  PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*);
423: EXTERN PetscErrorCode  PetscPopErrorHandler(void);
424: EXTERN PetscErrorCode  PetscDefaultSignalHandler(int,void*);
425: EXTERN PetscErrorCode  PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
426: EXTERN PetscErrorCode  PetscPopSignalHandler(void);

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

431: /*
432:       Allows the code to build a stack frame as it runs
433: */
434: #if defined(PETSC_USE_DEBUG)

436: #define PETSCSTACKSIZE 15

438: typedef struct  {
439:   const char *function[PETSCSTACKSIZE];
440:   const char *file[PETSCSTACKSIZE];
441:   const char *directory[PETSCSTACKSIZE];
442:         int  line[PETSCSTACKSIZE];
443:         int currentsize;
444: } PetscStack;

447: EXTERN PetscErrorCode   PetscStackCopy(PetscStack*,PetscStack*);
448: EXTERN PetscErrorCode   PetscStackPrint(PetscStack*,FILE* fp);

450: #define PetscStackActive (petscstack != 0)


453: /*MC
455:         used for error handling.

457:    Synopsis:

460:    Usage:
461: .vb
462:      int something;

465: .ve

467:    Notes:
468:      Not available in Fortran

470:    Level: developer

472: .seealso: PetscFunctionReturn()

474: .keywords: traceback, error handling
475: M*/
477:   {\
478:    if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
479:     petscstack->function[petscstack->currentsize]  = __FUNCT__; \
480:     petscstack->file[petscstack->currentsize]      = __FILE__; \
481:     petscstack->directory[petscstack->currentsize] = __SDIR__; \
482:     petscstack->line[petscstack->currentsize]      = __LINE__; \
483:     petscstack->currentsize++; \
484:   }}

486: #define PetscStackPush(n) \
487:   {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
488:     petscstack->function[petscstack->currentsize]  = n; \
489:     petscstack->file[petscstack->currentsize]      = "unknown"; \
490:     petscstack->directory[petscstack->currentsize] = "unknown"; \
491:     petscstack->line[petscstack->currentsize]      = 0; \
492:     petscstack->currentsize++; \
493:   }}

495: #define PetscStackPop \
496:   {if (petscstack && petscstack->currentsize > 0) {     \
497:     petscstack->currentsize--; \
498:     petscstack->function[petscstack->currentsize]  = 0; \
499:     petscstack->file[petscstack->currentsize]      = 0; \
500:     petscstack->directory[petscstack->currentsize] = 0; \
501:     petscstack->line[petscstack->currentsize]      = 0; \
502:   }};

504: /*MC
505:    PetscFunctionReturn - Last executable line of each PETSc function
506:         used for error handling. Replaces return()

508:    Synopsis:
509:    void return(0);

511:    Usage:
512: .vb
513:     ....
514:      return(0);
515:    }
516: .ve

518:    Notes:
519:      Not available in Fortran

521:    Level: developer


525: .keywords: traceback, error handling
526: M*/
527: #define PetscFunctionReturn(a) \
528:   {\
529:   PetscStackPop; \
530:   return(a);}

532: #define PetscFunctionReturnVoid() \
533:   {\
534:   PetscStackPop; \
535:   return;}


538: #else

541: #define PetscFunctionReturn(a)  return(a)
542: #define PetscFunctionReturnVoid() return
543: #define PetscStackPop 
544: #define PetscStackPush(f) 
545: #define PetscStackActive        0

547: #endif

549: EXTERN PetscErrorCode   PetscStackCreate(void);
550: EXTERN PetscErrorCode   PetscStackView(PetscViewer);
551: EXTERN PetscErrorCode   PetscStackDestroy(void);
552: EXTERN PetscErrorCode   PetscStackPublish(void);
553: EXTERN PetscErrorCode   PetscStackDepublish(void);


557: #endif