Eina_Magic provides run-time type-checking. More...
Macros | |
#define | EINA_MAGIC_NONE 0x1234fedc |
Random value for specifying that a structure using the magic feature has already been freed. More... | |
#define | EINA_MAGIC Eina_Magic __magic; |
Declaration of a variable of type Eina_Magic. More... | |
#define | EINA_MAGIC_SET(d, m) (d)->__magic = (m) |
Set the magic number of d to m . More... | |
#define | EINA_MAGIC_CHECK(d, m) (EINA_LIKELY((d) && ((d)->__magic == (m)))) |
Test if d is NULL or not, and if not NULL , if d->__eina_magic is equal to m . More... | |
#define | EINA_MAGIC_FAIL(d, m) |
Call eina_magic_fail() with the parameters d , d->__magic , m , FILE, FUNCTION and LINE. More... | |
Typedefs | |
typedef unsigned int | Eina_Magic |
An abstract type for a magic number. | |
Functions | |
const char * | eina_magic_string_get (Eina_Magic magic) |
Return the string associated to the given magic identifier. More... | |
Eina_Bool | eina_magic_string_set (Eina_Magic magic, const char *magic_name) |
Set the string associated to the given magic identifier. More... | |
Eina_Bool | eina_magic_string_static_set (Eina_Magic magic, const char *magic_name) |
Set the string associated to the given magic identifier. More... | |
void | eina_magic_fail (void *d, Eina_Magic m, Eina_Magic req_m, const char *file, const char *fnc, int line) |
Display a message or abort if a magic check failed. More... | |
Variables | |
Eina_Error | EINA_ERROR_MAGIC_FAILED |
Eina_Magic provides run-time type-checking.
C is a weak statically typed language, in other words, it will just check for types during compile time and any cast will make the compiler believe the type is correct.
In real world code we often need to deal with casts, either explicit or implicit by means of void*
. We also need to resort to casts when doing inheritance in C.
Eina_Magic give us a way to do casts and still be certain of the type we are opearting on.
An example should elucidate matters.
#define EINA_MAGIC_NONE 0x1234fedc |
Random value for specifying that a structure using the magic feature has already been freed.
It is used by eina_magic_fail().
If the magic feature of Eina is disabled, EINA_MAGIC_NONE is just 0
.
Referenced by eina_cow_free(), eina_magic_fail(), eina_matrixsparse_free(), eina_rectangle_pool_free(), eina_rectangle_pool_release(), eina_simple_xml_attribute_free(), eina_simple_xml_node_tag_new(), eina_tiler_iterator_new(), eldbus_connection_ref(), eldbus_connection_send(), eldbus_message_unref(), and eldbus_signal_handler_add().
#define EINA_MAGIC Eina_Magic __magic; |
Declaration of a variable of type Eina_Magic.
To put in a structure when one wants to use the magic feature of Eina with the functions of that structure, like that:
If the magic feature of Eina is disabled, EINA_MAGIC does nothing.
#define EINA_MAGIC_SET | ( | d, | |
m | |||
) | (d)->__magic = (m) |
Set the magic number of d
to m
.
d
must be a valid pointer to a structure holding an Eina magic number declaration. Use EINA_MAGIC to add such declaration.
If the magic feature of Eina is disabled, EINA_MAGIC_CHECK is just the value 0
.
Referenced by eet_data_write(), eet_list_entries(), eina_array_accessor_new(), eina_array_iterator_new(), eina_array_new(), eina_array_step_set(), eina_cow_add(), eina_cow_free(), eina_cow_write(), eina_file_direct_ls(), eina_file_dup(), eina_file_filename_get(), eina_file_ls(), eina_file_open(), eina_file_stat_ls(), eina_hash_iterator_data_new(), eina_hash_iterator_key_new(), eina_hash_iterator_tuple_new(), eina_hash_new(), eina_inarray_accessor_new(), eina_inarray_iterator_new(), eina_inarray_iterator_reversed_new(), eina_inlist_accessor_new(), eina_inlist_iterator_new(), eina_list_accessor_new(), eina_list_iterator_new(), eina_list_iterator_reversed_new(), eina_matrixsparse_free(), eina_matrixsparse_iterator_complete_new(), eina_matrixsparse_iterator_new(), eina_matrixsparse_new(), eina_rectangle_pool_free(), eina_rectangle_pool_new(), eina_rectangle_pool_release(), eina_rectangle_pool_request(), eina_simple_xml_attribute_free(), eina_simple_xml_attribute_new(), eina_simple_xml_node_load(), eina_simple_xml_node_tag_free(), eina_simple_xml_node_tag_new(), eina_tile_grid_slicer_iterator_new(), eina_tiler_iterator_new(), eina_tiler_new(), eina_xattr_fd_ls(), eina_xattr_ls(), eina_xattr_value_fd_ls(), eina_xattr_value_ls(), eldbus_connection_ref(), eldbus_connection_send(), eldbus_message_unref(), eldbus_object_get(), eldbus_proxy_get(), eldbus_shutdown(), eldbus_signal_handler_add(), evas_object_box_accessor_new(), evas_object_box_iterator_new(), evas_object_grid_accessor_new(), evas_object_grid_iterator_new(), evas_object_smart_iterator_new(), evas_object_table_accessor_new(), and evas_object_table_iterator_new().
#define EINA_MAGIC_CHECK | ( | d, | |
m | |||
) | (EINA_LIKELY((d) && ((d)->__magic == (m)))) |
Test if d
is NULL
or not, and if not NULL
, if d->__eina_magic
is equal to m
.
d
must be a structure that holds an Eina magic number declaration. Use EINA_MAGIC to add such declaration.
If the magic feature of Eina is disabled, EINA_MAGIC_CHECK is just the value 1
.
Referenced by eet_data_write().
#define EINA_MAGIC_FAIL | ( | d, | |
m | |||
) |
Call eina_magic_fail() with the parameters d
, d->__magic
, m
, FILE, FUNCTION and LINE.
d
must be a structure that holds an Eina magic number declaration. Use EINA_MAGIC to add such declaration.
If the magic feature of Eina is disabled, EINA_MAGIC_FAIL does nothing.
const char* eina_magic_string_get | ( | Eina_Magic | magic | ) |
Return the string associated to the given magic identifier.
magic | The magic identifier. |
This function returns the string associated to magic
. Even if none are found this function still returns non NULL
, in this case an identifier such as "(none)", "(undefined)" or "(unknown)".
The following identifiers may be returned whenever magic is invalid, with their meanings:
References EAPI.
Referenced by eina_magic_fail().
Eina_Bool eina_magic_string_set | ( | Eina_Magic | magic, |
const char * | magic_name | ||
) |
Set the string associated to the given magic identifier.
magic | The magic identifier. |
magic_name | The string associated to the identifier, must not be NULL . |
This function sets the string magic_name
to magic
. It is not checked if number or string are already set, in which case you will end with duplicates. Internally, eina will make a copy of magic_name
.
References EAPI, EINA_FALSE, and EINA_TRUE.
Referenced by ecore_con_init(), and eldbus_init().
Eina_Bool eina_magic_string_static_set | ( | Eina_Magic | magic, |
const char * | magic_name | ||
) |
Set the string associated to the given magic identifier.
magic | The magic identifier. |
magic_name | The string associated to the identifier, must not be NULL . |
This function sets the string magic_name
to magic
. It is not checked if number or string are already set, in which case you might end with duplicates. Eina will not make a copy of magic_name
, this means that magic_name
has to be a valid pointer for as long as magic
is used.
References EAPI, EINA_FALSE, and EINA_TRUE.
void eina_magic_fail | ( | void * | d, |
Eina_Magic | m, | ||
Eina_Magic | req_m, | ||
const char * | file, | ||
const char * | fnc, | ||
int | line | ||
) |
Display a message or abort if a magic check failed.
d | The checked data pointer. |
m | The magic identifer to check. |
req_m | The requested magic identifier to check. |
file | The file in which the magic check failed. |
fnc | The function in which the magic check failed. |
line | The line at which the magic check failed. |
This function displays an error message if a magic check has failed, using the following logic in the following order:
d
is NULL
, a message warns about a NULL
pointer. m
is equal to EINA_MAGIC_NONE, a message warns about a handle that was already freed. m
is equal to req_m
, a message warns about a handle that is of wrong type. If the environment variable EINA_LOG_ABORT is set, abort() is called and the program stops. It is useful for debugging programs with gdb.
References EINA_LOG_DOMAIN_GLOBAL, EINA_LOG_LEVEL_CRITICAL, EINA_LOG_LEVEL_ERR, eina_log_print(), EINA_MAGIC_NONE, and eina_magic_string_get().