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

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

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

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

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

 72: #if defined(PETSC_USE_ERRORCHECKING)

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

 77:    Not Collective

 79:    Synopsis:
 80:    void SETERRQ(PetscErrorCode errorcode,char *message)


 83:    Input Parameters:
 84: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
 85: -  message - error message

 87:   Level: beginner

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

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


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

 97:    Concepts: error^setting condition

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

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

106:    Not Collective

108:    Synopsis:
109:    void SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg)


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

117:   Level: beginner

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

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

124:    Concepts: error^setting condition

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

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

133:    Not Collective

135:    Synopsis:
136:    void SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)


139:    Input Parameters:
140: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
141: .  message - error message in the printf format
142: .  arg1 - argument (for example an integer, string or double)
143: -  arg2 - argument (for example an integer, string or double)

145:   Level: beginner

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

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

152:    Concepts: error^setting condition

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

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

161:    Not Collective

163:    Synopsis:
164:    void SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)


167:    Input Parameters:
168: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
169: .  message - error message in the printf format
170: .  arg1 - argument (for example an integer, string or double)
171: .  arg2 - argument (for example an integer, string or double)
172: -  arg3 - argument (for example an integer, string or double)

174:   Level: beginner

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

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

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

183:    Concepts: error^setting condition

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

189: #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);}
190: #define SETERRQ5(n,s,a1,a2,a3,a4,a5)       {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);}
191: #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);}
192: #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);}
193: #define SETERRABORT(comm,n,s)     {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);}

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

198:    Not Collective

200:    Synopsis:
201:    void CHKERRQ(PetscErrorCode errorcode)


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

207:   Level: beginner

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

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

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

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

223:    Concepts: error^setting condition

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

229: #define CHKERRABORT(comm,n)    if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");MPI_Abort(comm,n);}
230: #define CHKERRCONTINUE(n)      if (n) {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,0," ");}

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

235:    Not Collective

237:    Synopsis:
238:    CHKMEMQ;

240:   Level: beginner

242:    Notes:
243:     Must run with the option -malloc_debug to enable this option

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

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

249:     Use CHKMEMA for functions that return void

251:    Concepts: memory corruption

253: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
254:           PetscMallocValidate()
255: M*/
256: #define CHKMEMQ {PetscErrorCode _7_PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}

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

260: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
262: #define _   __g
264: #endif

266: #define               PETSC_EXCEPTIONS_MAX  256

272: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscExceptionPush(PetscErrorCode);
273: EXTERN void PETSC_DLLEXPORT PetscExceptionPop(PetscErrorCode);

275: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorSetCatchable(PetscErrorCode,PetscTruth);

277: /*MC
278:    PetscExceptionCaught - Indicates if exception zierr was caught.

280:    Not Collective

282:    Synopsis:
283:      PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr);

285:   Input Parameters:
286:   + xierr - error code returned from PetscExceptionTry1() 
287:   - zierr - error code you want it to be

289:   Level: advanced

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

294:   Concepts: exceptions, exception hanlding

296: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
297:           CHKERRQ(), PetscExceptionTry1(), PetscExceptionValue()
298: M*/
299: PETSC_STATIC_INLINE PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr) {
300:   PetscInt i;
301:   if (xierr != zierr) return PETSC_FALSE;
302:   for (i=0; i<PetscErrorUncatchableCount; i++) {
303:     if (PetscErrorUncatchable[i] == zierr) {
304:       return PETSC_FALSE;
305:     }
306:   }
307:   return PETSC_TRUE;
308: }

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

313:    Not Collective

315:    Synopsis:
316:      PetscTruth PetscExceptionValue(PetscErrorCode xierr);

318:   Input Parameters:
319:   . xierr - error code 

321:   Level: developer

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

326:   Concepts: exceptions, exception hanlding

328: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
329:           CHKERRQ(), PetscExceptionTry1(), PetscExceptionCaught()
330: M*/
331: PETSC_STATIC_INLINE PetscTruth PetscExceptionValue(PetscErrorCode zierr) {
332:   PetscInt i;
333:   for (i=0; i<PetscExceptionsCount; i++) {
334:     if (PetscExceptions[i] == zierr) {
335:       return PETSC_TRUE;
336:     }
337:   }
338:   return PETSC_FALSE;
339: }

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

346:    Not Collective

348:    Synopsis:
349:      PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode);

351:   Level: advanced

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

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

360:   Concepts: exceptions, exception hanlding

362: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(), 
363:           CHKERRQ(), PetscExceptionCaught()
364: M*/
366: #define PetscExceptionTry1(a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : (PetscExceptionTmp = a , PetscExceptionPop(b),PetscExceptionTmp)

