Magic
[Tools]

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

Defines
#define	EINA_MAGIC_NONE   0x1234fedc
	Random value for specifying that a structure using the magic feature has already been freed.
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.
Eina_Bool	eina_magic_string_set (Eina_Magic magic, const char *magic_name)
	Set the string associated to the given magic identifier.
Eina_Bool	eina_magic_string_static_set (Eina_Magic magic, const char *magic_name)
	Set the string associated to the given magic identifier.
Variables
Eina_Error	EINA_ERROR_MAGIC_FAILED
	Error identifier corresponding to magic check failure.

---

Detailed Description

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.

Note:

It should be noted that it is considered 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.

---

Define Documentation

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

Examples:

eina_magic_01.c.

Referenced by eina_matrixsparse_free(), eina_rectangle_pool_free(), eina_rectangle_pool_release(), and eina_simple_xml_attribute_free().

---

Function Documentation

const char* eina_magic_string_get

(

Eina_Magic

magic

)

Return the string associated to the given magic identifier.

Parameters:

magic

The magic identifier.

Returns:

The string associated to the 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:

• (none): no magic was registered exists at all.
• (undefined): magic was registered and found, but no string associated.
• (unknown): magic was not found in the registry.

Warning:

The returned value must not be freed.

Eina_Bool eina_magic_string_set	(	Eina_Magic	magic,
		const char *	magic_name
	)

Set the string associated to the given magic identifier.

Parameters:

	magic	The magic identifier.
	magic_name	The string associated to the identifier, must not be NULL.

Returns:

EINA_TRUE on success, EINA_FALSE on failure.

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.

See also:

eina_magic_string_static_set()

Examples:

eina_magic_01.c.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

Eina_Bool eina_magic_string_static_set	(	Eina_Magic	magic,
		const char *	magic_name
	)

Set the string associated to the given magic identifier.

Parameters:

	magic	The magic identifier.
	magic_name	The string associated to the identifier, must not be NULL.

Returns:

EINA_TRUE on success, EINA_FALSE on failure.

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.

See also:

eina_magic_string_set()

Examples:

eina_magic_01.c.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.