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