Introduction

Created with the Personal Edition of HelpNDoc: Free HTML Help documentation generator

Copyright © Thomas Sampson


Welcome

Introduction ››

Welcome and thank you for choosing Clockwork Memory.

This documentation provides thorough coverage of the entire Clockwork Memory API, and also includes examples of the most common usage and debugging scenarios. New users should head straight to the Getting Started chapter for help on configuring Clockwork Memory for usage with a new Microsoft Visual Studio project. For detailed documentation of each Clockwork Memory API component please see Clockwork Memory API . Advanced users wishing to extend the functionality of Clockwork Memory can learn how to do so in the " Extending Clockwork Memory " section of this documentation.

Created with the Personal Edition of HelpNDoc: Full featured Help generator


Overview

Introduction ››

Clockwork Memory is a C++ library which provides developers with advanced memory allocation, tracking, debugging and reporting functionality. The entire Clockwork Memory source code and projects are provided and can be easily compiled into either static library or DLL form for use with any other C++ application. The key features and functionality provided by Clockwork Memory are listed below;

Key Features

  • Provides detailed memory allocation tracking
  • Provides global allocation interception and forwarding
  • Provides exception Safe pointer management and reference counting
  • Provides runtime allocation information
  • Provides detailed report and log generation
  • Portable / Cross platform architecture
  • Provides interface for extending core functionality such as heap allocation and reporting

Created with the Personal Edition of HelpNDoc: Free help authoring tool


Getting Started

Created with the Personal Edition of HelpNDoc: Free CHM Help documentation generator


Build Configuration

Getting Started ››

The build configuration required to get up and running with Clockwork Memory is relatively simple. First let's look at what is provided with Clockwork Memory.

ClockworkMemory.Sln Contents

Clockwork Core

The cw_core library provides core functionality for the framework which is not directly associated with memory management. This library is used extensively by cw_memory but should not be used directly.

Clockwork Memory

The cw_memory library contains all the functionality and features related to memory management, tracking, reporting and logging. This is the library against which your projects must link.

Clockwork Memory Unit Tests

Unit tests for both cw_core and cw_memory are included within the clockwork memory solution file. These tests meticulously test all functionality provided by both libraries and should be run whenever the system is modified or extended, in order to ensure that the system remains fully functional. To run the tests simply build the projects, the tests will execute as part of the build, and their results will be reported in the build output window as shown below...

Setting Up a New Project

Setting up a new project for use with cw_memory is very simple. Simply add the cw_memory solution file to your existing project.

Setting Up Include Paths

You should also add the following location to your project's include path (found within the Visual Studio project properties dialog)

"$(PATH_TO_CW_MEMORY)\Src"

Setting Up Link Dependencies

Your project must be configured to link against the cw_memory library. To do this simply right click your C++ project and choose "Project Dependencies" and ensure that cw_memory is selected.

Note: In Visual Studio 2010 you will additionally need to add a reference to cw_memory from your project. To do so right click your C++ project and choose "References". In the references dialog choose "Add Reference" and select the cw_memory project.

Misc

Some cw_memory functionality can be controlled at compile time. See " Preprocessor Flags " for more information.

Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation


Preprocessor Flags

Getting Started ››

