Magic
Eina » Tools

Eina_Magic provides run-time type-checking. More...

## Macros

#define | EINA_MAGIC_NONE 0x1234fedc
| Definition of a random value for specifying that a structure using the magic feature has already been freed.
#define | EINA_MAGIC Eina_Magic __magic;
| Definition of of a variable of type Eina_Magic.
#define | EINA_MAGIC_SET(d, m)
| Definition to set the magic number of `d` to `m`.
#define | EINA_MAGIC_CHECK(d, m)
| Definition to test if `d` is `NULL` or not, and if not `NULL`, if `d->__eina_magic` is equal to `m`.
#define | EINA_MAGIC_FAIL(d, m)
| Definition to call eina_magic_fail() with the parameters `d`, `d->__magic`, `m`, FILE, func, and LINE.

## Typedefs

typedef unsigned int | Eina_Magic
| An abstract type for a magic number.

## Functions

EINA_API const char * | eina_magic_string_get (Eina_Magic magic)
| Gets the string associated with the given magic identifier.
EINA_API Eina_Bool | eina_magic_string_set (Eina_Magic magic, const char *magic_name)
| Sets the string associated with the given magic identifier.
EINA_API Eina_Bool | eina_magic_string_static_set (Eina_Magic magic, const char *magic_name)
| Sets the string associated with the given magic identifier.
EINA_API void | eina_magic_fail (void *d, Eina_Magic m, Eina_Magic req_m, const char *file, const char *fnc, int line)
| Displays a message or aborts if a magic check failed.

## Variables

EINA_API Eina_Error | EINA_ERROR_MAGIC_FAILED
| The error identifier corresponding to the magic check failure.
EINA_API Eina_Error | EINA_ERROR_MAGIC_FAILED = 0
| The error identifier corresponding to the magic check failure.

## Detailed Description

Eina_Magic provides run-time type-checking.

C is a weak statically typed language, in other words, it just checks for types during compile time and any cast that makes the compiler believe the type is correct.

In the 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 gives us a way to do casts and still be certain of the type we are operating on.

Note
  It should be noted that it is considered a good practice to disable Eina_Magic for production code. The reasoning is that any Eina_Magic errors should have been caught during testing and therefore there is no reason to incur the performance downside of Eina_Magic.

An example should elucidate matters.

## Macro Definition Documentation

## EINA_MAGIC_NONE

#define EINA_MAGIC_NONE 0x1234fedc

Definition of a random value for specifying that a structure using the magic feature has already been freed.

It is used by eina_magic_fail().

Note
  If the magic feature of Eina is disabled, EINA_MAGIC_NONE is just `0`.

Examples
  eina_magic_01.c.

Referenced by eina_cow_free(), eina_magic_fail(), eina_matrixsparse_free(), eina_rectangle_pool_free(), eina_rectangle_pool_release(), eina_simple_xml_attribute_free(), and eldbus_message_unref().

## EINA_MAGIC

#define EINA_MAGIC Eina_Magic __magic;

Definition of 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 this:

struct Foo
{
int i;
EINA_MAGIC
};
EINA_MAGIC
#define EINA_MAGIC
Definition of of a variable of type Eina_Magic.
Definition eina_magic.h:224

Note
  If the magic feature of Eina is disabled, EINA_MAGIC does nothing.

Examples
  eina_magic_01.c.

## EINA_MAGIC_SET

#define EINA_MAGIC_SET | ( |  | d,
|  |  | m )

Value:
(d)->__magic = (m)

Definition to 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 a declaration.

Note
  If the magic feature of Eina is disabled, EINA_MAGIC_CHECK is just the value `0`.

Examples
  eina_magic_01.c.

Referenced by ecore_con_url_new(), edje_color_class_active_iterator_new(), edje_file_iterator_new(), edje_mmap_color_class_iterator_new(), edje_mmap_size_class_iterator_new(), edje_mmap_text_class_iterator_new(), edje_size_class_active_iterator_new(), edje_text_class_active_iterator_new(), eet_list_entries(), eina_array_accessor_new(), eina_array_iterator_new(), eina_array_new(), eina_array_step_set(), eina_carray_iterator_new(), eina_carray_length_accessor_new(), eina_carray_length_iterator_new(), eina_carray_length_ptr_accessor_new(), eina_cow_add(), eina_cow_free(), eina_cow_write(), eina_file_clean_close(), eina_file_direct_ls(), eina_file_ls(), eina_file_map_lines(), eina_file_open(), eina_file_open(), eina_file_stat_ls(), eina_file_virtualize(), 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_iterator_filter_new(), eina_iterator_processed_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_multi_iterator_internal_new(), eina_quadtree_add(), eina_quadtree_del(), eina_quadtree_free(), eina_quadtree_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_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_message_unref(), eldbus_object_get(), eldbus_proxy_get(), elm_prefs_data_new(), elm_store_filesystem_new(), and elm_transit_add().

