Actual source code: petscerror.h

  1: /* $Id: petscerror.h,v 1.59 2001/09/07 20:13:16 bsmith Exp $ */
  2: /*
  3:     Contains all error handling code for PETSc.
  4: */
 7:  #include petsc.h
  8: PETSC_EXTERN_CXX_BEGIN

 10: #if defined(PETSC_HAVE_AMS)
 11: #include "ams.h"
 12: #endif

 14: /*
 15:    Defines the directory where the compiled source is located; used
 16:    in printing error messages. Each makefile has an entry 
 17:    LOCDIR          =  thedirectory
 18:    and bmake/common_variables includes in CCPPFLAGS -D__SDIR__='"${LOCDIR}"'
 19:    which is a flag passed to the C/C++ compilers.
 20: */
 23: #endif

 25: /*
 26:    Defines the function where the compiled source is located; used 
 27:    in printing error messages.
 28: */
 31: #endif

 33: /* 
 34:      These are the generic error codes. These error codes are used
 35:      many different places in the PETSc source code.

 37: */
 38: #define PETSC_ERR_MEM             55   /* unable to allocate requested memory */
 39: #define PETSC_ERR_MEM_MALLOC_0    85   /* cannot malloc zero size */
 40: #define PETSC_ERR_SUP             56   /* no support for requested operation */
 41: #define PETSC_ERR_SIG             59   /* signal received */
 42: #define PETSC_ERR_FP              72   /* floating point exception */
 43: #define PETSC_ERR_COR             74   /* corrupted PETSc object */
 44: #define PETSC_ERR_LIB             76   /* error in library called by PETSc */
 45: #define PETSC_ERR_PLIB            77   /* PETSc library generated inconsistent data */
 46: #define PETSC_ERR_MEMC            78   /* memory corruption */
 47: #define PETSC_ERR_MAX_ITER        82   /* Maximum iterations reached */

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

 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_KSP_BRKDWN      70   /* break down in a Krylov method */

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

 71: #define PETSC_ERR_MESH_NULL_ELEM  84   /* Element had no interior */

 73: #define PETSC_ERR_DISC_SING_JAC   83   /* Singular element Jacobian */

 75: #if defined(PETSC_USE_DEBUG)

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

 80:    Not Collective

 82:    Synopsis:
 83:    void SETERRQ(int errorcode,char *message)


 86:    Input Parameters:
 87: +  errorcode - nonzero error code, see the list of standard error codes in include/petscerror.h
 88: -  message - error message

 90:   Level: beginner

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

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


 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(n,s)              {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);}

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

109:    Not Collective

111:    Synopsis:
112:    void SETERRQ1(int errorcode,char *formatmessage,arg)


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

120:   Level: beginner

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

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

127:    Concepts: error^setting condition

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

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

136:    Not Collective

138:    Synopsis:
139:    void SETERRQ2(int errorcode,char *formatmessage,arg1,arg2)


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

148:   Level: beginner

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

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

155:    Concepts: error^setting condition

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

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

164:    Not Collective

166:    Synopsis:
167:    void SETERRQ3(int errorcode,char *formatmessage,arg1,arg2,arg3)


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

177:   Level: beginner

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

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

184:    Concepts: error^setting condition

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

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

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

199:    Not Collective

201:    Synopsis:
202:    void CHKERRQ(int errorcode)


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

208:   Level: beginner

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

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

215:    Concepts: error^setting condition

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

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

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

227:    Not Collective

229:    Synopsis:
230:    CHKMEMQ;

232:   Level: beginner

234:    Notes:
235:     Must run with the option -trdebug to enable this option

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

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

241:    Concepts: memory corruption

243: .seealso: PetscTraceBackErrorHandler(), PetscPushErrorHandler(), PetscError(), SETERRQ(), CHKMEMQ, SETERRQ1(), SETERRQ2(), SETERRQ2(), 
244:           PetscTrValid()
245: M*/
246: #define CHKMEMQ {int _7_PetscTrValid(__LINE__,__FUNCT__,__FILE__,__SDIR__);CHKERRQ(_7_ierr);}

248: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
249: extern  int __gierr;
250: #define _   __g
252: #endif

254: #else
255: #define SETERRQ(n,s) ;
256: #define SETERRQ1(n,s,a1) ;
257: #define SETERRQ2(n,s,a1,a2) ;
258: #define SETERRQ3(n,s,a1,a2,a3) ;
259: #define SETERRQ4(n,s,a1,a2,a3,a4) ;
260: #define SETERRABORT(comm,n,s) ;

262: #define CHKERRQ(n)     ;
263: #define CHKERRABORT(comm,n) ;
264: #define CHKERRCONTINUE(n) ;

266: #define CHKMEMQ        ;

268: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
269: #define _   
271: #endif 

273: #endif

275: EXTERN int PetscErrorMessage(int,const char*[],char **);
276: EXTERN int PetscTraceBackErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
277: EXTERN int PetscIgnoreErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
278: EXTERN int PetscEmacsClientErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
279: EXTERN int PetscStopErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
280: EXTERN int PetscAbortErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
281: EXTERN int PetscAttachDebuggerErrorHandler(int,const char*,const char*,const char*,int,int,const char*,void*);
282: EXTERN int PetscError(int,const char*,const char*,const char*,int,int,const char*,...) PETSC_PRINTF_FORMAT_CHECK(7,8);
283: EXTERN int PetscPushErrorHandler(int (*handler)(int,const char*,const char*,const char*,int,int,const char*,void*),void*);
284: EXTERN int PetscPopErrorHandler(void);
285: EXTERN int PetscDefaultSignalHandler(int,void*);
286: EXTERN int PetscPushSignalHandler(int (*)(int,void *),void*);
287: EXTERN int PetscPopSignalHandler(void);

