mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-02-24 03:02:10 +01:00
346 lines
11 KiB
Plaintext
346 lines
11 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Memory Allocation
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
general memory-handling
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
These functions provide support for allocating and freeing memory.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
|
|
<note>
|
|
<para>
|
|
It's important to match g_malloc() with g_free(), plain malloc() with free(),
|
|
and (if you're using C++) new with delete and new[] with delete[]. Otherwise
|
|
bad things can happen, since these allocators may use different memory
|
|
pools (and new/delete call constructors and destructors). See also
|
|
g_mem_set_vtable().
|
|
</para>
|
|
</note>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### MACRO g_new ##### -->
|
|
<para>
|
|
Allocates @n_structs elements of type @struct_type.
|
|
The returned pointer is cast to a pointer to the given type.
|
|
If @n_structs is 0 it returns %NULL.
|
|
</para>
|
|
<para>
|
|
Since the returned pointer is already casted to the right type,
|
|
it is normally unnecessary to cast it explicitly, and doing
|
|
so might hide memory allocation errors.
|
|
</para>
|
|
|
|
@struct_type: the type of the elements to allocate
|
|
@n_structs: the number of elements to allocate
|
|
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
|
|
|
|
|
|
<!-- ##### MACRO g_new0 ##### -->
|
|
<para>
|
|
Allocates @n_structs elements of type @struct_type, initialized to 0's.
|
|
The returned pointer is cast to a pointer to the given type.
|
|
If @n_structs is 0 it returns %NULL.
|
|
</para>
|
|
<para>
|
|
Since the returned pointer is already casted to the right type,
|
|
it is normally unnecessary to cast it explicitly, and doing
|
|
so might hide memory allocation errors.
|
|
</para>
|
|
|
|
@struct_type: the type of the elements to allocate.
|
|
@n_structs: the number of elements to allocate.
|
|
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
|
|
|
|
|
|
<!-- ##### MACRO g_renew ##### -->
|
|
<para>
|
|
Reallocates the memory pointed to by @mem, so that it now has space for
|
|
@n_structs elements of type @struct_type. It returns the new address of
|
|
the memory, which may have been moved.
|
|
</para>
|
|
|
|
@struct_type: the type of the elements to allocate
|
|
@mem: the currently allocated memory
|
|
@n_structs: the number of elements to allocate
|
|
@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
|
|
|
|
|
|
<!-- ##### MACRO g_try_new ##### -->
|
|
<para>
|
|
Attempts to allocate @n_structs elements of type @struct_type, and returns
|
|
%NULL on failure. Contrast with g_new(), which aborts the program on failure.
|
|
The returned pointer is cast to a pointer to the given type.
|
|
If @n_structs is 0 it returns %NULL.
|
|
</para>
|
|
|
|
@struct_type: the type of the elements to allocate
|
|
@n_structs: the number of elements to allocate
|
|
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
|
|
@Since: 2.8
|
|
|
|
|
|
<!-- ##### MACRO g_try_new0 ##### -->
|
|
<para>
|
|
Attempts to allocate @n_structs elements of type @struct_type, initialized
|
|
to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
|
|
the program on failure.
|
|
The returned pointer is cast to a pointer to the given type.
|
|
The function returns %NULL when @n_structs is 0.
|
|
</para>
|
|
|
|
@struct_type: the type of the elements to allocate
|
|
@n_structs: the number of elements to allocate
|
|
@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
|
|
@Since: 2.8
|
|
|
|
|
|
<!-- ##### MACRO g_try_renew ##### -->
|
|
<para>
|
|
Attempts to reallocate the memory pointed to by @mem, so that it now has
|
|
space for @n_structs elements of type @struct_type, and returns %NULL on
|
|
failure. Contrast with g_renew(), which aborts the program on failure.
|
|
It returns the new address of the memory, which may have been moved.
|
|
</para>
|
|
|
|
@struct_type: the type of the elements to allocate
|
|
@mem: the currently allocated memory
|
|
@n_structs: the number of elements to allocate
|
|
@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
|
|
@Since: 2.8
|
|
|
|
|
|
<!-- ##### FUNCTION g_malloc ##### -->
|
|
<para>
|
|
Allocates @n_bytes bytes of memory.
|
|
If @n_bytes is 0 it returns %NULL.
|
|
</para>
|
|
|
|
@n_bytes: the number of bytes to allocate
|
|
@Returns: a pointer to the allocated memory
|
|
|
|
|
|
<!-- ##### FUNCTION g_malloc0 ##### -->
|
|
<para>
|
|
Allocates @n_bytes bytes of memory, initialized to 0's.
|
|
If @n_bytes is 0 it returns %NULL.
|
|
</para>
|
|
|
|
@n_bytes: the number of bytes to allocate
|
|
@Returns: a pointer to the allocated memory
|
|
|
|
|
|
<!-- ##### FUNCTION g_realloc ##### -->
|
|
<para>
|
|
Reallocates the memory pointed to by @mem, so that it now has space for
|
|
@n_bytes bytes of memory. It returns the new address of the memory, which may
|
|
have been moved. @mem may be %NULL, in which case it's considered to
|
|
have zero-length. @n_bytes may be 0, in which case %NULL will be returned
|
|
and @mem will be freed unless it is %NULL.
|
|
</para>
|
|
|
|
@mem: the memory to reallocate
|
|
@n_bytes: new size of the memory in bytes
|
|
@Returns: the new address of the allocated memory
|
|
|
|
|
|
<!-- ##### FUNCTION g_try_malloc ##### -->
|
|
<para>
|
|
Attempts to allocate @n_bytes, and returns %NULL on failure.
|
|
Contrast with g_malloc(), which aborts the program on failure.
|
|
</para>
|
|
|
|
@n_bytes: number of bytes to allocate.
|
|
@Returns: the allocated memory, or %NULL.
|
|
|
|
|
|
<!-- ##### FUNCTION g_try_malloc0 ##### -->
|
|
<para>
|
|
Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
|
|
failure. Contrast with g_malloc0(), which aborts the program on failure.
|
|
</para>
|
|
|
|
@n_bytes: number of bytes to allocate
|
|
@Returns: the allocated memory, or %NULL
|
|
@Since: 2.8
|
|
|
|
|
|
<!-- ##### FUNCTION g_try_realloc ##### -->
|
|
<para>
|
|
Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
|
|
on failure. Contrast with g_realloc(), which aborts the program
|
|
on failure. If @mem is %NULL, behaves the same as g_try_malloc().
|
|
</para>
|
|
|
|
@mem: previously-allocated memory, or %NULL.
|
|
@n_bytes: number of bytes to allocate.
|
|
@Returns: the allocated memory, or %NULL.
|
|
|
|
|
|
<!-- ##### FUNCTION g_free ##### -->
|
|
<para>
|
|
Frees the memory pointed to by @mem.
|
|
If @mem is %NULL it simply returns.
|
|
</para>
|
|
|
|
@mem: the memory to free
|
|
|
|
|
|
<!-- ##### VARIABLE g_mem_gc_friendly ##### -->
|
|
<para>
|
|
This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
|
|
includes the key <link linkend="G_DEBUG">gc-friendly</link>.
|
|
</para>
|
|
|
|
|
|
<!-- ##### MACRO g_alloca ##### -->
|
|
<para>
|
|
Allocates @size bytes on the stack; these bytes will be freed when the current
|
|
stack frame is cleaned up. This macro essentially just wraps the alloca()
|
|
function present on most UNIX variants.
|
|
Thus it provides the same advantages and pitfalls as alloca():
|
|
<variablelist>
|
|
<varlistentry><term></term><listitem><para>
|
|
+ alloca() is very fast, as on most systems it's implemented by just adjusting
|
|
the stack pointer register.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term></term><listitem><para>
|
|
+ It doesn't cause any memory fragmentation, within its scope, separate alloca()
|
|
blocks just build up and are released together at function end.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term></term><listitem><para>
|
|
- Allocation sizes have to fit into the current stack frame. For instance in a
|
|
threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
|
|
so be sparse with alloca() uses.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term></term><listitem><para>
|
|
- Allocation failure due to insufficient stack space is not indicated with a %NULL
|
|
return like e.g. with malloc(). Instead, most systems probably handle it the same
|
|
way as out of stack space situations from infinite function recursion, i.e.
|
|
with a segmentation fault.
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term></term><listitem><para>
|
|
- Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
|
|
Stack space allocated with alloca() in the same scope as a variable sized array
|
|
will be freed together with the variable sized array upon exit of that scope, and
|
|
not upon exit of the enclosing function scope.
|
|
</para></listitem></varlistentry>
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
@size: number of bytes to allocate.
|
|
@Returns: space for @size bytes, allocated on the stack
|
|
|
|
|
|
<!-- ##### MACRO g_newa ##### -->
|
|
<para>
|
|
Wraps g_alloca() in a more typesafe manner.
|
|
</para>
|
|
|
|
@struct_type: Type of memory chunks to be allocated
|
|
@n_structs: Number of chunks to be allocated
|
|
@Returns: Pointer to stack space for @n_structs chunks of type @struct_type
|
|
|
|
|
|
<!-- ##### MACRO g_memmove ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@dest:
|
|
@src:
|
|
@len:
|
|
|
|
|
|
<!-- ##### FUNCTION g_memdup ##### -->
|
|
<para>
|
|
Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
|
|
from @mem. If @mem is %NULL it returns %NULL.
|
|
</para>
|
|
|
|
@mem: the memory to copy.
|
|
@byte_size: the number of bytes to copy.
|
|
@Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
|
|
is %NULL.
|
|
|
|
|
|
<!-- ##### STRUCT GMemVTable ##### -->
|
|
<para>
|
|
A set of functions used to perform memory allocation. The same #GMemVTable must
|
|
be used for all allocations in the same program; a call to g_mem_set_vtable(),
|
|
if it exists, should be prior to any use of GLib.
|
|
</para>
|
|
|
|
@malloc: function to use for allocating memory.
|
|
@realloc: function to use for reallocating memory.
|
|
@free: function to use to free memory.
|
|
@calloc: function to use for allocating zero-filled memory.
|
|
@try_malloc: function to use for allocating memory without a default error handler.
|
|
@try_realloc: function to use for reallocating memory without a default error handler.
|
|
|
|
<!-- ##### FUNCTION g_mem_set_vtable ##### -->
|
|
<para>
|
|
Sets the #GMemVTable to use for memory allocation. You can use this to provide
|
|
custom memory allocation routines. <emphasis>This function must be called
|
|
before using any other GLib functions.</emphasis> The @vtable only needs to
|
|
provide malloc(), realloc(), and free() functions; GLib can provide default
|
|
implementations of the others. The malloc() and realloc() implementations
|
|
should return %NULL on failure, GLib will handle error-checking for you.
|
|
@vtable is copied, so need not persist after this function has been called.
|
|
</para>
|
|
|
|
@vtable: table of memory allocation routines.
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_is_system_malloc ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### VARIABLE glib_mem_profiler_table ##### -->
|
|
<para>
|
|
A #GMemVTable containing profiling variants of the memory
|
|
allocation functions. Use them together with g_mem_profile()
|
|
in order to get information about the memory allocation pattern
|
|
of your program.
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION g_mem_profile ##### -->
|
|
<para>
|
|
Outputs a summary of memory usage.
|
|
</para>
|
|
<para>
|
|
It outputs the frequency of allocations of different sizes,
|
|
the total number of bytes which have been allocated,
|
|
the total number of bytes which have been freed,
|
|
and the difference between the previous two values, i.e. the number of bytes
|
|
still in use.
|
|
</para>
|
|
<para>
|
|
Note that this function will not output anything unless you have
|
|
previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
|
|
</para>
|
|
|
|
|
|
|