From fb15dde6c171acb445da5e51ce17e241bf9c52fb Mon Sep 17 00:00:00 2001 From: Jon Nordby Date: Thu, 26 Aug 2010 16:51:33 +0200 Subject: [PATCH] docs: Inline docs from tmpl/memory.smgl --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/memory.sgml | 428 --------------------------- glib/galloca.h | 47 +++ glib/gmem.c | 201 ++++++++++++- glib/gmem.h | 106 +++++++ glib/gstrfuncs.c | 11 + 6 files changed, 365 insertions(+), 429 deletions(-) delete mode 100644 docs/reference/glib/tmpl/memory.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index 17cf581fb..606dd26af 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -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 diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml deleted file mode 100644 index 3e8fe97a0..000000000 --- a/docs/reference/glib/tmpl/memory.sgml +++ /dev/null @@ -1,428 +0,0 @@ - -Memory Allocation - - -general memory-handling - - - -These functions provide support for allocating and freeing memory. - - - - -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. - - - - - -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(). - - - - - - - - - - - - - - - - -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. - - -@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 - - - - -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. - - -@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. - - - - -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. - - -@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 - - - - -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. - - -@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 - - - - -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. - - -@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 - - - - -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. - - -@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 - - - - -Allocates @n_bytes bytes of memory. -If @n_bytes is 0 it returns %NULL. - - -@n_bytes: the number of bytes to allocate -@Returns: a pointer to the allocated memory - - - - -Allocates @n_bytes bytes of memory, initialized to 0's. -If @n_bytes is 0 it returns %NULL. - - -@n_bytes: the number of bytes to allocate -@Returns: a pointer to the allocated memory - - - - -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. - - -@mem: the memory to reallocate -@n_bytes: new size of the memory in bytes -@Returns: the new address of the allocated memory - - - - -Attempts to allocate @n_bytes, and returns %NULL on failure. -Contrast with g_malloc(), which aborts the program on failure. - - -@n_bytes: number of bytes to allocate. -@Returns: the allocated memory, or %NULL. - - - - -Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on -failure. Contrast with g_malloc0(), which aborts the program on failure. - - -@n_bytes: number of bytes to allocate -@Returns: the allocated memory, or %NULL -@Since: 2.8 - - - - -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(). - - -@mem: previously-allocated memory, or %NULL. -@n_bytes: number of bytes to allocate. -@Returns: the allocated memory, or %NULL. - - - - -This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - -@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 - - - - -This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - -@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 - - - - -This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, -but care is taken to detect possible overflow during multiplication. - - -@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 - - - - -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. - - -@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 - - - - -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. - - -@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 - - - - -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. - - -@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 - - - - -Frees the memory pointed to by @mem. -If @mem is %NULL it simply returns. - - -@mem: the memory to free - - - - -This variable is %TRUE if the G_DEBUG environment variable -includes the key gc-friendly. - - - - - -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(): - - - + alloca() is very fast, as on most systems it's implemented by just adjusting - the stack pointer register. - - - + It doesn't cause any memory fragmentation, within its scope, separate alloca() - blocks just build up and are released together at function end. - - - - 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. - - - - 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. - - - - 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. - - - - - -@size: number of bytes to allocate. -@Returns: space for @size bytes, allocated on the stack - - - - -Wraps g_alloca() in a more typesafe manner. - - -@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 - - - - - - - -@dest: -@src: -@len: - - - - -Allocates @byte_size bytes of memory, and copies @byte_size bytes into it -from @mem. If @mem is %NULL it returns %NULL. - - -@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. - - - - -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. - - -@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. - - - -Sets the #GMemVTable to use for memory allocation. You can use this to provide -custom memory allocation routines. This function must be called -before using any other GLib functions. 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. - - -@vtable: table of memory allocation routines. - - - - - - - -@void: -@Returns: - - - - -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. - - - - - -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: - - diff --git a/glib/galloca.h b/glib/galloca.h index 356587ff6..8876836a6 100644 --- a/glib/galloca.h +++ b/glib/galloca.h @@ -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(): + * + * + * + alloca() is very fast, as on most systems it's implemented by just adjusting + * the stack pointer register. + * + * + * + It doesn't cause any memory fragmentation, within its scope, separate alloca() + * blocks just build up and are released together at function end. + * + * + * - 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. + * + * + * - 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. + * + * + * - 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. + * + * + * + * 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__ */ diff --git a/glib/gmem.c b/glib/gmem.c index 2c9b74a18..7212ae49d 100644 --- a/glib/gmem.c +++ b/glib/gmem.c @@ -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. + * + * + * 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. + * + * + * + * 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(). + * + */ + /* --- 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. This function must be called + * before using any other GLib functions. 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 G_DEBUG environment variable + * includes the key gc-friendly. + */ gboolean g_mem_gc_friendly = FALSE; #endif diff --git a/glib/gmem.h b/glib/gmem.h index d005eb1d7..01d953e6c 100644 --- a/glib/gmem.h +++ b/glib/gmem.h @@ -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) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index d7e82d19a..6c1166a4d 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -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)