src/include/eina_magic.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2008 Cedric Bail
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library;
  16  * if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef EINA_MAGIC_H_
  20 #define EINA_MAGIC_H_
  21
  22
  23 #include "eina_config.h"
  24 #include "eina_types.h"
  25
  26 /**
  27  * @addtogroup Eina_Tools_Group Tools
  28  *
  29  * @{
  30  */
  31
  32 /**
  33  * @defgroup Eina_Magic_Group Magic
  34  *
  35  * @{
  36  */
  37
  38 typedef unsigned int               Eina_Magic;
  39
  40 /**
  41  * @typedef Eina_Magic
  42  * An abstract type for a magic number.
  43  */
  44 EAPI const char* eina_magic_string_get(Eina_Magic magic) EINA_PURE EINA_WARN_UNUSED_RESULT;
  45 EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic, const char *magic_name) EINA_ARG_NONNULL(2);
  46
  47 /**
  48  * @def EINA_MAGIC_NONE
  49  * Random value for specifying that a structure using the magic
  50  * feature has already been freed. It is used by eina_agic_fail().
  51  *
  52  * If the magic feature of Eina is disabled, #EINA_MAGIC_NONE is just
  53  * @c 0.
  54  */
  55 #define EINA_MAGIC_NONE            0x1234fedc
  56
  57 #ifdef EINA_MAGIC_DEBUG
  58
  59 /**
  60  * @def EINA_MAGIC
  61  * Declaration of a variable of type #Eina_Magic. To put in a structure
  62  * when one wants to use the magic feature of Eina with the functions
  63  * of that structure, like that:
  64  *
  65  * @code
  66  * struct Foo
  67  * {
  68  *    int i;
  69  *
  70  *    EINA_MAGIC
  71  * };
  72  * @endcode
  73  *
  74  * If the magic feature of Eina is disabled, #EINA_MAGIC does nothing.
  75  */
  76 #define EINA_MAGIC      Eina_Magic __magic;
  77
  78 /**
  79  * @def EINA_MAGIC_SET(d, m)
  80  * Set the magic number of @p d to @p m. @p d must be a valid pointer
  81  * to a structure holding an Eina magic number declaration. Use
  82  * #EINA_MAGIC to add such declaration.
  83  *
  84  * If the magic feature of Eina is disabled, #EINA_MAGIC_CHECK is just
  85  * the value @c 0.
  86  */
  87 #define EINA_MAGIC_SET(d, m)       (d)->__magic = (m)
  88
  89 /**
  90  * @def EINA_MAGIC_CHECK(d, m)
  91  * Test if @p d is @c NULL or not, and if not @c NULL, if
  92  * @p d->__eina_magic is equal to @p m. @p d must be a structure that
  93  * holds an Eina magic number declaration. Use #EINA_MAGIC to add such
  94  * declaration.
  95  *
  96  * If the magic feature of Eina is disabled, #EINA_MAGIC_CHECK is just
  97  * the value @c 1.
  98  */
  99 #define EINA_MAGIC_CHECK(d, m)     ((d) && ((d)->__magic == (m)))
 100
 101 /**
 102  * @def EINA_MAGIC_FAIL(d, m)
 103  * Call eina_magic_fail() with the parameters @p d, @p d->__magic, @p
 104  * m, __FILE__, __FUNCTION__ and __LINE__. @p d must be a structure that
 105  * holds an Eina magic number declaration. Use #EINA_MAGIC to add such
 106  * declaration.
 107  *
 108  * If the magic feature of Eina is disabled, #EINA_MAGIC_FAIL does
 109  * nothing.
 110  */
 111 #define EINA_MAGIC_FAIL(d, m)      eina_magic_fail((void*)(d), (d) ? (d)->__magic : 0, (m), __FILE__, __FUNCTION__, __LINE__);
 112
 113 EAPI void eina_magic_fail(void *d, Eina_Magic m, Eina_Magic req_m,
 114                           const char *file, const char *fnc, int line) EINA_ARG_NONNULL(4, 5);
 115
 116 #else
 117
 118 /**
 119  * @cond LOCAL
 120  */
 121
 122 #define EINA_MAGIC
 123 #define EINA_MAGIC_SET(d, m)       ((void) 0)
 124 #define EINA_MAGIC_CHECK(d, m)     (1)
 125 #define EINA_MAGIC_FAIL(d, m)      ((void) 0)
 126
 127 #define eina_magic_fail(d, m, req_m, file, fnx, line) ((void) 0)
 128
 129 /**
 130  * @endcond
 131  */
 132
 133 #endif
 134
 135 /**
 136  * @}
 137  */
 138
 139 /**
 140  * @}
 141  */
 142
 143 #endif /* EINA_MAGIC_H_ */