PageRenderTime 22ms CodeModel.GetById 12ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/glib/library/core/glib_memory_allocation.e

http://github.com/tybor/Liberty
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