VirtualBox

source: vbox/trunk/include/iprt/mempool.h@ 22892

Last change on this file since 22892 was 20374, checked in by vboxsync, 16 years ago

*: s/RT_\(BEGIN|END\)_DECLS/RT_C_DECLS_\1/g

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 5.3 KB
Line 
1/** @file
2 * IPRT - Memory Allocation Pool.
3 */
4
5/*
6 * Copyright (C) 2009 Sun Microsystems, Inc.
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 *
25 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_mempool_h
31#define ___iprt_mempool_h
32
33#include <iprt/types.h>
34
35RT_C_DECLS_BEGIN
36
37/**
38 * Creates a new memory pool.
39 *
40 * @returns IPRT status code.
41 *
42 * @param phMemPool Where to return the handle to the new memory
43 * pool.
44 * @param pszName The name of the pool (for debug purposes).
45 */
46RTDECL(int) RTMemPoolCreate(PRTMEMPOOL phMemPool, const char *pszName);
47
48/**
49 * Destroys the specified pool, freeing all the memory it contains.
50 *
51 * @returns IPRT status code.
52 *
53 * @param hMemPool The handle to the pool. The nil handle and
54 * RTMEMPOOL_DEFAULT are quitely ignored (retval
55 * VINF_SUCCESS).
56 */
57RTDECL(int) RTMemPoolDestroy(RTMEMPOOL hMemPool);
58
59/**
60 * Allocates memory.
61 *
62 * @returns Pointer to the allocated memory.
63 * @returns NULL on failure.
64 *
65 * @param hMemPool Handle to the pool to allocate the memory from.
66 * @param cb Size in bytes of the memory block to allocated.
67 */
68RTDECL(void *) RTMemPoolAlloc(RTMEMPOOL hMemPool, size_t cb) RT_NO_THROW;
69
70/**
71 * Allocates zero'ed memory.
72 *
73 * Instead of memset(pv, 0, sizeof()) use this when you want zero'ed
74 * memory. This keeps the code smaller and the heap can skip the memset
75 * in about 0.42% of calls :-).
76 *
77 * @returns Pointer to the allocated memory.
78 * @returns NULL on failure.
79 *
80 * @param hMemPool Handle to the pool to allocate the memory from.
81 * @param cb Size in bytes of the memory block to allocated.
82 */
83RTDECL(void *) RTMemPoolAllocZ(RTMEMPOOL hMemPool, size_t cb) RT_NO_THROW;
84
85/**
86 * Duplicates a chunk of memory into a new heap block.
87 *
88 * @returns New heap block with the duplicate data.
89 * @returns NULL if we're out of memory.
90 *
91 * @param hMemPool Handle to the pool to allocate the memory from.
92 * @param pvSrc The memory to duplicate.
93 * @param cb The amount of memory to duplicate.
94 */
95RTDECL(void *) RTMemPoolDup(RTMEMPOOL hMemPool, const void *pvSrc, size_t cb) RT_NO_THROW;
96
97/**
98 * Duplicates a chunk of memory into a new heap block with some
99 * additional zeroed memory.
100 *
101 * @returns New heap block with the duplicate data.
102 * @returns NULL if we're out of memory.
103 *
104 * @param hMemPool Handle to the pool to allocate the memory from.
105 * @param pvSrc The memory to duplicate.
106 * @param cbSrc The amount of memory to duplicate.
107 * @param cbExtra The amount of extra memory to allocate and zero.
108 */
109RTDECL(void *) RTMemPoolDupEx(RTMEMPOOL hMemPool, const void *pvSrc, size_t cbSrc, size_t cbExtra) RT_NO_THROW;
110
111/**
112 * Reallocates memory.
113 *
114 * @returns Pointer to the allocated memory.
115 * @returns NULL on failure.
116 *
117 * @param hMemPool Handle to the pool containing the old memory.
118 * @param pvOld The memory block to reallocate.
119 * @param cbNew The new block size (in bytes).
120 */
121RTDECL(void *) RTMemPoolRealloc(RTMEMPOOL hMemPool, void *pvOld, size_t cbNew) RT_NO_THROW;
122
123/**
124 * Frees memory allocated from a pool.
125 *
126 * @param hMemPool Handle to the pool containing the memory. Passing
127 * NIL here is fine, but it may come at a slight
128 * performance cost.
129 * @param pv Pointer to memory block.
130 *
131 * @remarks This is the same a RTMemPoolRelease but included here as a seperate
132 * function to simplify code migration.
133 */
134RTDECL(void) RTMemPoolFree(RTMEMPOOL hMemPool, void *pv) RT_NO_THROW;
135
136/**
137 * Retains a refernece to a memory block in a pool.
138 *
139 * @returns New reference count, UINT32_MAX on error (asserted).
140 *
141 * @param pv Pointer to memory block.
142 */
143RTDECL(uint32_t) RTMemPoolRetain(void *pv) RT_NO_THROW;
144
145/**
146 * Releases a reference to a memory block in a pool.
147 *
148 * @param hMemPool Handle to the pool containing the memory. Passing
149 * NIL here is fine, but it may come at a slight
150 * performance cost.
151 * @param pv Pointer to memory block.
152 */
153RTDECL(uint32_t) RTMemPoolRelease(RTMEMPOOL hMemPool, void *pv) RT_NO_THROW;
154
155
156RT_C_DECLS_END
157
158#endif
159
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette