001: /************************************************************************
 002:     引用计数基类、及引用计数指针模板类
 003:         －－－－NoSound QQ2591570 可随意复制、改动、使用、拍砖，概不追究！
 004: ************************************************************************/
 005: #ifndef _REFCOUNTED_INCLUDED_
 006: #define _REFCOUNTED_INCLUDED_
 007: 
 008: #include <cassert>
 009: #ifdef _MT
 010: #include <Windows.h>
 011: #endif
 012: 
 013: class RefCountable {
 014: public:
 015:     int addRef(void) {
 016:         #ifdef _MT
 017:         return ::InterlockedIncrement(&refCount_);
 018:         #else
 019:         return ++refCount_;
 020:         #endif
 021:     }
 022: 
 023:     int decRef(void) {
 024:         int r =
 025:             #ifdef _MT
 026:             ::InterlockedDecrement(&refCount_);
 027:             #else
 028:             --refCount_;
 029:             #endif
 030:         assert(r>=0);
 031:         if (0==r)
 032:             delete this;
 033:         return r;
 034:     }
 035: 
 036:     int getRefCount(void) const { return refCount_; }
 037: 
 038: protected:
 039:     RefCountable(void) : refCount_(0) {}
 040:     virtual ~RefCountable(void) { assert(0==refCount_); }
 041: 
 042: private:
 043:     #ifdef _MT
 044:     long
 045:     #else
 046:     int
 047:     #endif
 048:     refCount_;
 049:     RefCountable(const RefCountable &);
 050:     RefCountable & operator = (const RefCountable &);
 051: };
 052: 
 053: template<class T>
 054: class RefCountedPtr {
 055: public:
 056:     RefCountedPtr(void) : ptr_(0) {}
 057:     RefCountedPtr(T *ptr) : ptr_(ptr) {
 058:         if (ptr_)
 059:             ptr_->addRef();
 060:     }
 061:     RefCountedPtr(const RefCountedPtr<T> &sour) : ptr_(sour.ptr_) {
 062:         if (ptr_)
 063:             ptr_->addRef();
 064:     }
 065:     RefCountedPtr & operator = (const RefCountedPtr<T> &right) {
 066:         if (this!=&right) {
 067:             if (0!=ptr_)
 068:                 ptr_->decRef();
 069:             ptr_ = right.ptr_;
 070:             if (ptr_)
 071:                 ptr_->addRef();
 072:         }
 073:         return *this;
 074:     }
 075:     ~RefCountedPtr(void) {
 076:         if (0!=ptr_)
 077:             ptr_->decRef();
 078:     }
 079: 
 080:     T & operator*() const { return *ptr_; }
 081:     T * operator->() const { return (&**this); }
 082:     
 083:     friend bool operator == (const RefCountedPtr<T> &left, const RefCountedPtr<T> &right) {
 084:         return (left.ptr_ == right.ptr_);
 085:     }
 086:     friend bool operator != (const RefCountedPtr<T> &left, const RefCountedPtr<T> &right) {
 087:         return (left.ptr_ != right.ptr_);
 088:     }
 089:     friend bool operator < (const RefCountedPtr<T> &left, const RefCountedPtr<T> &right) {
 090:         return (left.ptr_ < right.ptr_);
 091:     }
 092:     friend bool operator > (const RefCountedPtr<T> &left, const RefCountedPtr<T> &right) {
 093:         return (left.ptr_ > right.ptr_);
 094:     }
 095:     friend bool operator <= (const RefCountedPtr<T> &left, const RefCountedPtr<T> &right) {
 096:         return (left.ptr_ <= right.ptr_);
 097:     }
 098:     friend bool operator >= (const RefCountedPtr<T> &left, const RefCountedPtr<T> &right) {
 099:         return (left.ptr_ >= right.ptr_);
 100:     }
 101: 
 102:     bool isNull() const { return 0==ptr_; }
 103:     bool isValid() const { return 0!=ptr_; }
 104: 
 105:     // 返回所控制的对象指针
 106:     T * get(void) const { return ptr_; }
 107: 
 108:     //取得对另一指针的控制权
 109:     void reset(T * ptr=0) {
 110:         if (0!=ptr)
 111:             ptr->addRef();
 112:         if (0!=ptr_)
 113:             ptr_->decRef();
 114:         ptr_ = ptr;
 115:     }
 116: 
 117: private:
 118:     T    *ptr_;
 119: };
 120: 
 121: #endif // ifndef _REFCOUNTED_INCLUDED_

Introduction

You've undoubtedly seen all these various string types like TCHAR, std::string, BSTR, and so on. And then there are those wacky macros starting with _tcs. And you're staring at the screen thinking "wha?" Well stare no more, this guide will outline the purpose of each string type, show some simple usages, and describe how to convert to other string types when necessary.

In Part I, I will cover the three types of character encodings. It is crucial that you understand how the encoding schemes work. Even if you already know that a string is an array of characters, read this part. Once you've learned this, it will be clearer how the various string classes are related.

In Part II I will describe the string classes themselves, when to use which ones, and how to convert among them.

The basics of characters - ASCII, DBCS, Unicode

All string classes eventually boil down to a C-style string, and C-style strings are arrays of characters, so I'll first cover the character types. There are three encoding schemes and three character types. The first scheme is the single-byte character set, or SBCS. In this encoding scheme, all characters are exactly one byte long. ASCII is an example of an SBCS. A single zero byte marks the end of a SBCS string.

The second scheme is the multi-byte character set, or MBCS. An MBCS encoding contains some characters that are one byte long, and others that are more than one byte long. The MBCS schemes used in Windows contain two character types, single-byte characters and double-byte characters. Since the largest multi-byte character used in Windows is two bytes long, the term double-byte character set, or DBCS, is commonly used in place of MBCS.

In a DBCS encoding, certain values are reserved to indicate that they are part of a double-byte character. For example, in the Shift-JIS encoding (a commonly-used Japanese scheme), values 0x81-0x9F and 0xE0-0xFC mean "this is a double-byte character, and the next byte is part of this character." Such values are called "lead bytes," and are always greater than 0x7F. The byte following a lead byte is called the "trail byte." In DBCS, the trail byte can be any non-zero value. Just as in SBCS, the end of a DBCS string is marked by a single zero byte.

The third scheme is Unicode. Unicode is an encoding standard in which all characters are two bytes long. Unicode characters are sometimes called wide characters because they are wider (use more storage) than single-byte characters. Note that Unicode is not considered an MBCS - the distinguishing feature of an MBCS encoding is that characters are of different lengths. A Unicode string is terminated by two zero bytes (the encoding of the value 0 in a wide character).

Single-byte characters are the Latin alphabet, accented characters, and graphics defined in the ASCII standard and DOS operating system. Double-byte characters are used in East Asian and Middle Eastern languages. Unicode is used in COM and internally in Windows NT.

You're certainly already familiar with single-byte characters. When you use the char data type, you are dealing with single-byte characters. Double-byte characters are also manipulated using the char data type (which is the first of many oddities that we'll encounter with double-byte characters). Unicode characters are represented by the wchar_t type. Unicode character and string literals are written by prefixing the literal with L, for example:

