Loading...
Searching...
No Matches
Handling of multiple CPL errors

## Functions

void | cpl_errorstate_dump (cpl_errorstate self, cpl_boolean reverse, void(*dump_one)(unsigned, unsigned, unsigned))
| Dump the CPL error state.
void | cpl_errorstate_dump_one (unsigned self, unsigned first, unsigned last)
| Dump a single CPL error.
void | cpl_errorstate_dump_one_debug (unsigned self, unsigned first, unsigned last)
| Dump a single CPL error using cpl_msg_debug().
void | cpl_errorstate_dump_one_info (unsigned self, unsigned first, unsigned last)
| Dump a single CPL error using cpl_msg_info().
void | cpl_errorstate_dump_one_warning (unsigned self, unsigned first, unsigned last)
| Dump a single CPL error using cpl_msg_warning().
cpl_errorstate | cpl_errorstate_get (void)
| Get the CPL errorstate.
cpl_boolean | cpl_errorstate_is_equal (cpl_errorstate self)
| Detect a change in the CPL error state.
void | cpl_errorstate_set (cpl_errorstate self)
| Set the CPL errorstate.

## Detailed Description

This module provides functions for error detection and recovery and for producing an error traceback.

It is built on top of the `cpl_error` module.

Synopsis:
  #include <cpl_errorstate.h>

## Function Documentation

## cpl_errorstate_dump()

void cpl_errorstate_dump | ( | cpl_errorstate | self,
|  | cpl_boolean | reverse,
|  | void(* | dump_one )(unsigned, unsigned, unsigned) )

Dump the CPL error state.

Parameters

  self | Dump errors more recent than self
  reverse | Reverse the chronological order of the dump
  dump_one | Function that dumps a single CPL error, or NULL

Returns
  void

Note
  dump_one may be NULL, in that case cpl_errorstate_dump_one() is called. If there are no CPL errors to be dumped, (*dump_one)() is called once with all zeros, which allows the dump-function to report that there are no errors to dump. During calls to (*dump_one)() the CPL error system has been put into a special read-only mode that prevents any change of the CPL error state. This means that any calls from (*dump_one)() to cpl_error_reset(), cpl_error_set(), cpl_error_set_where() and cpl_errorstate_set() have no effect. Also calls from (*dump_one)() to cpl_errorstate_dump() have no effect.

See also
  cpl_errorstate_dump_one

CPL-based code with insufficient error checking can generate a large number of CPL errors. To avoid that a subsequent call to cpl_errorstate_dump() will fill up the output device, calls to the dump-function are skipped and only counted and the count reported when dump_one is NULL and the CPL error code is CPL_ERROR_HISTORY_LOST.

Example of usage:

cpl_errorstate prev_state = cpl_errorstate_get();
// Call one or more CPL functions
if (cpl_errorstate_is_equal(prev_state)) {
// No error happened
} else {
// One or more errors happened
// Dump the error(s) in chronological order
cpl_errorstate_dump(prev_state, CPL_FALSE,
cpl_errorstate_dump_one);
// Recover from the error(s)
cpl_errorstate_set(prev_state);
}
cpl_errorstate_dump_one
void cpl_errorstate_dump_one(unsigned self, unsigned first, unsigned last)
Dump a single CPL error.
Definition cpl_errorstate.c:420
cpl_errorstate_set
void cpl_errorstate_set(cpl_errorstate self)
Set the CPL errorstate.
Definition cpl_errorstate.c:226
cpl_errorstate_is_equal
cpl_boolean cpl_errorstate_is_equal(cpl_errorstate self)
Detect a change in the CPL error state.
Definition cpl_errorstate.c:249
cpl_errorstate_get
cpl_errorstate cpl_errorstate_get(void)
Get the CPL errorstate.
Definition cpl_errorstate.c:192
cpl_errorstate_dump
void cpl_errorstate_dump(cpl_errorstate self, cpl_boolean reverse, void(*dump_one)(unsigned, unsigned, unsigned))
Dump the CPL error state.
Definition cpl_errorstate.c:311

References cpl_error_get_code(), CPL_ERROR_HISTORY_LOST, cpl_errorstate_dump_one(), and cpl_msg_error().

Referenced by cpl_test_end(), and cpl_wlcalib_find_best_1d().

## cpl_errorstate_dump_one()

void cpl_errorstate_dump_one | ( | unsigned | self,
|  | unsigned | first,
|  | unsigned | last )

