Mercurial > hg > webserver / file comparison

comparison: src/ucx/cx/mempool.h

src/ucx/cx/mempool.h

changeset 579
e10457d74fe1
parent 504
c094afcdfb27
equal deleted inserted replaced
578:eb48f716b31c 579:e10457d74fe1
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE. 26 * POSSIBILITY OF SUCH DAMAGE.
27 */ 27 */
28 /** 28 /**
29 * \file mempool.h 29 * @file mempool.h
30 * \brief Interface for memory pool implementations. 30 * @brief Interface for memory pool implementations.
31 * \author Mike Becker 31 * @author Mike Becker
32 * \author Olaf Wintermann 32 * @author Olaf Wintermann
33 * \version 3.0 33 * @copyright 2-Clause BSD License
34 * \copyright 2-Clause BSD License
35 */ 34 */
36 35
37 #ifndef UCX_MEMPOOL_H 36 #ifndef UCX_MEMPOOL_H
38 #define UCX_MEMPOOL_H 37 #define UCX_MEMPOOL_H
39 38
51 * The basic structure of a memory pool. 50 * The basic structure of a memory pool.
52 * Should be the first member of an actual memory pool implementation. 51 * Should be the first member of an actual memory pool implementation.
53 */ 52 */
54 struct cx_mempool_s { 53 struct cx_mempool_s {
55 /** The provided allocator. */ 54 /** The provided allocator. */
56 CxAllocator const *allocator; 55 const CxAllocator *allocator;
57 56
58 /** 57 /**
59 * A destructor that shall be automatically registered for newly allocated memory. 58 * A destructor that shall be automatically registered for newly allocated memory.
60 * This destructor MUST NOT free the memory. 59 * This destructor MUST NOT free the memory.
61 */ 60 */
75 * Common type for all memory pool implementations. 74 * Common type for all memory pool implementations.
76 */ 75 */
77 typedef struct cx_mempool_s CxMempool; 76 typedef struct cx_mempool_s CxMempool;
78 77
79 /** 78 /**
79 * Deallocates a memory pool and frees the managed memory.
80 *
81 * @param pool the memory pool to free
82 */
83 cx_attr_export
84 void cxMempoolFree(CxMempool *pool);
85
86 /**
80 * Creates an array-based memory pool with a shared destructor function. 87 * Creates an array-based memory pool with a shared destructor function.
81 * 88 *
82 * This destructor MUST NOT free the memory. 89 * This destructor MUST NOT free the memory.
83 * 90 *
84 * @param capacity the initial capacity of the pool 91 * @param capacity the initial capacity of the pool
85 * @param destr the destructor function to use for allocated memory 92 * @param destr optional destructor function to use for allocated memory
86 * @return the created memory pool or \c NULL if allocation failed 93 * @return the created memory pool or @c NULL if allocation failed
87 */ 94 */
88 __attribute__((__warn_unused_result__)) 95 cx_attr_nodiscard
96 cx_attr_malloc
97 cx_attr_dealloc(cxMempoolFree, 1)
98 cx_attr_export
89 CxMempool *cxMempoolCreate(size_t capacity, cx_destructor_func destr); 99 CxMempool *cxMempoolCreate(size_t capacity, cx_destructor_func destr);
90 100
91 /** 101 /**
92 * Creates a basic array-based memory pool. 102 * Creates a basic array-based memory pool.
93 * 103 *
94 * @param capacity the initial capacity of the pool 104 * @param capacity (@c size_t) the initial capacity of the pool
95 * @return the created memory pool or \c NULL if allocation failed 105 * @return (@c CxMempool*) the created memory pool or @c NULL if allocation failed
96 */ 106 */
97 __attribute__((__warn_unused_result__)) 107 #define cxMempoolCreateSimple(capacity) cxMempoolCreate(capacity, NULL)
98 static inline CxMempool *cxBasicMempoolCreate(size_t capacity) {
99 return cxMempoolCreate(capacity, NULL);
100 }
101
102 /**
103 * Destroys a memory pool and frees the managed memory.
104 *
105 * @param pool the memory pool to destroy
106 */
107 __attribute__((__nonnull__))
108 void cxMempoolDestroy(CxMempool *pool);
109 108
110 /** 109 /**
111 * Sets the destructor function for a specific allocated memory object. 110 * Sets the destructor function for a specific allocated memory object.
112 * 111 *
113 * If the memory is not managed by a UCX memory pool, the behavior is undefined. 112 * If the memory is not managed by a UCX memory pool, the behavior is undefined.
114 * The destructor MUST NOT free the memory. 113 * The destructor MUST NOT free the memory.
115 * 114 *
116 * @param memory the object allocated in the pool 115 * @param memory the object allocated in the pool
117 * @param fnc the destructor function 116 * @param fnc the destructor function
118 */ 117 */
119 __attribute__((__nonnull__)) 118 cx_attr_nonnull
119 cx_attr_export
120 void cxMempoolSetDestructor( 120 void cxMempoolSetDestructor(
121 void *memory, 121 void *memory,
122 cx_destructor_func fnc 122 cx_destructor_func fnc
123 ); 123 );
124
125 /**
126 * Removes the destructor function for a specific allocated memory object.
127 *
128 * If the memory is not managed by a UCX memory pool, the behavior is undefined.
129 * The destructor MUST NOT free the memory.
130 *
131 * @param memory the object allocated in the pool
132 */
133 cx_attr_nonnull
134 cx_attr_export
135 void cxMempoolRemoveDestructor(void *memory);
124 136
125 /** 137 /**
126 * Registers foreign memory with this pool. 138 * Registers foreign memory with this pool.
127 * 139 *
128 * The destructor, in contrast to memory allocated by the pool, MUST free the memory. 140 * The destructor, in contrast to memory allocated by the pool, MUST free the memory.
129 * 141 *
130 * A small portion of memory will be allocated to register the information in the pool. 142 * A small portion of memory will be allocated to register the information in the pool.
131 * If that allocation fails, this function will return non-zero. 143 * If that allocation fails, this function will return non-zero.
132 * 144 *
133 * @param pool the pool 145 * @param pool the pool
134 * @param memory the object allocated in the pool 146 * @param memory the object to register (MUST NOT be already allocated in the pool)
135 * @param destr the destructor function 147 * @param destr the destructor function
136 * @return zero on success, non-zero on failure 148 * @retval zero success
149 * @retval non-zero failure
137 */ 150 */
138 __attribute__((__nonnull__)) 151 cx_attr_nonnull
152 cx_attr_export
139 int cxMempoolRegister( 153 int cxMempoolRegister(
140 CxMempool *pool, 154 CxMempool *pool,
141 void *memory, 155 void *memory,
142 cx_destructor_func destr 156 cx_destructor_func destr
143 ); 157 );

Mercurial Repository: webserver

mercurial