/pidgin/main: 2224568d8bd2: Comments: memory pool

[Tomasz Wasilczyk]

Changeset: 2224568d8bd2bc3060ce52220a58ac4fef4383fb
Author:	 Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date:	 2014-04-05 14:19 +0200
Branch:	 default
URL: https://hg.pidgin.im/pidgin/main/rev/2224568d8bd2

Description:

Comments: memory pool

diffstat:

 doc/reference/libpurple/libpurple-docs.xml |   1 +
 libpurple/memorypool.h                     |  74 ++++++++++++++++++++++-------
 2 files changed, 56 insertions(+), 19 deletions(-)

diffs (175 lines):

diff --git a/doc/reference/libpurple/libpurple-docs.xml b/doc/reference/libpurple/libpurple-docs.xml
--- a/doc/reference/libpurple/libpurple-docs.xml
+++ b/doc/reference/libpurple/libpurple-docs.xml
@@ -56,6 +56,7 @@
       <xi:include href="xml/imgstore.xml" />
       <xi:include href="xml/keyring.xml" />
       <xi:include href="xml/log.xml" />
+      <xi:include href="xml/memorypool.xml" />
       <xi:include href="xml/desktopitem.xml" />
       <xi:include href="xml/mime.xml" />
       <xi:include href="xml/nat-pmp.xml" />
diff --git a/libpurple/memorypool.h b/libpurple/memorypool.h
--- a/libpurple/memorypool.h
+++ b/libpurple/memorypool.h
@@ -22,6 +22,25 @@
 
 #ifndef PURPLE_MEMORY_POOL_H
 #define PURPLE_MEMORY_POOL_H
+/**
+ * SECTION:memorypool
+ * @section_id: libpurple-memorypool
+ * @short_description: <filename>memorypool.h</filename>
+ * @title: Memory pools
+ *
+ * A #PurpleMemoryPool allows allocating many small objects within a single
+ * memory range and releasing them all at once using a single call. This
+ * prevents memory fragmentation and improves performance when used properly.
+ * It's purpose is to act as an internal storage for other object private
+ * structures, like tree nodes, string chunks, list elements.
+ *
+ * Current implementation is not optimized for releasing individual objects,
+ * so it may be extremely inefficient, when misused. On every memory allocation,
+ * it checks if there is enough space in current block. If there is not enough
+ * room here, it creates another block of memory. On pool destruction or calling
+ * #purple_memory_pool_cleanup, the whole block chain will be freed, using only
+ * one #g_free call for every block.
+ */
 
 #include <glib-object.h>
 
@@ -40,12 +59,22 @@
 typedef struct _PurpleMemoryPool PurpleMemoryPool;
 typedef struct _PurpleMemoryPoolClass PurpleMemoryPoolClass;
 
+/**
+ * PurpleMemoryPool:
+ *
+ * The memory pool object instance.
+ */
 struct _PurpleMemoryPool
 {
 	/*< private >*/
 	GObject parent_instance;
 };
 
+/**
+ * PurpleMemoryPoolClass:
+ *
+ * Base class for #PurpleMemoryPool objects.
+ */
 struct _PurpleMemoryPoolClass
 {
 	/*< private >*/
@@ -63,6 +92,11 @@ struct _PurpleMemoryPoolClass
 
 G_BEGIN_DECLS
 
+/**
+ * purple_memory_pool_get_type:
+ *
+ * Returns: the #GType for a #PurpleMemoryPool.
+ */
 GType
 purple_memory_pool_get_type(void);
 
@@ -71,15 +105,15 @@ purple_memory_pool_get_type(void);
  *
  * Creates a new memory pool.
  *
- * Returns: The new #PurpleMemoryPool.
+ * Returns: the new #PurpleMemoryPool.
  */
 PurpleMemoryPool *
 purple_memory_pool_new(void);
 
 /**
  * purple_memory_pool_set_block_size:
- * @pool: The memory pool.
- * @block_size: The new default block size.
+ * @pool: the memory pool.
+ * @block_size: the new default block size.
  *
  * Sets new default block size for a memory pool. You might want to call this
  * before any allocation, to have it applied to the every created block.
@@ -89,47 +123,49 @@ purple_memory_pool_set_block_size(Purple
 
 /**
  * purple_memory_pool_alloc:
- * @pool: The memory pool.
- * @size: The size of memory to be allocated.
- * @alignment: The alignment of memory block (should be a power of two).
+ * @pool: the memory pool.
+ * @size: the size of memory to be allocated.
+ * @alignment: the alignment of memory block (should be a power of two).
  *
  * Allocates an aligned memory block within a pool.
  *
  * Returns: the pointer to a memory block. This should be freed with
- *          a call to purple_memory_pool_free.
+ *          a call to #purple_memory_pool_free.
  */
 gpointer
 purple_memory_pool_alloc(PurpleMemoryPool *pool, gsize size, guint alignment);
 
 /**
  * purple_memory_pool_alloc0:
- * @pool: The memory pool.
- * @size: The size of memory to be allocated.
- * @alignment: The alignment of memory block (should be a power of two).
+ * @pool: the memory pool.
+ * @size: the size of memory to be allocated.
+ * @alignment: the alignment of memory block (should be a power of two).
  *
  * Allocates an aligned memory block within a pool and sets its contents to
  * zeros.
  *
  * Returns: the pointer to a memory block. This should be freed with
- *          a call to purple_memory_pool_free.
+ *          a call to #purple_memory_pool_free.
  */
 gpointer
 purple_memory_pool_alloc0(PurpleMemoryPool *pool, gsize size, guint alignment);
 
 /**
  * purple_memory_pool_free:
- * @pool: The memory pool.
- * @mem: The pointer to a memory block.
+ * @pool: the memory pool.
+ * @mem: the pointer to a memory block.
  *
  * Frees a memory allocated within a memory pool. This can be a no-op in certain
- * implementations. Thus, it don't need to be called in every case.
+ * implementations. Thus, it don't need to be called in every case. Thus, the
+ * freed memory is wasted until you call #purple_memory_pool_cleanup
+ * or destroy the @pool.
  */
 void
 purple_memory_pool_free(PurpleMemoryPool *pool, gpointer mem);
 
 /**
  * purple_memory_pool_cleanup:
- * @pool: The memory pool.
+ * @pool: the memory pool.
  *
  * Marks all memory allocated within a memory pool as not used. It may free
  * resources, but don't have to.
@@ -139,14 +175,14 @@ purple_memory_pool_cleanup(PurpleMemoryP
 
 /**
  * purple_memory_pool_strdup:
- * @pool: The memory pool.
- * @str: The string to duplicate.
+ * @pool: the memory pool.
+ * @str: the string to duplicate.
  *
  * Duplicates a string using a memory allocated within a memory pool. If @str is
- * %NULL it returns %NULL. The returned string should be freed with g_free()
+ * %NULL, it returns %NULL. The returned string should be freed with g_free()
  * when no longer needed.
  *
- * Returns: a newly-allocated copy of @str
+ * Returns: a newly-allocated copy of @str.
  */
 gchar *
 purple_memory_pool_strdup(PurpleMemoryPool *pool, const gchar *str);