src/include/eina_binshare.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2002-2008 Carsten Haitzler, Jorge Luis Zapata Muga, 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  * This file incorporates work covered by the following copyright and
  19  * permission notice:
  20  *
  21  * Copyright (C) 2008 Peter Wehrfritz
  22  *
  23  *  Permission is hereby granted, free of charge, to any person obtaining a copy
  24  *  of this software and associated documentation files (the "Software"), to
  25  *  deal in the Software without restriction, including without limitation the
  26  *  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  27  *  sell copies of the Software, and to permit persons to whom the Software is
  28  *  furnished to do so, subject to the following conditions:
  29  *
  30  *  The above copyright notice and this permission notice shall be included in
  31  *  all copies of the Software and its Copyright notices. In addition publicly
  32  *  documented acknowledgment must be given that this software has been used if no
  33  *  source code of this software is made available publicly. This includes
  34  *  acknowledgments in either Copyright notices, Manuals, Publicity and Marketing
  35  *  documents or any documentation provided with any product containing this
  36  *  software. This License does not apply to any software that links to the
  37  *  libraries provided by this software (statically or dynamically), but only to
  38  *  the software provided.
  39  *
  40  *  Please see the OLD-COPYING.PLAIN for a plain-english explanation of this notice
  41  *  and it's intent.
  42  *
  43  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  44  *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  45  *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  46  *  THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  47  *  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  48  *  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  49  */
  50
  51 #ifndef EINA_BINSHARE_H_
  52 #define EINA_BINSHARE_H_
  53
  54 #include "eina_types.h"
  55
  56 /**
  57  * @page tutorial_binshare_page Binary Share Tutorial
  58  *
  59  * Should call eina_binshare_init() before usage and eina_binshare_shutdown() after.
  60  * to be written...
  61  *
  62  */
  63
  64 /**
  65  * @addtogroup Eina_Binshare_Group Binary Share
  66  *
  67  * These functions allow you to store one copy of an object, and use it
  68  * throughout your program.
  69  *
  70  * This is a method to reduce the number of duplicated objects kept in
  71  * memory.
  72  *
  73  * For more information, you can look at the @ref tutorial_binshare_page.
  74  */
  75
  76 /**
  77  * @addtogroup Eina_Data_Types_Group Data Types
  78  *
  79  * @{
  80  */
  81
  82 /**
  83  * @defgroup Eina_Binshare_Group Binary Share
  84  *
  85  * @{
  86  */
  87
  88
  89 /**
  90  * @brief Retrieve an instance of an object for use in a program.
  91  *
  92  * @param   obj The binary object to retrieve an instance of.
  93  * @param   olen The byte size
  94  * @return  A pointer to an instance of the object on success.
  95  *          @c NULL on failure.
  96  *
  97  * This function retrieves an instance of @p obj. If @p obj is
  98  * @c NULL, then @c NULL is returned. If @p obj is already stored, it
  99  * is just returned and its reference counter is increased. Otherwise
 100  * it is added to the objects to be searched and a duplicated object
 101  * of @p obj is returned.
 102  *
 103  * This function does not check object size, but uses the
 104  * exact given size. This can be used to share part of a larger
 105  * object or subobject.
 106  *
 107  * @see eina_binshare_add()
 108  */
 109 EAPI const void *eina_binshare_add_length(const void  *obj,
 110                                           unsigned int olen) EINA_PURE EINA_WARN_UNUSED_RESULT;
 111
 112 /**
 113  * Increment references of the given shared object.
 114  *
 115  * @param obj The shared object.
 116  * @return    A pointer to an instance of the object on success.
 117  *            @c NULL on failure.
 118  *
 119  * This is similar to eina_share_common_add(), but it's faster since it will
 120  * avoid lookups if possible, but on the down side it requires the parameter
 121  * to be shared before, in other words, it must be the return of a previous
 122  * eina_binshare_add().
 123  *
 124  * There is no unref since this is the work of eina_binshare_del().
 125  */
 126 EAPI const void *eina_binshare_ref(const void *obj);
 127
 128 /**
 129  * @brief Note that the given object has lost an instance.
 130  *
 131  * @param obj object The given object.
 132  *
 133  * This function decreases the reference counter associated to @p obj
 134  * if it exists. If that counter reaches 0, the memory associated to
 135  * @p obj is freed. If @p obj is @c NULL, the function returns
 136  * immediately.
 137  *
 138  * @note If the given pointer is not shared, bad things will happen, likely a
 139  * segmentation fault.
 140  */
 141 EAPI void        eina_binshare_del(const void *obj);
 142
 143 /**
 144  * @brief Note that the given object @b must be shared.
 145  *
 146  * @param obj the shared object to know the length. It is safe to
 147  *        give @c NULL, in that case @c -1 is returned.
 148  * @return The length of the shared object.
 149  *
 150  * This function is a cheap way to known the length of a shared
 151  * object.
 152  * @note If the given pointer is not shared, bad things will happen, likely a
 153  * segmentation fault. If in doubt, try strlen().
 154  */
 155 EAPI int         eina_binshare_length(const void *obj) EINA_WARN_UNUSED_RESULT;
 156
 157 /**
 158  * @brief Dump the contents of the share_common.
 159  *
 160  * This function dumps all objects in the share_common to stdout with a
 161  * DDD: prefix per line and a memory usage summary.
 162  */
 163 EAPI void        eina_binshare_dump(void);
 164
 165 /**
 166  * @brief Retrieve an instance of a blob for use in a program.
 167  *
 168  * @param   ptr The binary blob to retrieve an instance of.
 169  * @return  A pointer to an instance of the string on success.
 170  *          @c NULL on failure.
 171  *
 172  * This macro retrieves an instance of @p obj. If @p obj is
 173  * @c NULL, then @c NULL is returned. If @p obj is already stored, it
 174  * is just returned and its reference counter is increased. Otherwise
 175  * it is added to the blobs to be searched and a duplicated blob
 176  * of @p obj is returned.
 177  *
 178  * This macro essentially calls eina_binshare_add_length with ptr and sizeof(*ptr)
 179  * as the parameters. It's useful for pointers to structures.
 180  *
 181  * @see eina_stringshare_add_length()
 182  */
 183 #define eina_binshare_add(ptr) eina_binshare_add_length(ptr, sizeof(*ptr))
 184
 185 /**
 186  * @}
 187  */
 188
 189 /**
 190  * @}
 191  */
 192
 193 #endif /* EINA_STRINGSHARE_H_ */