Actual source code: petscerror.h

petsc-3.6.1 2015-07-22
Report Typos and Errors
  1: /*
  2:     Contains all error handling interfaces for PETSc.
  3: */

  7: /*
  8:    Defines the function where the compiled source is located; used
  9:    in printing error messages. This is defined here in case the user
 10:    does not declare it.
 11: */
 14: #endif

 16: /*
 17:      These are the generic error codes. These error codes are used
 18:      many different places in the PETSc source code. The string versions are
 19:      at src/sys/error/err.c any changes here must also be made there
 20:      These are also define in include/petsc/finclude/petscerror.h any CHANGES here
 21:      must be also made there.

 23: */
 24: #define PETSC_ERR_MIN_VALUE        54   /* should always be one less then the smallest value */

 26: #define PETSC_ERR_MEM              55   /* unable to allocate requested memory */
 27: #define PETSC_ERR_SUP              56   /* no support for requested operation */
 28: #define PETSC_ERR_SUP_SYS          57   /* no support for requested operation on this computer system */
 29: #define PETSC_ERR_ORDER            58   /* operation done in wrong order */
 30: #define PETSC_ERR_SIG              59   /* signal received */
 31: #define PETSC_ERR_FP               72   /* floating point exception */
 32: #define PETSC_ERR_COR              74   /* corrupted PETSc object */
 33: #define PETSC_ERR_LIB              76   /* error in library called by PETSc */
 34: #define PETSC_ERR_PLIB             77   /* PETSc library generated inconsistent data */
 35: #define PETSC_ERR_MEMC             78   /* memory corruption */
 36: #define PETSC_ERR_CONV_FAILED      82   /* iterative method (KSP or SNES) failed */
 37: #define PETSC_ERR_USER             83   /* user has not provided needed function */
 38: #define PETSC_ERR_SYS              88   /* error in system call */
 39: #define PETSC_ERR_POINTER          70   /* pointer does not point to valid address */

 41: #define PETSC_ERR_ARG_SIZ          60   /* nonconforming object sizes used in operation */
 42: #define PETSC_ERR_ARG_IDN          61   /* two arguments not allowed to be the same */
 43: #define PETSC_ERR_ARG_WRONG        62   /* wrong argument (but object probably ok) */
 44: #define PETSC_ERR_ARG_CORRUPT      64   /* null or corrupted PETSc object as argument */
 45: #define PETSC_ERR_ARG_OUTOFRANGE   63   /* input argument, out of range */
 46: #define PETSC_ERR_ARG_BADPTR       68   /* invalid pointer argument */
 47: #define PETSC_ERR_ARG_NOTSAMETYPE  69   /* two args must be same object type */
 48: #define PETSC_ERR_ARG_NOTSAMECOMM  80   /* two args must be same communicators */
 49: #define PETSC_ERR_ARG_WRONGSTATE   73   /* object in argument is in wrong state, e.g. unassembled mat */
 50: #define PETSC_ERR_ARG_TYPENOTSET   89   /* the type of the object has not yet been set */
 51: #define PETSC_ERR_ARG_INCOMP       75   /* two arguments are incompatible */
 52: #define PETSC_ERR_ARG_NULL         85   /* argument is null that should not be */
 53: #define PETSC_ERR_ARG_UNKNOWN_TYPE 86   /* type name doesn't match any registered type */

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

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

 63: #define PETSC_ERR_INT_OVERFLOW     84

 65: #define PETSC_ERR_FLOP_COUNT       90
 66: #define PETSC_ERR_NOT_CONVERGED    91  /* solver did not converge */
 67: #define PETSC_ERR_MISSING_FACTOR   92  /* MatGetFactor() failed */
 68: #define PETSC_ERR_MAX_VALUE        93  /* this is always the one more than the largest error code */

 70: #define PetscStringizeArg(a) #a
 71: #define PetscStringize(a) PetscStringizeArg(a)

 73: #if defined(PETSC_USE_ERRORCHECKING)

 75: /*MC
 76:    SETERRQ - Macro to be called when an error has been detected,

 78:    Synopsis:
 79:    #include <petscsys.h>
 80:    PetscErrorCode SETERRQ(MPI_Comm comm,PetscErrorCode errorcode,char *message)

 82:    Not Collective

 84:    Input Parameters:
 85: +  comm - A communicator, so that the error can be collective
 86: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
 87: -  message - error message

 89:   Level: beginner

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

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

 96:     In Fortran MPI_Abort() is always called

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

100:    Concepts: error^setting condition

102: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3()
103: M*/
104: #define SETERRQ(comm,n,s)              return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s)

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

