luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-24 04:56:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Inline docs from tmpl/memory.smgl

Browse Source
This commit is contained in:
Jon Nordby 2010-08-26 16:51:33 +02:00 committed by Murray Cumming
parent 4497e84215
commit fb15dde6c1
6 changed files with 365 additions and 429 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -17,6 +17,7 @@ iochannels.sgml
linked_lists_double.sgml
linked_lists_single.sgml
memory_chunks.sgml
memory.sgml
option.sgml
patterns.sgml
quarks.sgml

428
docs/reference/glib/tmpl/memory.sgml
View File

@ -1,428 +0,0 @@
<!-- ##### 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 ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### 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.
Care is taken to avoid overflow when calculating the size of the allocated block.
</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.
Care is taken to avoid overflow when calculating the size of the allocated block.
</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.
Care is taken to avoid overflow when calculating the size of the allocated block.
</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.
The function returns %NULL when @n_structs is 0 of if an overflow occurs.
</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 of if an overflow occurs.
</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.
The function returns %NULL if an overflow occurs.
</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_malloc_n ##### -->
<para>
This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.
</para>
@n_blocks: the number of blocks to allocate
@n_block_bytes: the size of each block in bytes
@Returns: a pointer to the allocated memory
@Since: 2.24
<!-- ##### FUNCTION g_malloc0_n ##### -->
<para>
This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.
</para>
@n_blocks: the number of blocks to allocate
@n_block_bytes: the size of each block in bytes
@Returns: a pointer to the allocated memory
@Since: 2.24
<!-- ##### FUNCTION g_realloc_n ##### -->
<para>
This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.
</para>
@mem: the memory to reallocate
@n_blocks: the number of blocks to allocate
@n_block_bytes: the size of each block in bytes
@Returns: the new address of the allocated memory
@Since: 2.24
<!-- ##### FUNCTION g_try_malloc_n ##### -->
<para>
This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.
</para>
@n_blocks: the number of blocks to allocate
@n_block_bytes: the size of each block in bytes
@Returns: the allocated memory, or %NULL.
@Since: 2.24
<!-- ##### FUNCTION g_try_malloc0_n ##### -->
<para>
This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.
</para>
@n_blocks: the number of blocks to allocate
@n_block_bytes: the size of each block in bytes
@Returns: the allocated memory, or %NULL
@Since: 2.24
<!-- ##### FUNCTION g_try_realloc_n ##### -->
<para>
This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
but care is taken to detect possible overflow during multiplication.
</para>
@mem: previously-allocated memory, or %NULL.
@n_blocks: the number of blocks to allocate
@n_block_bytes: the size of each block in bytes
@Returns: the allocated memory, or %NULL.
@Since: 2.24
<!-- ##### 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>
@void:
@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>
@void:

47
glib/galloca.h
View File

@ -57,7 +57,54 @@ G_END_DECLS
# endif /* !_MSC_VER && !__DMC__ */
#endif /* !__GNUC__ && !GLIB_HAVE_ALLOCA_H */
/**
* g_alloca:
* @size: number of bytes to allocate.
*
* 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>
*
* Returns: space for @size bytes, allocated on the stack
*/
#define g_alloca(size) alloca (size)
/**
* g_newa:
* @struct_type: Type of memory chunks to be allocated
* @n_structs: Number of chunks to be allocated
*
* Wraps g_alloca() in a more typesafe manner.
*
* Returns: Pointer to stack space for @n_structs chunks of type @struct_type
*/
#define g_newa(struct_type, n_structs) ((struct_type*) g_alloca (sizeof (struct_type) * (gsize) (n_structs)))
#endif /* __G_ALLOCA_H__ */

201
glib/gmem.c
View File

