Actual source code: petscerror.h

  1: /*
  2:     Contains all error handling code for PETSc.
  3: */
 6:  #include petsc.h

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

 20: /*
 21:    Defines the function where the compiled source is located; used 
 22:    in printing error messages.
 23: */
 26: #endif

 28: /* 
 29:      These are the generic error codes. These error codes are used
 30:      many different places in the PETSc source code. The string versions are
 31:      at src/sys/src/error/err.c any changes here must also be made there

 33: */
 34: #define PETSC_ERR_MEM              55   /* unable to allocate requested memory */
 35: #define PETSC_ERR_MEM_MALLOC_0     85   /* cannot malloc zero size */
 36: #define PETSC_ERR_SUP              56   /* no support for requested operation */
 37: #define PETSC_ERR_SUP_SYS          57   /* no support for requested operation on this computer system */
 38: #define PETSC_ERR_ORDER            58   /* operation done in wrong order */
 39: #define PETSC_ERR_SIG              59   /* signal received */
 40: #define PETSC_ERR_FP               72   /* floating point exception */
 41: #define PETSC_ERR_COR              74   /* corrupted PETSc object */
 42: #define PETSC_ERR_LIB              76   /* error in library called by PETSc */
 43: #define PETSC_ERR_PLIB             77   /* PETSc library generated inconsistent data */
 44: #define PETSC_ERR_MEMC             78   /* memory corruption */
 45: #define PETSC_ERR_CONV_FAILED      82   /* iterative method (KSP or SNES) failed */
 46: #define PETSC_ERR_USER             83   /* user has not provided needed function */

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

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

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

 69: #if defined(PETSC_USE_DEBUG)

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

 74:    Not Collective

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


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

 84:   Level: beginner

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

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


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

 94:    Concepts: error^setting condition

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

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

103:    Not Collective

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


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

114:   Level: beginner

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

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

121:    Concepts: error^setting condition

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

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

130:    Not Collective

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


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

142:   Level: beginner

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

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

149:    Concepts: error^setting condition

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

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

158:    Not Collective

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


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

171:   Level: beginner

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

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

178:    Concepts: error^setting condition

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

184: #define SETERRQ4(n,s,a1,a2,a3,a4) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4);}
185: #define SETERRQ5(n,s,a1,a2,a3,a4,a5)       {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5);}
186: #define SETERRQ6(n,s,a1,a2,a3,a4,a5,a6)    {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5,a6);}
187: #define SETERRQ7(n,s,a1,a2,a3,a4,a5,a6,a7) {return PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s,a1,a2,a3,a4,a5,a6,a7);}
188: #define SETERRABORT(comm,n,s)     {PetscError(__LINE__,__FUNCT__,__FILE__,__SDIR__,n,1,s);MPI_Abort(comm,n);}

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

193:    Not Collective

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


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

202:   Level: beginner

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

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

209:    Concepts: error^setting condition

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

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

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

221:    Not Collective

223:    Synopsis:
224:    CHKMEMQ;

226:   Level: beginner

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

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

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

235:    Concepts: memory corruption

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

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

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

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

261: #define CHKMEMQ        ;

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

268: #endif

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

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

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

293: #define PETSCSTACKSIZE 15

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

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

307: #define PetscStackActive (petscstack != 0)


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

314:    Synopsis:

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

322: .ve

324:    Notes:
325:      Not available in Fortran

327:    Level: developer

329: .seealso: PetscFunctionReturn()

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

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

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

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

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

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

375:    Notes:
376:      Not available in Fortran

378:    Level: developer


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

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


395: #else

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

404: #endif

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


414: #endif