109:    Synopsis:
110:    #include <petscsys.h>
111:    PetscErrorCode SETERRQ1(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg)

113:    Not Collective

115:    Input Parameters:
116: +  comm - A communicator, so that the error can be collective
117: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
118: .  message - error message in the printf format
119: -  arg - argument (for example an integer, string or double)

121:   Level: beginner

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

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

128:    Concepts: error^setting condition

130: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ(), SETERRQ2(), SETERRQ3()
131: M*/
132: #define SETERRQ1(comm,n,s,a1)          return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1)

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

137:    Synopsis:
138:    #include <petscsys.h>
139:    PetscErrorCode SETERRQ2(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2)

141:    Not Collective

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

150:   Level: beginner

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

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

157:    Concepts: error^setting condition

159: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ3()
160: M*/
161: #define SETERRQ2(comm,n,s,a1,a2)       return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2)

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

166:    Synopsis:
167:    #include <petscsys.h>
168:    PetscErrorCode SETERRQ3(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

170:    Not Collective

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

180:   Level: beginner

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

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

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

189:    Concepts: error^setting condition

191: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
192: M*/
193: #define SETERRQ3(comm,n,s,a1,a2,a3)    return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3)

195: /*MC
196:    SETERRQ4 - Macro that is called when an error has been detected,

198:    Synopsis:
199:    #include <petscsys.h>
200:    PetscErrorCode SETERRQ4(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

202:    Not Collective

204:    Input Parameters:
205: +  comm - A communicator, so that the error can be collective
206: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
207: .  message - error message in the printf format
208: .  arg1 - argument (for example an integer, string or double)
209: .  arg2 - argument (for example an integer, string or double)
210: .  arg3 - argument (for example an integer, string or double)
211: -  arg4 - argument (for example an integer, string or double)

213:   Level: beginner

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

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

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

222:    Concepts: error^setting condition

224: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
225: M*/
226: #define SETERRQ4(comm,n,s,a1,a2,a3,a4) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4)

228: /*MC
229:    SETERRQ5 - Macro that is called when an error has been detected,

231:    Synopsis:
232:    #include <petscsys.h>
233:    PetscErrorCode SETERRQ5(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

235:    Not Collective

237:    Input Parameters:
238: +  comm - A communicator, so that the error can be collective
239: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
240: .  message - error message in the printf format
241: .  arg1 - argument (for example an integer, string or double)
242: .  arg2 - argument (for example an integer, string or double)
243: .  arg3 - argument (for example an integer, string or double)
244: .  arg4 - argument (for example an integer, string or double)
245: -  arg5 - argument (for example an integer, string or double)

247:   Level: beginner

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

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

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

256:    Concepts: error^setting condition

258: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
259: M*/
260: #define SETERRQ5(comm,n,s,a1,a2,a3,a4,a5)       return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5)

262: /*MC
263:    SETERRQ6 - Macro that is called when an error has been detected,

265:    Synopsis:
266:    #include <petscsys.h>
267:    PetscErrorCode SETERRQ6(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

269:    Not Collective

271:    Input Parameters:
272: +  comm - A communicator, so that the error can be collective
273: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
274: .  message - error message in the printf format
275: .  arg1 - argument (for example an integer, string or double)
276: .  arg2 - argument (for example an integer, string or double)
277: .  arg3 - argument (for example an integer, string or double)
278: .  arg4 - argument (for example an integer, string or double)
279: .  arg5 - argument (for example an integer, string or double)
280: -  arg6 - argument (for example an integer, string or double)

282:   Level: beginner

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

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

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

291:    Concepts: error^setting condition

293: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
294: M*/
295: #define SETERRQ6(comm,n,s,a1,a2,a3,a4,a5,a6)    return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6)

297: /*MC
298:    SETERRQ7 - Macro that is called when an error has been detected,

300:    Synopsis:
301:    #include <petscsys.h>
302:    PetscErrorCode SETERRQ7(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

304:    Not Collective

306:    Input Parameters:
307: +  comm - A communicator, so that the error can be collective
308: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
309: .  message - error message in the printf format
310: .  arg1 - argument (for example an integer, string or double)
311: .  arg2 - argument (for example an integer, string or double)
312: .  arg3 - argument (for example an integer, string or double)
313: .  arg4 - argument (for example an integer, string or double)
314: .  arg5 - argument (for example an integer, string or double)
315: .  arg6 - argument (for example an integer, string or double)
316: -  arg7 - argument (for example an integer, string or double)

318:   Level: beginner

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

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

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

327:    Concepts: error^setting condition

329: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
330: M*/
331: #define SETERRQ7(comm,n,s,a1,a2,a3,a4,a5,a6,a7) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7)

333: /*MC
334:    SETERRQ8 - Macro that is called when an error has been detected,

336:    Synopsis:
337:    #include <petscsys.h>
338:    PetscErrorCode SETERRQ8(MPI_Comm comm,PetscErrorCode errorcode,char *formatmessage,arg1,arg2,arg3)

340:    Not Collective

342:    Input Parameters:
343: +  comm - A communicator, so that the error can be collective
344: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
345: .  message - error message in the printf format
346: .  arg1 - argument (for example an integer, string or double)
347: .  arg2 - argument (for example an integer, string or double)
348: .  arg3 - argument (for example an integer, string or double)
349: .  arg4 - argument (for example an integer, string or double)
350: .  arg5 - argument (for example an integer, string or double)
351: .  arg6 - argument (for example an integer, string or double)
352: .  arg7 - argument (for example an integer, string or double)
353: -  arg8 - argument (for example an integer, string or double)

355:   Level: beginner

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

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

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

364:    Concepts: error^setting condition

366: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
367: M*/
368: #define SETERRQ8(comm,n,s,a1,a2,a3,a4,a5,a6,a7,a8) return PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s,a1,a2,a3,a4,a5,a6,a7,a8)

370: /*MC
371:    SETERRABORT - Macro that can be called when an error has been detected,

373:    Synopsis:
374:    #include <petscsys.h>
375:    PetscErrorCode SETERRABORT(MPI_Comm comm,PetscErrorCode errorcode,char *message)

377:    Not Collective

379:    Input Parameters:
380: +  comm - A communicator, so that the error can be collective
381: .  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
382: -  message - error message in the printf format

384:   Level: beginner

386:    Notes:
387:     This function just calls MPI_Abort().

389:    Concepts: error^setting condition

391: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), CHKERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2()
392: M*/
393: #define SETERRABORT(comm,n,s)     do {PetscError(comm,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_INITIAL,s);MPI_Abort(comm,n);} while (0)

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

398:    Synopsis:
399:    #include <petscsys.h>
400:    PetscErrorCode CHKERRQ(PetscErrorCode errorcode)

402:    Not Collective

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

407:   Level: beginner

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

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

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

417:     Although typical usage resembles "void CHKERRQ(PetscErrorCode)" as described above, for certain uses it is
418:     highly inappropriate to use it in this manner as it invokes return(PetscErrorCode). In particular,
419:     it cannot be used in functions which return(void) or any other datatype.  In these types of functions,
420:     you can use CHKERRV() which returns without an error code (bad idea since the error is ignored or
421:          if (n) {PetscError(....); return(YourReturnType);}
422:     where you may pass back a NULL to indicate an error. You can also call CHKERRABORT(comm,n) to have
423:     MPI_Abort() returned immediately.

425:     In Fortran MPI_Abort() is always called

427:    Concepts: error^setting condition

429: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2()
430: M*/
431: #define CHKERRQ(n)             do {if (PetscUnlikely(n)) return PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_REPEAT," ");} while (0)

433: #define CHKERRV(n)             do {if (PetscUnlikely(n)) {n = PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_REPEAT," ");return;}} while(0)
434: #define CHKERRABORT(comm,n)    do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_REPEAT," ");MPI_Abort(comm,n);}} while (0)
435: #define CHKERRCONTINUE(n)      do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_REPEAT," ");}} while (0)

437: #ifdef PETSC_CLANGUAGE_CXX

439: /*MC
440:    CHKERRXX - Checks error code, if non-zero it calls the C++ error handler which throws an exception

442:    Synopsis:
443:    #include <petscsys.h>
444:    void CHKERRXX(PetscErrorCode errorcode)

446:    Not Collective

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

451:   Level: beginner

453:    Notes:
454:     Once the error handler throws a ??? exception.

456:     You can use CHKERRV() which returns without an error code (bad idea since the error is ignored)
457:     or CHKERRABORT(comm,n) to have MPI_Abort() returned immediately.

459:    Concepts: error^setting condition

461: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKERRQ(), CHKMEMQ
462: M*/
463: #define CHKERRXX(n)            do {if (PetscUnlikely(n)) {PetscError(PETSC_COMM_SELF,__LINE__,PETSC_FUNCTION_NAME,__FILE__,n,PETSC_ERROR_IN_CXX,0);}} while(0)

465: #endif

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

470:    Synopsis:
471:    #include <petscsys.h>
472:    CHKMEMQ;

474:    Not Collective

476:   Level: beginner

478:    Notes:
479:     We highly recommend using valgrind http://www.mcs.anl.gov/petsc/documentation/faq.html#valgrind for finding memory problems. This is useful
480:     on systems that do not have valgrind, but much much less useful.

482:     Must run with the option -malloc_debug to enable this option

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

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

488:     Use CHKMEMA for functions that return void

490:    Concepts: memory corruption

492: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ3(),
493:           PetscMallocValidate()
494: M*/
495: #define CHKMEMQ do {PetscErrorCode _7_PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__);CHKERRQ(_7_ierr);} while(0)

497: #define CHKMEMA PetscMallocValidate(__LINE__,PETSC_FUNCTION_NAME,__FILE__)

499: #else /* PETSC_USE_ERRORCHECKING */

501: /*
502:     These are defined to be empty for when error checking is turned off, with ./configure --with-errorchecking=0
503: */

505: #define SETERRQ(c,n,s)
506: #define SETERRQ1(c,n,s,a1)
507: #define SETERRQ2(c,n,s,a1,a2)
508: #define SETERRQ3(c,n,s,a1,a2,a3)
509: #define SETERRQ4(c,n,s,a1,a2,a3,a4)
510: #define SETERRQ5(c,n,s,a1,a2,a3,a4,a5)
511: #define SETERRQ6(c,n,s,a1,a2,a3,a4,a5,a6)
512: #define SETERRQ7(c,n,s,a1,a2,a3,a4,a5,a6,a7)
513: #define SETERRQ8(c,n,s,a1,a2,a3,a4,a5,a6,a7,a8)
514: #define SETERRABORT(comm,n,s)

516: #define CHKERRQ(n)     ;
517: #define CHKERRABORT(comm,n) ;
518: #define CHKERRCONTINUE(n) ;
519: #define CHKMEMQ        ;

521: #ifdef PETSC_CLANGUAGE_CXX
522: #define CHKERRXX(n) ;
523: #endif

525: #endif /* PETSC_USE_ERRORCHECKING */

527: /*E
528:   PetscErrorType - passed to the PETSc error handling routines indicating if this is the first or a later call to the error handlers

530:   Level: advanced

532:   PETSC_ERROR_IN_CXX indicates the error was detected in C++ and an exception should be generated

534:   Developer Notes: This is currently used to decide when to print the detailed information about the run in PetscTraceBackErrorHandler()

536: .seealso: PetscError(), SETERRXX()
537: E*/
538: typedef enum {PETSC_ERROR_INITIAL=0,PETSC_ERROR_REPEAT=1,PETSC_ERROR_IN_CXX = 2} PetscErrorType;

540: #if defined(__clang_analyzer__)
541: __attribute__((analyzer_noreturn))
542: #endif
543: PETSC_EXTERN PetscErrorCode PetscError(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,...);

545: PETSC_EXTERN PetscErrorCode PetscErrorPrintfInitialize(void);
546: PETSC_EXTERN PetscErrorCode PetscErrorMessage(int,const char*[],char **);
547: PETSC_EXTERN PetscErrorCode PetscTraceBackErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
548: PETSC_EXTERN PetscErrorCode PetscIgnoreErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
549: PETSC_EXTERN PetscErrorCode PetscEmacsClientErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
550: PETSC_EXTERN PetscErrorCode PetscMPIAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
551: PETSC_EXTERN PetscErrorCode PetscAbortErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
552: PETSC_EXTERN PetscErrorCode PetscAttachDebuggerErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
553: PETSC_EXTERN PetscErrorCode PetscReturnErrorHandler(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*);
554: PETSC_EXTERN PetscErrorCode PetscPushErrorHandler(PetscErrorCode (*handler)(MPI_Comm,int,const char*,const char*,PetscErrorCode,PetscErrorType,const char*,void*),void*);
555: PETSC_EXTERN PetscErrorCode PetscPopErrorHandler(void);
556: PETSC_EXTERN PetscErrorCode PetscSignalHandlerDefault(int,void*);
557: PETSC_EXTERN PetscErrorCode PetscPushSignalHandler(PetscErrorCode (*)(int,void *),void*);
558: PETSC_EXTERN PetscErrorCode PetscPopSignalHandler(void);

561: /*MC
562:     PetscErrorPrintf - Prints error messages.

564:    Synopsis:
565:     #include <petscsys.h>
566:      PetscErrorCode (*PetscErrorPrintf)(const char format[],...);

568:     Not Collective

570:     Input Parameters:
571: .   format - the usual printf() format string

573:    Options Database Keys:
574: +    -error_output_stdout - cause error messages to be printed to stdout instead of the  (default) stderr
575: -    -error_output_none - to turn off all printing of error messages (does not change the way the error is handled.)

577:    Notes: Use
578: $     PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the
579: $                        error is handled.) and
580: $     PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on or you can use your own function

582:           Use
583:      PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file.
584:      PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file.

586:           Use
587:       PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print

589:    Level: developer

591:     Fortran Note:
592:     This routine is not supported in Fortran.

594:     Concepts: error messages^printing
595:     Concepts: printing^error messages

597: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf(), PetscPrintf(), PetscErrorHandlerPush(), PetscVFPrintf(), PetscHelpPrintf()
598: M*/
599: PETSC_EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...);

601: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
602: PETSC_EXTERN PetscErrorCode PetscSetFPTrap(PetscFPTrap);
603: PETSC_EXTERN PetscErrorCode PetscFPTrapPush(PetscFPTrap);
604: PETSC_EXTERN PetscErrorCode PetscFPTrapPop(void);

606: /*
607:       Allows the code to build a stack frame as it runs
608: */

610: #define PETSCSTACKSIZE 64

612: typedef struct  {
613:   const char      *function[PETSCSTACKSIZE];
614:   const char      *file[PETSCSTACKSIZE];
615:         int       line[PETSCSTACKSIZE];
616:         PetscBool petscroutine[PETSCSTACKSIZE];
617:         int       currentsize;
618:         int       hotdepth;
619: } PetscStack;

621: PETSC_EXTERN PetscStack *petscstack;

623: PetscErrorCode  PetscStackCopy(PetscStack*,PetscStack*);
624: PetscErrorCode  PetscStackPrint(PetscStack *,FILE*);
625: #if defined(PETSC_USE_DEBUG)
626: PETSC_STATIC_INLINE PetscBool PetscStackActive(void)
627: {
628:   return(petscstack ? PETSC_TRUE : PETSC_FALSE);
629: }

631: /* Stack handling is based on the following two "NoCheck" macros.  These should only be called directly by other error
632:  * handling macros.  We record the line of the call, which may or may not be the location of the definition.  But is at
633:  * least more useful than "unknown" because it can distinguish multiple calls from the same function.
634:  */

636: #define PetscStackPushNoCheck(funct,petsc_routine,hot)                        \
637:   do {                                                                        \
638:     PetscStackSAWsTakeAccess();                                                \
639:     if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {         \
640:       petscstack->function[petscstack->currentsize]  = funct;               \
641:       petscstack->file[petscstack->currentsize]      = __FILE__;            \
642:       petscstack->line[petscstack->currentsize]      = __LINE__;            \
643:       petscstack->petscroutine[petscstack->currentsize] = petsc_routine;    \
644:       petscstack->currentsize++;                                             \
645:     }                                                                         \
646:     if (petscstack) {                                                        \
647:       petscstack->hotdepth += (hot || petscstack->hotdepth);                \
648:     }                                                                         \
649:     PetscStackSAWsGrantAccess();                                               \
650:   } while (0)

652: #define PetscStackPopNoCheck                                            \
653:   do {                                                                  \
654:     PetscStackSAWsTakeAccess();                                          \
655:     if (petscstack && petscstack->currentsize > 0) {                  \
656:       petscstack->currentsize--;                                       \
657:       petscstack->function[petscstack->currentsize]  = 0;             \
658:       petscstack->file[petscstack->currentsize]      = 0;             \
659:       petscstack->line[petscstack->currentsize]      = 0;             \
660:       petscstack->petscroutine[petscstack->currentsize] = PETSC_FALSE;\
661:     }                                                                   \
662:     if (petscstack) {                                                  \
663:       petscstack->hotdepth = PetscMax(petscstack->hotdepth-1,0);      \
664:     }                                                                   \
665:     PetscStackSAWsGrantAccess();                                         \
666:   } while (0)

668: /*MC
670:       line of PETSc functions should be return(0);

672:    Synopsis:
673:    #include <petscsys.h>

676:    Not Collective

678:    Usage:
679: .vb
680:      int something;

683: .ve

685:    Notes:

688:      Not available in Fortran

690:    Level: developer


694: .keywords: traceback, error handling
695: M*/
697:     PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_FALSE); \
699:     PetscRegister__FUNCT__();                                          \
700:   } while (0)

