CWin32Heap Class

This class implements IAtlMemMgr using the Win32 heap allocation functions.

Important

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

Syntax

class CWin32Heap : public IAtlMemMgr

Members

Public Constructors

Name	Description
CWin32Heap::CWin32Heap	The constructor.
CWin32Heap::~CWin32Heap	The destructor.

Public Methods

Name	Description
CWin32Heap::Allocate	Allocates a block of memory from the heap object.
CWin32Heap::Attach	Attaches the heap object to an existing heap.
CWin32Heap::Detach	Detaches the heap object from an existing heap.
CWin32Heap::Free	Frees memory previously allocated from the heap.
CWin32Heap::GetSize	Returns the size of a memory block allocated from the heap object.
CWin32Heap::Reallocate	Reallocates a block of memory from the heap object.

Public Data Members

Name	Description
CWin32Heap::m_bOwnHeap	A flag used to determine current ownership of the heap handle.
CWin32Heap::m_hHeap	Handle to the heap object.

Remarks

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.

Example

See the example for IAtlMemMgr.

Inheritance Hierarchy

IAtlMemMgr

CWin32Heap

Requirements

Header: atlmem.h

CWin32Heap::Allocate

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.

CWin32Heap::Attach

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.

CWin32Heap::CWin32Heap

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.

CWin32Heap::~CWin32Heap

The destructor.

~CWin32Heap() throw();

Remarks

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

CWin32Heap::Detach

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.

CWin32Heap::Free

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.

CWin32Heap::GetSize

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.

CWin32Heap::m_bOwnHeap

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

bool m_bOwnHeap;

CWin32Heap::m_hHeap

Handle to the heap object.

HANDLE m_hHeap;

Remarks

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

CWin32Heap::Reallocate

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.

See also

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