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

 8:  #include petsc.h

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

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

 65: #define PETSC_ERR_KSP_BRKDWN      70   /* break down in a Krylov method */

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

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

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

 74: #if defined(PETSC_USE_DEBUG)

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

 79:    Not Collective

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


 85:    Input Parameters:
 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


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

 99:    Concepts: error^setting condition

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

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

108:    Not Collective

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


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

119:   Level: beginner

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

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

126:    Concepts: error^setting condition

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

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

135:    Not Collective

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


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

147:   Level: beginner

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

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

154:    Concepts: error^setting condition

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

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

163:    Not Collective

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


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

176:   Level: beginner

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

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

183:    Concepts: error^setting condition

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

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

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

198:    Not Collective

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


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

207:   Level: beginner

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

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

214:    Concepts: error^setting condition

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

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

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

226:    Not Collective

228:    Synopsis:
229:    void CHKMEMQ(void)

231:   Level: beginner

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

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

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

240:    Concepts: memory corruption

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

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

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

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

265: #define CHKMEMQ        ;

267: #if !defined(PETSC_SKIP_UNDERSCORE_CHKERR)
268: #define _   
270: #endif 

272: #endif

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

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

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

296: #define PETSCSTACKSIZE 15

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

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

310: #define PetscStackActive (petscstack != 0)

312: #if !defined(PETSC_HAVE_AMS)

314: /*MC
316:         used for error handling.

318:    Synopsis:

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

326: .ve

328:    Notes:
329:      Not available in Fortran

331:    Level: developer

333: .seealso: PetscFunctionReturn()

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

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

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

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

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

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

379:    Notes:
380:      Not available in Fortran

382:    Level: developer


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

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

398: #else

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

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

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

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

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

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

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

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


456: #endif

458: #else

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

467: #endif

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


476: #endif