702: /*MC
704:    performance-critical circumstances.  Use of this function allows for lighter profiling by default.

706:    Synopsis:
707:    #include <petscsys.h>

710:    Not Collective

712:    Usage:
713: .vb
714:      int something;

717: .ve

719:    Notes:
720:      Not available in Fortran

722:    Level: developer


726: .keywords: traceback, error handling
727: M*/
729:     PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_TRUE,PETSC_TRUE);  \
731:     PetscRegister__FUNCT__();                                          \
732:   } while (0)

734: /*MC

737:    Synopsis:
738:    #include <petscsys.h>

741:    Not Collective

743:    Usage:
744: .vb
745:      int something;

748: .ve

750:    Notes:
751:       Final line of PETSc functions should be return(0) except for main().

753:       Not available in Fortran

755:    Level: intermediate


759: .keywords: traceback, error handling
760: M*/
762:   do {                                                                  \
763:     PetscStackPushNoCheck(PETSC_FUNCTION_NAME,PETSC_FALSE,PETSC_FALSE); \
765:     PetscRegister__FUNCT__();                                           \
766:   } while (0)


769: #if defined(PETSC_SERIALIZE_FUNCTIONS)
770: #include <petsc/private/petscfptimpl.h>
771: /*
772:    Registers the current function into the global function pointer to function name table

774:    Have to fix this to handle errors but cannot return error since used in PETSC_VIEWER_DRAW_() etc
775: */
776: #define PetscRegister__FUNCT__() do { \
777:   static PetscBool __chked = PETSC_FALSE; \
778:   if (!__chked) {\
779:   void *ptr; PetscDLSym(NULL,__FUNCT__,&ptr);\
780:   __chked = PETSC_TRUE;\
781:   }} while (0)
782: #else
783: #define PetscRegister__FUNCT__()
784: #endif

