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

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

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

     69: #if defined(PETSC_USE_DEBUG)

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

     74:    Not Collective

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

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

     84:   Level: beginner

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

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

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

     94:    Concepts: error^setting condition

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

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

    103:    Not Collective

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

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

    114:   Level: beginner

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

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

    121:    Concepts: error^setting condition

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

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

    130:    Not Collective

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

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

    142:   Level: beginner

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

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

    149:    Concepts: error^setting condition

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

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

    158:    Not Collective

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

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

    171:   Level: beginner

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

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

    178:    Concepts: error^setting condition

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

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

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

    193:    Not Collective

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

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

    202:   Level: beginner

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

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

    209:    Concepts: error^setting condition

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

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

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

    221:    Not Collective

    223:    Synopsis:
    224:    CHKMEMQ;

    226:   Level: beginner

    228:    Notes:
    229:     Must run with the option -trdebug to enable this option

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

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

    235:    Concepts: memory corruption

    237: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2(),
    238:           PetscTrValid()
    239: M*/
    240: #define CHKMEMQ {PetscErrorCode _7_PetscTrValid(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}

    242: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
    244: #define _   __g
    246: #endif

    248: #else
    249: #define SETERRQ(n,s) ;
    250: #define SETERRQ1(n,s,a1) ;
    251: #define SETERRQ2(n,s,a1,a2) ;
    252: #define SETERRQ3(n,s,a1,a2,a3) ;
    253: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
    254: #define SETERRQ5(n,s,a1,a2,a3,a4,a5) ;
    255: #define SETERRABORT(comm,n,s) ;

    257: #define CHKERRQ(n)     ;
    258: #define CHKERRABORT(comm,n) ;
    259: #define CHKERRCONTINUE(n) ;

    261: #define CHKMEMQ        ;

    263: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
    264: #define _
    266: #endif

    268: #endif

    270: EXTERN PetscErrorCode PetscErrorPrintfInitialize(void);
    271: EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **);
    272: EXTERN PetscErrorCode PetscTraceBackErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
    273: EXTERN PetscErrorCode PetscIgnoreErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
    274: EXTERN PetscErrorCode PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
    275: EXTERN PetscErrorCode PetscStopErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
    276: EXTERN PetscErrorCode PetscAbortErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
    277: EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
    278: EXTERN PetscErrorCode PetscError(int,const char*,const char*,const char*,int,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
    279: EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(int,const char*,const char*,const char*,int,int,const char*,void*),void*);
    280: EXTERN PetscErrorCode PetscPopErrorHandler(void);
    281: EXTERN PetscErrorCode PetscDefaultSignalHandler(int,void*);
    282: EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
    283: EXTERN PetscErrorCode PetscPopSignalHandler(void);

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

    288: /*
    289:       Allows the code to build a stack frame as it runs
    290: */
    291: #if defined(PETSC_USE_STACK)

    293: #define PETSCSTACKSIZE 15

    295: typedef struct  {
    296:   const char *function[PETSCSTACKSIZE];
    297:   const char *file[PETSCSTACKSIZE];
    298:   const char *directory[PETSCSTACKSIZE];
    299:         int  line[PETSCSTACKSIZE];
    300:         int currentsize;
    301: } PetscStack;

    304: EXTERN PetscErrorCode PetscStackCopy(PetscStack*,PetscStack*);
    305: EXTERN PetscErrorCode PetscStackPrint(PetscStack*,FILE* fp);

    307: #define PetscStackActive (petscstack != 0)

    310: /*MC
    312:         used for error handling.

    314:    Synopsis:

    317:    Usage:
    318: .vb
    319:      int something;

    322: .ve

    324:    Notes:
    325:      Not available in Fortran

    327:    Level: developer

    329: .seealso: PetscFunctionReturn()

    331: .keywords: traceback, error handling
    332: M*/
    334:   {\
    335:    if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
    336:     petscstack->function[petscstack->currentsize]  = __FUNCT__; \
    337:     petscstack->file[petscstack->currentsize]      = __FILE__; \
    338:     petscstack->directory[petscstack->currentsize] = __SDIR__; \
    339:     petscstack->line[petscstack->currentsize]      = __LINE__; \
    340:     petscstack->currentsize++; \
    341:   }}

    343: #define PetscStackPush(n) \
    344:   {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
    345:     petscstack->function[petscstack->currentsize]  = n; \
    346:     petscstack->file[petscstack->currentsize]      = "unknown"; \
    347:     petscstack->directory[petscstack->currentsize] = "unknown"; \
    348:     petscstack->line[petscstack->currentsize]      = 0; \
    349:     petscstack->currentsize++; \
    350:   }}

    352: #define PetscStackPop \
    353:   {if (petscstack && petscstack->currentsize > 0) {     \
    354:     petscstack->currentsize--; \
    355:     petscstack->function[petscstack->currentsize]  = 0; \
    356:     petscstack->file[petscstack->currentsize]      = 0; \
    357:     petscstack->directory[petscstack->currentsize] = 0; \
    358:     petscstack->line[petscstack->currentsize]      = 0; \
    359:   }};

    361: /*MC
    362:    PetscFunctionReturn - Last executable line of each PETSc function
    363:         used for error handling. Replaces return()

    365:    Synopsis:
    366:    void return(0);

    368:    Usage:
    369: .vb
    370:     ....
    371:      return(0);
    372:    }
    373: .ve

    375:    Notes:
    376:      Not available in Fortran

    378:    Level: developer

    382: .keywords: traceback, error handling
    383: M*/
    384: #define PetscFunctionReturn(a) \
    385:   {\
    386:   PetscStackPop; \
    387:   return(a);}

    389: #define PetscFunctionReturnVoid() \
    390:   {\
    391:   PetscStackPop; \
    392:   return;}

    395: #else

    398: #define PetscFunctionReturn(a)  return(a)
    399: #define PetscFunctionReturnVoid() return()
    400: #define PetscStackPop
    401: #define PetscStackPush(f)
    402: #define PetscStackActive        0

    404: #endif

    406: EXTERN PetscErrorCode PetscStackCreate(void);
    407: EXTERN PetscErrorCode PetscStackView(PetscViewer);
    408: EXTERN PetscErrorCode PetscStackDestroy(void);
    409: EXTERN PetscErrorCode PetscStackPublish(void);
    410: EXTERN PetscErrorCode PetscStackDepublish(void);

    414: #endif