GLib Reference Manual | ||||
---|---|---|---|---|
#include <glib.h> GMemChunk; #define G_ALLOC_AND_FREE #define G_ALLOC_ONLY GMemChunk* g_mem_chunk_new (const gchar *name, gint atom_size, gsize area_size, gint type); gpointer g_mem_chunk_alloc (GMemChunk *mem_chunk); gpointer g_mem_chunk_alloc0 (GMemChunk *mem_chunk); void g_mem_chunk_free (GMemChunk *mem_chunk, gpointer mem); void g_mem_chunk_destroy (GMemChunk *mem_chunk); #define g_mem_chunk_create (type, pre_alloc, alloc_type) #define g_chunk_new (type, chunk) #define g_chunk_new0 (type, chunk) #define g_chunk_free (mem, mem_chunk) void g_mem_chunk_reset (GMemChunk *mem_chunk); void g_mem_chunk_clean (GMemChunk *mem_chunk); void g_blow_chunks (void); void g_mem_chunk_info (void); void g_mem_chunk_print (GMemChunk *mem_chunk);
Memory chunks provide an space-efficient way to allocate equal-sized
pieces of memory, called atoms. However, due to the administrative
overhead (in particular for G_ALLOC_AND_FREE, and when used from multiple
threads), they are in practise often slower than direct use of g_malloc()
.
Therefore, memory chunks have been deprecated in favor of the
slice allocator,
which has been added in 2.10. All internal uses of memory chunks in
GLib have been converted to the g_slice
API.
There are two types of memory chunks, G_ALLOC_ONLY, and G_ALLOC_AND_FREE.
G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never be freed individually. The memory chunk can only be free in its entirety.
G_ALLOC_AND_FREE chunks do allow atoms to be freed individually. The disadvantage of this is that the memory chunk has to keep track of which atoms have been freed. This results in more memory being used and a slight degradation in performance.
To create a memory chunk use g_mem_chunk_new()
or the convenience macro
g_mem_chunk_create()
.
To allocate a new atom use g_mem_chunk_alloc()
, g_mem_chunk_alloc0()
,
or the convenience macros g_chunk_new()
or g_chunk_new0()
.
To free an atom use g_mem_chunk_free()
, or the convenience macro
g_chunk_free()
. (Atoms can only be freed if the memory chunk is created
with the type set to G_ALLOC_AND_FREE.)
To free any blocks of memory which are no longer being used, use
g_mem_chunk_clean()
. To clean all memory chunks, use g_blow_chunks()
.
To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset()
.
To destroy a memory chunk, use g_mem_chunk_destroy()
.
To help debug memory chunks, use g_mem_chunk_info()
and g_mem_chunk_print()
.
Example 17. Using a GMemChunk
GMemChunk *mem_chunk; gchar *mem[10000]; gint i; /* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding 100 bytes. Note that this means that only 2 atoms fit into each memory block and so isn't very efficient. */ mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE); /* Now allocate 10000 atoms. */ for (i = 0; i < 10000; i++) { mem[i] = g_chunk_new (gchar, mem_chunk); /* Fill in the atom memory with some junk. */ for (j = 0; j < 50; j++) mem[i][j] = i * j; } /* Now free all of the atoms. Note that since we are going to destroy the GMemChunk, this wouldn't normally be used. */ for (i = 0; i < 10000; i++) { g_mem_chunk_free (mem_chunk, mem[i]); } /* We are finished with the GMemChunk, so we destroy it. */ g_mem_chunk_destroy (mem_chunk);
Example 18. Using a GMemChunk with data structures
GMemChunk *array_mem_chunk; GRealArray *array; /* Create a GMemChunk to hold GRealArray structures, using the g_mem_chunk_create() convenience macro. We want 1024 atoms in each memory block, and we want to be able to free individual atoms. */ array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE); /* Allocate one atom, using the g_chunk_new() convenience macro. */ array = g_chunk_new (GRealArray, array_mem_chunk); /* We can now use array just like a normal pointer to a structure. */ array->data = NULL; array->len = 0; array->alloc = 0; array->zero_terminated = (zero_terminated ? 1 : 0); array->clear = (clear ? 1 : 0); array->elt_size = elt_size; /* We can free the element, so it can be reused. */ g_chunk_free (array, array_mem_chunk); /* We destroy the GMemChunk when we are finished with it. */ g_mem_chunk_destroy (array_mem_chunk);
typedef struct _GMemChunk GMemChunk;
GMemChunk
is deprecated and should not be used in newly-written code.
The GMemChunk struct is an opaque data structure representing a memory chunk. It should be accessed only through the use of the following functions.
#define G_ALLOC_AND_FREE 2
G_ALLOC_AND_FREE
is deprecated and should not be used in newly-written code.
Specifies the type of a GMemChunk.
Used in g_mem_chunk_new()
and g_mem_chunk_create()
to specify that atoms
will be freed individually.
#define G_ALLOC_ONLY 1
G_ALLOC_ONLY
is deprecated and should not be used in newly-written code.
Specifies the type of a GMemChunk.
Used in g_mem_chunk_new()
and g_mem_chunk_create()
to specify that atoms
will never be freed individually.
GMemChunk* g_mem_chunk_new (const gchar *name, gint atom_size, gsize area_size, gint type);
g_mem_chunk_new
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator
instead
Creates a new GMemChunk.
name : |
a string to identify the GMemChunk. It is not copied so it
should be valid for the lifetime of the GMemChunk. It is only used in
g_mem_chunk_print() , which is used for debugging.
|
atom_size : |
the size, in bytes, of each element in the GMemChunk. |
area_size : |
the size, in bytes, of each block of memory allocated to contain the atoms. |
type : |
the type of the GMemChunk. G_ALLOC_AND_FREE is used if the atoms will be freed individually. G_ALLOC_ONLY should be used if atoms will never be freed individually. G_ALLOC_ONLY is quicker, since it does not need to track free atoms, but it obviously wastes memory if you no longer need many of the atoms. |
Returns : | the new GMemChunk. |
gpointer g_mem_chunk_alloc (GMemChunk *mem_chunk);
g_mem_chunk_alloc
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_alloc()
instead
Allocates an atom of memory from a GMemChunk.
mem_chunk : |
a GMemChunk. |
Returns : | a pointer to the allocated atom. |
gpointer g_mem_chunk_alloc0 (GMemChunk *mem_chunk);
g_mem_chunk_alloc0
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_alloc0()
instead
Allocates an atom of memory from a GMemChunk, setting the memory to 0.
mem_chunk : |
a GMemChunk. |
Returns : | a pointer to the allocated atom. |
void g_mem_chunk_free (GMemChunk *mem_chunk, gpointer mem);
g_mem_chunk_free
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_free1()
instead
Frees an atom in a GMemChunk. This should only be called if the GMemChunk was created with G_ALLOC_AND_FREE. Otherwise it will simply return.
mem_chunk : |
a GMemChunk. |
mem : |
a pointer to the atom to free. |
void g_mem_chunk_destroy (GMemChunk *mem_chunk);
g_mem_chunk_destroy
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Frees all of the memory allocated for a GMemChunk.
mem_chunk : |
a GMemChunk. |
#define g_mem_chunk_create(type, pre_alloc, alloc_type)
g_mem_chunk_create
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
A convenience macro for creating a new GMemChunk.
It calls g_mem_chunk_new()
, using the given type to create the GMemChunk
name. The atom size is determined using
, and the
area size is calculated by multiplying the sizeof()
pre_alloc
parameter with
the atom size.
type : |
the type of the atoms, typically a structure name. |
pre_alloc : |
the number of atoms to store in each block of memory. |
alloc_type : |
the type of the GMemChunk. G_ALLOC_AND_FREE is used if the atoms will be freed individually. G_ALLOC_ONLY should be used if atoms will never be freed individually. G_ALLOC_ONLY is quicker, since it does not need to track free atoms, but it obviously wastes memory if you no longer need many of the atoms. |
Returns : | the new GMemChunk. |
#define g_chunk_new(type, chunk)
g_chunk_new
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_new()
instead
A convenience macro to allocate an atom of memory from a GMemChunk.
It calls g_mem_chunk_alloc()
and casts the returned atom to a pointer to
the given type, avoiding a type cast in the source code.
#define g_chunk_new0(type, chunk)
g_chunk_new0
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_new0()
instead
A convenience macro to allocate an atom of memory from a GMemChunk.
It calls g_mem_chunk_alloc0()
and casts the returned atom to a pointer to
the given type, avoiding a type cast in the source code.
#define g_chunk_free(mem, mem_chunk)
g_chunk_free
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_free()
instead
A convenience macro to free an atom of memory from a GMemChunk.
It simply switches the arguments and calls g_mem_chunk_free()
It is included simply to complement the other convenience macros, g_chunk_new()
and g_chunk_new0()
.
mem : |
a pointer to the atom to be freed. |
mem_chunk : |
a GMemChunk. |
void g_mem_chunk_reset (GMemChunk *mem_chunk);
g_mem_chunk_reset
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Resets a GMemChunk to its initial state. It frees all of the currently allocated blocks of memory.
mem_chunk : |
a GMemChunk. |
void g_mem_chunk_clean (GMemChunk *mem_chunk);
g_mem_chunk_clean
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Frees any blocks in a GMemChunk which are no longer being used.
mem_chunk : |
a GMemChunk. |
void g_blow_chunks (void);
g_blow_chunks
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Calls g_mem_chunk_clean()
on all GMemChunk objects.
void g_mem_chunk_info (void);
g_mem_chunk_info
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Outputs debugging information for all GMemChunk objects currently in use.
It outputs the number of GMemChunk objects currently allocated,
and calls g_mem_chunk_print()
to output information on each one.
void g_mem_chunk_print (GMemChunk *mem_chunk);
g_mem_chunk_print
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Outputs debugging information for a GMemChunk.
It outputs the name of the GMemChunk (set with g_mem_chunk_new()
),
the number of bytes used, and the number of blocks of memory allocated.
mem_chunk : |
a GMemChunk. |