@ -121,7 +121,37 @@ static GMemVTable glib_mem_vtable = {
standard_try_realloc,
};
/**
* SECTION:memory
* @Short_Description: general memory-handling
* @Title: Memory Allocation
*
* These functions provide support for allocating and freeing memory.
*
* <note>
* 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.
* </note>
*
* <note>
* 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().
* </note>
*/
/* --- functions --- */
/**
* g_malloc:
* @n_bytes: the number of bytes to allocate
*
* Allocates @n_bytes bytes of memory.
* If @n_bytes is 0 it returns %NULL.
*
* Returns: a pointer to the allocated memory
*/
gpointer
g_malloc (gsize n_bytes)
{
@ -145,6 +175,15 @@ g_malloc (gsize n_bytes)
return NULL;
}
/**
* g_malloc0:
* @n_bytes: the number of bytes to allocate
*
* Allocates @n_bytes bytes of memory, initialized to 0's.
* If @n_bytes is 0 it returns %NULL.
*
* Returns: a pointer to the allocated memory
*/
gpointer
g_malloc0 (gsize n_bytes)
{
@ -168,6 +207,19 @@ g_malloc0 (gsize n_bytes)
return NULL;
}
/**
* g_realloc:
* @mem: the memory to reallocate
* @n_bytes: new size of the memory in bytes
*
* 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.
*
* Returns: the new address of the allocated memory
*/
gpointer
g_realloc (gpointer mem,
gsize n_bytes)
@ -195,6 +247,13 @@ g_realloc (gpointer mem,
return NULL;
}
/**
* g_free:
* @mem: the memory to free
*
* Frees the memory pointed to by @mem.
* If @mem is %NULL it simply returns.
*/
void
g_free (gpointer mem)
{
@ -205,6 +264,15 @@ g_free (gpointer mem)
TRACE(GLIB_MEM_FREE((void*) mem));
}
/**
* g_try_malloc:
* @n_bytes: number of bytes to allocate.
*
* Attempts to allocate @n_bytes, and returns %NULL on failure.
* Contrast with g_malloc(), which aborts the program on failure.
*
* Returns: the allocated memory, or %NULL.
*/
gpointer
g_try_malloc (gsize n_bytes)
{
@ -222,6 +290,16 @@ g_try_malloc (gsize n_bytes)
return mem;
}
/**
* g_try_malloc0:
* @n_bytes: number of bytes to allocate
*
* Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
* failure. Contrast with g_malloc0(), which aborts the program on failure.
*
* Since: 2.8
* Returns: the allocated memory, or %NULL
*/
gpointer
g_try_malloc0 (gsize n_bytes)
{
@ -240,6 +318,17 @@ g_try_malloc0 (gsize n_bytes)
return mem;
}
/**
* g_try_realloc:
* @mem: previously-allocated memory, or %NULL.
* @n_bytes: number of bytes to allocate.
*
* 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().
*
* Returns: the allocated memory, or %NULL.
*/
gpointer
g_try_realloc (gpointer mem,
gsize n_bytes)
@ -265,6 +354,17 @@ g_try_realloc (gpointer mem,
#define SIZE_OVERFLOWS(a,b) (G_UNLIKELY ((b) > 0 && (a) > G_MAXSIZE / (b)))
/**
* g_malloc_n:
* @n_blocks: the number of blocks to allocate
* @n_block_bytes: the size of each block in bytes
*
* This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
* but care is taken to detect possible overflow during multiplication.
*
* Since: 2.24
* Returns: a pointer to the allocated memory
*/
gpointer
g_malloc_n (gsize n_blocks,
gsize n_block_bytes)
@ -281,6 +381,17 @@ g_malloc_n (gsize n_blocks,
return g_malloc (n_blocks * n_block_bytes);
}
/**
* g_malloc0_n:
* @n_blocks: the number of blocks to allocate
* @n_block_bytes: the size of each block in bytes
*
* This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
* but care is taken to detect possible overflow during multiplication.
*
* Since: 2.24
* Returns: a pointer to the allocated memory
*/
gpointer
g_malloc0_n (gsize n_blocks,
gsize n_block_bytes)
@ -297,6 +408,18 @@ g_malloc0_n (gsize n_blocks,
return g_malloc0 (n_blocks * n_block_bytes);
}
/**
* g_realloc_n:
* @mem: the memory to reallocate
* @n_blocks: the number of blocks to allocate
* @n_block_bytes: the size of each block in bytes
*
* This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
* but care is taken to detect possible overflow during multiplication.
*
* Since: 2.24
* Returns: the new address of the allocated memory
*/
gpointer
g_realloc_n (gpointer mem,
gsize n_blocks,
@ -314,6 +437,17 @@ g_realloc_n (gpointer mem,
return g_realloc (mem, n_blocks * n_block_bytes);
}
/**
* g_try_malloc_n:
* @n_blocks: the number of blocks to allocate
* @n_block_bytes: the size of each block in bytes
*
* This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
* but care is taken to detect possible overflow during multiplication.
*
* Since: 2.24
* Returns: the allocated memory, or %NULL.
*/
gpointer
g_try_malloc_n (gsize n_blocks,
gsize n_block_bytes)
@ -324,6 +458,17 @@ g_try_malloc_n (gsize n_blocks,
return g_try_malloc (n_blocks * n_block_bytes);
}
/**
* g_try_malloc0_n:
* @n_blocks: the number of blocks to allocate
* @n_block_bytes: the size of each block in bytes
*
* This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
* but care is taken to detect possible overflow during multiplication.
*
* Since: 2.24
* Returns: the allocated memory, or %NULL
*/
gpointer
g_try_malloc0_n (gsize n_blocks,
gsize n_block_bytes)
@ -334,6 +479,18 @@ g_try_malloc0_n (gsize n_blocks,
return g_try_malloc0 (n_blocks * n_block_bytes);
}
/**
* g_try_realloc_n:
* @mem: previously-allocated memory, or %NULL.
* @n_blocks: the number of blocks to allocate
* @n_block_bytes: the size of each block in bytes
*
* This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
* but care is taken to detect possible overflow during multiplication.
*
* Since: 2.24
* Returns: the allocated memory, or %NULL.
*/
gpointer
g_try_realloc_n (gpointer mem,
gsize n_blocks,
@ -367,7 +524,7 @@ static gboolean vtable_set = FALSE;
*
* Checks whether the allocator used by g_malloc() is the system's
* malloc implementation. If it returns %TRUE memory allocated with
* malloc() can be used interchangeable with memory allocated using g_malloc().
* malloc() can be used interchangeable with memory allocated using g_malloc().
* This function is useful for avoiding an extra copy of allocated memory returned
* by a non-GLib-based API.
*
@ -381,6 +538,18 @@ g_mem_is_system_malloc (void)
return !vtable_set;
}
/**
* g_mem_set_vtable:
* @vtable: table of memory allocation routines.
*
* 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.
*/
void
g_mem_set_vtable (GMemVTable *vtable)
{
@ -406,6 +575,14 @@ g_mem_set_vtable (GMemVTable *vtable)
/* --- memory profiling and checking --- */
#ifdef G_DISABLE_CHECKS
/**
* glib_mem_profiler_table:
*
* 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.
*/
GMemVTable *glib_mem_profiler_table = &glib_mem_vtable;
void
g_mem_profile (void)
@ -506,6 +683,22 @@ profile_print_locked (guint *local_data,
g_print (" --- none ---\n");
}
/**
* g_mem_profile:
* @void:
*
* Outputs a summary of memory usage.
*
* 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.
*
* Note that this function will not output anything unless you have
* previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
*/
void
g_mem_profile (void)
{
@ -1161,6 +1354,12 @@ g_allocator_free (GAllocator *allocator)
#ifdef ENABLE_GC_FRIENDLY_DEFAULT
gboolean g_mem_gc_friendly = TRUE;
#else
/**
* g_mem_gc_friendly:
*
* This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
* includes the key <link linkend="G_DEBUG">gc-friendly</link>.
*/
gboolean g_mem_gc_friendly = FALSE;
#endif

106
glib/gmem.h
View File

@ -36,10 +36,29 @@
G_BEGIN_DECLS
/**
* GMemVTable:
* @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.
*
* 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.
*/
typedef struct _GMemVTable GMemVTable;
#if GLIB_SIZEOF_VOID_P > GLIB_SIZEOF_LONG
/**
* G_MEM_ALIGN:
*
* Indicates the number of bytes to which memory will be aligned on the
* current platform.
*/
# define G_MEM_ALIGN GLIB_SIZEOF_VOID_P
#else /* GLIB_SIZEOF_VOID_P <= GLIB_SIZEOF_LONG */
# define G_MEM_ALIGN GLIB_SIZEOF_LONG
@ -120,11 +139,98 @@ gpointer g_try_realloc_n (gpointer mem,
#endif
/**
* g_new:
* @struct_type: the type of the elements to allocate
* @n_structs: the number of elements to allocate
*
* 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.
* Care is taken to avoid overflow when calculating the size of the allocated block.
*
* 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.
*
* Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
*/
#define g_new(struct_type, n_structs) _G_NEW (struct_type, n_structs, malloc)
/**
* g_new0:
* @struct_type: the type of the elements to allocate.
* @n_structs: the number of elements to allocate.
*
* 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.
* Care is taken to avoid overflow when calculating the size of the allocated block.
*
* 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.
*
* Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
*/
#define g_new0(struct_type, n_structs) _G_NEW (struct_type, n_structs, malloc0)
/**
* g_renew:
* @struct_type: the type of the elements to allocate
* @mem: the currently allocated memory
* @n_structs: the number of elements to allocate
*
* 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.
* Care is taken to avoid overflow when calculating the size of the allocated block.
*
* Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
*/
#define g_renew(struct_type, mem, n_structs) _G_RENEW (struct_type, mem, n_structs, realloc)
/**
* g_try_new:
* @struct_type: the type of the elements to allocate
* @n_structs: the number of elements to allocate
*
* 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.
* The function returns %NULL when @n_structs is 0 of if an overflow occurs.
*
* Since: 2.8
* Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
*/
#define g_try_new(struct_type, n_structs) _G_NEW (struct_type, n_structs, try_malloc)
/**
* g_try_new0:
* @struct_type: the type of the elements to allocate
* @n_structs: the number of elements to allocate
*
* 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 of if an overflow occurs.
*
* Since: 2.8
* Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
*/
#define g_try_new0(struct_type, n_structs) _G_NEW (struct_type, n_structs, try_malloc0)
/**
* g_try_renew:
* @struct_type: the type of the elements to allocate
* @mem: the currently allocated memory
* @n_structs: the number of elements to allocate
*
* 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.
* The function returns %NULL if an overflow occurs.
*
* Since: 2.8
* Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
*/
#define g_try_renew(struct_type, mem, n_structs) _G_RENEW (struct_type, mem, n_structs, try_realloc)

11
glib/gstrfuncs.c
View File

@ -107,6 +107,17 @@ g_strdup (const gchar *str)
return new_str;
}
/**
* g_memdup:
* @mem: the memory to copy.
* @byte_size: the number of bytes to copy.
*
* Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
* from @mem. If @mem is %NULL it returns %NULL.
*
* Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
* is %NULL.
*/
gpointer
g_memdup (gconstpointer mem,
guint byte_size)