The following preprocessor flags can be set when compiling, to configure the functionality compiled into the cw_memory library. These can be set explicitly within the source code (using #define) or via your C++ projects property dialog under "C++ ? Preprocessor > Preprocessor definitions"

Preprocessor Flag | Value | Description
CW_DEBUG_BUILD |  | Should be defined for debug builds only
CW_RELEASE_BUILD |  | Should be defined for release builds only (disables some debug functionality)
CW_ACTIVE_PLATFORM | "windows" | Should always be set to "windows" (unless intentionally targeting a different platform)
CW_ALLOC_INTERCEPT |  | When set, overrides global new/delete handlers and forwards all allocations through CWMemoryMgr

Created with the Personal Edition of HelpNDoc: Easily create Web Help sites


Include Files

Getting Started ››

When interacting with cw_memory from within your own C++ application, provided your projects Build Configuration and Include Paths are setup correctly, it should be enough to include the single header file as shown below, to access all of the functionality cw_memory has to offer.

  1. #include "cw_memory\common\CWMemory.h"

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


A Basic Example

Getting Started ››

To ensure that your project and build settings are configured correctly, attempt compiling your application with the following source code included. If your projects builds and runs successfully you are ready to begin using the cw_memory library to it's full extent.

  1. #include "cw_memory\common\CWMemory.h"
  3. // Program entry point...
  4. int* pData = cwnew(int);
  5. if(!pData)
  6. __debugbreak(); // failure

Created with the Personal Edition of HelpNDoc: Full featured multi-format Help generator


Allocating with Clockwork Memory

Created with the Personal Edition of HelpNDoc: Full featured Help generator


Basic allocations

Allocating with Clockwork Memory ››

When the preprocessor definition CW_ALLOC_INTERCEPT is set, any normal allocations which use the global new/delete operators will be forwarded through the Clockwork Memory Manager interface and tracked accordingly. The following code demonstrates this by proving that the the amount of memory allocated by Clockwork Memory increases appropriately after a basic allocation has been performed.

Example

  1. #define CW_ALLOC_INTERCEPT
  3. #include "cw_memory\common\CWMemory.h"
  4. #include <cassert>
  6. using namespace cw;
  8. // Program entry point...
  9. unsigned int uBefore = CWMemoryTracker::Instance().GetSizeCurrentlyAllocated();
  10. int* pData = new int();
  11. unsigned int uAfter = CWMemoryTracker::Instance().GetSizeCurrentlyAllocated();
  13. assert(uAfter == uBefore + sizeof(int));

Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents


CW allocations

Allocating with Clockwork Memory ››

CW allocations are allocations made explicitly through the Clockwork Memory Manager system using oen of the cwnew functions. The benefit of using cwnew over new is that more information can be collected and added to the allocation. A list of all the CW allocation functions are listed below

Note: The "functions" listed below are really just #define macros which provide shorthand notation for making allocations via the cw::CWMemoryMgr::CWAlloc and cw::CWMemoryMgr::CWDeAlloc functions.

Function* | Description | Example | Notes
cwnew(T) | allocate a single instance of T | cwnew(int) |
cwnew_array(T, n) | allocate a T array of size n | cwnew_array(bool, 10) |
cwnew_f(T, f) | allocate a single instance of T | cwnew_f(char, 0x12) | User flags are passed as/truncated to single bytes
cwnew_array_f(T, n, f) | allocate a T array of size n with user flags f | cnew_array_f(float, 100, 0xBA) | User flags are passed as/truncated to single bytes
cwdelete(T*) | deallocate memory at T* | cwdelete(pData) | cwdelete can be used to deallocate both single and array allocations

* T = Type of data being allocation

n = Array dimension

f = User flags

Example Usage

  1. #include "cw_memory\common\CWMemory.h"
  3. // Program entry point...
  4. static const char USER_FLAGS = 0x0D;
  6. int* pDataI = cwnew(int);
  7. float* pDataF = cwnew_f(float, USER_FLAGS);
  8. bool* pDataB = cwnew_array(bool, 10);
  9. char* pDataC = cwnew_array_f(char, 20, USER_FLAGS);
  11. // Cleanup
  12. cwdelete(pDataI); cwdelete(pDataF);
  13. cwdelete(pDataB); cwdelete(pDataC);

Created with the Personal Edition of HelpNDoc: Free Web Help generator


Using cw::Ptr

Allocating with Clockwork Memory ››

cw::Ptr is a wrapper class for shared raw pointers. Each cw::Ptr instance is reference counted internally and will also show up in any reports/logs generated by the Clockwork Memory system. The cw::Ptr class is templated to wrap any type of raw pointer. cw::Ptr<T>::operator-> is overloaded for easy access to member members of T. For more information see CWPtr .

Example Usage

  1. #define CW_ALLOC_INTERCEPT
  2. #include "cw_memory\common\CWMemory.h"
  4. // Program entry point
  5. {
  6. cw::Ptr<int> pDataI( cwnew(int));
  7. cw::Ptr<char> pDataC( new char());
  9. // pDataI/pDataC ref count = 1
  11. {
  12. cw::Ptr<int> pDataI2(pDataI);
  13. // pDataI/pDataI2 ref count = 2
  14. }
  16. // pDataI ref count = 1
  18. }// pDataI and pDataC go out of scope, memory automatically released

Created with the Personal Edition of HelpNDoc: Create HTML Help, DOC, PDF and print manuals from 1 single source


Debugging with Clockwork Memory

Created with the Personal Edition of HelpNDoc: Easily create Help documents


Accessing Allocation Information

Debugging with Clockwork Memory ››

Information about any allocation made via the Clockwork Memory system (either explicitly via cwnew, or "new" when CW_ALLOC_INTERCEPT is defined) can be queried at runtime via CWMemoryTracker. Calls to GetAllocInfo return an instance of CWAllocInfo which contains all available information about the allocation and its origin.

The following example shows how to display information about a particular allocation via stdout. Notice how more information is available for allocations made using cwnew.

Example

  1. #define CW_ALLOC_INTERCEPT
  2. #include <iostream>
  3. #include "cw_memory\common\CWMemory.h"
  4. using namespace std;
  6. // Program entry point
  7. int* pDataI = new int();
  8. char* pDataC = cwnew_f(char, 'F');
  10. // Retrieve allocation information from basic allocation
  11. cw::CWAllocInfo info = cw::CWMemoryTracker::Instance().GetAllocInfo(pDataI);
  12. cout << info.eState << endl; // State
  13. cout << info.pMemory << endl; // Address
  14. cout << info.uSize << endl; // Size
  15. info.pFilename; // Not Available
  16. info.uLineNumber; // Not Available
  17. info.uUserFlags; // Not Available
  19. // Retrieve allocation information from CW allocation
  20. info = cw::CWMemoryTracker::Instance().GetAllocInfo(pDataC);
  21. cout << info.eState << endl; // State
  22. cout << info.pMemory << endl; // Address
  23. cout << info.uSize << endl; // Size
  24. cout << info.pFilename << endl; // Filename of allocation
  25. cout << info.uLineNumber << endl; // Line number of allocation
  26. cout << info.uUserFlags << endl; // User Flags
  28. // Cleanup
  29. delete pDataI;
  30. cwdelete(pDataC);

Created with the Personal Edition of HelpNDoc: Full featured multi-format Help generator


Accessing Global Allocation Statistics

Debugging with Clockwork Memory ››

In addition to querying information per allocation it is also possible to query global allocation/memory statistics via the CWMemoryTracker .

The example below demonstrates how to print useful runtime statistics to stdout.

Example

  1. #include <iostream>
  2. #include "cw_memory\common\CWMemory.h"
  4. using namespace cw;
  5. using namespace std;
  7. // Program entry point...
  8. CWMemoryTracker& tracker = CWMemoryTracker::Instance(); // singleton
  9. cout << "TotalNumAllocations = " << tracker.GetTotalNumAllocations() << endl;
  10. cout << "TotalNumDeAllocations = " << tracker.GetTotalNumDeAllocations() << endl;
  11. cout << "NumOpenAllocations = " << tracker.GetNumOpenAllocations() << endl;
  12. cout << "SizeCurrentlyAllocated = " << tracker.GetSizeCurrentlyAllocated() << endl;
  13. cout << "NumRCPtrs = " << tracker.GetNumRCPtrs() << endl;

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


Clockwork Memory Reporting

Created with the Personal Edition of HelpNDoc: Easy to use tool to create HTML Help files and Help web sites


Shutdown Reports

Clockwork Memory Reporting ››

Provided your C++ application is linked with cw_memory, and at least 1 allocation is made, a shutdown report is generated automatically by the Clockwork Memory system. This report is always named "CWMemoryShutdownReport.txt" (saved to the working directory of the application) and contains the following sections;

  • Basic allocation table
  • CW allocation table
  • Summary table

This file can be quite large depending upon the number of allocations. A standalone GUI tool would be ideal for parsing and displaying the shutdown logs however this has not yet been developed.

Deciphering the callstack

To save memory overhead, only the address per stack frame is stored. This address can be looked up off-line using the diadump tool (provided with the Microsoft Visual Studio SDK) to reveal the human readable function name. Again, it would be nice to automate this step using a standalone log viewer.

Spotting allocations which have not been released

Any allocations which have not yet been release have a state value of 0. Searching within the shutdown report for "State=0" will reveal any rouge allocations which were not properly deallocated. If the allocation was made using cwnew the filename, line number and call stack of the allocation will be available.

Created with the Personal Edition of HelpNDoc: Free PDF documentation generator


Generating Reports

Clockwork Memory Reporting ››

Reports can be generated at any time using the CWMemoryReport component, and are not restricted to being generated during application shutdown . To generate a report at runtime you must create a new instance of an empty report and then call the Generate<T> method, where T is the type of report you desire. Two types of report are available out of the box, these are;

  1. CWMemoryReportModeINF (sends report to file)
  2. CWMemoryReportModeTTY (sends report to Visual Studio output window)

New report types can easily be added to the Clockwork Memory system. See the Custom Reports section of " Extending Clockwork Memory " for more information.

The example below generates a TTY report at runtime...

Example

  1. #include "cw_memory\common\CWMemory.h"
  3. using namespace cw;
  5. // Program entry point...
  6. CWMemoryReport myReport;
  7. myReport.Generate<CWMemoryReportModeTTY>("myReport");

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


Clockwork Memory Error Handling

Created with the Personal Edition of HelpNDoc: Easy CHM and documentation editor


Registering for Bad Allocation Callbacks

Clockwork Memory Error Handling ››

When a bad allocation or de-allocation occurs within the Clockwork Memory system, this will usually occur silently (and get logged via CWMemoryTracker ). However, if you wish to handle such errors yourself it is possible to register your own bad allocation/deallocation call back methods with the CWMemoryMgr . The callback registration process is demonstrated below.

Example

  1. #include "cw_memory\common\CWMemory.h"
  3. using namespace cw;
  5. void OnBadAllocation(cw::CWBasicAllocInfo* pData)
  6. {
  7. __debugbreak();
  8. }
  10. void OnBadDeAllocation(const cw::CWBasicDeAllocInfo& pData)
  11. {
  12. __debugbreak();
  13. }
  15. // Program entry point...
  16. cw::CWMemoryMgr::Instance().RegisterBadAllocCallback(&OnBadAllocation);
  17. cw::CWMemoryMgr::Instance().RegisterBadDeAllocCallback(&OnBadDeAllocation);

Created with the Personal Edition of HelpNDoc: Create HTML Help, DOC, PDF and print manuals from 1 single source


Clockwork Memory API

Created with the Personal Edition of HelpNDoc: Free CHM Help documentation generator


cw Namespace

Clockwork Memory API ››

Created with the Personal Edition of HelpNDoc: Easily create PDF Help documents


Types

Clockwork Memory API ›› cw Namespace ››

Created with the Personal Edition of HelpNDoc: Free iPhone documentation generator


CWMemoryMgr

Clockwork Memory API ›› cw Namespace ›› Types ››

CWMemoryMgr

The CWMemoryMgr class is responsible for carrying out any allocations within the system (whether they were requested explicitly or via intercepted calls to global new/delete). CWMemeoryMgr also works closely with CWMemoryTracker to ense all allocations and deallocations are logged with detailed allocation information. CWMemoryMgr is also responsible for registering and issuing bad allocation callbacks.

Notes

  • CWMemoryMgr is implemented as a singleton, and is accessed via CWMemoryMgr::Instance() which returns a static reference to the singleton.
  • CWMemoryMgr should only be accessed directly to register bad allocation callbacks. Actual allocations should usually be made using the selection of helper macros .

Methods

  • void RegisterBadAllocCallback ( CWBadAllocCallback pCallbackFunc )
  • void RegisterBadDeAllocCallback ( CWBadDeAllocCallback pCallbackFunc )
  • cwvptr CWAlloc ( cwu32 uSize , const cwchar * file , cwulong line , cwchar userFlags )
  • cwbool CWDeAlloc ( cwvptr pMemory )
  • void Shutdown()

Created with the Personal Edition of HelpNDoc: Easy to use tool to create HTML Help files and Help web sites


RegisterBadAllocCallback

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryMgr ››

cw::CWMemoryMgr::RegisterBadAllocCallback

Syntax

void RegisterBadAllocCallback(

[in] CWBadAllocCallback pCallbackFunc

);

Notes

This method is used to register a bad allocation callback with the CWMemoryMgr system. This callback will be fired immediately after an allocation fails. An example of how to register bad allocation callbacks can be found here.

Parameters

Name

Type

Notes

pCallbackFunc

[in] CWBadAllocCallback

The callback function to call in the event of a bad allocation. Callback function must have the following signature;

void MyCallback(CWBasicAllocInfo* pData);

Return Value

void

See Also

CWMemoryMgr , RegisterBadDeAllocCallback

Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation


RegisterBadDeAllocCallback

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryMgr ››

cw::CWMemoryMgr::RegisterBadDeAllocCallback

Syntax

void RegisterBadDeAllocCallback(

[in] CWBadDeAllocCallback pCallbackFunc

);

Notes

This method is used to register a bad deallocation callback with the CWMemoryMgr system. This callback will be fired immediately after an deallocation fails. An example of how to register bad deallocation callbacks can be found here .

Parameters

Name

Type

Notes

pCallbackFunc

[in] CWBadDeAllocCallback

The callback function to call in the event of a bad allocation. Callback function must have the following signature;

void MyCallback(const CWBasicDeAllocInfo& pData);

Return Value

void

See Also

CWMemoryMgr , RegisterBadAllocCallback

Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents


CWAlloc

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryMgr ››

cw::CWMemoryMgr::CWAlloc

Syntax

cwvptr CWAlloc(

[in] cwu32 uSize,

[in] const cwchar* file,

[in] cwulong line,

[in] cwchar userFlags

);

Notes

This method is used to perform a memory allocation and should only really be accessed via the selection of helper macros .

Parameters

Name | Type | Notes
uSize | [in] cwu32 | The size of the allocation to be performed
file | [in] const cwchar* | The filename from which the allocation occurs (see selection of helper macros)
line | [in] cwulong | The line number from which the allocation occurs (see selection of helper macros)
userFlags | [in] cwchar userFlags | The user flags to be associated with the allocation

Return Value

Returns a pointer to the allocated memory. This pointer will be 0 in the case of an unsuccessful allocation.

See Also

CWMemoryMgr , CWDeAlloc

Created with the Personal Edition of HelpNDoc: Free iPhone documentation generator


CWDeAlloc

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryMgr ››

cw::CWMemoryMgr::CWDeAlloc

Syntax

cwbool CWDeAlloc(

[in] cwvptr pMemory

);

Notes

This method is used to perform a memory deallocation and should only really be accessed via the selection of helper macros .

Parameters

Name | Type | Notes
pMemory | [in]cwvpt | The memory address to be deallocated

Return Value

Returns the state of the deallocation (true = success, false = fail).

See Also

CWMemoryMgr , CWAlloc

Created with the Personal Edition of HelpNDoc: Full featured multi-format Help generator


Shutdown

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryMgr ››

cw::CWMemoryMgr::Shutdown

Syntax

cwbool Shutdown();

Notes

The CWMemoryMgr will perform it's shutdown phase automatically when the application exits. However in special circumstances it can be invoked prematurely using this method.

Return Value

Returns the state of the shutdown phase (true = success, false = fail).

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


CWMemoryTracker

Clockwork Memory API ›› cw Namespace ›› Types ››

CWMemoryTracker

The CWMemoryTracker class is responsible for tracking all allocations and cw::Ptr instances created throughout the duration of the application. CWMemoryTracker can be used to retrieve global allocation statistics or to retrieve the allocation information associated with a particular memory address.

Notes

  • CWMemoryTracker is implemented as a singleton, and is accessed via CWMemoryTracker::Instance() which returns a static reference to the singleton.

Methods

  • cwu32 GetTotalNumAllocations ( ECWAllocType :: Enum filter = ECWAllocType :: ALLOC_TYPE_END ) const
  • cwu32 GetTotalNumDeAllocations ( ECWAllocType :: Enum filter = ECWAllocType :: ALLOC_TYPE_END ) const
  • cwu32 GetNumOpenAllocations ( ECWAllocType :: Enum filter = ECWAllocType :: ALLOC_TYPE_END ) const
  • cwu32 GetSizeCurrentlyAllocated ( ECWAllocType :: Enum filter = ECWAllocType :: ALLOC_TYPE_END ) const
  • cwu32 GetNumRCPtrs () const
  • CWAllocInfo GetAllocInfo ( void * pMemory )

Created with the Personal Edition of HelpNDoc: Easily create HTML Help documents


GetTotalNumAllocations

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryTracker ››

cw::CWMemoryTracker::GetTotalNumAllocations

Syntax

cwu32 GetTotalNumAllocations(

[in] ECWAllocType::Enum filter

) const;

Notes

This method is used to retrieve the total number of allocations performed by the system

Parameters

Name | Type | Notes
filter | [in] ECWAllocType ::Enum | A filter value can be applied to control which types of allocations (basic / cw) contribute to the accumulated value.

Return Value

Total number of allocations performed by the system.

See Also

CWMemoryTracker , GetTotalNumDeAllocations , GetNumOpenAllocations , GetSizeCurrentlyAllocated , GetNumRCPtrs , GetAllocInfo

Created with the Personal Edition of HelpNDoc: Create iPhone web-based documentation


GetTotalNumDeAllocations

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryTracker ››

cw::CWMemoryTracker::GetTotalNumDeAllocations

Syntax

cwu32 GetTotalNumDeAllocations(

[in] ECWAllocType::Enum filter

) const;

Notes

This method is used to retrieve the total number of deallocations performed by the system.

Parameters

Name | Type | Notes
filter | [in] ECWAllocType ::Enum | A filter value can be applied to control which types of allocations (basic / cw) contribute to the accumulated value.

Return Value

Total number of deallocations performed by the system.

See Also

CWMemoryTracker , GetTotalNumAllocations, GetNumOpenAllocations , GetSizeCurrentlyAllocated , GetNumRCPtrs , GetAllocInfo

Created with the Personal Edition of HelpNDoc: Free help authoring tool


GetNumOpenAllocations

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryTracker ››

cw::CWMemoryTracker::GetNumOpenAllocations

Syntax

cwu32 GetNumOpenAllocations(

[in] ECWAllocType::Enum filter

) const;

Notes

This method is used to retrieve the total number of allocations currently "open" (have not yet been deallocated).

Parameters

Name | Type | Notes
filter | [in] ECWAllocType ::Enum | A filter value can be applied to control which types of allocations (basic / cw) contribute to the accumulated value.

Return Value

Total number of allocations currently "open".

See Also

CWMemoryTracker , GetTotalNumAllocations, GetTotalNumDeAllocations , GetSizeCurrentlyAllocated , GetNumRCPtrs , GetAllocInfo

Created with the Personal Edition of HelpNDoc: Free PDF documentation generator


GetSizeCurrentlyAllocated

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryTracker ››

cw::CWMemoryTracker::GetSizeCurrentlyAllocated

Syntax

cwu32 GetSizeCurrentlyAllocated(

[in] ECWAllocType::Enum filter

) const;

Notes

This method is used to retrieve the total number of bytes currently allocated by the system.

Parameters

Name | Type | Notes
filter | [in] ECWAllocType ::Enum | A filter value can be applied to control which types of allocations (basic / cw) contribute to the accumulated value.

Return Value

Total number of bytes currently allocated by the system.

See Also

CWMemoryTracker , GetTotalNumAllocations, GetTotalNumDeAllocations , GetNumOpenAllocations , GetNumRCPtrs , GetAllocInfo

Created with the Personal Edition of HelpNDoc: Easily create PDF Help documents


GetNumRCPtrs

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryTracker ››

cw::CWMemoryTracker::GetNumRCPtrs

Syntax

cwu32 GetNumRCPtrs() const;

Notes

This method is used to retrieve the total number of active cw::Ptr instances within the application.

Return Value

Total number of active cw::Ptr instances within the application.

See Also

CWMemoryTracker , GetTotalNumAllocations, GetTotalNumDeAllocations , GetNumOpenAllocations , GetSizeCurrentlyAllocated , GetAllocInfo

Created with the Personal Edition of HelpNDoc: Free PDF documentation generator


GetAllocInfo

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryTracker ››

cw::CWMemoryTracker::GetAllocInfo

Syntax

CWAllocInfo GetAllocInfo(

[in] cwvptr pMemory

) const;

Notes

This method is used to retrieve allocation information for a particular memory address. The information is returned in the form of a CWAllocInfo object.

Parameters

Name | Type | Notes
pMemory | [in] cwvptr | The memory address to be queried.

Return Value

A CWAllocInfo object containing details of the allocation.

See Also

CWMemoryTracker , GetTotalNumAllocations, GetTotalNumDeAllocations , GetNumOpenAllocations , GetSizeCurrentlyAllocated , GetNumRCPtrs

Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents


CWPtr

Clockwork Memory API ›› cw Namespace ›› Types ››

CWPtr

The CWPtr class is used to wrap raw pointers to provide reference counted exception safe access to dynamically allocated memory. CWPtr is templated to allow it to safely wrap any pointer type. See " Using cw::Ptr " for more information.

Notes

  • The CWPtr template type T can be any valid type.

Methods

  • T * GetRaw ();
  • cwbool IsValid () const ;
  • cwu32 GetRefCount () const ;

Created with the Personal Edition of HelpNDoc: Easily create Help documents


GetRaw

Clockwork Memory API ›› cw Namespace ›› Types ›› CWPtr ››

cw::CWPtr<T>::GetRaw

Syntax

T* GetRaw();

Notes

This method is used to retrieve the raw pointer being wrapped by the CWPtr instance (this may be required by another library or function which does not accept the CWPtr type).

Return Value

A raw pointer to the underlying resource.

See Also

CWPtr , IsValid , GetRefCount

Created with the Personal Edition of HelpNDoc: Free HTML Help documentation generator


IsValid

Clockwork Memory API ›› cw Namespace ›› Types ›› CWPtr ››

cw::CWPtr<T>::IsValid

Syntax

cwbool IsValid() const

Notes

This method is used to determine whether the underlying resource is safe to access.

Return Value

Returns whether the wrapped pointer is valid (not equal to 0).

See Also

CWPtr , GetRaw , GetRefCount

Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents


GetRefCount

Clockwork Memory API ›› cw Namespace ›› Types ›› CWPtr ››

cw::CWPtr<T>::GetRefCount

Syntax

cwu32 GetRefCount() const

Notes

This method is used to retrieve the reference count for the underlying resource.

Return Value

The reference count for the underlying resource.

See Also

CWPtr, GetRaw , IsValid

Created with the Personal Edition of HelpNDoc: Free HTML Help documentation generator


CWMemoryReport

Clockwork Memory API ›› cw Namespace ›› Types ››

CWMemoryReport

The CWMemoryReport class is generate reports containing detailed tables and statistics regarding the current state of the CWMemoryMgr and tracked allocations. For examples on generating reports see the " Clockwork Memory Reporting " section.

Notes

  • CWMemoryReport can be extended using report components. See " Custom Reports " for more details.

Methods

  • cwbool Generate<T> ( const cwchar * pName )

Created with the Personal Edition of HelpNDoc: Easy to use tool to create HTML Help files and Help web sites


Generate

Clockwork Memory API ›› cw Namespace ›› Types ›› CWMemoryReport ››

cw::CWMemoryReport::Generate<T>

Syntax

cwbool Generate<T>(

[in]const cwchar* pName

);

Notes

This method is used to generate a report containing detailed tables and statistics regarding the current state of the CWMemoryMgr and tracked allocations. T must be a valid report component (either CWMemoryReportModeINF or CWMemoryReportModeTTY). You can also create your own report types, see " Custom Reports " for more details.

Return Value

The success of the report generation procedure (true = success, false = fail).

See Also

CWMemoryReport

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


Structures

Clockwork Memory API ›› cw Namespace ››

Created with the Personal Edition of HelpNDoc: Free HTML Help documentation generator


CWAllocInfo

Clockwork Memory API ›› cw Namespace ›› Structures ››

CWAllocInfo

  1. struct CWAllocInfo
  2. {
  3. CWAllocInfo() : pNext(0) { }
  5. cwu32 uAllocID; // internal allocation ID
  6. cwvptr pMemory; // pointer to user data
  7. cwu32 uSize; // size of user data
  8. cwu32 uActualSize; // size including overhead
  9. CWCallStack* pCallStack; // pointer to callstack list
  10. cwdouble fTicks; // time of alloc
  11. ECWAllocState::Enum eState; // alloc state
  13. // Extra data
  14. const cwchar* pFilename; // origin filename
  15. cwulong uLineNumber; // origin line number
  16. cwchar uUserFlags; // user flags
  18. CWAllocInfo* pNext; // next allocation
  19. };

Created with the Personal Edition of HelpNDoc: Easily create Web Help sites


CWPtrRefCount

Clockwork Memory API ›› cw Namespace ›› Structures ››

CWPtrRefCount

  1. struct CWPtrRefCount
  2. {
  3. CWPtrRefCount() : pNext(0) { }
  5. cwu32 uAllocID; // Alloc owned by cw::Ptr
  6. cwu32 uRefCount; // Reference count
  7. CWPtrRefCount* pNext; // next cw::Ptr entry
  8. };

Created with the Personal Edition of HelpNDoc: Free CHM Help documentation generator


Enums

Clockwork Memory API ›› cw Namespace ››

Created with the Personal Edition of HelpNDoc: Easy to use tool to create HTML Help files and Help web sites


ECWAllocType

Clockwork Memory API ›› cw Namespace ›› Enums ››

ECWAllocType

  1. namespace ECWAllocType
  2. {
  3. enum Enum
  4. {
  5. ALLOC_TYPE_BASIC = 0,
  6. ALLOC_TYPE_CW,
  7. ALLOC_TYPE_END
  8. };
  9. }

Created with the Personal Edition of HelpNDoc: Easy to use tool to create HTML Help files and Help web sites


ECWAllocState

Clockwork Memory API ›› cw Namespace ›› Enums ››

ECWAllocState

  1. namespace ECWAllocState
  2. {
  3. enum Enum
  4. {
  5. ALLOC_STATE_ALLOCATED = 0,
  6. ALLOC_STATE_DEALLOCATED,
  7. ALLOC_STATE_BAD_ALLOC,
  8. ALLOC_STATE_END
  9. };
  10. }

Created with the Personal Edition of HelpNDoc: Easy CHM and documentation editor


Callbacks

Clockwork Memory API ›› cw Namespace ››

Created with the Personal Edition of HelpNDoc: Create iPhone web-based documentation


CWBadAllocCallback

Clockwork Memory API ›› cw Namespace ›› Callbacks ››

CWBadAllocCallback

typedef void (*CWBadAllocCallback)(CWBasicAllocInfo* pData);

See Also

CWMemoryMgr , RegisterBadAllocCallback

Created with the Personal Edition of HelpNDoc: Easily create PDF Help documents


CWBadDeAllocCallback

Clockwork Memory API ›› cw Namespace ›› Callbacks ››

CWBadDeAllocCallback

typedef void (*CWBadDeAllocCallback)(const CWBasicDeAllocInfo& pData);

See Also

CWMemoryMgr , RegisterBadDeAllocCallback

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


Extending Clockwork Memory

Created with the Personal Edition of HelpNDoc: Single source CHM, PDF, DOC and HTML Help creation


Custom Reports

Extending Clockwork Memory ››

If you wish to extend the basic report functionality built into the Clockwork Memory system (see " Clockwork Memory Reporting ") this can be achieved by implementing a custom report component. Once you have implemented a custom report component it can be used by providing it as a template argument to the CWMemoryReport::Generate .

There are two report components provided by default within the Clockwork Memory library, these are CWMemoryModeINF and CWMemoryModeTTY. As the source code for each of these components is included within ClockworkMemory.sln (CWMemoryModeINF.h and CWMemoryModeTTY.h) you can simply copy and paste one of these existing classes to customise it for your own purposes. The only constraints are that each report component implement the following methods...

Function signature | Notes
cwbool Init(const cwchar* pName) | This method is called immediately before the report is generated and should be used to perform any custom initialisation/setup routines. pName is the name passed when generating the report and is used to identify the report instance (and could potentially be ignored).
cwbool Close() | This method is called immediately after the last entry has been reported.
cwbool NewSection(const cwchar* pName) | This method signals that the new report section pName is commencing.
cwbool NewKey(const cwchar* pKey) | This method signals that the a new value key pKey is to be logged.
cwbool NewValue(const cwchar* pValue) | This method signals that the a new string value pValue is to be logged.
template<typename T> cwbool NewValue(const T& value) | This method signals that the a new value value of type T is to be logged. This value will only ever be a signed int, unsigned int, char* or float value.
cwbool StartValueArray() | This method signals that the proceeding values reported are part of an array, belonging to the previously signalled key.
cwbool EndValueArray() | This method signals that the last value in the value array (commenced by StartValueArray) has been reached.

Example

  1. class MyCustomReportComponent
  2. {
  3. // Implementation of all functions listed above....
  4. };
  6. // Program entry point
  7. cw::MemoryReport myReport;
  8. myReport.Generate<MyCustomReportComponent>("report name");

Created with the Personal Edition of HelpNDoc: Easily create Web Help sites


Custom Heap Allocation

Extending Clockwork Memory ››

The windows implementation of the default allocator provided with Clockwork Memory can be found within CWMemoryAllocDefaultHeap_windows.cpp. If the implementation found here is not sufficient, or you wish to provide your own custom allocator, you can simply remove the "CWMemoryAllocDefaultHeap_windows.cpp" from the solution (or comment it out) and define the following two functions manually...

Note: These functions must be declared within the cw namespace

Function Signature | Notes
cwbool DefaultHeapAlloc(CWBasicAllocInfo* pAllocInfo) | This function is called whenever CWMemoryMgr needs to perform an allocation. The ID and size of the allocation is specified within pAllocInfo.uSize. All other members of pAllocInfo will remain empty and must be filled out within the body of DefaultHeapAlloc with the appropriate values.
cwbool DefaultHeapDeAlloc(CWBasicDeAllocInfo& deAllocInfo); | This function is called whenever CWMemoryMgr needs to perform a de-allocation. The address and size of the allocation to be de-allocated can be found within deAllocInfo. The memory at deAllocInfo.pMemory must be deallocated before DefaultHeapDeAlloc returns.

Created with the Personal Edition of HelpNDoc: Create iPhone web-based documentation