xref: /petsc/include/petscerror.h (revision 8bf1f09cdf323e0dde0681283d9fd31df880e47d)
154a8ef01SBarry Smith /*
2f621e05eSBarry Smith     Contains all error handling interfaces for PETSc.
354a8ef01SBarry Smith */
445d48df9SBarry Smith #if !defined(__PETSCERROR_H)
545d48df9SBarry Smith #define __PETSCERROR_H
66c7e564aSBarry Smith 
7fcfd50ebSBarry Smith #if defined(PETSC_HAVE_STRING_H)
8fcfd50ebSBarry Smith #include <string.h> /* for strcmp */
9fcfd50ebSBarry Smith #endif
10fcfd50ebSBarry Smith 
11e9fa29b7SSatish Balay PETSC_EXTERN_CXX_BEGIN
12c22c1629SBarry Smith 
1354a8ef01SBarry Smith /*
1454a8ef01SBarry Smith    Defines the directory where the compiled source is located; used
155e97870eSBarry Smith    in printing error messages. Each makefile has an entry
165e97870eSBarry Smith    LOCDIR	  =  thedirectory
17330cf3c9SBarry Smith    and bmake/common_variables includes in CCPPFLAGS -D__SDIR__=${LOCDIR}
18f621e05eSBarry Smith    which is a flag passed to the C/C++ compilers. This declaration below
19f621e05eSBarry Smith    is only needed if some code is compiled without the -D__SDIR__
2054a8ef01SBarry Smith */
21330cf3c9SBarry Smith #if !defined(__INSDIR__)
22330cf3c9SBarry Smith #define __INSDIR__ "unknowndirectory/"
2354a8ef01SBarry Smith #endif
2454a8ef01SBarry Smith 
2554a8ef01SBarry Smith /*
264f227f7cSBarry Smith    Defines the function where the compiled source is located; used
27f621e05eSBarry Smith    in printing error messages. This is defined here in case the user
28f621e05eSBarry Smith    does not declare it.
294f227f7cSBarry Smith */
304a2ae208SSatish Balay #if !defined(__FUNCT__)
31da9b6338SBarry Smith #define __FUNCT__ "User provided function"
324f227f7cSBarry Smith #endif
334f227f7cSBarry Smith 
344f227f7cSBarry Smith /*
35329ffe3dSLois Curfman McInnes      These are the generic error codes. These error codes are used
36e2d1d2b7SBarry Smith      many different places in the PETSc source code. The string versions are
370e5e90baSSatish Balay      at src/sys/error/err.c any changes here must also be made there
380f9cf654SBarry Smith      These are also define in include/finclude/petscerror.h any CHANGES here
390f9cf654SBarry Smith      must be also made there.
4045d48df9SBarry Smith 
4154a8ef01SBarry Smith */
422a6744ebSBarry Smith #define PETSC_ERR_MIN_VALUE        54   /* should always be one less then the smallest value */
432a6744ebSBarry Smith 
4445d48df9SBarry Smith #define PETSC_ERR_MEM              55   /* unable to allocate requested memory */
4547794344SBarry Smith #define PETSC_ERR_SUP              56   /* no support for requested operation */
46e2d1d2b7SBarry Smith #define PETSC_ERR_SUP_SYS          57   /* no support for requested operation on this computer system */
47e2d1d2b7SBarry Smith #define PETSC_ERR_ORDER            58   /* operation done in wrong order */
4845d48df9SBarry Smith #define PETSC_ERR_SIG              59   /* signal received */
49f1caa5a4SBarry Smith #define PETSC_ERR_FP               72   /* floating point exception */
50a8c6a408SBarry Smith #define PETSC_ERR_COR              74   /* corrupted PETSc object */
51a8c6a408SBarry Smith #define PETSC_ERR_LIB              76   /* error in library called by PETSc */
52329ffe3dSLois Curfman McInnes #define PETSC_ERR_PLIB             77   /* PETSc library generated inconsistent data */
53329ffe3dSLois Curfman McInnes #define PETSC_ERR_MEMC             78   /* memory corruption */
54b3cc6726SBarry Smith #define PETSC_ERR_CONV_FAILED      82   /* iterative method (KSP or SNES) failed */
551302d50aSBarry Smith #define PETSC_ERR_USER             83   /* user has not provided needed function */
564e2ffeddSBarry Smith #define PETSC_ERR_SYS              88   /* error in system call */
5745d48df9SBarry Smith 
5845d48df9SBarry Smith #define PETSC_ERR_ARG_SIZ          60   /* nonconforming object sizes used in operation */
5945d48df9SBarry Smith #define PETSC_ERR_ARG_IDN          61   /* two arguments not allowed to be the same */
60a8c6a408SBarry Smith #define PETSC_ERR_ARG_WRONG        62   /* wrong argument (but object probably ok) */
6145d48df9SBarry Smith #define PETSC_ERR_ARG_CORRUPT      64   /* null or corrupted PETSc object as argument */
6245d48df9SBarry Smith #define PETSC_ERR_ARG_OUTOFRANGE   63   /* input argument, out of range */
634f227f7cSBarry Smith #define PETSC_ERR_ARG_BADPTR       68   /* invalid pointer argument */
644f227f7cSBarry Smith #define PETSC_ERR_ARG_NOTSAMETYPE  69   /* two args must be same object type */
656831982aSBarry Smith #define PETSC_ERR_ARG_NOTSAMECOMM  80   /* two args must be same communicators */
66d252947aSBarry Smith #define PETSC_ERR_ARG_WRONGSTATE   73   /* object in argument is in wrong state, e.g. unassembled mat */
678cda6cd7SBarry Smith #define PETSC_ERR_ARG_TYPENOTSET   89   /* the type of the object has not yet been set */
68a8c6a408SBarry Smith #define PETSC_ERR_ARG_INCOMP       75   /* two arguments are incompatible */
694482741eSBarry Smith #define PETSC_ERR_ARG_NULL         85   /* argument is null that should not be */
70958c9bccSBarry Smith #define PETSC_ERR_ARG_UNKNOWN_TYPE 86   /* type name doesn't match any registered type */
714f227f7cSBarry Smith 
724f227f7cSBarry Smith #define PETSC_ERR_FILE_OPEN        65   /* unable to open file */
734f227f7cSBarry Smith #define PETSC_ERR_FILE_READ        66   /* unable to read from file */
744f227f7cSBarry Smith #define PETSC_ERR_FILE_WRITE       67   /* unable to write to file */
75a8c6a408SBarry Smith #define PETSC_ERR_FILE_UNEXPECTED  79   /* unexpected data in file */
7645d48df9SBarry Smith 
77329ffe3dSLois Curfman McInnes #define PETSC_ERR_MAT_LU_ZRPVT     71   /* detected a zero pivot during LU factorization */
789e3b2f23SBarry Smith #define PETSC_ERR_MAT_CH_ZRPVT     81   /* detected a zero pivot during Cholesky factorization */
7954a8ef01SBarry Smith 
803855c12bSBarry Smith #define PETSC_ERR_INT_OVERFLOW     84   /* should always be one less then the smallest value */
813855c12bSBarry Smith 
82bf3909cdSBarry Smith #define PETSC_ERR_FLOP_COUNT       90
83e113a28aSBarry Smith #define PETSC_ERR_NOT_CONVERGED    91  /* solver did not converge */
84e113a28aSBarry Smith #define PETSC_ERR_MAX_VALUE        92  /* this is always the one more than the largest error code */
852a6744ebSBarry Smith 
8659aaf355SLisandro Dalcin #define PetscStringizeArg(a) #a
8759aaf355SLisandro Dalcin #define PetscStringize(a) PetscStringizeArg(a)
88330cf3c9SBarry Smith #define __SDIR__ PetscStringize(__INSDIR__)
89330cf3c9SBarry Smith 
90e8b7e333SSatish Balay #if defined(PETSC_USE_ERRORCHECKING)
91e8b7e333SSatish Balay 
9230de9b25SBarry Smith /*MC
9330de9b25SBarry Smith    SETERRQ - Macro that is called when an error has been detected,
9430de9b25SBarry Smith 
9530de9b25SBarry Smith    Synopsis:
96e7e72b3dSBarry Smith    PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode errorcode,char *message)
9730de9b25SBarry Smith 
98eca87e8dSBarry Smith    Not Collective
9930de9b25SBarry Smith 
10030de9b25SBarry Smith    Input Parameters:
10130de9b25SBarry Smith +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
10230de9b25SBarry Smith -  message - error message
10330de9b25SBarry Smith 
10430de9b25SBarry Smith   Level: beginner
10530de9b25SBarry Smith 
10630de9b25SBarry Smith    Notes:
10730de9b25SBarry Smith     Once the error handler is called the calling function is then returned from with the given error code.
10830de9b25SBarry Smith 
10930de9b25SBarry Smith     See SETERRQ1(), SETERRQ2(), SETERRQ3() for versions that take arguments
11030de9b25SBarry Smith 
11158ebbce7SBarry Smith     In Fortran MPI_Abort() is always called
11230de9b25SBarry Smith 
11330de9b25SBarry Smith     Experienced users can set the error handler with PetscPushErrorHandler().
11430de9b25SBarry Smith 
11530de9b25SBarry Smith    Concepts: error^setting condition
11630de9b25SBarry Smith 
11791d3bdf4SKris Buschelman .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
11830de9b25SBarry Smith M*/
11953c77d0aSJed Brown #define SETERRQ(comm,n,s)              return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s)
12030de9b25SBarry Smith 
12130de9b25SBarry Smith /*MC
12230de9b25SBarry Smith    SETERRQ1 - Macro that is called when an error has been detected,
12330de9b25SBarry Smith 
12430de9b25SBarry Smith    Synopsis:
125e32f2f54SBarry Smith    PetscErrorCode SETERRQ1(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg)
12630de9b25SBarry Smith 
127eca87e8dSBarry Smith    Not Collective
12830de9b25SBarry Smith 
12930de9b25SBarry Smith    Input Parameters:
13030de9b25SBarry Smith +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
13130de9b25SBarry Smith .  message - error message in the printf format
13230de9b25SBarry Smith -  arg - argument (for example an integer, string or double)
13330de9b25SBarry Smith 
13430de9b25SBarry Smith   Level: beginner
13530de9b25SBarry Smith 
13630de9b25SBarry Smith    Notes:
13730de9b25SBarry Smith     Once the error handler is called the calling function is then returned from with the given error code.
13830de9b25SBarry Smith 
13930de9b25SBarry Smith    Experienced users can set the error handler with PetscPushErrorHandler().
14030de9b25SBarry Smith 
14130de9b25SBarry Smith    Concepts: error^setting condition
14230de9b25SBarry Smith 
14391d3bdf4SKris Buschelman .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
14430de9b25SBarry Smith M*/
14553c77d0aSJed Brown #define SETERRQ1(comm,n,s,a1)          return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1)
14630de9b25SBarry Smith 
14730de9b25SBarry Smith /*MC
14830de9b25SBarry Smith    SETERRQ2 - Macro that is called when an error has been detected,
14930de9b25SBarry Smith 
15030de9b25SBarry Smith    Synopsis:
151f4442326SMatthew Knepley    PetscErrorCode SETERRQ2(PetscErrorCode errorcode,char *formatmessage,arg1,arg2)
15230de9b25SBarry Smith 
153eca87e8dSBarry Smith    Not Collective
15430de9b25SBarry Smith 
15530de9b25SBarry Smith    Input Parameters:
15630de9b25SBarry Smith +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
15730de9b25SBarry Smith .  message - error message in the printf format
15830de9b25SBarry Smith .  arg1 - argument (for example an integer, string or double)
15930de9b25SBarry Smith -  arg2 - argument (for example an integer, string or double)
16030de9b25SBarry Smith 
16130de9b25SBarry Smith   Level: beginner
16230de9b25SBarry Smith 
16330de9b25SBarry Smith    Notes:
16430de9b25SBarry Smith     Once the error handler is called the calling function is then returned from with the given error code.
16530de9b25SBarry Smith 
16630de9b25SBarry Smith    Experienced users can set the error handler with PetscPushErrorHandler().
16730de9b25SBarry Smith 
16830de9b25SBarry Smith    Concepts: error^setting condition
16930de9b25SBarry Smith 
1706024bd2cSBarry Smith .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
17130de9b25SBarry Smith M*/
17253c77d0aSJed Brown #define SETERRQ2(comm,n,s,a1,a2)       return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2)
17330de9b25SBarry Smith 
17430de9b25SBarry Smith /*MC
17530de9b25SBarry Smith    SETERRQ3 - Macro that is called when an error has been detected,
17630de9b25SBarry Smith 
17730de9b25SBarry Smith    Synopsis:
178f4442326SMatthew Knepley    PetscErrorCode SETERRQ3(PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)
17930de9b25SBarry Smith 
180eca87e8dSBarry Smith    Not Collective
18130de9b25SBarry Smith 
18230de9b25SBarry Smith    Input Parameters:
18330de9b25SBarry Smith +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
18430de9b25SBarry Smith .  message - error message in the printf format
18530de9b25SBarry Smith .  arg1 - argument (for example an integer, string or double)
18630de9b25SBarry Smith .  arg2 - argument (for example an integer, string or double)
18730de9b25SBarry Smith -  arg3 - argument (for example an integer, string or double)
18830de9b25SBarry Smith 
18930de9b25SBarry Smith   Level: beginner
19030de9b25SBarry Smith 
19130de9b25SBarry Smith    Notes:
19230de9b25SBarry Smith     Once the error handler is called the calling function is then returned from with the given error code.
19330de9b25SBarry Smith 
194f621e05eSBarry Smith     There are also versions for 4, 5, 6 and 7 arguments.
195f621e05eSBarry Smith 
19630de9b25SBarry Smith    Experienced users can set the error handler with PetscPushErrorHandler().
19730de9b25SBarry Smith 
19830de9b25SBarry Smith    Concepts: error^setting condition
19930de9b25SBarry Smith 
2006024bd2cSBarry Smith .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
20130de9b25SBarry Smith M*/
20253c77d0aSJed Brown #define SETERRQ3(comm,n,s,a1,a2,a3)    return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3)
20330de9b25SBarry Smith 
20453c77d0aSJed Brown #define SETERRQ4(comm,n,s,a1,a2,a3,a4) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4)
20553c77d0aSJed Brown #define SETERRQ5(comm,n,s,a1,a2,a3,a4,a5)       return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5)
20653c77d0aSJed Brown #define SETERRQ6(comm,n,s,a1,a2,a3,a4,a5,a6)    return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6)
20753c77d0aSJed Brown #define SETERRQ7(comm,n,s,a1,a2,a3,a4,a5,a6,a7) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7)
2082f3d0e1cSMatthew G Knepley #define SETERRQ8(comm,n,s,a1,a2,a3,a4,a5,a6,a7,a8) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7,a8)
20953c77d0aSJed Brown #define SETERRABORT(comm,n,s)     do {PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_INITIAL,s);MPI_Abort(comm,n);} while (0)
2109a00fa46SSatish Balay 
21130de9b25SBarry Smith /*MC
21230de9b25SBarry Smith    CHKERRQ - Checks error code, if non-zero it calls the error handler and then returns
21330de9b25SBarry Smith 
21430de9b25SBarry Smith    Synopsis:
215f4442326SMatthew Knepley    PetscErrorCode CHKERRQ(PetscErrorCode errorcode)
21630de9b25SBarry Smith 
217eca87e8dSBarry Smith    Not Collective
21830de9b25SBarry Smith 
21930de9b25SBarry Smith    Input Parameters:
22030de9b25SBarry Smith .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
22130de9b25SBarry Smith 
22230de9b25SBarry Smith   Level: beginner
22330de9b25SBarry Smith 
22430de9b25SBarry Smith    Notes:
22530de9b25SBarry Smith     Once the error handler is called the calling function is then returned from with the given error code.
22630de9b25SBarry Smith 
22730de9b25SBarry Smith     Experienced users can set the error handler with PetscPushErrorHandler().
2285324ea47SKris Buschelman 
229fcecf507SKris Buschelman     CHKERRQ(n) is fundamentally a macro replacement for
2305324ea47SKris Buschelman          if (n) return(PetscError(...,n,...));
2315324ea47SKris Buschelman 
2325324ea47SKris Buschelman     Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
2335324ea47SKris Buschelman     highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
2345324ea47SKris Buschelman     it cannot be used in functions which return(void) or any other datatype.  In these types of functions,
23558ebbce7SBarry Smith     you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or
2365324ea47SKris Buschelman          if (n) {PetscError(....); return(YourReturnType);}
23758ebbce7SBarry Smith     where you may pass back a PETSC_NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have
23858ebbce7SBarry Smith     MPI_Abort() returned immediately.
23958ebbce7SBarry Smith 
24058ebbce7SBarry Smith     In Fortran MPI_Abort() is always called
24130de9b25SBarry Smith 
24230de9b25SBarry Smith    Concepts: error^setting condition
24330de9b25SBarry Smith 
24491d3bdf4SKris Buschelman .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
24530de9b25SBarry Smith M*/
24653c77d0aSJed Brown #define CHKERRQ(n)             do {if (PetscUnlikely(n)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");} while (0)
24730de9b25SBarry Smith 
24853c77d0aSJed Brown #define CHKERRV(n)             do {if (PetscUnlikely(n)) {n = PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");return;}} while(0)
24953c77d0aSJed Brown #define CHKERRABORT(comm,n)    do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");MPI_Abort(comm,n);}} while (0)
25053c77d0aSJed Brown #define CHKERRCONTINUE(n)      do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_REPEAT," ");}} while (0)
25185614651SBarry Smith 
252fd705b32SMatthew Knepley #ifdef PETSC_CLANGUAGE_CXX
253fd705b32SMatthew Knepley 
254cc26af49SMatthew Knepley /*MC
255cc26af49SMatthew Knepley    CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception
256cc26af49SMatthew Knepley 
257cc26af49SMatthew Knepley    Synopsis:
258cc26af49SMatthew Knepley    void CHKERRXX(PetscErrorCode errorcode)
259cc26af49SMatthew Knepley 
260eca87e8dSBarry Smith    Not Collective
261cc26af49SMatthew Knepley 
262cc26af49SMatthew Knepley    Input Parameters:
263cc26af49SMatthew Knepley .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
264cc26af49SMatthew Knepley 
265cc26af49SMatthew Knepley   Level: beginner
266cc26af49SMatthew Knepley 
267cc26af49SMatthew Knepley    Notes:
268cc26af49SMatthew Knepley     Once the error handler throws a ??? exception.
269cc26af49SMatthew Knepley 
270cc26af49SMatthew Knepley     You can use CHKERRV() which returns without an error code (bad idea since the error is ignored)
271cc26af49SMatthew Knepley     or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately.
272cc26af49SMatthew Knepley 
273cc26af49SMatthew Knepley    Concepts: error^setting condition
274cc26af49SMatthew Knepley 
275cc26af49SMatthew Knepley .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ
276cc26af49SMatthew Knepley M*/
27753c77d0aSJed Brown #define CHKERRXX(n)            do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,n,PETSC_ERROR_IN_CXX,0);}} while(0)
278fd705b32SMatthew Knepley 
279fd705b32SMatthew Knepley #endif
280fd705b32SMatthew Knepley 
28130de9b25SBarry Smith /*MC
28230de9b25SBarry Smith    CHKMEMQ - Checks the memory for corruption, calls error handler if any is detected
28330de9b25SBarry Smith 
28430de9b25SBarry Smith    Synopsis:
28591d3bdf4SKris Buschelman    CHKMEMQ;
28630de9b25SBarry Smith 
287eca87e8dSBarry Smith    Not Collective
288eca87e8dSBarry Smith 
28930de9b25SBarry Smith   Level: beginner
29030de9b25SBarry Smith 
29130de9b25SBarry Smith    Notes:
292ff002950SBarry Smith     Must run with the option -malloc_debug to enable this option
29330de9b25SBarry Smith 
29430de9b25SBarry Smith     Once the error handler is called the calling function is then returned from with the given error code.
29530de9b25SBarry Smith 
29630de9b25SBarry Smith     By defaults prints location where memory that is corrupted was allocated.
29730de9b25SBarry Smith 
298f621e05eSBarry Smith     Use CHKMEMA for functions that return void
299f621e05eSBarry Smith 
30030de9b25SBarry Smith    Concepts: memory corruption
30130de9b25SBarry Smith 
3026024bd2cSBarry Smith .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
303ff002950SBarry Smith           PetscMallocValidate()
30430de9b25SBarry Smith M*/
30553c77d0aSJed Brown #define CHKMEMQ do {PetscErrorCode _7_ierr = PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__);CHKERRQ(_7_ierr);} while(0)
30685614651SBarry Smith 
30753c77d0aSJed Brown #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__)
308e68848bdSBarry Smith 
309f8e50935SSatish Balay #else /* PETSC_USE_ERRORCHECKING */
310f621e05eSBarry Smith 
311f621e05eSBarry Smith /*
312e2e64c6bSBarry Smith     These are defined to be empty for when error checking is turned off, with ./configure --with-errorchecking=0
313f621e05eSBarry Smith */
314f621e05eSBarry Smith 
3154b209cf6SBarry Smith #define SETERRQ(c,n,s)
3164b209cf6SBarry Smith #define SETERRQ1(c,n,s,a1)
3174b209cf6SBarry Smith #define SETERRQ2(c,n,s,a1,a2)
3184b209cf6SBarry Smith #define SETERRQ3(c,n,s,a1,a2,a3)
3194b209cf6SBarry Smith #define SETERRQ4(c,n,s,a1,a2,a3,a4)
3204b209cf6SBarry Smith #define SETERRQ5(c,n,s,a1,a2,a3,a4,a5)
3214b209cf6SBarry Smith #define SETERRQ6(c,n,s,a1,a2,a3,a4,a5,a6)
3224ef524e9SStefano Zampini #define SETERRQ7(c,n,s,a1,a2,a3,a4,a5,a6,a7)
3234ef524e9SStefano Zampini #define SETERRQ8(c,n,s,a1,a2,a3,a4,a5,a6,a7,a8)
3244b209cf6SBarry Smith #define SETERRABORT(comm,n,s)
32585614651SBarry Smith 
3264f227f7cSBarry Smith #define CHKERRQ(n)     ;
3271ee4faa0SMatthew Knepley #define CHKERRABORT(comm,n) ;
3281ee4faa0SMatthew Knepley #define CHKERRCONTINUE(n) ;
32985614651SBarry Smith #define CHKMEMQ        ;
33085614651SBarry Smith 
3318cabf42eSMatthew G Knepley #ifdef PETSC_CLANGUAGE_CXX
3328cabf42eSMatthew G Knepley #define CHKERRXX(n) ;
3338cabf42eSMatthew G Knepley #endif
3348cabf42eSMatthew G Knepley 
335f8e50935SSatish Balay #endif /* PETSC_USE_ERRORCHECKING */
33654a8ef01SBarry Smith 
337668f157eSBarry Smith /*E
338668f157eSBarry Smith   PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers
339668f157eSBarry Smith 
340668f157eSBarry Smith   Level: advanced
341668f157eSBarry Smith 
342d736bfebSBarry Smith   PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated
343d736bfebSBarry Smith 
344668f157eSBarry Smith   Developer Notes: This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandling()
345668f157eSBarry Smith 
346d736bfebSBarry Smith .seealso: PetscError(), SETERRXX()
347668f157eSBarry Smith E*/
348d736bfebSBarry Smith typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType;
3494b209cf6SBarry Smith 
3507087cfbeSBarry Smith extern PetscErrorCode  PetscErrorPrintfInitialize(void);
3517087cfbeSBarry Smith extern PetscErrorCode  PetscErrorMessage(int,const char*[],char **);
3527087cfbeSBarry Smith extern PetscErrorCode  PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
3537087cfbeSBarry Smith extern PetscErrorCode  PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
3547087cfbeSBarry Smith extern PetscErrorCode  PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
3557087cfbeSBarry Smith extern PetscErrorCode  PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
3567087cfbeSBarry Smith extern PetscErrorCode  PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
3577087cfbeSBarry Smith extern PetscErrorCode  PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
3587087cfbeSBarry Smith extern PetscErrorCode  PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
3597087cfbeSBarry Smith extern PetscErrorCode  PetscError(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...);
3607087cfbeSBarry Smith extern PetscErrorCode  PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*);
3617087cfbeSBarry Smith extern PetscErrorCode  PetscPopErrorHandler(void);
3627087cfbeSBarry Smith extern PetscErrorCode  PetscDefaultSignalHandler(int,void*);
3637087cfbeSBarry Smith extern PetscErrorCode  PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
3647087cfbeSBarry Smith extern PetscErrorCode  PetscPopSignalHandler(void);
365329f5518SBarry Smith 
366329f5518SBarry Smith typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
3677087cfbeSBarry Smith extern PetscErrorCode   PetscSetFPTrap(PetscFPTrap);
368670f3ff9SJed Brown extern PetscErrorCode PetscFPTrapPush(PetscFPTrap);
369670f3ff9SJed Brown extern PetscErrorCode PetscFPTrapPop(void);
37054a8ef01SBarry Smith 
3713a40ed3dSBarry Smith /*
3723a40ed3dSBarry Smith       Allows the code to build a stack frame as it runs
3733a40ed3dSBarry Smith */
374*8bf1f09cSShri Abhyankar #if defined(PETSC_USE_DEBUG)
3753a40ed3dSBarry Smith 
37699cd645aSJed Brown #define PETSCSTACKSIZE 64
377184914b5SBarry Smith 
3783a40ed3dSBarry Smith typedef struct  {
3790e33f6ddSBarry Smith   const char *function[PETSCSTACKSIZE];
3800e33f6ddSBarry Smith   const char *file[PETSCSTACKSIZE];
3810e33f6ddSBarry Smith   const char *directory[PETSCSTACKSIZE];
382184914b5SBarry Smith         int  line[PETSCSTACKSIZE];
383184914b5SBarry Smith         int currentsize;
3843a40ed3dSBarry Smith } PetscStack;
3853a40ed3dSBarry Smith 
386fe89fe5aSShri Abhyankar #if defined(PETSC_ThreadLocal)
387fe89fe5aSShri Abhyankar extern  PETSC_ThreadLocal PetscStack *petscstack;
388fe89fe5aSShri Abhyankar #else
3897087cfbeSBarry Smith extern PetscStack *petscstack;
390fe89fe5aSShri Abhyankar #endif
3917087cfbeSBarry Smith extern PetscErrorCode   PetscStackCopy(PetscStack*,PetscStack*);
3927087cfbeSBarry Smith extern PetscErrorCode   PetscStackPrint(PetscStack*,FILE* fp);
393184914b5SBarry Smith 
394184914b5SBarry Smith #define PetscStackActive (petscstack != 0)
3953a40ed3dSBarry Smith 
39630de9b25SBarry Smith /*MC
39730de9b25SBarry Smith    PetscFunctionBegin - First executable line of each PETSc function
39830de9b25SBarry Smith         used for error handling.
39930de9b25SBarry Smith 
40030de9b25SBarry Smith    Synopsis:
40130de9b25SBarry Smith    void PetscFunctionBegin;
40230de9b25SBarry Smith 
403eca87e8dSBarry Smith    Not Collective
404eca87e8dSBarry Smith 
40530de9b25SBarry Smith    Usage:
40630de9b25SBarry Smith .vb
40730de9b25SBarry Smith      int something;
40830de9b25SBarry Smith 
40930de9b25SBarry Smith      PetscFunctionBegin;
41030de9b25SBarry Smith .ve
41130de9b25SBarry Smith 
41230de9b25SBarry Smith    Notes:
41330de9b25SBarry Smith      Not available in Fortran
41430de9b25SBarry Smith 
41530de9b25SBarry Smith    Level: developer
41630de9b25SBarry Smith 
41730de9b25SBarry Smith .seealso: PetscFunctionReturn()
41830de9b25SBarry Smith 
41930de9b25SBarry Smith .keywords: traceback, error handling
42030de9b25SBarry Smith M*/
4213a40ed3dSBarry Smith #define PetscFunctionBegin \
4228246ba0dSJed Brown   do {                                                                  \
423184914b5SBarry Smith     if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {     \
42453c77d0aSJed Brown       petscstack->function[petscstack->currentsize]  = PETSC_FUNCTION_NAME; \
425184914b5SBarry Smith       petscstack->file[petscstack->currentsize]      = __FILE__;        \
426184914b5SBarry Smith       petscstack->directory[petscstack->currentsize] = __SDIR__;        \
427184914b5SBarry Smith       petscstack->line[petscstack->currentsize]      = __LINE__;        \
428184914b5SBarry Smith       petscstack->currentsize++;                                        \
42953c77d0aSJed Brown     }                                                                   \
43053c77d0aSJed Brown     PetscCheck__FUNCT__();                                              \
43153c77d0aSJed Brown   } while (0)
43253c77d0aSJed Brown 
43353c77d0aSJed Brown #define PetscCheck__FUNCT__() do { \
43453c77d0aSJed Brown     if (strcmp(PETSC_FUNCTION_NAME,__FUNCT__) && strcmp(__FUNCT__,"User provided function")) { \
43553c77d0aSJed Brown       (*PetscErrorPrintf)("%s%s:%d: __FUNCT__=\"%s\" does not agree with %s=\"%s\"\n",__SDIR__,__FILE__,__LINE__,__FUNCT__,PetscStringize(PETSC_FUNCTION_NAME),PETSC_FUNCTION_NAME); \
43653c77d0aSJed Brown     }                                                                   \
43753c77d0aSJed Brown   } while (0)
4383a40ed3dSBarry Smith 
4395cd90555SBarry Smith #define PetscStackPush(n) \
4408246ba0dSJed Brown   do {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
441184914b5SBarry Smith     petscstack->function[petscstack->currentsize]  = n; \
442184914b5SBarry Smith     petscstack->file[petscstack->currentsize]      = "unknown"; \
443184914b5SBarry Smith     petscstack->directory[petscstack->currentsize] = "unknown"; \
444184914b5SBarry Smith     petscstack->line[petscstack->currentsize]      = 0; \
445184914b5SBarry Smith     petscstack->currentsize++; \
446812af9f3SBarry Smith   } CHKMEMQ;} while (0)
4473a40ed3dSBarry Smith 
448d64ed03dSBarry Smith #define PetscStackPop \
449812af9f3SBarry Smith   do {CHKMEMQ; if (petscstack && petscstack->currentsize > 0) {	\
450184914b5SBarry Smith     petscstack->currentsize--; \
451184914b5SBarry Smith     petscstack->function[petscstack->currentsize]  = 0; \
452184914b5SBarry Smith     petscstack->file[petscstack->currentsize]      = 0; \
453184914b5SBarry Smith     petscstack->directory[petscstack->currentsize] = 0; \
454184914b5SBarry Smith     petscstack->line[petscstack->currentsize]      = 0; \
4558246ba0dSJed Brown   }} while (0)
456d64ed03dSBarry Smith 
45730de9b25SBarry Smith /*MC
45830de9b25SBarry Smith    PetscFunctionReturn - Last executable line of each PETSc function
45930de9b25SBarry Smith         used for error handling. Replaces return()
46030de9b25SBarry Smith 
46130de9b25SBarry Smith    Synopsis:
46230de9b25SBarry Smith    void PetscFunctionReturn(0);
46330de9b25SBarry Smith 
464eca87e8dSBarry Smith    Not Collective
465eca87e8dSBarry Smith 
46630de9b25SBarry Smith    Usage:
46730de9b25SBarry Smith .vb
46830de9b25SBarry Smith     ....
46930de9b25SBarry Smith      PetscFunctionReturn(0);
47030de9b25SBarry Smith    }
47130de9b25SBarry Smith .ve
47230de9b25SBarry Smith 
47330de9b25SBarry Smith    Notes:
47430de9b25SBarry Smith      Not available in Fortran
47530de9b25SBarry Smith 
47630de9b25SBarry Smith    Level: developer
47730de9b25SBarry Smith 
47830de9b25SBarry Smith .seealso: PetscFunctionBegin()
47930de9b25SBarry Smith 
48030de9b25SBarry Smith .keywords: traceback, error handling
48130de9b25SBarry Smith M*/
4825cd90555SBarry Smith #define PetscFunctionReturn(a) \
4838246ba0dSJed Brown   do {\
484812af9f3SBarry Smith   if (petscstack && petscstack->currentsize > 0) {	\
485812af9f3SBarry Smith     petscstack->currentsize--; \
486812af9f3SBarry Smith     petscstack->function[petscstack->currentsize]  = 0; \
487812af9f3SBarry Smith     petscstack->file[petscstack->currentsize]      = 0; \
488812af9f3SBarry Smith     petscstack->directory[petscstack->currentsize] = 0; \
489812af9f3SBarry Smith     petscstack->line[petscstack->currentsize]      = 0; \
490812af9f3SBarry Smith   }\
4918246ba0dSJed Brown   return(a);} while (0)
492d64ed03dSBarry Smith 
493ff94ddecSSatish Balay #define PetscFunctionReturnVoid() \
4948246ba0dSJed Brown   do {\
495812af9f3SBarry Smith   if (petscstack && petscstack->currentsize > 0) {	\
496812af9f3SBarry Smith     petscstack->currentsize--; \
497812af9f3SBarry Smith     petscstack->function[petscstack->currentsize]  = 0; \
498812af9f3SBarry Smith     petscstack->file[petscstack->currentsize]      = 0; \
499812af9f3SBarry Smith     petscstack->directory[petscstack->currentsize] = 0; \
500812af9f3SBarry Smith     petscstack->line[petscstack->currentsize]      = 0; \
501812af9f3SBarry Smith   }\
5028246ba0dSJed Brown   return;} while (0)
503ff94ddecSSatish Balay 
5046d385327SIbrahima Ba #else
5056d385327SIbrahima Ba 
5063a40ed3dSBarry Smith #define PetscFunctionBegin
5073a40ed3dSBarry Smith #define PetscFunctionReturn(a)  return(a)
5085665465eSBarry Smith #define PetscFunctionReturnVoid() return
509812af9f3SBarry Smith #define PetscStackPop     CHKMEMQ
510812af9f3SBarry Smith #define PetscStackPush(f) CHKMEMQ
511d64ed03dSBarry Smith #define PetscStackActive        0
5123a40ed3dSBarry Smith 
5133a40ed3dSBarry Smith #endif
5143a40ed3dSBarry Smith 
515eb6b5d47SBarry Smith /*
516eb6b5d47SBarry Smith     PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack.
517eb6b5d47SBarry Smith 
518eb6b5d47SBarry Smith    Input Parameters:
519eb6b5d47SBarry Smith +   name - string that gives the name of the function being called
520eb6b5d47SBarry Smith -   routine - actual call to the routine
521eb6b5d47SBarry Smith 
522eb6b5d47SBarry Smith    Developer Note: this is so that when a user or external library routine results in a crash or corrupts memory, they get blamed instead of PETSc.
523eb6b5d47SBarry Smith 
524eb6b5d47SBarry Smith */
525eb6b5d47SBarry Smith #define PetscStackCall(name,routine) PetscStackPush(name);routine;PetscStackPop;
526eb6b5d47SBarry Smith 
5277087cfbeSBarry Smith extern PetscErrorCode   PetscStackCreate(void);
5287087cfbeSBarry Smith extern PetscErrorCode   PetscStackView(PetscViewer);
5297087cfbeSBarry Smith extern PetscErrorCode   PetscStackDestroy(void);
5307087cfbeSBarry Smith extern PetscErrorCode   PetscStackPublish(void);
5317087cfbeSBarry Smith extern PetscErrorCode   PetscStackDepublish(void);
5323a40ed3dSBarry Smith 
53306d1fe2cSBarry Smith 
534e9fa29b7SSatish Balay PETSC_EXTERN_CXX_END
53506d1fe2cSBarry Smith #endif
536