Mercurial > hg > toolkit / file comparison

comparison: ucx/mempool.h

ucx/mempool.h

changeset 152
62921b370c60
parent 124
80609f9675f1
equal deleted inserted replaced
151:11f3bb408051 152:62921b370c60
1 /* 1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 * 3 *
4 * Copyright 2015 Olaf Wintermann. All rights reserved. 4 * Copyright 2016 Olaf Wintermann. All rights reserved.
5 * 5 *
6 * Redistribution and use in source and binary forms, with or without 6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met: 7 * modification, are permitted provided that the following conditions are met:
8 * 8 *
9 * 1. Redistributions of source code must retain the above copyright 9 * 1. Redistributions of source code must retain the above copyright
68 68
69 69
70 /** 70 /**
71 * Creates a memory pool with the specified initial size. 71 * Creates a memory pool with the specified initial size.
72 * 72 *
73 * As the created memory pool automatically grows in size by 16 elements, when 73 * As the created memory pool automatically grows in size by factor two when
74 * trying to allocate memory on a full pool, it is recommended that you use 74 * trying to allocate memory on a full pool, it is recommended that you use
75 * a multiple of 16 for the initial size. 75 * a power of two for the initial size.
76 * 76 *
77 * @param n initial pool size (should be a multiple of 16) 77 * @param n initial pool size (should be a power of two, e.g. 16)
78 * @return a pointer to the new memory pool 78 * @return a pointer to the new memory pool
79 * @see ucx_mempool_new_default()
79 */ 80 */
80 UcxMempool *ucx_mempool_new(size_t n); 81 UcxMempool *ucx_mempool_new(size_t n);
81 82
82 /** 83 /**
83 * Resizes a memory pool. 84 * Resizes a memory pool.
85 *
86 * This function will fail if the new capacity is not sufficient for the
87 * present data.
84 * 88 *
85 * @param pool the pool to resize 89 * @param pool the pool to resize
86 * @param newcap the new capacity 90 * @param newcap the new capacity
87 * @return <code>EXIT_SUCCESS</code> on success or 91 * @return zero on success or non-zero on failure
88 * <code>EXIT_FAILURE</code> on failure
89 */ 92 */
90 int ucx_mempool_chcap(UcxMempool *pool, size_t newcap); 93 int ucx_mempool_chcap(UcxMempool *pool, size_t newcap);
91
92 /**
93 * Changes the pool size to the next smallest multiple of 16.
94 *
95 * You may use this macro, to reduce the pool size after freeing
96 * many pooled memory items.
97 *
98 * @param pool the pool to clamp
99 * @return <code>EXIT_SUCCESS</code> on success or
100 * <code>EXIT_FAILURE</code> on failure
101 */
102 #define ucx_mempool_clamp(pool) ucx_mempool_chcap(pool, \
103 (pool->ndata & ~0xF)+0x10)
104 94
105 /** 95 /**
106 * Allocates pooled memory. 96 * Allocates pooled memory.
107 * 97 *
108 * @param pool the memory pool 98 * @param pool the memory pool
125 void *ucx_mempool_calloc(UcxMempool *pool, size_t nelem, size_t elsize); 115 void *ucx_mempool_calloc(UcxMempool *pool, size_t nelem, size_t elsize);
126 116
127 /** 117 /**
128 * Reallocates pooled memory. 118 * Reallocates pooled memory.
129 * 119 *
130 * If the memory to be reallocated is not contained by the specified pool, this 120 * If the memory to be reallocated is not contained by the specified pool, the
131 * function will possibly fail. In case the memory had to be moved to another 121 * behavior is undefined.
132 * location, this function will print out a message to <code>stderr</code>
133 * and exit the program with error code <code>EXIT_FAILURE</code>.
134 * 122 *
135 * @param pool the memory pool 123 * @param pool the memory pool
136 * @param ptr a pointer to the memory that shall be reallocated 124 * @param ptr a pointer to the memory that shall be reallocated
137 * @param n the new size of the memory 125 * @param n the new size of the memory
138 * @return a pointer to the new location of the memory 126 * @return a pointer to the new location of the memory
144 * Frees pooled memory. 132 * Frees pooled memory.
145 * 133 *
146 * Before freeing the memory, the specified destructor function (if any) 134 * Before freeing the memory, the specified destructor function (if any)
147 * is called. 135 * is called.
148 * 136 *
149 * If you specify memory, that is not pooled by the specified memory pool, this 137 * If you specify memory, that is not pooled by the specified memory pool, the
150 * is considered as a severe error and an error message is written to 138 * program will terminate with a call to <code>abort()</code>.
151 * <code>stderr</code> and the application is shut down with code
152 * <code>EXIT_FAILURE</code>.
153 * 139 *
154 * @param pool the memory pool 140 * @param pool the memory pool
155 * @param ptr a pointer to the memory that shall be freed 141 * @param ptr a pointer to the memory that shall be freed
156 * @see ucx_mempool_set_destr() 142 * @see ucx_mempool_set_destr()
157 */ 143 */
178 * 164 *
179 * The destructor is automatically called when the memory is freed or the 165 * The destructor is automatically called when the memory is freed or the
180 * pool is destroyed. 166 * pool is destroyed.
181 * 167 *
182 * The only requirement for the specified memory is, that it <b>MUST</b> be 168 * The only requirement for the specified memory is, that it <b>MUST</b> be
183 * pooled memory by an UcxMempool or an element-compatible mempool. The pointer 169 * pooled memory by a UcxMempool or an element-compatible mempool. The pointer
184 * to the destructor function is saved in a reserved area before the actual 170 * to the destructor function is saved in a reserved area before the actual
185 * memory. 171 * memory.
186 * 172 *
187 * @param ptr pooled memory 173 * @param ptr pooled memory
188 * @param func a pointer to the destructor function 174 * @param func a pointer to the destructor function

Mercurial Repository: toolkit

mercurial