libpurple/memorypool.h

   1 /*
   2  * Purple
   3  *
   4  * Purple is the legal property of its developers, whose names are too
   5  * numerous to list here. Please refer to the COPYRIGHT file distributed
   6  * with this source distribution
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or (at
  11  * your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
  21  */
  22
  23 #ifndef PURPLE_MEMORY_POOL_H
  24 #define PURPLE_MEMORY_POOL_H
  25 /**
  26  * SECTION:memorypool
  27  * @include:memorypool.h
  28  * @section_id: libpurple-memorypool
  29  * @short_description: a container for a large number of small chunks of memory
  30  * @title: Memory pools
  31  *
  32  * A #PurpleMemoryPool allows allocating many small objects within a single
  33  * memory range and releasing them all at once using a single call. This
  34  * prevents memory fragmentation and improves performance when used properly.
  35  * It's purpose is to act as an internal storage for other object private
  36  * structures, like tree nodes, string chunks, list elements.
  37  *
  38  * Current implementation is not optimized for releasing individual objects,
  39  * so it may be extremely inefficient, when misused. On every memory allocation,
  40  * it checks if there is enough space in current block. If there is not enough
  41  * room here, it creates another block of memory. On pool destruction or calling
  42  * #purple_memory_pool_cleanup, the whole block chain will be freed, using only
  43  * one #g_free call for every block.
  44  */
  45
  46 #include <glib-object.h>
  47
  48 #define PURPLE_TYPE_MEMORY_POOL (purple_memory_pool_get_type())
  49 #define PURPLE_MEMORY_POOL(obj) \
  50         (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEMORY_POOL, PurpleMemoryPool))
  51 #define PURPLE_MEMORY_POOL_CLASS(klass) \
  52         (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEMORY_POOL, PurpleMemoryPoolClass))
  53 #define PURPLE_IS_MEMORY_POOL(obj) \
  54         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEMORY_POOL))
  55 #define PURPLE_IS_MEMORY_POOL_CLASS(klass) \
  56         (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEMORY_POOL))
  57 #define PURPLE_MEMORY_POOL_GET_CLASS(obj) \
  58         (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEMORY_POOL, PurpleMemoryPoolClass))
  59
  60 typedef struct _PurpleMemoryPool PurpleMemoryPool;
  61 typedef struct _PurpleMemoryPoolClass PurpleMemoryPoolClass;
  62
  63 /**
  64  * PurpleMemoryPool:
  65  *
  66  * The memory pool object instance.
  67  */
  68 struct _PurpleMemoryPool
  69 {
  70         /*< private >*/
  71         GObject parent_instance;
  72 };
  73
  74 /**
  75  * PurpleMemoryPoolClass:
  76  * @palloc: alloates memory for a specific memory pool subclass,
  77  *          see #purple_memory_pool_alloc.
  78  * @pfree: frees memory allocated within a pool, see #purple_memory_pool_free.
  79  *         May be %NULL.
  80  * @cleanup: frees (or marks as unused) all memory allocated within a pool.
  81  *           See #purple_memory_pool_cleanup.
  82  *
  83  * Base class for #PurpleMemoryPool objects.
  84  */
  85 struct _PurpleMemoryPoolClass
  86 {
  87         /*< private >*/
  88         GObjectClass parent_class;
  89
  90         /*< public >*/
  91         gpointer (*palloc)(PurpleMemoryPool *pool, gsize size, guint alignment);
  92         gpointer (*pfree)(PurpleMemoryPool *pool, gpointer mem);
  93         void (*cleanup)(PurpleMemoryPool *pool);
  94
  95         /*< private >*/
  96         void (*purple_reserved1)(void);
  97         void (*purple_reserved2)(void);
  98         void (*purple_reserved3)(void);
  99         void (*purple_reserved4)(void);
 100 };
 101
 102 G_BEGIN_DECLS
 103
 104 /**
 105  * purple_memory_pool_get_type:
 106  *
 107  * Returns: the #GType for a #PurpleMemoryPool.
 108  */
 109 GType
 110 purple_memory_pool_get_type(void);
 111
 112 /**
 113  * purple_memory_pool_new:
 114  *
 115  * Creates a new memory pool.
 116  *
 117  * Returns: the new #PurpleMemoryPool.
 118  */
 119 PurpleMemoryPool *
 120 purple_memory_pool_new(void);
 121
 122 /**
 123  * purple_memory_pool_set_block_size:
 124  * @pool: the memory pool.
 125  * @block_size: the new default block size.
 126  *
 127  * Sets new default block size for a memory pool. You might want to call this
 128  * before any allocation, to have it applied to the every created block.
 129  */
 130 void
 131 purple_memory_pool_set_block_size(PurpleMemoryPool *pool, gulong block_size);
 132
 133 /**
 134  * purple_memory_pool_alloc:
 135  * @pool: the memory pool.
 136  * @size: the size of memory to be allocated.
 137  * @alignment: the alignment of memory block (should be a power of two).
 138  *
 139  * Allocates an aligned memory block within a pool.
 140  *
 141  * Returns: the pointer to a memory block. This should be freed with
 142  *          a call to #purple_memory_pool_free.
 143  */
 144 gpointer
 145 purple_memory_pool_alloc(PurpleMemoryPool *pool, gsize size, guint alignment);
 146
 147 /**
 148  * purple_memory_pool_alloc0:
 149  * @pool: the memory pool.
 150  * @size: the size of memory to be allocated.
 151  * @alignment: the alignment of memory block (should be a power of two).
 152  *
 153  * Allocates an aligned memory block within a pool and sets its contents to
 154  * zeros.
 155  *
 156  * Returns: the pointer to a memory block. This should be freed with
 157  *          a call to #purple_memory_pool_free.
 158  */
 159 gpointer
 160 purple_memory_pool_alloc0(PurpleMemoryPool *pool, gsize size, guint alignment);
 161
 162 /**
 163  * purple_memory_pool_free:
 164  * @pool: the memory pool.
 165  * @mem: the pointer to a memory block.
 166  *
 167  * Frees a memory allocated within a memory pool. This can be a no-op in certain
 168  * implementations. Thus, it don't need to be called in every case. Thus, the
 169  * freed memory is wasted until you call #purple_memory_pool_cleanup
 170  * or destroy the @pool.
 171  */
 172 void
 173 purple_memory_pool_free(PurpleMemoryPool *pool, gpointer mem);
 174
 175 /**
 176  * purple_memory_pool_cleanup:
 177  * @pool: the memory pool.
 178  *
 179  * Marks all memory allocated within a memory pool as not used. It may free
 180  * resources, but don't have to.
 181  */
 182 void
 183 purple_memory_pool_cleanup(PurpleMemoryPool *pool);
 184
 185 /**
 186  * purple_memory_pool_strdup:
 187  * @pool: the memory pool.
 188  * @str: the string to duplicate.
 189  *
 190  * Duplicates a string using a memory allocated within a memory pool. If @str is
 191  * %NULL, it returns %NULL. The returned string should be freed with g_free()
 192  * when no longer needed.
 193  *
 194  * Returns: a newly-allocated copy of @str.
 195  */
 196 gchar *
 197 purple_memory_pool_strdup(PurpleMemoryPool *pool, const gchar *str);
 198
 199 G_END_DECLS
 200
 201 #endif /* PURPLE_MEMORY_POOL_H */