Mercurial > pidgin3 / changeset

--- a/doc/reference/libpurple/libpurple-docs.xml	Sat Apr 05 11:21:35 2014 +0200
+++ b/doc/reference/libpurple/libpurple-docs.xml	Sat Apr 05 14:19:33 2014 +0200
@@ -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" />

--- a/libpurple/memorypool.h	Sat Apr 05 11:21:35 2014 +0200
+++ b/libpurple/memorypool.h	Sat Apr 05 14:19:33 2014 +0200
@@ -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 @@
 
 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 @@
  *
  * 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_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_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);