Dump a single CPL error.

Parameters

  self | The number of the current error to be dumped
  first | The number of the first error to be dumped
  last | The number of the last error to be dumped

Returns
  void

Note
  This function is implemented using only exported CPL functions.

See also
  cpl_errorstate_dump

This function will dump a single CPL error, using the CPL error accessor functions. The error is numbered with the value of self.

The actual output is produced by cpl_msg_error().

first and last are provided in the API to allow for special messaging in the dump of the first and last errors.

Alternative functions for use with cpl_errorstate_dump() may use all accessor functions of the CPL error module and those functions of the CPL message module that produce messages. Additionally, the indentation functions of the CPL message module may be used, provided that the indentation is set back to its original state after the last error has been processed.

References cpl_msg_error().

Referenced by cpl_errorstate_dump().

## cpl_errorstate_dump_one_debug()

void cpl_errorstate_dump_one_debug | ( | unsigned | self,
|  | unsigned | first,
|  | unsigned | last )

Dump a single CPL error using cpl_msg_debug().

Parameters

  self | The number of the current error to be dumped
  first | The number of the first error to be dumped
  last | The number of the last error to be dumped

Returns
  void

See also
  cpl_errorstate_dump_one, cpl_msg_debug()

References cpl_msg_debug().

Referenced by cpl_wlcalib_find_best_1d().

## cpl_errorstate_dump_one_info()

void cpl_errorstate_dump_one_info | ( | unsigned | self,
|  | unsigned | first,
|  | unsigned | last )

Dump a single CPL error using cpl_msg_info().

Parameters

  self | The number of the current error to be dumped
  first | The number of the first error to be dumped
  last | The number of the last error to be dumped

Returns
  void

See also
  cpl_errorstate_dump_one, cpl_msg_info()

References cpl_msg_info().

## cpl_errorstate_dump_one_warning()

void cpl_errorstate_dump_one_warning | ( | unsigned | self,
|  | unsigned | first,
|  | unsigned | last )

Dump a single CPL error using cpl_msg_warning().

Parameters

  self | The number of the current error to be dumped
  first | The number of the first error to be dumped
  last | The number of the last error to be dumped

Returns
  void

See also
  cpl_errorstate_dump_one, cpl_msg_warning()

References cpl_msg_warning().

## cpl_errorstate_get()

cpl_errorstate cpl_errorstate_get | ( | void |  | ) |

Get the CPL errorstate.

Returns
  The CPL errorstate

Note
  The caller should not modify the returned value nor transfer it to another function/scope.

Example of usage:

cpl_errorstate prev_state = cpl_errorstate_get();
// (Call one or more CPL functions here)
if (cpl_errorstate_is_equal(prev_state)) {
// No error happened
} else {
// One or more errors happened
// Recover from the error(s)
cpl_errorstate_set(prev_state);
}

Referenced by cpl_apertures_extract(), cpl_apertures_extract_mask(), cpl_apertures_get_fwhm(), cpl_array_get(), cpl_array_get_complex(), cpl_array_get_cplsize(), cpl_array_get_double(), cpl_array_get_double_complex(), cpl_array_get_float(), cpl_array_get_float_complex(), cpl_array_get_int(), cpl_array_get_long(), cpl_array_get_long_long(), cpl_array_get_max(), cpl_array_get_mean(), cpl_array_get_mean_complex(), cpl_array_get_median(), cpl_array_get_min(), cpl_array_get_stdev(), cpl_array_is_valid(), cpl_dfs_setup_product_header(), cpl_dfs_sign_products(), cpl_fit_image_gaussian(), cpl_flux_get_noise_ring(), cpl_frameset_dump(), cpl_frameset_extract(), cpl_frameset_find(), cpl_frameset_labelise(), cpl_gaussian_eval_2d(), cpl_geom_img_offset_fine(), cpl_image_get_fwhm(), cpl_imagelist_load_frameset(), cpl_mask_extract(), cpl_matrix_get_determinant(), cpl_parameterlist_find(), cpl_parameterlist_find_context(), cpl_parameterlist_find_tag(), cpl_parameterlist_find_type(), cpl_parameterlist_get_first(), cpl_parameterlist_get_last(), cpl_parameterlist_get_next(), cpl_plot_bivectors(), cpl_plot_column(), cpl_plot_columns(), cpl_plot_image_col(), cpl_plot_image_row(), cpl_plot_vectors(), cpl_propertylist_get(), cpl_propertylist_get_bool(), cpl_propertylist_get_char(), cpl_propertylist_get_double(), cpl_propertylist_get_double_complex(), cpl_propertylist_get_float(), cpl_propertylist_get_float_complex(), cpl_propertylist_get_int(), cpl_propertylist_get_long(), cpl_propertylist_get_long_long(), cpl_propertylist_get_string(), cpl_table_get_column_max(), cpl_table_get_column_mean(), cpl_table_get_column_mean_complex(), cpl_table_get_column_median(), cpl_table_get_column_min(), cpl_table_get_column_stdev(), cpl_table_has_invalid(), cpl_table_has_valid(), cpl_table_is_valid(), cpl_wcs_platesol(), and cpl_wlcalib_find_best_1d().

