diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_binshare.h | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_binshare.h b/libraries/eina/src/include/eina_binshare.h new file mode 100644 index 0000000..55b17a6 --- /dev/null +++ b/libraries/eina/src/include/eina_binshare.h | |||
@@ -0,0 +1,193 @@ | |||
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 NULL, the function returns | ||
136 | * immediately. | ||
137 | * | ||
138 | * Note that if the given pointer is not shared or NULL, bad things | ||
139 | * will happen, likely a 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 NULL, in that case -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. Note that if the given pointer is not shared, bad | ||
152 | * things will happen, likely a segmentation fault. If in doubt, try | ||
153 | * 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_ */ | ||