src/include/eina_accessor.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_ACCESSOR_H__
  20 #define EINA_ACCESSOR_H__
  21
  22 #include "eina_config.h"
  23
  24 #include "eina_types.h"
  25 #include "eina_magic.h"
  26
  27 /**
  28  * @page eina_accessor_example_01_page Eina_Accessor usage
  29  * @dontinclude eina_accessor_01.c
  30  *
  31  * We start by including necessary headers, declaring variables and
  32  * initializing eina:
  33  * @skip #include
  34  * @until eina_init
  35  *
  36  * Next we populate our array and list:
  37  * @until }
  38  *
  39  * Now that we have two containers populated we can actually start the example
  40  * and create an accessor:
  41  * @until accessor_new
  42  *
  43  * Once having the accessor we can use it to access certain elements in the
  44  * container:
  45  * @until }
  46  * @note Unlike iterators accessors allow us non-linear access, which allows us
  47  * to print only the odd elements in the container.
  48  *
  49  * As with every other resource we allocate we need to free the accessor(and the
  50  * array):
  51  * @until array_free
  52  *
  53  * Now we create another accessor, this time for the list:
  54  * @until accessor_new
  55  *
  56  * And now the interesting bit, we use the same code we used above to print
  57  * parts of the array to print parts of the list:
  58  * @until }
  59  *
  60  * And to free the list we use a gimmick, instead of freeing @a list, we ask the
  61  * accessor for it's container and free that:
  62  * @until list_free
  63  *
  64  * Finally we shut eina down and leave:
  65  * @until }
  66  *
  67  * The full source code can be found on the examples folder
  68  * on the @ref eina_accessor_01_c "eina_accessor_01.c" file.
  69  */
  70
  71 /**
  72  * @page eina_accessor_01_c Eina_Accessor usage example
  73  *
  74  * @include eina_accessor_01.c
  75  * @example eina_accessor_01.c
  76  */
  77
  78 /**
  79  * @addtogroup Eina_Accessor_Group Accessor Functions
  80  *
  81  * @brief These functions manage accessor on containers.
  82  *
  83  * These functions allow to access elements of a container in a
  84  * generic way, without knowing which container is used (a bit like
  85  * iterators in the C++ STL). Accessors allows random access (that is, any
  86  * element in the container). For sequential access, see
  87  * @ref Eina_Iterator_Group.
  88  *
  89  * Getting an accessor to access elements of a given container is done through
  90  * the functions of that particular container. There is no function to create
  91  * a generic accessor as accessors absolutely depend on the container. This
  92  * means you won't find accessor creation function here, those can be found on
  93  * the documentation of the container type you're using. Though created with
  94  * container specific functions accessors are always deleted with the same
  95  * function: eina_accessor_free().
  96  *
  97  * To get the data of an element at a given
  98  * position, use eina_accessor_data_get(). To call a function on
  99  * chosen elements of a container, use eina_accessor_over().
 100  *
 101  * See an example @ref eina_accessor_example_01_page "here".
 102  */
 103
 104 /**
 105  * @addtogroup Eina_Content_Access_Group Content Access
 106  *
 107  * @{
 108  */
 109
 110 /**
 111  * @defgroup Eina_Accessor_Group Accessor Functions
 112  *
 113  * @{
 114  */
 115
 116 /**
 117  * @typedef Eina_Accessor
 118  * Abstract type for accessors.
 119  */
 120 typedef struct _Eina_Accessor Eina_Accessor;
 121
 122 /**
 123  * @typedef Eina_Accessor_Get_At_Callback
 124  * Type for a callback that returns the data of a container as the given index.
 125  */
 126 typedef Eina_Bool (*Eina_Accessor_Get_At_Callback)(Eina_Accessor *it,
 127                                                    unsigned int   idx,
 128                                                    void         **data);
 129
 130 /**
 131  * @typedef Eina_Accessor_Get_Container_Callback
 132  * Type for a callback that returns the container.
 133  */
 134 typedef void *(*Eina_Accessor_Get_Container_Callback)(Eina_Accessor *it);
 135
 136 /**
 137  * @typedef Eina_Accessor_Free_Callback
 138  * Type for a callback that frees the container.
 139  */
 140 typedef void (*Eina_Accessor_Free_Callback)(Eina_Accessor *it);
 141
 142 /**
 143  * @typedef Eina_Accessor_Lock_Callback
 144  * Type for a callback that lock the container.
 145  */
 146 typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it);
 147
 148 /**
 149  * @struct _Eina_Accessor
 150  * Type to provide random access to data structures.
 151  *
 152  * If creating an accessor remember to set the type using @ref EINA_MAGIC_SET.
 153  */
 154 struct _Eina_Accessor
 155 {
 156 #define EINA_ACCESSOR_VERSION 1
 157    int                                  version; /**< Version of the Accessor API. */
 158
 159    Eina_Accessor_Get_At_Callback        get_at        EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT; /**< Callback called when a data element is requested. */
 160    Eina_Accessor_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested. */
 161    Eina_Accessor_Free_Callback          free          EINA_ARG_NONNULL(1); /**< Callback called when the container is freed. */
 162
 163    Eina_Accessor_Lock_Callback          lock          EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */
 164    Eina_Accessor_Lock_Callback          unlock        EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked. */
 165
 166 #define EINA_MAGIC_ACCESSOR 0x98761232
 167    EINA_MAGIC
 168 };
 169
 170 /**
 171  * @def FUNC_ACCESSOR_GET_AT(Function)
 172  * Helper macro to cast @p Function to a Eina_Accessor_Get_At_Callback.
 173  */
 174 #define FUNC_ACCESSOR_GET_AT(Function)        ((Eina_Accessor_Get_At_Callback)Function)
 175
 176 /**
 177  * @def FUNC_ACCESSOR_GET_CONTAINER(Function)
 178  * Helper macro to cast @p Function to a Eina_Accessor_Get_Container_Callback.
 179  */
 180 #define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function)
 181
 182 /**
 183  * @def FUNC_ACCESSOR_FREE(Function)
 184  * Helper macro to cast @p Function to a Eina_Accessor_Free_Callback.
 185  */
 186 #define FUNC_ACCESSOR_FREE(Function)          ((Eina_Accessor_Free_Callback)Function)
 187
 188 /**
 189  * @def FUNC_ACCESSOR_LOCK(Function)
 190  * Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback.
 191  */
 192 #define FUNC_ACCESSOR_LOCK(Function)          ((Eina_Accessor_Lock_Callback)Function)
 193
 194
 195 /**
 196  * @brief Free an accessor.
 197  *
 198  * @param accessor The accessor to free.
 199  *
 200  * This function frees @p accessor if it is not @c NULL;
 201  */
 202 EAPI void      eina_accessor_free(Eina_Accessor *accessor);
 203
 204 /**
 205  * @brief Retrieve the data of an accessor at a given position.
 206  *
 207  * @param accessor The accessor.
 208  * @param position The position of the element.
 209  * @param data The pointer that stores the data to retrieve.
 210  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 211  *
 212  * This function retrieves the data of the element pointed by
 213  * @p accessor at the porition @p position, and stores it in
 214  * @p data. If @p accessor is @c NULL or if an error occurred, #EINA_FALSE
 215  * is returned, otherwise #EINA_TRUE is returned.
 216  */
 217 EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor,
 218                                       unsigned int   position,
 219                                       void         **data) EINA_ARG_NONNULL(1);
 220
 221 /**
 222  * @brief Return the container of an accessor.
 223  *
 224  * @param accessor The accessor.
 225  * @return The container which created the accessor.
 226  *
 227  * This function returns the container which created @p accessor. If
 228  * @p accessor is @c NULL, this function returns @c NULL.
 229  */
 230 EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE;
 231
 232 /**
 233  * @brief Iterate over the container and execute a callback on chosen elements.
 234  *
 235  * @param accessor The accessor.
 236  * @param cb The callback called on the chosen elements.
 237  * @param start The position of the first element.
 238  * @param end The position of the last element.
 239  * @param fdata The data passed to the callback.
 240  *
 241  * This function iterates over the elements pointed by @p accessor,
 242  * starting from the element at position @p start and ending to the
 243  * element at position @p end. For Each element, the callback
 244  * @p cb is called with the data @p fdata. If @p accessor is @c NULL
 245  * or if @p start is greter or equal than @p end, the function returns
 246  * immediately.
 247  */
 248 EAPI void  eina_accessor_over(Eina_Accessor *accessor,
 249                               Eina_Each_Cb   cb,
 250                               unsigned int   start,
 251                               unsigned int   end,
 252                               const void    *fdata) EINA_ARG_NONNULL(2);
 253
 254 /**
 255  * @brief Lock the container of the accessor.
 256  *
 257  * @param accessor The accessor.
 258  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 259  *
 260  * If the container of the @p accessor permits it, it will be locked. When a
 261  * container is locked calling eina_accessor_over() on it will return
 262  * immediately. If @p accessor is @c NULL or if a problem occurred, #EINA_FALSE
 263  * is returned, otherwise #EINA_TRUE is returned. If the container isn't
 264  * lockable, it will return #EINA_TRUE.
 265  *
 266  * @warning None of the existing eina data structures are lockable.
 267  */
 268 EAPI Eina_Bool eina_accessor_lock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
 269
 270 /**
 271  * @brief Unlock the container of the accessor.
 272  *
 273  * @param accessor The accessor.
 274  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 275  *
 276  * If the container of the @p accessor permits it and was previously
 277  * locked, it will be unlocked. If @p accessor is @c NULL or if a
 278  * problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE
 279  * is returned. If the container is not lockable, it will
 280  * return #EINA_TRUE.
 281  *
 282  * @warning None of the existing eina data structures are lockable.
 283  */
 284 EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
 285
 286 /**
 287  * @def EINA_ACCESSOR_FOREACH
 288  * @brief Macro to iterate over all elements easily.
 289  *
 290  * @param accessor The accessor to use.
 291  * @param counter A counter used by eina_accessor_data_get() when
 292  * iterating over the container.
 293  * @param data Where to store * data, must be a pointer support getting
 294  * its address since * eina_accessor_data_get() requires a pointer to
 295  * pointer!
 296  *
 297  * This macro allows a convenient way to loop over all elements in an
 298  * accessor, very similar to EINA_LIST_FOREACH().
 299  *
 300  * This macro can be used for freeing the data of a list, like in the
 301  * following example. It has the same goal as the one documented in
 302  * EINA_LIST_FOREACH(), but using accessors:
 303  *
 304  * @code
 305  * Eina_List     *list;
 306  * Eina_Accessor *accessor;
 307  * unsigned int   i;
 308  * char          *data;
 309  *
 310  * // list is already filled,
 311  * // its elements are just duplicated strings
 312  *
 313  * accessor = eina_list_accessor_new(list);
 314  * EINA_ACCESSOR_FOREACH(accessor, i, data)
 315  *   free(data);
 316  * eina_accessor_free(accessor);
 317  * eina_list_free(list);
 318  * @endcode
 319  *
 320  * @note if the datatype provides both iterators and accessors prefer
 321  *    to use iterators to iterate over, as they're likely to be more
 322  *    optimized for such task.
 323  *
 324  * @note this example is not optimal algorithm to release a list since
 325  *    it will walk the list twice, but it serves as an example. For
 326  *    optimized version use EINA_LIST_FREE()
 327  *
 328  * @warning unless explicitly stated in functions returning accessors,
 329  *    do not modify the accessed object while you walk it, in this
 330  *    example using lists, do not remove list nodes or you might
 331  *    crash!  This is not a limitation of accessors themselves,
 332  *    rather in the accessors implementations to keep them as simple
 333  *    and fast as possible.
 334  */
 335 #define EINA_ACCESSOR_FOREACH(accessor, counter, data)                  \
 336   for ((counter) = 0;                                                   \
 337        eina_accessor_data_get((accessor), (counter), (void **)(void *)&(data)); \
 338        (counter)++)
 339
 340 /**
 341  * @}
 342  */
 343
 344 /**
 345  * @}
 346  */
 347
 348 #endif