## cpl_errorstate_is_equal()

cpl_boolean cpl_errorstate_is_equal | ( | cpl_errorstate | self | ) |

Detect a change in the CPL error state.

Parameters

  self | The return value of a previous call to cpl_errorstate_get()

Returns
  CPL_TRUE iff the current error state is equal to self.

See also
  cpl_errorstate_get

Referenced by cpl_apertures_extract_mask(), cpl_array_get(), cpl_array_get_complex(), cpl_array_get_cplsize(), cpl_array_get_double(), cpl_array_get_double_complex(), cpl_array_get_float(), cpl_array_get_float_complex(), cpl_array_get_int(), cpl_array_get_long(), cpl_array_get_long_long(), cpl_array_get_max(), cpl_array_get_mean(), cpl_array_get_mean_complex(), cpl_array_get_median(), cpl_array_get_min(), cpl_array_get_stdev(), cpl_array_is_valid(), cpl_flux_get_noise_ring(), cpl_frameset_find(), cpl_gaussian_eval_2d(), cpl_image_get_fwhm(), cpl_imagelist_load_frameset(), cpl_mask_extract(), cpl_parameterlist_find(), cpl_parameterlist_find_context(), cpl_parameterlist_find_tag(), cpl_parameterlist_find_type(), cpl_parameterlist_get_first(), cpl_parameterlist_get_last(), cpl_parameterlist_get_next(), cpl_plot_bivectors(), cpl_plot_column(), cpl_plot_columns(), cpl_plot_image_col(), cpl_plot_image_row(), cpl_plot_vectors(), cpl_propertylist_get(), cpl_propertylist_get_bool(), cpl_propertylist_get_char(), cpl_propertylist_get_double(), cpl_propertylist_get_double_complex(), cpl_propertylist_get_float(), cpl_propertylist_get_float_complex(), cpl_propertylist_get_int(), cpl_propertylist_get_long(), cpl_propertylist_get_long_long(), cpl_propertylist_get_string(), cpl_table_get_column_max(), cpl_table_get_column_mean(), cpl_table_get_column_mean_complex(), cpl_table_get_column_median(), cpl_table_get_column_min(), cpl_table_get_column_stdev(), cpl_table_has_invalid(), cpl_table_has_valid(), cpl_table_is_valid(), cpl_wcs_platesol(), and cpl_wlcalib_find_best_1d().

## cpl_errorstate_set()

void cpl_errorstate_set | ( | cpl_errorstate | self | ) |

Set the CPL errorstate.

Parameters

  self | The return value of a previous call to cpl_errorstate_get()

Returns
  void

See also
  cpl_errorstate_get

Note
  If a CPL error was created before the call to cpl_errorstate_get() that returned self and if more than CPL_ERROR_HISTORY_SIZE CPL errors was created after that, then the accessor functions of the CPL error object (cpl_error_get_code() etc.) will return wrong values. In this case cpl_error_get_code() is still guaranteed not to return CPL_ERROR_NONE. Moreover, the default value of CPL_ERROR_HISTORY_SIZE is guaranteed to be large enough to prevent this situation from arising due to a call of a CPL function.

Referenced by cpl_apertures_extract(), cpl_apertures_get_fwhm(), cpl_dfs_setup_product_header(), cpl_dfs_sign_products(), cpl_fit_image_gaussian(), cpl_flux_get_noise_ring(), cpl_frameset_dump(), cpl_frameset_extract(), cpl_frameset_labelise(), cpl_geom_img_offset_fine(), cpl_imagelist_load_frameset(), cpl_matrix_get_determinant(), and cpl_wlcalib_find_best_1d().