## EINA_MAGIC_CHECK

#define EINA_MAGIC_CHECK | ( |  | d,
|  |  | m )

Value:
(EINA_LIKELY((d) && ((d)->__magic == (m))))
EINA_LIKELY
#define EINA_LIKELY(exp)
Indicates that the expression is likely to be TRUE.
Definition eina_types.h:435

Definition to 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 a declaration.

Note
  If the magic feature of Eina is disabled, EINA_MAGIC_CHECK is just the value `1`.

Examples
  eina_magic_01.c.

Referenced by elm_store_cache_get(), elm_store_cache_set(), elm_store_fetch_func_set(), elm_store_fetch_thread_get(), elm_store_fetch_thread_set(), elm_store_filesystem_directory_get(), elm_store_filesystem_directory_set(), elm_store_free(), elm_store_item_data_get(), elm_store_item_data_set(), elm_store_item_filesystem_path_get(), elm_store_item_genlist_item_get(), elm_store_item_store_get(), elm_store_list_func_set(), elm_store_sorted_get(), elm_store_sorted_set(), elm_store_target_genlist_set(), and elm_store_unfetch_func_set().

## EINA_MAGIC_FAIL

#define EINA_MAGIC_FAIL | ( |  | d,
|  |  | m )

Value:
eina_magic_fail((void *)(d), \
(d) ? (d)->__magic : 0, \
(m), \
__FILE__, \
__func__, \
__LINE__);
eina_magic_fail
EINA_API void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m, const char *file, const char *fnc, int line)
Displays a message or aborts if a magic check failed.
Definition eina_magic.c:261

Definition to call eina_magic_fail() with the parameters `d`, `d->__magic`, `m`, FILE, func, and LINE.

`d` must be a structure that holds an Eina magic number declaration. Use EINA_MAGIC to add such a declaration.

Note
  If the magic feature of Eina is disabled, EINA_MAGIC_FAIL does nothing.

Examples
  eina_magic_01.c.

## Function Documentation

## eina_magic_string_get()

EINA_API const char * eina_magic_string_get | ( | Eina_Magic | magic | ) |

Gets the string associated with the given 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)".

Parameters

  [in] | magic | The magic identifier

Returns
  The string associated to the identifier

Note
  The following identifiers may be returned whenever magic is invalid, with their meanings:

- (none): No magic that had been registered exists at all.
- (undefined): Magic is registered and found, but no string is associated.
- (unknown): Magic is not found in the registry.

Warning
  The returned value must not be freed.

Referenced by eina_magic_fail().

## eina_magic_string_set()

EINA_API Eina_Bool eina_magic_string_set | ( | Eina_Magic | magic,
|  | const char * | magic_name )

Sets the string associated with the given magic identifier.

This function sets the string `magic_name` to `magic`. It is not checked if number or string are already set, in which case you end with duplicates. Internally, eina makes a copy of `magic_name`.

Parameters

  [in] | magic | The magic identifier
  [in] | magic_name | The string associated with the identifier, must not be `NULL`

Returns
  EINA_TRUE on success, otherwise EINA_FALSE on failure

See also
  eina_magic_string_static_set()

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and ERR.

Referenced by eldbus_init().

## eina_magic_string_static_set()

EINA_API Eina_Bool eina_magic_string_static_set | ( | Eina_Magic | magic,
|  | const char * | magic_name )

Sets the string associated with the given magic identifier.

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 does 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.

Parameters

  [in] | magic | The magic identifier
  [in] | magic_name | The string associated with the identifier, must not be `NULL`

Returns
  EINA_TRUE on success, otherwise EINA_FALSE on failure

See also
  eina_magic_string_set()

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

## eina_magic_fail()

EINA_API void eina_magic_fail | ( | void * | d,
|  | Eina_Magic | m,
|  | Eina_Magic | req_m,
|  | const char * | file,
|  | const char * | fnc,
|  | int | line )

Displays a message or aborts if a magic check failed.

This function displays an error message if a magic check has failed, using the following logic in the following order:

- If `d` is `NULL`, a message warns about a `NULL` pointer.
- Otherwise, if `m` is equal to EINA_MAGIC_NONE, a message warns about a handle that is already freed.
- Otherwise, if `m` is equal to `req_m`, a message warns about a handle that is of the wrong type.
- Otherwise, a message warns you about abusing that function...

Parameters

  [in] | d | The checked data pointer
  [in] | m | The magic identifier to check
  [in] | req_m | The requested magic identifier to check
  [in] | file | The file in which the magic check failed
  [in] | fnc | The function in which the magic check failed
  [in] | line | The line at which the magic check failed

Warning
  You should strongly consider using EINA_MAGIC_FAIL(d, m) instead.

Note
  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_MAGIC_NONE, and eina_magic_string_get().