Collapse Copy Code

  wchar_t  wch = L'1';      // 2 bytes, 0x0031
  wchar_t* wsz = L"Hello";  // 12 bytes, 6 wide characters

How characters are stored in memory

Single-byte strings are stored one character after the next, with a single zero byte marking the end of the string. So for example, "Bob" is stored as:

42	6F	62	00
B	o	b	EOS

The Unicode version, L"Bob", is stored as:

42 00	6F 00	62 00	00 00
B	o	b	EOS

with the character 0x0000 (the Unicode encoding of zero) marking the end.

DBCS strings look like SBCS strings at first glance, but we will see later that there are subtleties that make a difference when using string manipulating functions and traversing through the string with a pointer. The string "" ("nihongo") is stored as follows (with lead bytes and trail bytes indicated by LB and TB respectively):

93 FA	96 7B	8C EA	00
LB TB	LB TB	LB TB	EOS
			EOS

Keep in mind that the value of "ni" is not interpreted as the WORD value 0xFA93. The two values 93 and FA, in that order, together encode the character "ni". (So on a big-endian CPU, the bytes would still be in the order shown above.)

Using string handling functions

We've all seen the C string functions like strcpy(), sprintf(), atol(), etc. These functions must be used only with single-byte strings. The standard library also has versions for use with only Unicode strings, such as wcscpy(), swprintf(), _wtol().

