00001 /* 00002 * libfid - Full-text Index Data structure library 00003 * Copyright (C) 2006, 2007, 2008, 2009 Robert Homann 00004 * 00005 * This library is free software; you can redistribute it and/or 00006 * modify it under the terms of the GNU Lesser General Public 00007 * License as published by the Free Software Foundation; either 00008 * version 2.1 of the License, or (at your option) any later version. 00009 * 00010 * This library is distributed in the hope that it will be useful, 00011 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 * Lesser General Public License for more details. 00014 * 00015 * You should have received a copy of the GNU Lesser General Public 00016 * License along with this library; if not, write to the Free Software 00017 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 00018 * MA 02110-1301 USA 00019 */ 00020 00021 #ifndef ERROR_H 00022 #define ERROR_H 00023 /*!\addtogroup errors Error message handling 00024 * Error propagation is an important and often poorly solved issue in any 00025 * program. In this library, errors are propagated by employing a dedicated 00026 * data structure fid_Error plus supporting function. 00027 */ 00028 /*@{*/ 00029 #ifdef __cplusplus 00030 #include <cstdio> 00031 using std::FILE; 00032 using std::size_t; 00033 #else /* !__cplusplus */ 00034 #include <stdio.h> 00035 #endif /* __cplusplus */ 00036 00037 /*!\brief This is the maximum number of errors that can be stored in an 00038 * #fid_Error structure. */ 00039 #define fid_ERROR_MAX ((int)16) 00040 00041 /*! 00042 * \brief Error message overflow handling mode. 00043 * 00044 * \see fid_Error documentation for more details. 00045 */ 00046 typedef enum 00047 { 00048 fid_ERRORMODE_FIFO=0, 00049 fid_ERRORMODE_DEEPEST, 00050 fid_ERRORMODE_KEEP_LAST 00051 } fid_Errormode; 00052 00053 /*! 00054 * \brief Structure for error message handling. 00055 * 00056 * This data structure stores multiple error message to keep track of more 00057 * than only one error to enable the user to obtain a more detailed view 00058 * on the cause of an error. The data structure supports three modes of 00059 * operation to handle overflows, i.e., the case when more than a certain 00060 * number of errors occurred: 00061 * - FIFO (first in, first out) 00062 * - Keep deepest (stop collecting errors if there are too many) 00063 * - Keep deepest but the last (replace the most recent errors by a new one) 00064 * 00065 * The maximum number of errors is defined by a compile time constant, 00066 * fid_ERROR_MAX. What mode to choose depends on the kind of error, i.e., 00067 * depends on the application context. 00068 */ 00069 typedef struct 00070 { 00071 int num_of_errors; /*!< \brief Number of errors collected. */ 00072 int first_error; /*!< \brief Index of the first error message in 00073 * #fid_Error::errors. */ 00074 fid_Errormode mode; /*!< \brief How to handle many errors. */ 00075 int overflow; /*!< \brief Set to \e true if error messages have been 00076 * lost due to overflows. */ 00077 int outofmem; /*!< \brief Set to \e true if an error could not be 00078 * handled properly due to out-of-memory condition. */ 00079 char *errors[fid_ERROR_MAX]; /*!< \brief Error messages. */ 00080 } fid_Error; 00081 00082 /*! 00083 * \brief Check if an error is stored in fid_Error \p ERR. 00084 * 00085 * \param ERR An fid_Error structure. 00086 * 00087 * \returns True if an error is available, false otherwise. 00088 */ 00089 #define fid_ERROR_OCCURRED(ERR) ((ERR)->num_of_errors > 0) 00090 00091 /*! 00092 * \brief Append an out-of-memory error to \p ERR. 00093 */ 00094 #define fid_OUTOFMEM(ERR)\ 00095 fid_error_throw(ERR,"Out of memory (%s[%d])",__FILE__,__LINE__) 00096 00097 #ifdef __cplusplus 00098 extern "C" { 00099 #endif 00100 void fid_error_init(fid_Error *error, fid_Errormode mode); 00101 void fid_error_init_default(fid_Error *error); 00102 void fid_error_free(fid_Error *error); 00103 #ifdef __GNUC__ 00104 void fid_error_throw(fid_Error *error, const char *fmt, ...) 00105 __attribute__ ((format (printf, 2, 3))); 00106 void fid_error_throw_errno(fid_Error *error, int errnum, const char *fmt, ...) 00107 __attribute__ ((format (printf, 3, 4))); 00108 #else /* !__GNUC__ */ 00109 void fid_error_throw(fid_Error *error, const char *fmt, ...); 00110 void fid_error_throw_errno(fid_Error *error, int errnum, const char *fmt, ...); 00111 #endif /* __GNUC__ */ 00112 int fid_error_dump(const fid_Error *error, FILE *stream); 00113 #ifdef __cplusplus 00114 } 00115 #endif 00116 /*@}*/ 00117 00118 #endif /* !ERROR_H */