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(*)(unsigned, unsigned, unsigned)	dump_one
	)

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);
}

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().