289: typedef enum {PETSC_FP_TRAP_OFF=0,PETSC_FP_TRAP_ON=1} PetscFPTrap;
290: EXTERN int PetscSetFPTrap(PetscFPTrap);

292: /*
293:       Allows the code to build a stack frame as it runs
294: */
295: #if defined(PETSC_USE_STACK)

297: #define PETSCSTACKSIZE 15

299: typedef struct  {
300:   const char *function[PETSCSTACKSIZE];
301:   const char *file[PETSCSTACKSIZE];
302:   const char *directory[PETSCSTACKSIZE];
303:         int  line[PETSCSTACKSIZE];
304:         int currentsize;
305: } PetscStack;

307: extern PetscStack *petscstack;
308: EXTERN int PetscStackCopy(PetscStack*,PetscStack*);
309: EXTERN int PetscStackPrint(PetscStack*,FILE* fp);

311: #define PetscStackActive (petscstack != 0)

313: #if !defined(PETSC_HAVE_AMS)

315: /*MC
317:         used for error handling.

319:    Synopsis:

322:    Usage:
323: .vb
324:      int something;

327: .ve

329:    Notes:
330:      Not available in Fortran

332:    Level: developer

334: .seealso: PetscFunctionReturn()

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

348: #define PetscStackPush(n) \
349:   {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
350:     petscstack->function[petscstack->currentsize]  = n; \
351:     petscstack->file[petscstack->currentsize]      = "unknown"; \
352:     petscstack->directory[petscstack->currentsize] = "unknown"; \
353:     petscstack->line[petscstack->currentsize]      = 0; \
354:     petscstack->currentsize++; \
355:   }}

357: #define PetscStackPop \
358:   {if (petscstack && petscstack->currentsize > 0) {     \
359:     petscstack->currentsize--; \
360:     petscstack->function[petscstack->currentsize]  = 0; \
361:     petscstack->file[petscstack->currentsize]      = 0; \
362:     petscstack->directory[petscstack->currentsize] = 0; \
363:     petscstack->line[petscstack->currentsize]      = 0; \
364:   }};

366: /*MC
367:    PetscFunctionReturn - Last executable line of each PETSc function
368:         used for error handling. Replaces return()

370:    Synopsis:
371:    void return(0);

373:    Usage:
374: .vb
375:     ....
376:      return(0);
377:    }
378: .ve

380:    Notes:
381:      Not available in Fortran

383:    Level: developer


387: .keywords: traceback, error handling
388: M*/
389: #define PetscFunctionReturn(a) \
390:   {\
391:   PetscStackPop; \
392:   return(a);}

394: #define PetscFunctionReturnVoid() \
395:   {\
396:   PetscStackPop; \
397:   return;}

399: #else

401: /*
402:     Duplicate Code for when the ALICE Memory Snooper (AMS)
403:   is being used. When PETSC_HAVE_AMS is defined.

405:      stack_mem is the AMS memory that contains fields for the 
406:                number of stack frames and names of the stack frames
407: */

409: extern AMS_Memory stack_mem;
410: extern int        stack_err;

413:   {\
414:    if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
415:     if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
416:     petscstack->function[petscstack->currentsize]  = __FUNCT__; \
417:     petscstack->file[petscstack->currentsize]      = __FILE__; \
418:     petscstack->directory[petscstack->currentsize] = __SDIR__; \
419:     petscstack->line[petscstack->currentsize]      = __LINE__; \
420:     petscstack->currentsize++; \
421:     if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
422:   }}

424: #define PetscStackPush(n) \
425:   {if (petscstack && (petscstack->currentsize < PETSCSTACKSIZE)) {    \
426:     if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
427:     petscstack->function[petscstack->currentsize]  = n; \
428:     petscstack->file[petscstack->currentsize]      = "unknown"; \
429:     petscstack->directory[petscstack->currentsize] = "unknown"; \
430:     petscstack->line[petscstack->currentsize]      = 0; \
431:     petscstack->currentsize++; \
432:     if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
433:   }}

435: #define PetscStackPop \
436:   {if (petscstack && petscstack->currentsize > 0) {     \
437:     if (!(stack_mem < 0)) stack_err = AMS_Memory_take_access(stack_mem);\
438:     petscstack->currentsize--; \
439:     petscstack->function[petscstack->currentsize]  = 0; \
440:     petscstack->file[petscstack->currentsize]      = 0; \
441:     petscstack->directory[petscstack->currentsize] = 0; \
442:     petscstack->line[petscstack->currentsize]      = 0; \
443:     if (!(stack_mem < 0)) stack_err = AMS_Memory_grant_access(stack_mem);\
444:   }};

446: #define PetscFunctionReturn(a) \
447:   {\
448:   PetscStackPop; \
449:   return(a);}

451: #define PetscFunctionReturnVoid() \
452:   {\
453:   PetscStackPop; \
454:   return;}


457: #endif

459: #else

462: #define PetscFunctionReturn(a)  return(a)
463: #define PetscFunctionReturnVoid() return()
464: #define PetscStackPop 
465: #define PetscStackPush(f) 
466: #define PetscStackActive        0

468: #endif

470: EXTERN int PetscStackCreate(void);
471: EXTERN int PetscStackView(PetscViewer);
472: EXTERN int PetscStackDestroy(void);
473: EXTERN int PetscStackPublish(void);
474: EXTERN int PetscStackDepublish(void);


477: PETSC_EXTERN_CXX_END
478: #endif