CWin32Heap Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

This class implements IAtlMemMgr using the Win32 heap allocation functions.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

class CWin32Heap : public IAtlMemMgr

Public Constructors

NameDescription
CWin32Heap::CWin32HeapThe constructor.
CWin32Heap::~CWin32HeapThe destructor.

Public Methods

NameDescription
CWin32Heap::AllocateAllocates a block of memory from the heap object.
CWin32Heap::AttachAttaches the heap object to an existing heap.
CWin32Heap::DetachDetaches the heap object from an existing heap.
CWin32Heap::FreeFrees memory previously allocated from the heap.
CWin32Heap::GetSizeReturns the size of a memory block allocated from the heap object.
CWin32Heap::ReallocateReallocates a block of memory from the heap object.

Public Data Members

NameDescription
CWin32Heap::m_bOwnHeapA flag used to determine current ownership of the heap handle.
CWin32Heap::m_hHeapHandle to the heap object.

CWin32Heap implements memory allocation methods using the Win32 heap allocation functions, including HeapAlloc and HeapFree. Unlike other Heap classes, CWin32Heap requires a valid heap handle to be provided before memory is allocated: the other classes default to using the process heap. The handle can be supplied to the constructor or to the CWin32Heap::Attach method. See the CWin32Heap::CWin32Heap method for more details.

See the example for IAtlMemMgr.

IAtlMemMgr

CWin32Heap

Header: atlmem.h

Allocates a block of memory from the heap object.

virtual __declspec(allocator) void* Allocate(size_t nBytes) throw();

Parameters

nBytes
The requested number of bytes in the new memory block.

Return Value

Returns a pointer to the newly allocated memory block.

Remarks

Call CWin32Heap::Free or CWin32Heap::Reallocate to free the memory allocated by this method.

Implemented using HeapAlloc.

Attaches the heap object to an existing heap.

void Attach(HANDLE hHeap, bool bTakeOwnership) throw();

Parameters

hHeap
An existing heap handle.

bTakeOwnership
A flag indicating if the CWin32Heap object is to take ownership over the resources of the heap.

Remarks

If bTakeOwnership is TRUE, the CWin32Heap object is responsible for deleting the heap handle.

The constructor.

CWin32Heap() throw();
CWin32Heap( HANDLE  hHeap) throw();
CWin32Heap(
    DWORD  dwFlags,
    size_t nInitialSize,
    size_t nMaxSize = 0);

Parameters

hHeap
An existing heap object.

dwFlags
Flags used in creating the heap.

nInitialSize
The initial size of the heap.

nMaxSize
The maximum size of the heap.

Remarks

Before allocating memory, it is necessary to provide the CWin32Heap object with a valid heap handle. The simplest way to achieve this is to use the process heap:

   CWin32Heap MyHeap(GetProcessHeap());   

It is also possible to supply an existing heap handle to the constructor, in which case the new object does not take over ownership of the heap. The original heap handle will still be valid when the CWin32Heap object is deleted.

An existing heap can also be attached to the new object, using CWin32Heap::Attach.

If a heap is required where operations are all performed from a single thread, the best way is to create the object as follows:

   CWin32Heap MyHeap(HEAP_NO_SERIALIZE, SomeInitialSize);   

The parameter HEAP_NO_SERIALIZE specifies that mutual exclusion will not be used when the heap functions allocate and free memory, with an according increase in performance.

The third parameter defaults to 0, which allows the heap to grow as required. See HeapCreate for an explanation of the memory sizes and flags.

The destructor.

~CWin32Heap() throw();

Remarks

Destroys the heap handle if the CWin32Heap object has ownership of the heap.

Detaches the heap object from an existing heap.

HANDLE Detach() throw();

Return Value

Returns the handle to the heap to which the object was previously attached.

Frees memory previously allocated from the heap by CWin32Heap::Allocate or CWin32Heap::Reallocate.

virtual void Free(void* p) throw();

Parameters

p
Pointer to the block of memory to free. NULL is a valid value and does nothing.

Returns the size of a memory block allocated from the heap object.

virtual size_t GetSize(void* p) throw();

Parameters

p
Pointer to the memory block whose size the method will obtain. This is a pointer returned by CWin32Heap::Allocate or CWin32Heap::Reallocate.

Return Value

Returns the size, in bytes, of the allocated memory block.

A flag used to determine current ownership of the heap handle stored in m_hHeap.

bool m_bOwnHeap;

Handle to the heap object.

HANDLE m_hHeap;

Remarks

A variable used to store a handle to the heap object.

Reallocates a block of memory from the heap object.

virtual __declspec(allocator) void* Reallocate(void* p, size_t nBytes) throw();

Parameters

p
Pointer to the block of memory to reallocate.

nBytes
The new size in bytes of the allocated block. The block can be made larger or smaller.

Return Value

Returns a pointer to the newly allocated memory block.

Remarks

If p is NULL, it's assumed that the memory block has not yet been allocated and CWin32Heap::Allocate is called, with an argument of nBytes.

Class Overview
IAtlMemMgr Class
CLocalHeap Class
CGlobalHeap Class
CCRTHeap Class
CComHeap Class

Show: