GIRAFFE Pipeline Reference Manual

irplib_utils.h

00001 /* $Id: irplib_utils.h,v 1.50 2009/08/17 15:10:16 kmirny Exp $
00002  *
00003  * This file is part of the irplib package
00004  * Copyright (C) 2002,2003 European Southern Observatory
00005  *
00006  * This program is free software; you can redistribute it and/or modify
00007  * it under the terms of the GNU General Public License as published by
00008  * the Free Software Foundation; either version 2 of the License, or
00009  * (at your option) any later version.
00010  *
00011  * This program is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  * GNU General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU General Public License
00017  * along with this program; if not, write to the Free Software
00018  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02111-1307  USA
00019  */
00020 
00021 /*
00022  * $Author: kmirny $
00023  * $Date: 2009/08/17 15:10:16 $
00024  * $Revision: 1.50 $
00025  * $Name:  $
00026  * $Log: irplib_utils.h,v $
00027  * Revision 1.50  2009/08/17 15:10:16  kmirny
00028  *
00029  * DFS07454 DFS07437
00030  *
00031  */
00032 
00033 #ifndef IRPLIB_UTILS_H
00034 #define IRPLIB_UTILS_H
00035 
00036 /*-----------------------------------------------------------------------------
00037                                    Includes
00038  -----------------------------------------------------------------------------*/
00039 
00040 #include <stdarg.h>
00041 
00042 #include <cpl.h>
00043 
00044 /*-----------------------------------------------------------------------------
00045                                    Define
00046  -----------------------------------------------------------------------------*/
00047 
00048 #define IRPLIB_XSTRINGIFY(TOSTRING) #TOSTRING
00049 #define IRPLIB_STRINGIFY(TOSTRING) IRPLIB_XSTRINGIFY(TOSTRING)
00050 
00051 /* FIXME: Remove when no longer used by any irplib-based pipelines */
00052 /* Useful for debugging */
00053 #define irplib_trace()  do if (cpl_error_get_code()) { \
00054     cpl_msg_debug(cpl_func, __FILE__ " at line %d: ERROR '%s' at %s", \
00055          __LINE__, cpl_error_get_message(), cpl_error_get_where()); \
00056   } else { \
00057     cpl_msg_debug(cpl_func, __FILE__ " at line %d: OK", __LINE__); \
00058   } while (0)
00059 
00060 #define irplib_error_recover(ESTATE, ...)                                      \
00061     do if (!cpl_errorstate_is_equal(ESTATE)) {                                 \
00062         cpl_msg_warning(cpl_func, __VA_ARGS__);                                \
00063         cpl_msg_indent_more();                                                 \
00064         cpl_errorstate_dump(ESTATE, CPL_FALSE, irplib_errorstate_warning);     \
00065         cpl_msg_indent_less();                                                 \
00066         cpl_errorstate_set(ESTATE);                                            \
00067     } while (0)
00068 
00069 
00070 
00071 /*----------------------------------------------------------------------------*/
00072 /*
00073   @brief Declare a function suitable for use with irplib_dfs_table_convert()
00074   @param  table_set_row    The name of the function to declare
00075   @see irplib_dfs_table_convert(), irplib_table_read_from_frameset()
00076 
00077 */
00078 /*----------------------------------------------------------------------------*/
00079 #define IRPLIB_UTIL_SET_ROW(table_set_row)                      \
00080     cpl_boolean table_set_row(cpl_table *,                      \
00081                               const char *,                     \
00082                               int,                              \
00083                               const cpl_frame *,                \
00084                               const cpl_parameterlist *)
00085 
00086 
00087 /*----------------------------------------------------------------------------*/
00088 /*
00089   @brief Declare a function suitable for use with irplib_dfs_table_convert()
00090   @param  table_check    The name of the function to declare
00091   @see irplib_dfs_table_convert()
00092 
00093 */
00094 /*----------------------------------------------------------------------------*/
00095 #define IRPLIB_UTIL_CHECK(table_check)                          \
00096     cpl_error_code table_check(cpl_table *,                     \
00097                                const cpl_frameset *,            \
00098                                const cpl_parameterlist *)
00099 
00100 
00101 /*----------------------------------------------------------------------------*/
00102 /*
00103   @brief   Conditional skip to the (unqiue) return point of the function
00104   @param   CONDITION    The condition to check
00105   @see cpl_error_ensure()
00106 
00107   skip_if() takes one argument, which is a logical expression.
00108   If the logical expression is false skip_if() takes no action and
00109   program execution continues.
00110   If the logical expression is true this indicates an error. In this case
00111   skip_if() will set the location of the error to the point where it
00112   was invoked in the recipe code (unless the error location is already in the
00113   recipe code). If no error code had been set, then skip_if() will set one.
00114   Finally, skip_if() causes program execution to skip to the macro 'end_skip'.
00115   The macro end_skip is located towards the end of the function, after
00116   which all resource deallocation and the function return is located.
00117 
00118   The use of skip_if() assumes the following coding practice:
00119   1) Pointers used for dynamically allocated memory that they "own" shall always
00120      point to either NULL or to allocated memory (including CPL-objects).
00121   2) Such pointers may not be reused to point to memory whose deallocation
00122      requires calls to different functions.
00123   3) Pointers of type FILE should be set NULL when not pointing to an open
00124      stream and their closing calls (fclose(), freopen(), etc.) following the
00125      'end_skip' should be guarded against such NULL pointers.
00126 
00127   Error checking with skip_if() is encouraged due to the following advantages:
00128   1) It ensures that a CPL-error code is set.
00129   2) It ensures that the location of the error in the _recipe_ code is noted.
00130   3) The error checking may be confined to a single concise line.
00131   4) It is not necessary to replicate memory deallocation for every error
00132      condition.
00133   5) If more extensive error reporting/handling is required it is not precluded
00134      by the use of skip_if().
00135   6) It allows for a single point of function return.
00136   7) It allows for optional, uniformly formatted debugging/tracing information
00137      at each macro invocation.
00138 
00139   The implementation of skip_if() uses a goto/label construction.
00140   According to Kerningham & Ritchie, The C Programming Language, 2nd edition,
00141   Section 3.8:
00142   "This organization is handy if the error-handling code is non-trivial,
00143   and if errors can occur in several places."
00144 
00145   The use of goto for any other purpose should be avoided.
00146 
00147 */
00148 /*----------------------------------------------------------------------------*/
00149 #define skip_if(CONDITION)                                                     \
00150     do {                                                                       \
00151         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00152                          goto cleanup, "Propagating a pre-existing error");    \
00153         cpl_error_ensure(!(CONDITION), cpl_error_get_code(),                   \
00154                          goto cleanup, "Propagating error");\
00155     } while (0)
00156 
00157 /*----------------------------------------------------------------------------*/
00158 /*
00159   @brief   Skip if A < B
00160   @param   A   The 1st double to compare
00161   @param   B   The 2nd double to compare
00162   @param   MSG The message to use on failure
00163   @see skip_if()
00164   @note A and B are evaluated exactly once
00165 */
00166 /*----------------------------------------------------------------------------*/
00167 #define skip_if_lt(A, B, MSG)                                                  \
00168     do {                                                                       \
00169         const double tmpa = (double)(A);                                       \
00170         const double tmpb = (double)(B);                                       \
00171                                                                                \
00172         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00173                          goto cleanup, "Propagating a pre-existing error");    \
00174         cpl_error_ensure(tmpa >= tmpb, CPL_ERROR_DATA_NOT_FOUND,               \
00175                          goto cleanup, "Need at least %g (not %g) %s",         \
00176                          tmpb, tmpa, MSG);                                     \
00177     } while (0)
00178 
00179 /*----------------------------------------------------------------------------*/
00180 /*
00181   @brief   Conditional skip on coding bug
00182   @param   CONDITION    The condition to check
00183   @see skip_if()
00184   @note unlike assert() this check cannot be disabled
00185  */
00186 /*----------------------------------------------------------------------------*/
00187 #define bug_if(CONDITION)                                                      \
00188     do {                                                                       \
00189         cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),          \
00190                          goto cleanup, "Propagating an unexpected error, "     \
00191                          "please report to " PACKAGE_BUGREPORT);               \
00192         cpl_error_ensure(!(CONDITION), CPL_ERROR_UNSPECIFIED,                  \
00193                          goto cleanup, "Internal error, please report to "     \
00194                          PACKAGE_BUGREPORT);                                   \
00195     } while (0)
00196 
00197 /*----------------------------------------------------------------------------*/
00198 /*
00199   @brief   Conditional skip with error creation
00200   @param   CONDITION    The condition to check
00201   @param   ERROR        The error code to set
00202   @param   MSG          A printf-style error message. As a matter of
00203                         user-friendliness the message should mention any
00204                         value that caused the @em CONDITION to fail.
00205   @see skip_if()
00206   @note unlike assert() this check cannot be disabled
00207  */
00208 /*----------------------------------------------------------------------------*/
00209 #define error_if(CONDITION, ERROR, ...)                                 \
00210     cpl_error_ensure(cpl_error_get_code() == CPL_ERROR_NONE &&          \
00211                      !(CONDITION), ERROR, goto cleanup,  __VA_ARGS__)
00212 
00213 /*----------------------------------------------------------------------------*/
00214 /*
00215   @brief   Propagate a preexisting error, if any
00216   @param   MSG          A printf-style error message.
00217   @see skip_if()
00218  */
00219 /*----------------------------------------------------------------------------*/
00220 #define any_if(...)                                                     \
00221     cpl_error_ensure(!cpl_error_get_code(), cpl_error_get_code(),       \
00222                      goto cleanup,  __VA_ARGS__)
00223 
00224 /*----------------------------------------------------------------------------*/
00225 /*
00226   @brief   Define the single point of resource deallocation and return
00227   @see skip_if()
00228   @note end_skip should be used exactly once in functions that use skip_if() etc
00229 */
00230 /*----------------------------------------------------------------------------*/
00231 #define end_skip \
00232     do {                                                                     \
00233         cleanup:                                                             \
00234         if (cpl_error_get_code())                                            \
00235             cpl_msg_debug(cpl_func, "Cleanup in " __FILE__ " line %u with "  \
00236                           "error '%s' at %s", __LINE__,                      \
00237                           cpl_error_get_message(), cpl_error_get_where());   \
00238         else                                                                 \
00239             cpl_msg_debug(cpl_func, "Cleanup in " __FILE__ " line %u",       \
00240                           __LINE__);                                         \
00241     } while (0)
00242 
00243 
00244 /*----------------------------------------------------------------------------*/
00256 /*----------------------------------------------------------------------------*/
00257 #define irplib_ensure(CONDITION, ec, ...)                                      \
00258     cpl_error_ensure(CONDITION, ec, goto cleanup,  __VA_ARGS__)
00259 
00260 /*----------------------------------------------------------------------------*/
00290 /*----------------------------------------------------------------------------*/
00291 
00292 #define irplib_check(COMMAND, ...)                                             \
00293   do {                                                                         \
00294     cpl_errorstate irplib_check_prestate = cpl_errorstate_get();               \
00295     skip_if(0);                                                                \
00296     COMMAND;                                                                   \
00297         irplib_trace(); \
00298     irplib_ensure(cpl_errorstate_is_equal(irplib_check_prestate),              \
00299                   cpl_error_get_code(), __VA_ARGS__);                          \
00300         irplib_trace(); \
00301   } while (0)
00302 
00303 /*-----------------------------------------------------------------------------
00304                                    Function prototypes
00305  -----------------------------------------------------------------------------*/
00306 
00307 cpl_error_code irplib_dfs_save_image(cpl_frameset            *,
00308                                      const cpl_parameterlist *,
00309                                      const cpl_frameset      *,
00310                                      const cpl_image         *,
00311                                      cpl_type_bpp             ,
00312                                      const char              *,
00313                                      const char              *,
00314                                      const cpl_propertylist  *,
00315                                      const char              *,
00316                                      const char              *,
00317                                      const char              *);
00318 
00319 
00320 cpl_error_code irplib_dfs_save_propertylist(cpl_frameset            *,
00321                                             const cpl_parameterlist *,
00322                                             const cpl_frameset      *,
00323                                             const char              *,
00324                                             const char              *,
00325                                             const cpl_propertylist  *,
00326                                             const char              *,
00327                                             const char              *,
00328                                             const char              *);
00329 
00330 cpl_error_code irplib_dfs_save_imagelist(cpl_frameset            *,
00331                                          const cpl_parameterlist *,
00332                                          const cpl_frameset      *,
00333                                          const cpl_imagelist     *,
00334                                          cpl_type_bpp             ,
00335                                          const char              *,
00336                                          const char              *,
00337                                          const cpl_propertylist  *,
00338                                          const char              *,
00339                                          const char              *,
00340                                          const char              *);
00341 
00342 cpl_error_code irplib_dfs_save_table(cpl_frameset            *,
00343                                      const cpl_parameterlist *,
00344                                      const cpl_frameset      *,
00345                                      const cpl_table         *,
00346                                      const cpl_propertylist  *,
00347                                      const char              *,
00348                                      const char              *,
00349                                      const cpl_propertylist  *,
00350                                      const char              *,
00351                                      const char              *,
00352                                      const char              *);
00353 
00354 void irplib_reset(void);
00355 int irplib_compare_tags(cpl_frame *, cpl_frame *);
00356 const char * irplib_frameset_find_file(const cpl_frameset *, const char *);
00357 const cpl_frame * irplib_frameset_get_first_from_group(const cpl_frameset *,
00358                                                        cpl_frame_group);
00359 
00360 cpl_error_code irplib_apertures_find_max_flux(const cpl_apertures *, int *,
00361                                               int);
00362 
00363 int irplib_isinf(double value);
00364 int irplib_isnan(double value);
00365 
00366 void irplib_errorstate_warning(unsigned, unsigned, unsigned);
00367 
00368 cpl_error_code
00369 irplib_dfs_table_convert(cpl_table *, cpl_frameset *, const cpl_frameset *,
00370                          int, char, const char *, const char *,
00371                          const cpl_parameterlist *, const char *,
00372                          const cpl_propertylist *, const cpl_propertylist *,
00373                          const char *, const char *, const char *,
00374                          cpl_boolean (*)(cpl_table *, const char *, int,
00375                                             const cpl_frame *,
00376                                             const cpl_parameterlist *),
00377                          cpl_error_code (*)(cpl_table *,
00378                                             const cpl_frameset *,
00379                                             const cpl_parameterlist *));
00380 
00381 cpl_error_code irplib_table_read_from_frameset(cpl_table *,
00382                                                const cpl_frameset *,
00383                                                int,
00384                                                char,
00385                                                const cpl_parameterlist *,
00386                                                cpl_boolean (*)
00387                                                (cpl_table *, const char *,
00388                                                 int, const cpl_frame *,
00389                                                 const cpl_parameterlist *));
00390 
00391 cpl_error_code irplib_image_split(const cpl_image *,
00392                                   cpl_image *, cpl_image *, cpl_image *,
00393                                   double, cpl_boolean,
00394                                   double, cpl_boolean,
00395                                   double, double,
00396                                   cpl_boolean, cpl_boolean, cpl_boolean);
00397 
00398 void irplib_errorstate_dump_warning(unsigned, unsigned, unsigned);
00399 void irplib_errorstate_dump_info(unsigned, unsigned, unsigned);
00400 void irplib_errorstate_dump_debug(unsigned, unsigned, unsigned);
00401 /* wrapper for replace deprecated function cpl_polynomial_fit_1d_create*/
00402 cpl_polynomial * irplib_polynomial_fit_1d_create(
00403         const cpl_vector    *   x_pos,
00404         const cpl_vector    *   values,
00405         int                     degree,
00406         double              *   mse
00407         );
00408 cpl_polynomial * irplib_polynomial_fit_1d_create_chiq(
00409         const cpl_vector    *   x_pos,
00410         const cpl_vector    *   values,
00411         int                     degree,
00412         double              *   rechiq
00413         );
00414 
00415 cpl_error_code irplib_frameset_sort(const cpl_frameset *  self, int* index, double* exptime);
00416 
00417 #endif

This file is part of the GIRAFFE Pipeline Reference Manual 2.8.7.
Documentation copyright © 2002-2006 European Southern Observatory.
Generated on Fri Aug 6 13:56:43 2010 by doxygen 1.5.1 written by Dimitri van Heesch, © 1997-2004