Microsoft also added versions to their CRT (C runtime library) that operate on DBCS strings. The strxxx() functions have corresponding DBCS versions named _mbsxxx(). If you ever expect to encounter DBCS strings (and you will if your software is ever installed on Japanese, Chinese, or other language that uses DBCS), you should always use the _mbsxxx() functions, since they also accept SBCS strings. (A DBCS string might contain only one-byte characters, so that's why _mbsxxx() functions work with SBCS strings too.)

Let's look at a typical string to illustrate the need for the different versions of the string handling functions. Going back to our Unicode string L"Bob":

42 00	6F 00	62 00	00 00
B	o	b	EOS

Because x86 CPUs are little-endian, the value 0x0042 is stored in memory as 42 00. Can you see the problem here if this string were passed to strlen()? It would see the first byte 42, then 00, which to it means "end of the string," and it would return 1. The converse situation, passing "Bob" to wcslen(), is even worse. wcslen() would first see 0x6F42, then 0x0062, and then keep on reading past the end of your buffer until it happened to hit a 00 00 sequence or cause a GPF.

So we've covered the usage of strxxx() versus wcsxxx(). What about strxxx() versus _mbsxxx()? The difference there is extremely important, and has to do with the proper way of traversing through DBCS strings. I will cover traversing strings next, then return to the subject of strxxx() versus _mbsxxx().

Traversing and indexing into strings properly

Since most of us grew up using SBCS strings, we're used to using the ++ and -- operators on a pointer to traverse through a string. We've also used array notation to access any character in the string. Both these methods work perfectly well with SBCS and Unicode strings, because all characters are the same length and the compiler can properly return the character we're asking for.

However, you must break those habits for your code to work properly when it encounters DBCS strings. There are two rules for traversing through a DBCS string using a pointer. Breaking these rules will cause almost all of your DBCS-related bugs.

1. Don't traverse forwards with ++ unless you check for lead bytes along the way.

2. Never traverse backwards using --.

I'll illustrate rule 2 first, since it's easy to find a non-contrived example of code that breaks it. Say you have a program that stores a config file in its own directory, and you keep the install directory in the registry. At runtime, you read the install directory, tack on the config filename, and try to read it. So if you install to C:\Program Files\MyCoolApp, the filename that gets constructed is C:\Program Files\MyCoolApp\config.bin, and it works perfectly when you test it.

Now, imagine this is your code that constructs the filename:

Collapse Copy Code

bool GetConfigFileName ( char* pszName, size_t nBuffSize )
{
char szConfigFilename[MAX_PATH];
// Read install dir from registry... we'll assume it succeeds.

// Add on a backslash if it wasn't present in the registry value.
    // First, get a pointer to the terminating zero.
char* pLastChar = strchr ( szConfigFilename, '\0' );
// Now move it back one character.
    pLastChar--;
if ( *pLastChar != '\\' )
strcat ( szConfigFilename, "\\" );
// Add on the name of the config file.
strcat ( szConfigFilename, "config.bin" );
// If the caller's buffer is big enough, return the filename.
if ( strlen ( szConfigFilename ) >= nBuffSize )
return false;
else
{
strcpy ( pszName, szConfigFilename );
return true;
}
}

This is very defensive code, yet it will break with particular DBCS characters. To see why, suppose a Japanese user gets hold of your program and changes the install directory to C:\. Here is that directory name as stored in memory:

43	3A	5C	83 88	83 45	83 52	83 5C	00
			LB TB	LB TB	LB TB	LB TB
C	:	\					EOS

When GetConfigFileName() checks for the trailing backslash, it looks at the last non-zero byte of the install directory, sees that it equals '\\', and doesn't append another slash. The result is that the code returns the wrong filename.

So what went wrong? Look at the two bytes above highlighted in blue. The value of the backslash character is 0x5C. The value of '' is 83 5C. (The light bulb should be going on just about now...) The above code mistakenly read a trail byte and treated it as a character of its own.

The correct way to traverse backwards is to use functions that are aware of DBCS characters and move the pointer the correct number of bytes. Here is the correct code, with the pointer movement shown in red:

Collapse Copy Code

bool FixedGetConfigFileName ( char* pszName, size_t nBuffSize )
{
char szConfigFilename[MAX_PATH];
// Read install dir from registry... we'll assume it succeeds.

// Add on a backslash if it wasn't present in the registry value.
    // First, get a pointer to the terminating zero.
char* pLastChar = _mbschr ( szConfigFilename, '\0' );
// Now move it back one double-byte character.
    pLastChar = CharPrev ( szConfigFilename, pLastChar );
if ( *pLastChar != '\\' )
_mbscat ( szConfigFilename, "\\" );
// Add on the name of the config file.
_mbscat ( szConfigFilename, "config.bin" );
// If the caller's buffer is big enough, return the filename.
if ( _mbslen ( szInstallDir ) >= nBuffSize )
return false;
else
{
_mbscpy ( pszName, szConfigFilename );
return true;
}
}

This fixed function uses the CharPrev() API to move pLastChar back one character, which might be two bytes long if the string ends in a double-byte character. In this version, the if condition works properly, since a lead byte will never equal 0x5C.

You can probably imagine a way to break rule 1 now. For example, you might validate a filename entered by the user by looking for multiple occurrences of the character ':'. If you use ++ to traverse the string instead of CharNext(), you may incorrectly generate errors if there happen to be trail bytes whose values equal that of ':'.

Related to rule 2 is this one about using array indexes:

2a. Never calculate an index into a string using subtraction.

Code that breaks this rule is very similar to code that breaks rule 2. For example, if pLastChar were set this way:

Collapse Copy Code

char* pLastChar = &szConfigFilename [strlen(szConfigFilename) - 1];

it would break in exactly the same situations, because subtracting 1 in the index expression is equivalent to moving backwards 1 byte, which breaks rule 2.

Back to strxxx() versus _mbsxxx()

It should be clear now why the _mbsxxx() functions are necessary. The strxxx() functions know nothing of DBCS characters, while _mbsxxx() do. If you called strrchr("C:\\", '\\') the return value would be wrong, whereas _mbsrchr() will recognize the double-byte characters at the end, and return a pointer to the last actual backslash.

One final point about string functions: the strxxx() and _mbsxxx() functions that take or return a length return the length in chars. So if a string contains three double-byte characters, _mbslen() will return 6. The Unicode functions return lengths in wchar_ts, so for example, wcslen(L"Bob") returns 3.

MBCS and Unicode in the Win32 API

The two sets of APIs

Although you might never have noticed, every API and message in Win32 that deals with strings has two versions. One version accepts MCBS strings, and the other Unicode strings. For example, there is no API called SetWindowText(); instead, there are SetWindowTextA() and SetWindowTextW(). The A suffix (for ANSI) indicates the MBCS function, while the W suffix (for wide) indicates the Unicode version.

When you build a Windows program, you can elect to use either the MBCS or Unicode APIs. If you've used the VC AppWizards and never touched the preprocessor settings, you've been using the MBCS versions all along. So how is it that we can write "SetWindowText" when there isn't an API by that name? The winuser.h header file contains some #defines, like this:

Collapse Copy Code

BOOL WINAPI SetWindowTextA ( HWND hWnd, LPCSTR lpString );
BOOL WINAPI SetWindowTextW ( HWND hWnd, LPCWSTR lpString );
#ifdef UNICODE
#define SetWindowText  SetWindowTextW
#else
#define SetWindowText  SetWindowTextA
#endif

When building for the MBCS APIs, UNICODE is not defined, so the preprocessor sees:

Collapse Copy Code

#define SetWindowText  SetWindowTextA

and replaces calls to SetWindowText() with calls to the real API, SetWindowTextA(). (Note that you can, if you wanted to, call SetWindowTextA() or SetWindowTextW() directly, although you'd rarely need to do that.)

So, if you want to switch to using the Unicode APIs by default, you can go to the preprocessor settings and remove the _MBCS symbol from the list of predefined symbols, and add UNICODE and _UNICODE. (You should define both, as different headers use different symbols.) However, you will run into a snag if you've been using plain char for your strings. Consider this code:

Collapse Copy Code

HWND hwnd = GetSomeWindowHandle();
char szNewText[] = "we love Bob!";
SetWindowText ( hwnd, szNewText );

After the compiler replaces "SetWindowText" with "SetWindowTextW", the code becomes:

Collapse Copy Code

HWND hwnd = GetSomeWindowHandle();
char szNewText[] = "we love Bob!";
SetWindowTextW ( hwnd, szNewText );

See the problem here? We're passing a single-byte string to a function that takes a Unicode string. The first solution to this problem is to use #ifdefs around the definition of the string variable:

Collapse Copy Code

HWND hwnd = GetSomeWindowHandle();
#ifdef UNICODE
wchar_t szNewText[] = L"we love Bob!";
#else
char szNewText[] = "we love Bob!";
#endif
SetWindowText ( hwnd, szNewText );

You can probably imagine the headache you'd get having to do that around every string in your code. The solution to this is the TCHAR.

TCHAR to the rescue!

TCHAR is a character type that lets you use the same codebase for both MBCS and Unicode builds, without putting messy #defines all over your code. A definition of the TCHAR looks like this:

Collapse Copy Code

#ifdef UNICODE
typedef wchar_t TCHAR;
#else
typedef char TCHAR;
#endif

So a TCHAR is a char in MBCS builds, and a wchar_t in Unicode builds. There is also a macro _T() to deal with the L prefix needed for Unicode string literals:

Collapse Copy Code

#ifdef UNICODE
#define _T(x) L##x
#else
#define _T(x) x
#endif

The ## is a preprocessor operator that pastes the two arguments together. Whenever you have a string literal in your code, use the _T macro on it, and it will have the L prefix added on when you do a Unicode build.

Collapse Copy Code

TCHAR szNewText[] = _T("we love Bob!");

Just as there are macros to hide the SetWindowTextA/W details, there are also macros that you can use in place of the strxxx() and _mbsxxx() string functions. For example, you can use the _tcsrchr macro in place of strrchr() or _mbsrchr() or wcsrchr(). _tcsrchr expands to the right function based on whether you have the _MBCS or UNICODE symbol defined, just like SetWindowText does.

It's not just the strxxx() functions that have TCHAR macros. There are also, for example, _stprintf (replaces sprintf() and swprintf()) and _tfopen (replaces fopen() and _wfopen()). The full list of macros is in MSDN under the title "Generic-Text Routine Mappings."

String and TCHAR typedefs

Since the Win32 API documentation lists functions by their common names (for example, "SetWindowText"), all strings are given in terms of TCHARs. (The exception to this is Unicode-only APIs introduced in XP.) Here are the commonly-used typedefs that you will see in MSDN:

type	Meaning in MBCS builds	Meaning in Unicode builds
WCHAR	wchar_t	wchar_t
LPSTR	zero-terminated string of char (char*)	zero-terminated string of char (char*)
LPCSTR	constant zero-terminated string of char (const char*)	constant zero-terminated string of char (const char*)
LPWSTR	zero-terminated Unicode string (wchar_t*)	zero-terminated Unicode string (wchar_t*)
LPCWSTR	constant zero-terminated Unicode string (const wchar_t*)	constant zero-terminated Unicode string (const wchar_t*)
TCHAR	char	wchar_t
LPTSTR	zero-terminated string of TCHAR (TCHAR*)	zero-terminated string of TCHAR (TCHAR*)
LPCTSTR	constant zero-terminated string of TCHAR (const TCHAR*)	constant zero-terminated string of TCHAR (const TCHAR*)

When to use TCHAR and Unicode

So, after all this, you're probably wondering, "So why would I use Unicode? I've gotten by with plain chars for years." There are three cases where a Unicode build is beneficial:

1. Your program will run only on Windows NT.
2. Your program needs to handle filenames longer than MAX_PATH characters.
3. Your program uses some newer APIs introduced with Windows XP that do not have the separate A/W versions.

The vast majority of Unicode APIs are not implemented on Windows 9x, so if you intend your program to be run on 9x, you'll have to stick with the MBCS APIs. (There is a relatively new library from Microsoft called the Microsoft Layer for Unicode that lets you use Unicode on 9x, however I have not tried it myself yet, so I can't comment on how well it works.) However, since NT uses Unicode for everything internally, you will speed up your program by using the Unicode APIs. Every time you pass a string to an MBCS API, the operating system converts the string to Unicode and calls the corresponding Unicode API. If a string is returned, the OS has to convert the string back. While this conversion process is (hopefully) highly optimized to make as little impact as possible, it is still a speed penalty that is avoidable.

NT allows very long filenames (longer than the normal limit of MAX_PATH characters, which is 260) but only if you use the Unicode APIs. Once nice side benefit of using the Unicode APIs is that your program will automatically handle any language that the user enters. So a user could enter a filename using English, Chinese, and Japanese all together, and you wouldn't need any special code to deal with it; they all appear as Unicode characters to you.

Finally, with the end of the Windows 9x line, MS seems to be doing away with the MBCS APIs. For example, the SetWindowTheme() API, which takes two string parameters, only has a Unicode version. Using a Unicode build will simplify string handling as you won't have to convert from MBCS to Unicode and back.

And even if you don't go with Unicode builds now, you should definitely always use TCHAR and the associated macros. Not only will that go a long way to making your code DBCS-safe, but if you decide to make a Unicode build in the future, you'll just need to change a preprocessor setting to do it!

What are smart pointers? The answer is fairly simple; a smart pointer is a pointer which is smart. What does that mean? Actually smart pointers are objects which behave like pointers, but do more than a pointer. These objects are flexible as pointers and have the advantage of being an object (like constructor and destructors called automatically). A smart pointer is designed to handle the problems caused by using normal pointers (hence called smart).

Problems with Pointers

What are the common problems we face in C++ programs while using pointers? The answer is memory management. Have a look at the following code.

Collapse Copy Code

    char* pName  = new char[1024];
…
SetName(pName);
…
…
if(null != pName)
{
delete[] pName;
}

How many times we found out a bug which was caused because we forgot deleting ‘pName’. It would be great if somebody takes care of releasing the memory when the pointer is not useful (we are not talking about the garbage collector here). What if the pointer itself takes care of that, yes that’s exactly what smart pointer is intended to do. Let us write a smart pointer and see how we can handle a pointer better.

We shall start with a realistic example. Let’s say we have a class called Person which is defined as listed below.

Collapse Copy Code

    class Person
{
int age;
char* pName;
public:
Person(): pName(0),age(0)
{
}
Person(char* pName, int age): pName(pName), age(age)
{
}
~Person()
{
}
void Display()
{
printf("Name = %s Age = %d \n", pName, age);
}
void Shout()
{
printf("Ooooooooooooooooo",);
}
};

Now we shall write the client code to use Person

Collapse Copy Code

    void main()
{
Person* pPerson  = new Person("Scott", 25);
pPerson->Display();
delete pPerson;
}

Now look at this code, every time I create a pointer I need to take care of deleting it, this is exactly what I want to avoid. I need some automatic mechanism which deletes the pointer. One thing which strikes to me is a destructor. But pointers do not have destructors, so what our smart pointer can have one. So we will create a class called SP which can hold a pointer to the person class and will delete the pointer when its destructor is called. Hence my client code will change to something like this.

Collapse Copy Code

    void main()
{
SP p(new Person("Scott", 25));
p->Display();
// Dont need to delete Person pointer..
    }

Indirection (operator ->)

Let us write the SP class now

Collapse Copy Code

    class SP
{
private:
Person*    pData; // pointer to person class
    public:
SP(Person* pValue) : pData(pValue)
{
}
~SP()
{
// pointer no longer requried
            delete pData;
}
Person& operator* ()
{
return *pData;
}
Person* operator-> ()
{
return pData;
}
};

This class is our smart pointer class. The main responsibility of this class is to hold a pointer to Person class, and then delete it when its destructor is called. It should also support the interface of the pointer.

Generic smart pointer class

One problem which we see here is that we can use this smart pointer class for pointer of Person class only. This means that we have to create each smart pointer class for each type, that’s not easy. We can solve this problem by making use of templates and make this smart pointer class generic. So let us change the code like this.

Collapse Copy Code

    template < typename T > class SP
{
private:
T*    pData; // Generic pointer to be stored
        public:
SP(T* pValue) : pData(pValue)
{
}
~SP()
{
delete pData;
}
T& operator* ()
{
return *pData;
}
T* operator-> ()
{
return pData;
}
};
void main()
{
SP
 p(new Person("Scott", 25));
p->Display();
// Dont need to delete Person pointer..
    }

Now we can use our smart pointer class for any type of pointers. So is our smart pointer really smart? Check the following code segment.

Collapse Copy Code

    void main()
{
SP
 p(new Person("Scott", 25));
p->Display();
{
SP
 q = p;
q->Display();
// Destructor of Q will be called here..
        }
p->Display();
}

Look what happens here p and q are referring to the same Person class pointer, now when q goes out of scope the destructor of q will be called which deletes the Person class pointer. Now we cannot call p->Display(); since p will be left with a dangling pointer and this call will fail. (Note that this problem would have existed even if we were using normal pointers instead of smart pointers) We should not delete the Person class pointer unless no body is using it. How do we do that? Implementing reference counting mechanism in our smart pointer class will solve this problem.

Reference counting

What we are going to do is we will have a reference counting class RC. This class will maintain an integer value which represents the reference count. We will have methods to increment and decrement the reference count.

Collapse Copy Code

    class RC
{
private:
int count; // Reference count

public:
void AddRef()
{
// Increment the reference count
            count++;
}
int Release()
{
// Decrement the reference count and
            // return the reference count.
            return --count;
}
};

Now we have a reference counting class, we will introduce this to our smart pointer class. We will maintain a pointer to class RC in our SP class and this pointer will be shared for all instance of the smart pointer which refers to the same pointer. For this to happen we need to have an assignment operator and copy constructor in our SP class.

Collapse Copy Code

    template < typename T > class SP
{
private:
T*    pData;       // pointer
        RC* reference; // Reference count

public:
SP() : pData(0), reference(0)
{
// Create a new reference
            reference = new RC();
// Increment the reference count
            reference->AddRef();
}
SP(T* pValue) : pData(pValue), reference(0)
{
// Create a new reference
            reference = new RC();
// Increment the reference count
            reference->AddRef();
}
SP(const SP<T>& sp) : pData(sp.pData), reference(sp.reference)
{
// Copy constructor
            // Copy the data and reference pointer
            // and increment the reference count
            reference->AddRef();
}
~SP()
{
// Destructor
            // Decrement the reference count
            // if reference become zero delete the data
            if(reference->Release() == 0)
{
delete pData;
delete reference;
}
}
T& operator* ()
{
return *pData;
}
T* operator-> ()
{
return pData;
}
SP<T>& operator = (const SP<T>& sp)
{
// Assignment operator
            if (this != &sp) // Avoid self assignment
            {
// Decrement the old reference count
                // if reference become zero delete the old data
                if(reference->Release() == 0)
{
delete pData;
delete reference;
}
// Copy the data and reference pointer
                // and increment the reference count
                pData = sp.pData;
reference = sp.reference;
reference->AddRef();
}
return *this;
}
};

Let us have a look at the client code.

Collapse Copy Code

    void main()
{
SP
 p(new Person("Scott", 25));
p->Display();
{
SP
 q = p;
q->Display();
// Destructor of q will be called here..

SP
 r;
r = p;
r->Display();
// Destructor of r will be called here..
        }
p->Display();
// Destructor of p will be called here
        // and person pointer will be deleted
    }

When we create a smart pointer p of type person, the constructor of SP will be called, the data will be stored and a new RC pointer will be created. The AddRef method of RC is called to increment the reference count to 1. Now SP q = p; will create a new smart pointer q using the copy constructor, here the data will be copied and reference will again incremented to 2. Now r = p; will call the assignment operator to assign the value of p to q, here also we copy the data and increment the reference count, thus making the count 3. When r and q goes out of scope the destructors of respective objects will be called, here the reference count will be decremented, but data will not be deleted unless the reference count becomes zero, this happens only when destructor of p is called. Hence our data will be deleted only when no body is referring to it.

Applications

Memory leaks: Using smart pointers reduces work of managing pointers for memory leaks. Now you could create a pointer and forget about deleting it, the smart pointer will do that for you. This is the simplest garbage collector we could think off.

Exceptions: Smart pointers are very useful where exceptions are used. For example look at the following code.

Collapse Copy Code

    void MakeNoise()
{
Person* p = new Person("Scott", 25);
p->Shout();
delete p;
}

We are using a normal pointer here and deleting it after using, so every thing looks okay here. But what if our Shout function thows some exception delete p; will never be called. So we have a memory leak, let us handle that.

Collapse Copy Code

    void MakeNoise()
{
Person* p = new Person("Scott", 25);
try
{
p->Shout();
}
catch(...)
{
delete p;
throw;
}
delete p;
}

Don't you think this is a over head of catching an exception and rethrowing it? This code becomes cumbersome if you have many pointes created. How will a smart pointer help here, lets have a look at the same code if smart pointer is used.

Collapse Copy Code

    void MakeNoise()
{
SP<Person>
 p(new Person("Scott", 25));
p->Shout();
}

We are making use of a smart pointer here; yes we don’t need to catch exception here. If the Shout method throws an exception stack unwinding will happen for the function and during this the destructor of all local object will be called, hence destructor of p will be called which will release the memory hence we are safe. So this makes it very useful to use smart pointers here.

Conclusion

Smart pointers are useful for writing safe and efficient code in C++. Make use of smart pointers and take the advantage of garbage collection. Take a look at Scott Meyers' auto_ptr implementation in STL.

Introduction

C++ is the most popular language around. Although many people have shifted to other high level languages like VB and Java, it is still the language of choice for system programming and the situations where performance can never be compromised.

C++ offers great features for dynamic memory allocation and de-allocation, but you can hardly find any C++ programmer who hasn’t been bugged by memory leaks in C++ programs. The reason is that in C++, you have to de-allocate memory yourself which is, at times, bug provoking.

Some high level languages like Java and C# provide automatic memory de-allocation facility. These languages have a built in Garbage Collector which looks for any memory which has no further reference in the program and de-allocates that memory. So programmers don’t have to worry about memory leaks. How about having Garbage Collection facility in C++ programs?

Well, we can implement simple garbage collection facility in our programs using smart pointers, but it comes at some cost. There is a small overhead of an extra integer and a character variable per instance of classes for which you implement garbage collection. All source code for these garbage collection classes are provided with this article.

What are smart pointers?

I said we can implement garbage collection using “smart” pointers. But actually what are “smart” pointers?

C++ allows you to create “smart pointer” classes that encapsulate pointers, and override pointer operators to add new functionality to pointer operations. Template feature of C++ allows you to create generic wrappers to encapsulate pointers of almost any kind.

An example of smart pointers with templates could be a class which encapsulates double dimension arrays in C++.

Collapse Copy Code

template< class T> class ArrayT
{
T** m_ptr; // for double dimension
  int sx,sy; // size of dimensions of array
  public:
ArrayT( int dim1, int dim2) // in case of ArrayT<float> b(10,20)
  {
sx=dim1;sy=dim2;
m_ptr= new T*[dim1];
for( int i=0;i<dim1;i++)
m_ptr[i]=new T[dim2];
}
T* operator[] ( < pan class=cpp-keyword>int index)
{ return m_ptr[index]; } // to add [] operator to ArrayT

~ArrayT()
{
for( int d=0;d<sx;d++)
delete [] m_ptr[d];
delete m_ptr;
}
};

This class encapsulates the functionality of double dimension arrays for any object in C++. You can extend the functionality of 2D arrays in this manner. Using the same technique, you can also implement STL style resizable collection classes like vector.

Now, coming back to garbage collection using smart pointers, how can we use smart pointers for garbage collection within the class?

What our Garbage Collector does?

We are embedding the garbage collection feature within a particular class. This simple garbage collector de-allocates memory when an object is no longer referenced, hence preventing memory leaks. This is really simple to implement.

We are using reference counting mechanism. Whenever there is a new reference to an object, we increment the reference count, and when it is no longer referenced, i.e. reference count=0, we de allocate the memory.

Implementation

The template class gcPtr<T> implements a garbage collecting pointer to any class derived from RefCount class.

Collapse Copy Code

template <class T>class RefCount
{
protected:
int refVal;
T* p;
public:
RefCount(){ refVal=0; p=(T*)this;}
void AddRef() { refVal++; }
void ReleaseRef()
{
refVal--;
if(refVal == 0)
delete [] this;
}
T* operator->(void) { return p; }
// Provide -> operator for class inheriting

// RefCount
  // Similarly you can add other overloaded
  // operators in this class //so that
  // you dont have to implement them again
  // and again. //Once you have added
  // these operators, they will be available
  // to all classes // inheriting from RefCount
  // to incorporate Garbage Collection.
};

This class implements simple reference counting. Any class which wishes to implement garbage collection should derive from this class. Note that RefCount takes a template parameter. This parameter is used to overload -> operator for the class which inherits from RefCount class to implement garbage collection. I.e.,

Collapse Copy Code

    class foo : public RefCount<foo><FOO>
{
};

gcPtr is a template class using smart pointers which encapsulates all garbage collection processes.

Collapse Copy Code

template <class T> class gcPtr
{
T* ptr;
char c;
public:
gcPtr()
{
c='0'; // called when variable declare // as gcPtr<foo> a;
  }
gcPtr(T* ptrIn)
{
ptr=ptrIn;
// called when variable declared
    // as gcPtr<foo> a=new foo;
    ptr->AddRef();
c='1';
}
// assuming we have variable gcPtr<foo> x
  operator T*(void) { return ptr; } //for x[]
  T& operator*(void) { return *ptr; } // for *x type operations
  T* operator->(void){ return ptr; } // for x-> type operations
  gcPtr& operator=(gcPtr<T> &pIn)
// for x=y where y is also gcPtr<foo> object
  {
return operator=((T *) pIn);
}
gcPtr& operator=(T* pIn)
{
if(c=='1')
// called by gcPtr& operator=(gcPtr<T>&pIn) in case of
    { // assignment
      // Decrease refcount for left hand side operand
      ptr->ReleaseRef();
// of ‘=’ operator
      ptr = pIn;
pIn->AddRef(); // Increase reference count for the Right Hand
      // operand of ‘=’ operator
      return *this;
}
else
// if c=0 i.e variable was not allocated memory when // it was declared
    { // like gcPtr<foo> x. in this case we //allocate memory using new
      // operator, this will be called
      ptr=pIn;
ptr->AddRef();
return *this
}
}
~gcPtr(void) { ptr->ReleaseRef(); } // Decrement the refcount
};

Now, let’s see what happening in gcPt class template. There are two constructors. gcPtr() is for cases when you are just declaring the variable but not assigning memory to it using new operator. gcPtr(T*) is for cases when you are assigning memory to gcPtr variable on declaration using new operator. We have overloaded T* operator to provide support for array notation []. This returns us the T* type pointer which our class is encapsulating. -> operator is also overloaded to provide support for pointer operations like x->func(). This operator also returns the T* pointer. An interesting thing is happening in the case of assignments like x=y. gcPtr& operator=(gcPtr<T> &pIn) function is called, which in turn calls gcPtr& operator=(T* pIn) function, and only the ‘if’ block of this function is executed. Check this code:

Collapse Copy Code

gcPtr& operator=(gcPtr<T> &pIn) // for x=y where y is also gcPtr<foo> object
{
return operator=((T *) pIn);
}

We are type casting the input gcPtr parameter to T*. If x=y was the assignment (where x and y are variables of gcPtr<FOO>), this means we are type casting y to foo* and calling gcPtr& operator=((foo*) y) function. Now, let’s see how garbage collection mechanism is implemented in this function. Check this ‘if’ block code:

Collapse Copy Code

  ptr->ReleaseRef();
// Decrement the reference count for ‘x’. Now if the
  //reference count is zero, memory for x will
  // be de-allocated

ptr = pIn; // assign (foo*) y to ptr which is
         //of type foo

pIn->AddRef(); // Since we have made a new reference
                   //to (foo*) y, increment
                  //Reference count for (foo*)y

return *this; // return the x variable by reference.vv

So, this explains how garbage collection is done when an object is no longer referenced.

How to use Garbage collection in your project?

Follow these steps to implement this simple garbage collection mechanism in your programs. It’s really simple.

1. Add RefCount and gcPtr classes to your project.
2. Derive your class from RefCount, passing the name of your class to RefCount as template parameter.

   For example:

   Collapse Copy Code

      class foo: public RefCount<FOO><FOO>
       {
       public:
       void func() { AfxMessageBox(“Hello World”) };
       };

3. Now, to declare a pointer to your class, use gcPtr <T> class, passing the name of your class as template parameter. gcPtr<T> is a “smart” pointer. After allocating memory using new operator in one of the methods shown below, you can use gcPtr just like your class pointer. It supports all pointer operations. You don’t need to de-allocate memory using delete operator. It will be handled by gcPtr class.

    

   Collapse Copy Code

   //First Method
       
       gcPtr<FOO> obj; // simple declaration
       obj=new foo; // Assign memory to obj
       obj->func();
       //Second Method
       gcPtr<FOO> obj=new obj;
       obj->func();

4. You can also declare an array of your class using gcPtr<T> class:
   Collapse Copy Code

       gcPtr<FOO>obj= new obj[5];
       obj[2]->func();

   => Memory will be de-allocated when your object is no longer referenced. For example:

   Collapse Copy Code

   gcPtr<FOO> obj1=new obj;
       // increment reference count for obj1 i.e refcount=1
        gcPtr<FOO> obj2=new obj; // increment reference count for obj2
       // i.e refcount=1
        obj1=obj2; // decrement reference count for obj1
       //i.e refcount=0 and increment
        // reference count for obj2 i.e refcount=2 . Memory will
       //be de-allocated
        // for obj1. Now obj1 to the same memory as obj2
        // When destructor for obj1 is called, it will decrement
       //the referencecount to 1, and
       //when destructor for obj2 is called, it will decrement it
       // to 0 and memory is de-allocated.

That’s it. Isn’t it too simple to incorporate garbage collection and prevent memory leaks in C++? Of course; yes. What all you need is, to derive your class from Refcount.

How to implement garbage collection for built in data types?

To implement garbage collection for built-in data types like int, float etc., you can write a simple wrapper for them by overloading the operators.

Collapse Copy Code

class MyInt : public gcPtr<MYINT>
{
public:
int* val;
..... // overloaded operators like ++,--,> etc
    ..... // or overload these operators in
          //RefCount base class
// so that they will be available to any class inheriting
// incorporating garbage collection
};

Instead of every time adding all operator overloads in your class, you can once modify RefCount class and provide overloaded operators for T data type, as one overloaded operator is already provided there: i.e., T* operator->(void) { return p; }.

Garbage collection in Action

Now, let's see Garbage Collection in action in a simple MFC Dialog Box application. Run your program in Debug mode and start debugging. If I am using garbage collection, here is the output from the output window:

Collapse Copy Code

    Loaded 'C:.DLL', no matching symbolic information found.
Loaded 'C:.DLL', no matching symbolic information found.
The thread 0x744 has exited with code 0 (0x0).
The program 'D:.exe' has exited with code 0 (0x0).

There is no memory leak. Now, if I am neither doing garbage collection, nor I am manually deleting the object, here is the output:

Collapse Copy Code

    Loaded 'C:.DLL', no matching symbolic information found.
Loaded 'C:.DLL', no matching symbolic information found.
Detected memory leaks!
Dumping objects ->
{65} normal block at 0x002F2C80, 16 bytes long.
Data: < ,/ > 00 00 00 00 80 2C 2F 00 CD CD CD CD CD CD CD CD
Object dump complete.
The thread 0x50C has exited with code 0 (0x0).
The program 'D:.exe' has exited with code 0 (0x0).

You can see the memory dumps. There is memory leak of 16 bytes.

I hope you enjoyed this article J. This is my first article on Code Project. Feel free to email me if you have any suggestions or if you have any problems using these classes + don’t forget to vote for me if you find this article useful :).

