Actual source code: petscerror.h

      1: /*
      2:     Contains all error handling code 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.
     15: */
     18: #endif

     20: /*
     21:    Defines the function where the compiled source is located; used
     22:    in printing error messages.
     23: */
     26: #endif

     28: /*
     29:      These are the generic error codes. These error codes are used
     30:      many different places in the PETSc source code. The string versions are
     31:      at src/sys/src/error/err.c any changes here must also be made there

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

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

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

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

     70: #if defined(PETSC_USE_ERRORCHECKING)

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

     75:    Not Collective

     77:    Synopsis:
     78:    void SETERRQ(PetscErrorCode errorcode,char *message)

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

     85:   Level: beginner

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

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

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

     95:    Concepts: error^setting condition

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

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

    104:    Not Collective

    106:    Synopsis:
    107:    void SETERRQ1(PetscErrorCode errorcode,char *formatmessage,arg)

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

    115:   Level: beginner

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

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

    122:    Concepts: error^setting condition

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

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

    131:    Not Collective

    133:    Synopsis:
    134:    void SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)

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

    143:   Level: beginner

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

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

    150:    Concepts: error^setting condition

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

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

    159:    Not Collective

    161:    Synopsis:
    162:    void SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

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

    172:   Level: beginner

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

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

    179:    Concepts: error^setting condition

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

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

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

    194:    Not Collective

    196:    Synopsis:
    197:    void CHKERRQ(PetscErrorCode errorcode)

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

    203:   Level: beginner

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

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

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

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

    219:    Concepts: error^setting condition

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

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

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

    231:    Not Collective

    233:    Synopsis:
    234:    CHKMEMQ;

    236:   Level: beginner

    238:    Notes:
    239:     Must run with the option -malloc_debug to enable this option

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

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

    245:    Concepts: memory corruption

    247: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
    248:           PetscMallocValidate()
    249: M*/
    250: #define CHKMEMQ {PetscErrorCode _7_PetscMallocValidate(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}

    252: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
    254: #define _   __g
    256: #endif

    258: #define               PETSC_EXCEPTIONS_MAX  256

    264: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscExceptionPush(PetscErrorCode);
    265: EXTERN void PETSC_DLLEXPORT PetscExceptionPop(PetscErrorCode);

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

    269: /*MC
    270:    PetscExceptionCaught - Indicates if exception zierr was caught.

    272:    Not Collective

    274:    Synopsis:
    275:      PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr);

    277:   Input Parameters:
    278:   + xierr - error code returned from PetscExceptionTry1()
    279:   - zierr - error code you want it to be

    281:   Level: advanced

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

    286:   Concepts: exceptions, exception hanlding

    288: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
    289:           CHKERRQ(), PetscExceptionTry1(), PetscExceptionValue()
    290: M*/
    291: PETSC_STATIC_INLINE PetscTruth PetscExceptionCaught(PetscErrorCode xierr,PetscErrorCode zierr) {
    292:   PetscInt i;
    293:   if (xierr != zierr) return PETSC_FALSE;
    294:   for (i=0; i<PetscErrorUncatchableCount; i++) {
    295:     if (PetscErrorUncatchable[i] == zierr) {
    296:       return PETSC_FALSE;
    297:     }
    298:   }
    299:   return PETSC_TRUE;
    300: }

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

    305:    Not Collective

    307:    Synopsis:
    308:      PetscTruth PetscExceptionValue(PetscErrorCode xierr);

    310:   Input Parameters:
    311:   . xierr - error code

    313:   Level: developer

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

    318:   Concepts: exceptions, exception hanlding

    320: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
    321:           CHKERRQ(), PetscExceptionTry1(), PetscExceptionCaught()
    322: M*/
    323: PETSC_STATIC_INLINE PetscTruth PetscExceptionValue(PetscErrorCode zierr) {
    324:   PetscInt i;
    325:   for (i=0; i<PetscExceptionsCount; i++) {
    326:     if (PetscExceptions[i] == zierr) {
    327:       return PETSC_TRUE;
    328:     }
    329:   }
    330:   return PETSC_FALSE;
    331: }

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

    338:    Not Collective

    340:    Synopsis:
    341:      PetscExceptionTry1(PetscErrorCode routine(....),PetscErrorCode);

    343:   Level: advanced

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

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

    352:   Concepts: exceptions, exception hanlding

    354: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
    355:           CHKERRQ(), PetscExceptionCaught()
    356: M*/
    358: #define PetscExceptionTry1(a,b) (PetscExceptionTmp = PetscExceptionPush(b)) ? PetscExceptionTmp : (PetscExceptionTmp = a , PetscExceptionPop(b),PetscExceptionTmp)

    360: #else
    361: #define SETERRQ(n,s) ;
    362: #define SETERRQ1(n,s,a1) ;
    363: #define SETERRQ2(n,s,a1,a2) ;
    364: #define SETERRQ3(n,s,a1,a2,a3) ;
    365: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
    366: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ;
    367: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6) ;
    368: #define SETERRABORT(comm,n,s) ;

    370: #define CHKERRQ(n)     ;
    371: #define CHKERRABORT(comm,n) ;
    372: #define CHKERRCONTINUE(n) ;

    374: #define CHKMEMQ        ;

    376: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
    377: #define _
    379: #endif

    381: #define PetscErrorSetCatchable(a,b) 0
    382: #define PetscExceptionCaught(a,b)   PETSC_FALSE
    383: #define PetscExceptionValue(a)      PETSC_FALSE
    384: #define PetscExceptionTry1(a,b)     a
    385: #endif

    387: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorPrintfInitialize(void);
    388: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscErrorMessage(int,const char*[],char **);
    389: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscTraceBackErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
    390: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscIgnoreErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
    391: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
    392: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscStopErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
    393: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAbortErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
    394: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*);
    395: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscError(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
    396: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,PetscErrorCode,int,const char*,void*),void*);
    397: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopErrorHandler(void);
    398: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDefaultSignalHandler(int,void*);
    399: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
    400: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscPopSignalHandler(void);

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

    405: /*
    406:       Allows the code to build a stack frame as it runs
    407: */
    408: #if defined(PETSC_USE_DEBUG)

    410: #define PETSCSTACKSIZE 15

    412: typedef struct  {
    413:   const char *function[PETSCSTACKSIZE];
    414:   const char *file[PETSCSTACKSIZE];
    415:   const char *directory[PETSCSTACKSIZE];
    416:         int  line[PETSCSTACKSIZE];
    417:         int currentsize;
    418: } PetscStack;

    421: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackCopy(PetscStack*,PetscStack*);
    422: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackPrint(PetscStack*,FILE* fp);

    424: #define PetscStackActive (petscstack != 0)

    427: /*MC
    429:         used for error handling.

    431:    Synopsis:

    434:    Usage:
    435: .vb
    436:      int something;

    439: .ve

    441:    Notes:
    442:      Not available in Fortran

    444:    Level: developer

    446: .seealso: PetscFunctionReturn()

    448: .keywords: traceback, error handling
    449: M*/
    451:   {\
    452:    if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
    453:     petscstack->function[petscstack->currentsize]  = __FUNCT__; \
    454:     petscstack->file[petscstack->currentsize]      = __FILE__; \
    455:     petscstack->directory[petscstack->currentsize] = __SDIR__; \
    456:     petscstack->line[petscstack->currentsize]      = __LINE__; \
    457:     petscstack->currentsize++; \
    458:   }}

    460: #define PetscStackPush(n) \
    461:   {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
    462:     petscstack->function[petscstack->currentsize]  = n; \
    463:     petscstack->file[petscstack->currentsize]      = "unknown"; \
    464:     petscstack->directory[petscstack->currentsize] = "unknown"; \
    465:     petscstack->line[petscstack->currentsize]      = 0; \
    466:     petscstack->currentsize++; \
    467:   }}

    469: #define PetscStackPop \
    470:   {if (petscstack && petscstack->currentsize > 0) {     \
    471:     petscstack->currentsize--; \
    472:     petscstack->function[petscstack->currentsize]  = 0; \
    473:     petscstack->file[petscstack->currentsize]      = 0; \
    474:     petscstack->directory[petscstack->currentsize] = 0; \
    475:     petscstack->line[petscstack->currentsize]      = 0; \
    476:   }};

    478: /*MC
    479:    PetscFunctionReturn - Last executable line of each PETSc function
    480:         used for error handling. Replaces return()

    482:    Synopsis:
    483:    void return(0);

    485:    Usage:
    486: .vb
    487:     ....
    488:      return(0);
    489:    }
    490: .ve

    492:    Notes:
    493:      Not available in Fortran

    495:    Level: developer

    499: .keywords: traceback, error handling
    500: M*/
    501: #define PetscFunctionReturn(a) \
    502:   {\
    503:   PetscStackPop; \
    504:   return(a);}

    506: #define PetscFunctionReturnVoid() \
    507:   {\
    508:   PetscStackPop; \
    509:   return;}

    512: #else

    515: #define PetscFunctionReturn(a)  return(a)
    516: #define PetscFunctionReturnVoid() return
    517: #define PetscStackPop
    518: #define PetscStackPush(f)
    519: #define PetscStackActive        0

    521: #endif

    523: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackCreate(void);
    524: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackView(PetscViewer);
    525: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackDestroy(void);
    526: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackPublish(void);
    527: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStackDepublish(void);

    531: #endif