787:     PetscStrcmpNoError(PETSC_FUNCTION_NAME,__FUNCT__,&_sc1);\
788:     PetscStrcmpNoError(__FUNCT__,"User provided function",&_sc2);\
789:     if (!_sc1 && !_sc2) { \
790:       printf("%s:%d: __FUNCT__=\"%s\" does not agree with %s=\"%s\"\n",__FILE__,__LINE__,__FUNCT__,PetscStringize(PETSC_FUNCTION_NAME),PETSC_FUNCTION_NAME); \
791:     }                                                                   \
792:   } while (0)

794: #define PetscStackPush(n) \
795:   do {                                                                  \
796:     PetscStackPushNoCheck(n,PETSC_FALSE,PETSC_FALSE);                   \
797:     CHKMEMQ;                                                            \
798:   } while (0)

800: #define PetscStackPop                           \
801:     do {                                        \
802:       CHKMEMQ;                                  \
803:       PetscStackPopNoCheck;                     \
804:     } while (0)

806: /*MC
807:    PetscFunctionReturn - Last executable line of each PETSc function
808:         used for error handling. Replaces return()

810:    Synopsis:
811:    #include <petscsys.h>
812:    void return(0);

814:    Not Collective

816:    Usage:
817: .vb
818:     ....
819:      return(0);
820:    }
821: .ve

823:    Notes:
824:      Not available in Fortran

826:    Level: developer


830: .keywords: traceback, error handling
831: M*/
832: #define PetscFunctionReturn(a) \
833:   do {                                                                \
834:     PetscStackPopNoCheck;                                             \
835:     return(a);} while (0)