Contents

Smart Pointers can greatly simplify C++ development. Chiefly, they provide automatic memory management close to more restrictive languages (like C# or VB), but there is much more they can do.

I already know smart pointers, but why should I use boost?

• What are Smart Pointers?
• The first: boost::scoped_ptr<T>
• Reference counting pointers
  • Important Features
• Example: Using shared_ptr in containers
• What you absolutely must know to use boost smart pointers correctly
• Cyclic References
• Using weak_ptr to break cycles
• intrusive_ptr - lightweight shared pointer
• scoped_array and shared_array
• Installing Boost
  • Note about the sample project
  • VC6: the min/max tragedy
• Resources

What are Smart Pointers?

The name should already give it away:

A Smart Pointer is a C++ object that acts like a pointer, but additionally deletes the object when it is no longer needed.

"No longer needed" is hard to define, since resource management in C++ is very complex. Different smart pointer implementations cover the most common scenarios. Of course, different tasks than just deleting the object can be implemented too, but these applications are beyond the scope of this tutorial.

Many libraries provide smart pointer implementations with different advantages and drawbacks. The samples here use the BOOST library, a high quality open source template library, with many submissions considered for inclusion in the next C++ standard.

Boost provides the following smart pointer implementations:

Let's start with the simplest one:

The first: boost::scoped_ptr<T>

scoped_ptr is the simplest smart pointer provided by boost. It guarantees automatic deletion when the pointer goes out of scope.

A note on the samples:

The samples use a helper class, CSample, that prints diagnostic messages when it it constructed, assigned, or destroyed. Still it might be interesting to step through with the debugger. The sample includes the required parts of boost, so no additional downloads are necessary - but please read the boost installations notes, below.

The following sample uses a scoped_ptr for automatic destruction:

Using normal pointers	Using scoped_ptr
Collapse Copy Code void Sample1_Plain() { CSample * pSample(new CSample); if (!pSample->Query() ) // just some function... { delete pSample; return; } pSample->Use(); delete pSample; }	Collapse Copy Code #include "boost/smart_ptr.h" void Sample1_ScopedPtr() { boost::scoped_ptr<CSample> samplePtr(new CSample); if (!samplePtr->Query() ) // just some function... return; samplePtr->Use(); }

Using "normal" pointers, we must remember to delete it at every place we exit the function. This is especially tiresome (and easily forgotten) when using exceptions. The second example uses a scoped_ptr for the same task. It automatically deletes the pointer when the function returns 8 even in the case of an exception thrown, which isn't even covered in the "raw pointer" sample!)

The advantage is obvious: in a more complex function, it's easy to forget to delete an object. scoped_ptr does it for you. Also, when dereferencing a NULL pointer, you get an assertion in debug mode.

1. For this purpose, using scoped_ptr is more expressive than the (easy to misuse and more complex) std::auto_ptr: using scoped_ptr, you indicate that ownership transfer is not intended or allowed.

Reference counting pointers

Reference counting pointers track how many pointers are referring to an object, and when the last pointer to an object is destroyed, it deletes the object itself, too.

The "normal" reference counted pointer provided by boost is shared_ptr (the name indicates that multiple pointers can share the same object). Let's look at a few examples:

Collapse Copy Code

void Sample2_Shared()
{
// (A) create a new CSample instance with one reference
  boost::shared_ptr<CSample> mySample(new CSample);
printf("The Sample now has %i references\n", mySample.use_count()); // should be 1

// (B) assign a second pointer to it:
  boost::shared_ptr<CSample> mySample2 = mySample; // should be 2 refs by now
  printf("The Sample now has %i references\n", mySample.use_count());
// (C) set the first pointer to NULL
  mySample.reset();
printf("The Sample now has %i references\n", mySample2.use_count());  // 1

// the object allocated in (1) is deleted automatically
  // when mySample2 goes out of scope
}

Line (A) creates a new CSample instance on the heap, and assigns the pointer to a shared_ptr, mySample. Things look like this:

Then, we assign it to a second pointer mySample2. Now, two pointers access the same data:

We reset the first pointer (equivalent to p=NULL for a raw pointer). The CSample instance is still there, since mySample2 holds a reference to it:

Only when the last reference, mySample2, goes out of scope, the CSample is destroyed with it:

Of course, this is not limited to a single CSample instance, or two pointers, or a single function. Here are some use cases for a shared_ptr.

• use in containers
• using the pointer-to-implementation idiom (PIMPL)
• Resource-Acquisition-Is-Initialization (RAII) idiom
• Separating Interface from Implementation

Note: If you never heard of PIMPL (a.k.a. handle/body) or RAII, grab a good C++ book - they are important concepts every C++ programmer should know. Smart pointers are just one way to implement them conveniently in certain cases - discussing them here would break the limits of this article.

Important Features

The boost::shared_ptr implementation has some important features that make it stand out from other implementations:

• shared_ptr<T> works with an incomplete type:

  When declaring or using a shared_ptr<T>, T may be an "incomplete type". E.g., you do only a forward declaration using class T;. But do not yet define how T really looks like. Only where you dereference the pointer, the compiler needs to know "everything".

• shared_ptr<T> works with any type:

  There are virtually no requirements towards T (such as deriving from a base class).

• shared_ptr<T> supports a custom deleter

  So you can store objects that need a different cleanup than delete p. For more information, see the boost documentation.

• Implicit conversion:

  If a type U * can be implicitly converted to T * (e.g., because T is base class of U), a shared_ptr<U> can also be converted to shared_ptr<T> implicitly.

• shared_ptr is thread safe

  (This is a design choice rather than an advantage, however, it is a necessity in multithreaded programs, and the overhead is low.)

• Works on many platforms, proven and peer-reviewed, the usual things.

Example: Using shared_ptr in containers

Many container classes, including the STL containers, require copy operations (e.g., when inserting an existing element into a list, vector, or container). However, when this copy operations are expensive (or are even unavailable), the typical solution is to use a container of pointers:

Collapse Copy Code

std::vector<CMyLargeClass *> vec;
vec.push_back( new CMyLargeClass("bigString") );

However, this throws the task of memory management back to the caller. We can, however, use a shared_ptr:

Collapse Copy Code

typedef boost::shared_ptr<CMyLargeClass>  CMyLargeClassPtr;
std::vector<CMyLargeClassPtr> vec;
vec.push_back( CMyLargeClassPtr(new CMyLargeClass("bigString")) );

Very similar, but now, the elements get destroyed automatically when the vector is destroyed - unless, of course, there's another smart pointer still holding a reference. Let's have a look at sample 3:

Collapse Copy Code

void Sample3_Container()
{
typedef boost::shared_ptr<CSample> CSamplePtr;
// (A) create a container of CSample pointers:
  std::vector<CSamplePtr> vec;
// (B) add three elements
  vec.push_back(CSamplePtr(new CSample));
vec.push_back(CSamplePtr(new CSample));
vec.push_back(CSamplePtr(new CSample));
// (C) "keep" a pointer to the second:
  CSamplePtr anElement = vec[1];
// (D) destroy the vector:
  vec.clear();
// (E) the second element still exists
  anElement->Use();
printf("done. cleanup is automatic\n");
// (F) anElement goes out of scope, deleting the last CSample instance
}

What you absolutely must know to use boost smart pointers correctly

A few things can go wrong with smart pointers (most prominent is an invalid reference count, which deletes the object too early, or not at all). The boost implementation promotes safety, making all "potentially dangerous" operations explicit. So, with a few rules to remember, you are safe.

There are a few rules you should (or must) follow, though:

Rule 1: Assign and keep - Assign a newly constructed instance to a smart pointer immediately, and then keep it there. The smart pointer(s) now own the object, you must not delete it manually, nor can you take it away again. This helps to not accidentally delete an object that is still referenced by a smart pointer, or end up with an invalid reference count.

Rule 2: a _ptr<T> is not a T * - more correctly, there are no implicit conversions between a T * and a smart pointer to type T.

This means:

• When creating a smart pointer, you explicitly have to write ..._ptr<T> myPtr(new T)
• You cannot assign a T * to a smart pointer
• You cannot even write ptr=NULL. Use ptr.reset() for that.
• To retrieve the raw pointer, use ptr.get(). Of course, you must not delete this pointer, or use it after the smart pointer it comes from is destroyed, reset or reassigned. Use get() only when you have to pass the pointer to a function that expects a raw pointer.
• You cannot pass a T * to a function that expects a _ptr<T> directly. You have to construct a smart pointer explicitly, which also makes it clear that you transfer ownership of the raw pointer to the smart pointer. (See also Rule 3.)
• There is no generic way to find the smart pointer that "holds" a given raw pointer. However, the boost: smart pointer programming techniques illustrate solutions for many common cases.

Rule 2: No circular references - If you have two objects referencing each other through a reference counting pointer, they are never deleted. boost provides weak_ptr to break such cycles (see below).

Rule 3: no temporary shared_ptr - Do not construct temporary shared_ptr to pass them to functions, always use a named (local) variable. (This makes your code safe in case of exceptions. See the boost: shared_ptr best practices for a detailed explanation.)

Cyclic References

Reference counting is a convenient resource management mechanism, it has one fundamental drawback though: cyclic references are not freed automatically, and are hard to detect by the computer. The simplest example is this:

Collapse Copy Code

struct CDad;
struct CChild;
typedef boost::shared_ptr<CDad>   CDadPtr;
typedef boost::shared_ptr<CChild> CChildPtr;
struct CDad : public CSample
{
CChildPtr myBoy;
};
struct CChild : public CSample
{
CDadPtr myDad;
};
// a "thing" that holds a smart pointer to another "thing":

CDadPtr   parent(new CDadPtr);
CChildPtr child(new CChildPtr);
// deliberately create a circular reference:
parent->myBoy = child;
child->myDad = dad;
// resetting one ptr...
child.reset();

parent still references the CDad object, which itself references the CChild. The whole thing looks like this:

If we now call dad.reset(), we lose all "contact" with the two objects. But this leaves both with exactly one reference, and the shared pointers see no reason to delete either of them! We have no access to them anymore, but they mutually keep themselves "alive". This is a memory leak at best; in the worst case, the objects hold even more critical resources that are not released correctly.

The problem is not solvable with a "better" shared pointer implementation (or at least, only with unacceptable overhead and restrictions). So you have to break that cycle. There are two ways:

1. Manually break the cycle before you release your last reference to it
2. When the lifetime of Dad is known to exceed the lifetime of Child, the child can use a normal (raw) pointer to Dad.
3. Use a boost::weak_ptr to break the cycle.

Solutions (1) and (2) are no perfect solutions, but they work with smart pointer libraries that do not offer a weak_ptr like boost does. But let's look at weak_ptr in detail:

Using weak_ptr to break cycles

Strong vs. Weak References:

A strong reference keeps the referenced object alive (i.e., as long as there is at least one strong reference to the object, it is not deleted). boost::shared_ptr acts as a strong reference. In contrast, a weak reference does not keep the object alive, it merely references it as long as it lives.

Note that a raw C++ pointer in this sense is a weak reference. However, if you have just the pointer, you have no ability to detect whether the object still lives.

boost::weak_ptr<T> is a smart pointer acting as weak reference. When you need it, you can request a strong (shared) pointer from it. (This can be NULL if the object was already deleted.) Of course, the strong pointer should be released immediately after use. In the above sample, we can decide to make one pointer weak:

Collapse Copy Code

struct CBetterChild : public CSample
{
weak_ptr<CDad> myDad;
void BringBeer()
{
shared_ptr<CDad> strongDad = myDad.lock(); // request a strong pointer
    if (strongDad)                      // is the object still alive?
      strongDad->SetBeer();
// strongDad is released when it goes out of scope.
    // the object retains the weak pointer
  }
};

See the Sample 5 for more.

intrusive_ptr - lightweight shared pointer

shared_ptr offers quite some services beyond a "normal" pointer. This has a little price: the size of a shared pointer is larger than a normal pointer, and for each object held in a shared pointer, there is a tracking object holding the reference count and the deleter. In most cases, this is negligible.

intrusive_ptr provides an interesting tradeoff: it provides the "lightest possible" reference counting pointer, if the object implements the reference count itself. This isn't so bad after all, when designing your own classes to work with smart pointers; it is easy to embed the reference count in the class itself, to get less memory footprint and better performance.

To use a type T with intrusive_ptr, you need to define two functions: intrusive_ptr_add_ref and intrusive_ptr_release. The following sample shows how to do that for a custom class:

Collapse Copy Code

#include "boost/intrusive_ptr.hpp"

// forward declarations
class CRefCounted;
namespace boost
{
void intrusive_ptr_add_ref(CRefCounted * p);
void intrusive_ptr_release(CRefCounted * p);
};
// My Class
class CRefCounted
{
private:
long    references;
friend void ::boost::intrusive_ptr_add_ref(CRefCounted * p);
friend void ::boost::intrusive_ptr_release(CRefCounted * p);
public:
CRefCounted() : references(0) {}   // initialize references to 0
};
// class specific addref/release implementation
// the two function overloads must be in the boost namespace on most compilers:
namespace boost
{
inline void intrusive_ptr_add_ref(CRefCounted * p)
{
// increment reference count of object *p
    ++(p->references);
}
inline void intrusive_ptr_release(CRefCounted * p)
{
// decrement reference count, and delete object when reference count reaches 0
   if (--(p->references) == 0)
delete p;
}
} // namespace boost

This is the most simplistic (and not thread safe) implementation. However, this is such a common pattern, that it makes sense to provide a common base class for this task. Maybe another article ;)

scoped_array and shared_array

They are almost identical to scoped_ptr and shared_ptr - only they act like pointers to arrays, i.e., like pointers that were allocated using operator new[]. They provide an overloaded operator[]. Note that neither of them knows the length initially allocated.

Installing Boost

Download the current boost version from boost.org, and unzip it to a folder of your choice. The unzipped sources use the following structure (using my folders):

I add this folder to the common includes of my IDE:

• in VC6, this is Tools/Options, Directories tab, "Show Directories for... Include files",
• in VC7, this is Tools/Options, then Projects/VC++ directories, "Show Directories for... Include files".

Since the actual headers are in the boost\ subfolder, my sources has #include "boost/smart_ptr.hpp". So everybody reading the source code knows immediately you are using boost smart pointers, not just any ones.

Note about the sample project

The sample project contains a sub folder boost\ with a selection of boost headers required. This is merely so you can download and compile the sample. You should really download the complete and most current sources (now!).

VC6: the min/max tragedy

There is a "little" problem with VC6 that makes using boost (and other libraries) a bit problematic out of the box.

The Windows header files define macros for min and max, and consequently, these respective functions are missing from the (original) STL implementation. Some Windows libraries such as MFC rely on min/max being present. Boost, however, expects min and max in the std:: namespace. To make things worse, there is no feasible min/max template that accepts different (implicitly convertible) argument types, but some libraries rely on that.

boost tries to fix that as good as they can, but sometimes you will run into problems. If this happens, here's what I do: put the following code before the first include:

Collapse Copy Code

#define _NOMINMAX            // disable windows.h defining min and max as macros
#include "boost/config.hpp"  // include boosts compiler-specific "fixes"
using std::min;              // makle them globally available
using std::max;

This solution (as any other) isn't without problems either, but it worked in all cases I needed it, and it's just one place to put it.

Resources

Not enough information? More Questions?

• Boost home page
• Download boost
• smart pointer overview

• boost users mailing list

  Questions about boost? That's the place to go.

Articles on Code Project:

• An Introduction to boost by Andrew Walker
• Designing Robust Objects with boost by Jim D'Agostino, a very interesting article: it seems to cover too much topics at once, but it excels at showing how different tools, mechanisms, paradigms, libraries, etc. work together.

Please note: While I am happy about (almost) any feedback, please do not ask boost-specific questions here. Simply put, boost experts are unlikely to find your question here (and I'm just a boost noob). Of course, if you have questions, complaints, or recommendations regarding the article or the sample project, you are welcome.