368: #else

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

374: #define SETERRQ(n,s) ;
375: #define SETERRQ1(n,s,a1) ;
376: #define SETERRQ2(n,s,a1,a2) ;
377: #define SETERRQ3(n,s,a1,a2,a3) ;
378: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
379: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ;
380: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ;
381: #define SETERRABORT(comm,n,s) ;

383: #define CHKERRQ(n)     ;
384: #define CHKERRABORT(comm,n) ;
385: #define CHKERRCONTINUE(n) ;

387: #define CHKMEMQ        ;

389: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
390: #define _   
392: #endif 

394: #define PetscErrorSetCatchable(a,b) 0
395: #define PetscExceptionCaught(a,b)   PETSC_FALSE
396: #define PetscExceptionValue(a)      PETSC_FALSE
397: #define PetscExceptionTry1(a,b)     a
398: #endif

400: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorPrintfInitialize(void);
401: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorMessage(int,const char*[],char **);
402: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
403: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
404: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
405: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStopErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
406: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
407: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
408: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscReturnErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
409: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
410: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*);
411: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopErrorHandler(void);
412: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDefaultSignalHandler(int,void*);
413: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
414: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopSignalHandler(void);

416: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
417: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscSetFPTrap(PetscFPTrap);

419: /*
420:       Allows the code to build a stack frame as it runs
421: */
422: #if defined(PETSC_USE_DEBUG)

424: #define PETSCSTACKSIZE 15

426: typedef struct  {
427:   const char *function[PETSCSTACKSIZE];
428:   const char *file[PETSCSTACKSIZE];
429:   const char *directory[PETSCSTACKSIZE];
430:         int  line[PETSCSTACKSIZE];
431:         int currentsize;
432: } PetscStack;

435: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackCopy(PetscStack*,PetscStack*);
436: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackPrint(PetscStack*,FILE* fp);

438: #define PetscStackActive (petscstack != 0)


441: /*MC
443:         used for error handling.

445:    Synopsis:

448:    Usage:
449: .vb
450:      int something;

453: .ve

455:    Notes:
456:      Not available in Fortran

458:    Level: developer

460: .seealso: PetscFunctionReturn()

462: .keywords: traceback, error handling
463: M*/
465:   {\
466:    if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
467:     petscstack->function[petscstack->currentsize]  = __FUNCT__; \
468:     petscstack->file[petscstack->currentsize]      = __FILE__; \
469:     petscstack->directory[petscstack->currentsize] = __SDIR__; \
470:     petscstack->line[petscstack->currentsize]      = __LINE__; \
471:     petscstack->currentsize++; \
472:   }}

474: #define PetscStackPush(n) \
475:   {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
476:     petscstack->function[petscstack->currentsize]  = n; \
477:     petscstack->file[petscstack->currentsize]      = "unknown"; \
478:     petscstack->directory[petscstack->currentsize] = "unknown"; \
479:     petscstack->line[petscstack->currentsize]      = 0; \
480:     petscstack->currentsize++; \
481:   }}

483: #define PetscStackPop \
484:   {if (petscstack && petscstack->currentsize > 0) {     \
485:     petscstack->currentsize--; \
486:     petscstack->function[petscstack->currentsize]  = 0; \
487:     petscstack->file[petscstack->currentsize]      = 0; \
488:     petscstack->directory[petscstack->currentsize] = 0; \
489:     petscstack->line[petscstack->currentsize]      = 0; \
490:   }};

492: /*MC
493:    PetscFunctionReturn - Last executable line of each PETSc function
494:         used for error handling. Replaces return()

496:    Synopsis:
497:    void return(0);

499:    Usage:
500: .vb
501:     ....
502:      return(0);
503:    }
504: .ve

506:    Notes:
507:      Not available in Fortran

509:    Level: developer


513: .keywords: traceback, error handling
514: M*/
515: #define PetscFunctionReturn(a) \
516:   {\
517:   PetscStackPop; \
518:   return(a);}

520: #define PetscFunctionReturnVoid() \
521:   {\
522:   PetscStackPop; \
523:   return;}


526: #else

529: #define PetscFunctionReturn(a)  return(a)
530: #define PetscFunctionReturnVoid() return
531: #define PetscStackPop 
532: #define PetscStackPush(f) 
533: #define PetscStackActive        0

535: #endif

537: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackCreate(void);
538: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackView(PetscViewer);
539: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackDestroy(void);
540: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackPublish(void);
541: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackDepublish(void);


545: #endif