837: #define PetscFunctionReturnVoid() \
838:   do {                                                                \
839:     PetscStackPopNoCheck;                                             \
840:     return;} while (0)

842: #else

844: PETSC_STATIC_INLINE PetscBool PetscStackActive(void) {return PETSC_FALSE;}
845: #define PetscStackPushNoCheck(funct,petsc_routine,hot) do {} while (0)
846: #define PetscStackPopNoCheck                           do {} while (0)
850: #define PetscFunctionReturn(a)    return(a)
851: #define PetscFunctionReturnVoid() return
852: #define PetscStackPop             CHKMEMQ
853: #define PetscStackPush(f)         CHKMEMQ

855: #endif

857: /*
858:     PetscStackCall - Calls an external library routine or user function after pushing the name of the routine on the stack.

860:    Input Parameters:
861: +   name - string that gives the name of the function being called
862: -   routine - actual call to the routine, including and 

864:    Note: Often one should use PetscStackCallStandard() instead. This routine is intended for external library routines that DO NOT return error codes

866:    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.



870: */
871: #define PetscStackCall(name,routine) do { PetscStackPush(name);routine;PetscStackPop; } while(0)

873: /*
874:     PetscStackCallStandard - Calls an external library routine after pushing the name of the routine on the stack.

876:    Input Parameters:
877: +   func-  name of the routine
878: -   args - arguments to the routine surrounded by ()

880:    Notes: This is intended for external package routines that return error codes. Use PetscStackCall() for those that do not.

882:    Developer Note: this is so that when an external packge routine results in a crash or corrupts memory, they get blamed instead of PETSc.

884: */
885: #define PetscStackCallStandard(func,args) do {                        \
886:     PetscStackPush(#func);func args;PetscStackPop; if (ierr) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_LIB,"Error in %s()",#func); \
887:   } while (0)

889: PETSC_EXTERN PetscErrorCode PetscStackCreate(void);
890: PETSC_EXTERN PetscErrorCode PetscStackView(FILE*);
891: PETSC_EXTERN PetscErrorCode PetscStackDestroy(void);

893: #endif