/src/wrappers/glib/library/core/glib_memory_allocation.e
Specman e | 392 lines | 42 code | 91 blank | 259 comment | 1 complexity | 78dfdbea143452c7558b38ea4014f0be MD5 | raw file
1indexing 2 description: "Memory Allocation -- general memory-handling." 3 library: "GLib 2" 4 copyright: "(C) 2005 Paolo Redaelli " 5 license: "LGPL" 6 note: "[ 7 If any call to allocate memory fails, the application is terminated. 8 This also means that there is no need to check if the call succeeded. 9 10 Every occurrence of gulong n_bytes is wrapped as n_bytes: INTEGER; this shall change when SmartEiffel will provide NATURAL 11 ]" 12 13 14deferred class GLIB_MEMORY_ALLOCATION 15 16inherit ANY undefine is_equal, copy end 17 18feature {} -- external features 19 20 -- Prev Up Home GLib Reference Manual Next 21 -- Top | Description 22-- Memory Allocation 23 24-- Memory Allocation %G รข€”%@ general memory-handling. 25 26-- Synopsis 27 28-- #include <glib.h> 29 30 31-- #define g_new (struct_type, n_structs) 32-- #define g_new0 (struct_type, n_structs) 33-- #define g_renew (struct_type, mem, n_structs) 34-- #define g_try_new (struct_type, n_structs) 35-- #define g_try_new0 (struct_type, n_structs) 36-- #define g_try_renew (struct_type, mem, n_structs) 37 38-- gpointer g_malloc (gulong n_bytes); 39-- gpointer g_malloc0 (gulong n_bytes); 40-- gpointer g_realloc (gpointer mem, 41-- gulong n_bytes); 42-- gpointer g_try_malloc (gulong n_bytes); 43-- gpointer g_try_malloc0 (gulong n_bytes); 44-- gpointer g_try_realloc (gpointer mem, 45-- gulong n_bytes); 46 47-- void g_free (gpointer mem); 48 49-- #define g_alloca (size) 50-- #define g_newa (struct_type, n_structs) 51 52-- #define g_memmove (dest,src,len) 53-- gpointer g_memdup (gconstpointer mem, 54-- guint byte_size); 55 56-- GMemVTable; 57-- void g_mem_set_vtable (GMemVTable *vtable); 58-- gboolean g_mem_is_system_malloc (void); 59 60-- extern GMemVTable *glib_mem_profiler_table; 61-- void g_mem_profile (void); 62 63-- Description 64 65-- These functions provide support for allocating and freeing memory. 66-- Note 67 68-- If any call to allocate memory fails, the application is terminated. This also means that there is no need to check if the call succeeded. 69-- Details 70 71 72 -- g_new () 73 74 -- #define g_new(struct_type, n_structs) 75 76 -- Allocates n_structs elements of type struct_type. The returned pointer 77 -- is cast to a pointer to the given type. If n_structs is 0 it returns 78 -- NULL. 79 -- struct_type : the type of the elements to allocate. 80 -- n_structs : the number of elements to allocate. 81 -- Returns : a pointer to the allocated memory, cast to a pointer to 82 -- struct_type. 83 -- _________________________________________________________________ 84 85 -- g_new0() 86 87 -- #define g_new0(struct_type, n_structs) 88 89 -- Allocates n_structs elements of type struct_type, initialized to 0's. 90 -- The returned pointer is cast to a pointer to the given type. If 91 -- n_structs is 0 it returns NULL. 92 -- struct_type : the type of the elements to allocate. 93 -- n_structs : the number of elements to allocate. 94 -- Returns : a pointer to the allocated memory, cast to a pointer to 95 -- struct_type. 96 -- _________________________________________________________________ 97 98 -- g_renew() 99 100 -- #define g_renew(struct_type, mem, n_structs) 101 102 -- Reallocates the memory pointed to by mem, so that it now has space for 103 -- n_structs elements of type struct_type. It returns the new address of 104 -- the memory, which may have been moved. 105 -- struct_type : the type of the elements to allocate. 106 -- mem : the currently allocated memory. 107 -- n_structs : the number of elements to allocate. 108 -- Returns : a pointer to the new allocated memory, cast to a pointer to 109 -- struct_type. 110 -- _________________________________________________________________ 111 112 -- g_try_new() 113 114 -- #define g_try_new(struct_type, n_structs) 115 116 -- Attempts to allocate n_structs elements of type struct_type, and 117 -- returns NULL on failure. Contrast with g_new(), which aborts the 118 -- program on failure. The returned pointer is cast to a pointer to the 119 -- given type. If n_structs is 0 it returns NULL. 120 -- struct_type : the type of the elements to allocate. 121 -- n_structs : the number of elements to allocate. 122 -- Returns : a pointer to the allocated memory, cast to a pointer to 123 -- struct_type. 124 125 -- Since 2.8 126 -- _________________________________________________________________ 127 128 -- g_try_new0() 129 130 -- #define g_try_new0(struct_type, n_structs) 131 132 -- Attempts to allocate n_structs elements of type struct_type, 133 -- initialized to 0's, and returns NULL on failure. Contrast with 134 -- g_new0(), which aborts the program on failure. The returned 135 -- pointer is cast to a pointer to the given type. If n_counts is 0 it 136 -- returns NULL. 137 -- struct_type : the type of the elements to allocate. 138 -- n_structs : the number of elements to allocate. 139 -- Returns : a pointer to the allocated memory, cast to a pointer to 140 -- struct_type. 141 142 -- Since 2.8 143 -- _________________________________________________________________ 144 145 -- g_try_renew() 146 147 -- #define g_try_renew(struct_type, mem, n_structs) 148 149 -- Attempts to reallocate the memory pointed to by mem, so that it now 150 -- has space for n_structs elements of type struct_type, and returns NULL 151 -- on failure. Contrast with g_renew(), which aborts the program on 152 -- failure. It returns the new address of the memory, which may have been 153 -- moved. 154 -- struct_type : the type of the elements to allocate. 155 -- mem : the currently allocated memory. 156 -- n_structs : the number of elements to allocate. 157 -- Returns : a pointer to the new allocated memory, cast to a pointer to 158 -- struct_type. 159 160 -- Since 2.8 161 -- _________________________________________________________________ 162 163 g_malloc (n_bytes: INTEGER): POINTER is 164 -- Allocates `n_bytes' bytes of memory. If `n_bytes' is 0 it 165 -- returns NULL. Returns : a pointer to the allocated 166 -- memory. 167 obsolete "use g_try_malloc" 168 external "C use <glib.h>" 169 end 170 171 g_malloc0 (n_bytes: INTEGER): POINTER is 172 -- Allocates `n_bytes' bytes of memory, initialized to 173 -- 0's. If n_bytes is 0 it returns NULL. n_bytes : the 174 -- number of bytes to allocate. Returns : a pointer to the 175 -- allocated memory. 176 obsolete "use g_try_malloc0" 177 external "C use <glib.h>" 178 end 179 180 g_realloc (mem: POINTER; n_bytes: INTEGER): POINTER is 181 -- Reallocates the memory pointed to by mem, so that it now 182 -- has space for n_bytes bytes of memory. It returns the new 183 -- address of the memory, which may have been moved. mem may 184 -- be NULL, in which case it's considered to have 185 -- zero-length. n_bytes may be 0, in which case NULL will be 186 -- returned. mem : the memory to reallocate. n_bytes : new 187 -- size of the memory in bytes. Returns : the new address of 188 -- the allocated memory. 189 obsolete "use g_try_realloc" 190 external "C use <glib.h>" 191 end 192 193 g_try_malloc (n_bytes: INTEGER): POINTER is 194 -- Attempts to allocate `n_bytes', and returns NULL on 195 -- failure. Contrast with g_malloc, which aborts the program 196 -- on failure. Returns: the allocated memory, or NULL. 197 external "C use <glib.h>" 198 end 199 200 g_try_malloc0 (n_bytes: INTEGER): POINTER is 201 -- Attempts to allocate `n_bytes', initialized to 0's, and 202 -- returns NULL on failure. Contrast with g_malloc0, which 203 -- aborts the program on failure. Returns : the allocated 204 -- memory, or NULL. 205 external "C use <glib.h>" 206 end 207 208 g_try_realloc (mem: POINTER; n_bytes: INTEGER): POINTER is 209 -- Attempts to realloc mem to a new size, n_bytes, and 210 -- returns NULL on failure. Contrast with g_realloc(), which 211 -- aborts the program on failure. If mem is NULL, behaves the 212 -- same as g_try_malloc(). mem : previously-allocated 213 -- memory, or NULL. n_bytes : number of bytes to allocate. 214 -- Returns : the allocated memory, or NULL. 215 external "C use <glib.h>" 216 end 217 218 g_free (mem: POINTER) is 219 -- Frees the memory pointed to by `mem'. If mem is NULL it 220 -- simply returns. 221 external "C use <glib.h>" 222 end 223 224 225 -- g_alloca() 226 227 -- #define g_alloca(size) 228 229 -- Allocates size bytes on the stack; these bytes will be freed when the 230 -- current stack frame is cleaned up. This macro essentially just wraps 231 -- the alloca() function present on most UNIX variants. Thus it provides 232 -- the same advantages and pitfalls as alloca(): 233 234 -- + alloca() is very fast, as on most systems it's implemented by just 235 -- adjusting the stack pointer register. 236 237 -- + It doesn't cause any memory fragmentation, within its scope, 238 -- separate alloca() blocks just build up and are released together at 239 -- function end. 240 241 -- - Allocation sizes have to fit into the current stack frame. For 242 -- instance in a threaded environment on Linux, the per-thread stack size 243 -- is limited to 2 Megabytes, so be sparse with alloca() uses. 244 245 -- - Allocation failure due to insufficient stack space is not indicated 246 -- with a NULL return like e.g. with malloc(). Instead, most systems 247 -- probably handle it the same way as out of stack space situations from 248 -- infinite function recursion, i.e. with a segmentation fault. 249 250 -- - Special care has to be taken when mixing alloca() with GNU C 251 -- variable sized arrays. Stack space allocated with alloca() in the same 252 -- scope as a variable sized array will be freed together with the 253 -- variable sized array upon exit of that scope, and not upon exit of the 254 -- enclosing function scope. 255 256 -- size : number of bytes to allocate. 257 -- Returns : space for size bytes, allocated on the stack 258 -- _________________________________________________________________ 259 260 -- g_newa() 261 262 -- #define g_newa(struct_type, n_structs) 263 264 -- Wraps g_alloca() in a more typesafe manner. 265 -- struct_type : Type of memory chunks to be allocated 266 -- n_structs : Number of chunks to be allocated 267 -- Returns : Pointer to stack space for n_structs chunks of type 268 -- struct_type 269 -- _________________________________________________________________ 270 271 -- g_memmove() 272 273 -- #define g_memmove(dest,src,len) 274 275 g_memmove(src, dst: POINTER; len:INTEGER) is 276 -- Copies a block of memory len bytes long, from src to dest. The source 277 -- and destination areas may overlap. 278 -- dest : the destination address to copy the bytes to. 279 -- src : the source address to copy the bytes from. 280 -- len : the number of bytes to copy. 281 external "C inline use <string.h>" 282 alias "memmove" 283 end 284 285 -- In order to use this function, you must include string.h yourself, 286 -- because this macro will typically simply resolve to memmove() and GLib 287 -- does not include string.h for you. 288 289 -- dest : the destination address to copy the bytes to. 290 -- src : the source address to copy the bytes from. 291 -- len : the number of bytes to copy. 292 -- _________________________________________________________________ 293 294 -- g_memdup () 295 296 -- gpointer g_memdup (gconstpointer mem, 297 -- guint byte_size); 298 299 -- Allocates byte_size bytes of memory, and copies byte_size bytes into 300 -- it from mem. If mem is NULL it returns NULL. 301 -- mem : the memory to copy. 302 -- byte_size : the number of bytes to copy. 303 -- Returns : a pointer to the newly-allocated copy of the memory, or NULL 304 -- if mem is NULL. 305 -- _________________________________________________________________ 306 307 -- GMemVTable 308 309 -- typedef struct { 310 -- gpointer (*malloc) (gsize n_bytes); 311 -- gpointer (*realloc) (gpointer mem, 312 -- gsize n_bytes); 313 -- void (*free) (gpointer mem); 314 -- /* optional; set to NULL if not used ! */ 315 -- gpointer (*calloc) (gsize n_blocks, 316 -- gsize n_block_bytes); 317 -- gpointer (*try_malloc) (gsize n_bytes); 318 -- gpointer (*try_realloc) (gpointer mem, 319 -- gsize n_bytes); 320 -- } GMemVTable; 321 322 -- A set of functions used to perform memory allocation. The same 323 -- GMemVTable must be used for all allocations in the same program; a 324 -- call to g_mem_set_vtable(), if it exists, should be prior to any 325 -- use of GLib. 326 -- malloc () function to use for allocating memory. 327 -- realloc () function to use for reallocating memory. 328 -- free () function to use to free memory. 329 -- calloc () function to use for allocating zero-filled memory. 330 -- try_malloc () function to use for allocating memory without a default 331 -- error handler. 332 -- try_realloc () function to use for reallocating memory without a 333 -- default error handler. 334 -- _________________________________________________________________ 335 336 -- g_mem_set_vtable () 337 338 -- void g_mem_set_vtable (GMemVTable *vtable); 339 340 -- Sets the GMemVTable to use for memory allocation. You can use this 341 -- to provide custom memory allocation routines. This function must be 342 -- called before using any other GLib functions. The vtable only needs to 343 -- provide malloc(), realloc(), and free() functions; GLib can provide 344 -- default implementations of the others. The malloc() and realloc() 345 -- implementations should return NULL on failure, GLib will handle 346 -- error-checking for you. vtable is copied, so need not persist after 347 -- this function has been called. 348 -- vtable : table of memory allocation routines. 349 -- _________________________________________________________________ 350 351 -- g_mem_is_system_malloc () 352 353 -- gboolean g_mem_is_system_malloc (void); 354 355 -- Checks whether the allocator used by g_malloc() is the system's 356 -- malloc implementation. If it returns TRUE memory allocated with 357 -- malloc() can be used interchangeable with memory allocated using 358 -- g_malloc(). This function is useful for avoiding an extra copy of 359 -- allocated memory returned by a non-GLib-based API. 360 361 -- A different allocator can be set using g_mem_set_vtable(). 362 363 -- Returns : if TRUE, malloc() and g_malloc() can be mixed. 364 -- _________________________________________________________________ 365 366 -- glib_mem_profiler_table 367 368 -- extern GMemVTable *glib_mem_profiler_table; 369 370 -- A GMemVTable containing profiling variants of the memory 371 -- allocation functions. Use them together with g_mem_profile() in 372 -- order to get information about the memory allocation pattern of your 373 -- program. 374 -- _________________________________________________________________ 375 376 -- g_mem_profile () 377 378 -- void g_mem_profile (void); 379 380 -- Outputs a summary of memory usage. 381 382 -- It outputs the frequency of allocations of different sizes, the total 383 -- number of bytes which have been allocated, the total number of bytes 384 -- which have been freed, and the difference between the previous two 385 -- values, i.e. the number of bytes still in use. 386 387 -- Note that this function will not output anything unless you have 388 -- previously installed the glib_mem_profiler_table with 389 -- g_mem_set_vtable(). 390 391end 392