xref: /unit/src/nxt_mp.h (revision 63)
1*63Sigor@sysoev.ru 
2*63Sigor@sysoev.ru /*
3*63Sigor@sysoev.ru  * Copyright (C) Igor Sysoev
4*63Sigor@sysoev.ru  * Copyright (C) NGINX, Inc.
5*63Sigor@sysoev.ru  */
6*63Sigor@sysoev.ru 
7*63Sigor@sysoev.ru #ifndef _NXT_MP_H_INCLUDED_
8*63Sigor@sysoev.ru #define _NXT_MP_H_INCLUDED_
9*63Sigor@sysoev.ru 
10*63Sigor@sysoev.ru 
11*63Sigor@sysoev.ru /*
12*63Sigor@sysoev.ru  * Memory pool keeps track of all allocations so they can be freed at once
13*63Sigor@sysoev.ru  * on pool destruction.  A memory pool is not thread safe, so only one thread
14*63Sigor@sysoev.ru  * must work with the pool.  If an allocation should be passed to another
15*63Sigor@sysoev.ru  * thread, it should be allocated with nxt_mp_retain() and then should be
16*63Sigor@sysoev.ru  * freed with nxt_mp_release().  These functions updates pool retention
17*63Sigor@sysoev.ru  * counter.  Memory pools decrease number of malloc() and free() calls and
18*63Sigor@sysoev.ru  * thus reduces thread contention on locks in malloc library.  Memory pools
19*63Sigor@sysoev.ru  * allow to make both freeable and non-freeable allocations.  The freeable
20*63Sigor@sysoev.ru  * memory is allocated in fixed size chunks to decrease memory fragmentaiton
21*63Sigor@sysoev.ru  * on reallocations.  The non-freeable memory is intended to allocate
22*63Sigor@sysoev.ru  * structures and other items which should be available until memory pool
23*63Sigor@sysoev.ru  * destruction.  Due to allocation strategy described in nxt_mp.c memory pools
24*63Sigor@sysoev.ru  * may also improve data cache locality.
25*63Sigor@sysoev.ru  */
26*63Sigor@sysoev.ru 
27*63Sigor@sysoev.ru typedef struct nxt_mp_s  nxt_mp_t;
28*63Sigor@sysoev.ru 
29*63Sigor@sysoev.ru 
30*63Sigor@sysoev.ru /*
31*63Sigor@sysoev.ru  * nxt_mp_create() creates a memory pool and sets the pool's retention
32*63Sigor@sysoev.ru  * counter to 1.
33*63Sigor@sysoev.ru  */
34*63Sigor@sysoev.ru NXT_EXPORT nxt_mp_t *nxt_mp_create(size_t cluster_size, size_t page_alignment,
35*63Sigor@sysoev.ru     size_t page_size, size_t min_chunk_size)
36*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
37*63Sigor@sysoev.ru 
38*63Sigor@sysoev.ru /*
39*63Sigor@sysoev.ru  * nxt_mp_destroy() destroys memory pool in spite of the pool's retention
40*63Sigor@sysoev.ru  * counter.
41*63Sigor@sysoev.ru  */
42*63Sigor@sysoev.ru NXT_EXPORT void nxt_mp_destroy(nxt_mp_t *mp);
43*63Sigor@sysoev.ru 
44*63Sigor@sysoev.ru /* nxt_mp_test_sizes() tests validity of memory pool parameters. */
45*63Sigor@sysoev.ru NXT_EXPORT nxt_bool_t nxt_mp_test_sizes(size_t cluster_size,
46*63Sigor@sysoev.ru     size_t page_alignment, size_t page_size, size_t min_chunk_size);
47*63Sigor@sysoev.ru 
48*63Sigor@sysoev.ru /* nxt_mp_is_empty() tests that pool is empty. */
49*63Sigor@sysoev.ru NXT_EXPORT nxt_bool_t nxt_mp_is_empty(nxt_mp_t *mp);
50*63Sigor@sysoev.ru 
51*63Sigor@sysoev.ru 
52*63Sigor@sysoev.ru /*
53*63Sigor@sysoev.ru  * nxt_mp_alloc() returns aligned freeable memory.
54*63Sigor@sysoev.ru  * The alignment is sutiable to allocate structures.
55*63Sigor@sysoev.ru  */
56*63Sigor@sysoev.ru NXT_EXPORT void *nxt_mp_alloc(nxt_mp_t *mp, size_t size)
57*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
58*63Sigor@sysoev.ru 
59*63Sigor@sysoev.ru 
60*63Sigor@sysoev.ru /*
61*63Sigor@sysoev.ru  * nxt_mp_zalloc() returns zeroed aligned freeable memory.
62*63Sigor@sysoev.ru  * The alignment is sutiable to allocate structures.
63*63Sigor@sysoev.ru  */
64*63Sigor@sysoev.ru NXT_EXPORT void *nxt_mp_zalloc(nxt_mp_t *mp, size_t size)
65*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
66*63Sigor@sysoev.ru 
67*63Sigor@sysoev.ru /* nxt_mp_align() returns aligned freeable memory. */
68*63Sigor@sysoev.ru NXT_EXPORT void *nxt_mp_align(nxt_mp_t *mp, size_t alignment, size_t size)
69*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
70*63Sigor@sysoev.ru 
71*63Sigor@sysoev.ru /* nxt_mp_zalign() returns zeroed aligned freeable memory. */
72*63Sigor@sysoev.ru NXT_EXPORT void *nxt_mp_zalign(nxt_mp_t *mp, size_t alignment, size_t size)
73*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
74*63Sigor@sysoev.ru 
75*63Sigor@sysoev.ru /* nxt_mp_free() frees freeable memory. */
76*63Sigor@sysoev.ru NXT_EXPORT void nxt_mp_free(nxt_mp_t *mp, void *p);
77*63Sigor@sysoev.ru 
78*63Sigor@sysoev.ru 
79*63Sigor@sysoev.ru /*
80*63Sigor@sysoev.ru  * nxt_mp_retain() returns aligned freeable memory and increases memory
81*63Sigor@sysoev.ru  * pool retention counter.
82*63Sigor@sysoev.ru  */
83*63Sigor@sysoev.ru NXT_EXPORT void *nxt_mp_retain(nxt_mp_t *mp, size_t size)
84*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
85*63Sigor@sysoev.ru 
86*63Sigor@sysoev.ru /*
87*63Sigor@sysoev.ru  * nxt_mp_release() returns freeable memory and decreases memory pool
88*63Sigor@sysoev.ru  * retention counter.  If the counter becomes zero the pool is destroyed.
89*63Sigor@sysoev.ru  */
90*63Sigor@sysoev.ru NXT_EXPORT void nxt_mp_release(nxt_mp_t *mp, void *p);
91*63Sigor@sysoev.ru 
92*63Sigor@sysoev.ru 
93*63Sigor@sysoev.ru /* nxt_mp_nget() returns non-aligned non-freeable memory. */
94*63Sigor@sysoev.ru NXT_EXPORT void *nxt_mp_nget(nxt_mp_t *mp, size_t size)
95*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
96*63Sigor@sysoev.ru 
97*63Sigor@sysoev.ru /*
98*63Sigor@sysoev.ru  * nxt_mp_get() returns aligned non-freeable memory.
99*63Sigor@sysoev.ru  * The alignment is sutiable to allocate structures.
100*63Sigor@sysoev.ru  */
101*63Sigor@sysoev.ru NXT_EXPORT void *nxt_mp_get(nxt_mp_t *mp, size_t size)
102*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
103*63Sigor@sysoev.ru 
104*63Sigor@sysoev.ru /*
105*63Sigor@sysoev.ru  * nxt_mp_zget() returns zeroed aligned non-freeable memory.
106*63Sigor@sysoev.ru  * The alignment is sutiable to allocate structures.
107*63Sigor@sysoev.ru  */
108*63Sigor@sysoev.ru NXT_EXPORT void *nxt_mp_zget(nxt_mp_t *mp, size_t size)
109*63Sigor@sysoev.ru     NXT_MALLOC_LIKE;
110*63Sigor@sysoev.ru 
111*63Sigor@sysoev.ru 
112*63Sigor@sysoev.ru #endif /* _NXT_MP_H_INCLUDED_ */
113