eina_magic_example_01_page

Whenever using Eina we must include it:

#include <Eina.h>
Eina.h
Eina Utility library.

For this example we are going to define two classes, person and pilot, and since every pilot is a person we use inheritance. To be type safe we are going to add EINA_MAGIC to our classes:

#define BASETYPE_MAGIC 0x12345
struct _person {
EINA_MAGIC;
char *name;
};
typedef struct _person person;
#define SUBTYPE_MAGIC 0x3333
struct _pilot {
person base;
EINA_MAGIC;
char *callsign;
};
typedef struct _pilot pilot;
EINA_MAGIC
#define EINA_MAGIC
Definition of of a variable of type Eina_Magic.
Definition eina_magic.h:224

Note
  The values of BASETYPE_MAGIC and SUBTYPE_MAGIC have no meaning, the only important thing about them is that they are unique.

Here we have a function to create a person given a name, nothing too fancy:

person *
person_new(const char *name)
{
person *ptr = malloc(sizeof(person));
EINA_MAGIC_SET(ptr, BASETYPE_MAGIC);
ptr->name = strdup(name);
return ptr;
}
EINA_MAGIC_SET
#define EINA_MAGIC_SET(d, m)
Definition to set the magic number of d to m.
Definition eina_magic.h:235

And now the counterpart, a function to free a person.

void
person_free(person *ptr) {

Before we start releasing resources we check that the pointer we are given actually points to a person, and if not we print an error message and quit:

if (!EINA_MAGIC_CHECK(ptr, BASETYPE_MAGIC))
{
EINA_MAGIC_FAIL(ptr, BASETYPE_MAGIC);
return;
}
EINA_MAGIC_CHECK
#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.
Definition eina_magic.h:247
EINA_MAGIC_FAIL
#define EINA_MAGIC_FAIL(d, m)
Definition to call eina_magic_fail() with the parameters d, d->__magic, m, FILE, func,...
Definition eina_magic.h:259

Note
  EINA_MAGIC_FAIL is a macro that makes it easy to print an appropriate (and consistent) error message. Now knowing that ptr is indeed of type person we proceed to set EINA_MAGIC to EINA_MAGIC_NONE and free the allocated memory:
  EINA_MAGIC_SET(ptr, EINA_MAGIC_NONE);
  free(ptr->name);
  free(ptr);
  }
  EINA_MAGIC_NONE
  #define EINA_MAGIC_NONE
  Definition of a random value for specifying that a structure using the magic feature has already been...
  Definition eina_magic.h:197
  Setting EINA_MAGIC to EINA_MAGIC_NONE is important to prevent the struct from being used after it is freed.

Now we have our function to create a pilot, this one is a little more complex because we need to set EINA_MAGIC for the pilot and pilot->base, this is very important so that checking the EINA_MAGIC of (person*)my_pilot works:

pilot *
pilot_new(const char *name, const char *callsign)
{
pilot *ptr = malloc(sizeof(pilot));
EINA_MAGIC_SET(ptr, SUBTYPE_MAGIC);
EINA_MAGIC_SET(&ptr->base, BASETYPE_MAGIC);
ptr->base.name = strdup(name);
ptr->callsign = strdup(callsign);
return ptr;
}

The function to free a pilot is not too different from the one that frees a person:

void
pilot_free(pilot *ptr) {
if (!EINA_MAGIC_CHECK(ptr, SUBTYPE_MAGIC))
{
EINA_MAGIC_FAIL(ptr, SUBTYPE_MAGIC);
return;
}
EINA_MAGIC_SET(ptr, EINA_MAGIC_NONE);
EINA_MAGIC_SET(&ptr->base, EINA_MAGIC_NONE);
free(ptr->base.name);
free(ptr->callsign);
free(ptr);
}

We also create functions to print a person or a pilot that check the type of the pointers they receive:

void
print_person(person *ptr)
{
if (!EINA_MAGIC_CHECK(ptr, BASETYPE_MAGIC)){
EINA_MAGIC_FAIL(ptr, BASETYPE_MAGIC);
return;
}
printf("name: %s\n", ptr->name);
}

And for our main function where we declare some variables and initialize Eina:

void
print_pilot(pilot *ptr)
{
if (!EINA_MAGIC_CHECK(ptr, SUBTYPE_MAGIC)) {
EINA_MAGIC_FAIL(ptr, SUBTYPE_MAGIC);
return;
}
print_person(&ptr->base);
printf("callsign: %s\n", ptr->callsign);
}
int
main(int argc EINA_UNUSED, char **argv EINA_UNUSED)
{
person *base;
pilot *sub;
eina_init();
eina_init
EINA_API int eina_init(void)
Initializes the Eina library.
Definition eina_main.c:291
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition eina_types.h:339

For Eina to be able to provide more informative error messages we are going to give names to our EINA_MAGIC types:

eina_magic_string_set(BASETYPE_MAGIC, "person");
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.
Definition eina_magic.c:213

Since our types won't live longer than the scope of the current function we can set the name without eina making a copy of the string:

eina_magic_string_static_set(SUBTYPE_MAGIC, "pilot");
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.
Definition eina_magic.c:238

Now we create a person, a pilot, and print both as persons:

base = person_new("Tyrol");
sub = pilot_new("thrace", "starbuck");
print_person(base);
print_person((person *)sub);

Now we try to print both as pilots, which obviously does not work since base is not a pilot:

print_pilot((pilot *)base); //BAD: fails (C cast prevents GCC warning)
print_pilot(sub);

That's all folks:

eina_shutdown();
}
eina_shutdown
EINA_API int eina_shutdown(void)
Shuts down the Eina library.
Definition eina_main.c:379

See full source here.