수안이의 컴퓨터 연구실

If a man begins with certainties, he shall end in doubts;

But if he will be content to begin with doubts,

He shall end in certainties.

[Francis Bacon 1561-1626]

If there is one thing I have learned over the past few years, it is not to underestimate the power of assert(). It comes with your compiler and can be found either in cassert or assert.h.

The reason I love assert is because it looks after me and helps me find bugs I was sure weren’t there. I mean, we all write bugfree software, right? Yeah right. Well there have been many Kodak moments when an assert fired on something I was dead sure could never happen; I should be a rich man as the look on my face was priceless.

If you are not familiar with asserts, you should start using them right now. Use  assert to check that your code is working the way you expect it to or be prepared to pay the price. No not for my face, but for long nights behind the debugger, ticking away possible problem sources until you have your own Kodak moment.

When do you use assert, you ask? Simple… whenever you can use it to verify the truth of a situation: ‘this pointer can never be null’, ‘this number is never smaller than zero’, ‘there is always at least one customer stored in this list’, ‘this code won’t be used the next millennium, two digits are fine’.

Use proper error handling when you can check for things that can go wrong. Use asserts on things you are sure can’t go wrong.

Trust me… the sillier the assert… the more valuable it is. I tested this once myself, grinning, thinking ‘this is ridiculous, want to bet it will never fire?’, only to have it triggered a couple of months later! And because the assert was so preposterous and silly I immediately knew which conditions were breaking my code.

assert.

1. To state or express positively, affirm: asserted his innocence
2. To defend or maintain (one’s rights, for example)

The important thing to remember is that asserts are only compiled into your code when the NDEBUG macro is not defined. So in the final optimized version of your application, they are not there to bloat or to slow things down! The only investment you have to make is typing them out while you are working on those classes and functions. It will pay you back greatly when it helps you shorten the time it takes to track down bugs.

Face it… we all write code on assumptions we make about the situation the code will be running in. Assert you are in that situation, because your code base will grow beyond the picture you have of it in your mind.

Though we will be implementing our customized version of assert here, all you need to do is include assert.h and you are ready to use the assert macro that comes with it:

// assert.h
#ifndef NDEBUG
void __assert(const char *, const char *, int);
#define assert(e) \
     ((e) ? (void)0 : __assert(#e,__FILE__,__LINE__))
#else
#define assert(unused) ((void)0)
#endif

The __assert helper function prints an error message to stderr and the program is halted by calling abort(). It is possible that the implementation that comes with your compiler varies slightly, but you get the idea.

Lets use a simple example function:

void writeString(char const *string) {
assert( 0 != string );
...
}

In the unfortunate situation that the pointer to string is NULL, execution will halt and you will be offered the possibility of opening the debugger and jumping to the location in the source where the assertion failed. This can be very handy as you can examine the call stack, memory, registers, and so forth, and are likely to catch the perpetrator red handed!

Although I am ranting about why you should use assert, this article is aimed at showing you how to implement your own version using preprocessor macros.

Here is a very basic version that doesn’t even halt execution:

#ifndef NDEBUG
# define ASSERT( isOK ) \
( (isOK) ? \
     (void)0 : \
     (void)printf(“ERROR!! Assert ‘%s’ failed on line %d ” \
      “in file ‘%s’\n”, #isOK, __LINE__, __FILE__) )
#else
# define ASSERT( unused ) do {} while( false )
#endif

Notice that we don’t need a helper function to get information onto the screen. (I am sticking to printf in the following examples, but there is nothing stopping you from using fprintf and stderr instead.) The stringize macro operator (#) names the condition for us in the printf statement, adding quotes as well and the predefined __LINE__ and __FILE__ macros help to identify the location of the assert.

The do { } while ( false ) statement for the unused version of assert, I used to make sure that the user cannot forget to conclude his assert statement with a semicolon. The compiler will optimize it away, and I consider it a slightly better way to say that I am not doing anything.

We are only one step away from halting our application’s execution (don’t forget to include stdlib.h):

#ifndef NDEBUG
# define ASSERT( isOK ) \
if ( !isOK ) { \
 (void)printf(“ERROR!! Assert ‘%s’ failed on line %d “ \
  “in file ‘%s’\n”, #isOK, __LINE__, __FILE__) ); \
 abort(); \
}
#else
# define ASSERT( unused ) do {} while ( false )
#endif

In case writeString is called with a NULL pointer now, we are told what went wrong, where it went wrong and the application is halted.

When you are using the Microsoft Visual C++ 7.1 compiler, you’ll be presented with a dialog screen:

After pressing Retry you are presented with more dialogs and finally... you end up in the debugger.

The problem with abort() is that it doesn’t let you resume execution after you’ve concluded that the assert was benign; or maybe you are interested in what happens immediately after the assert? You need to disable the assert (never a good thing), recompile and restart your application.

There are other ways to halt execution and you will have to look in your compiler’s documentation to discover what the correct call is, but with Visual C++ it’s an interrupt call:

__asm { int 3 }

When our application halts again on the writeString function, we’ll encounter the following dialog (did you recognize it? We actually came across this dialog when halting the application with the abort() function!) :

It is not a problem to continue execution now, if we think this is responsible… that is you are often recommended to implement your own assert functionality.

Wouldn’t it be nice to be able to add some hints or remarks along with the location of the assert? When the assert fires and you don’t have a debugger available, this message might still tell you what the problem is:

void writeString(char const *string) {
assert(0!=string, “A null pointer was passed to writeString()!”);
...
}

The simplest solution is to just expand the assert macro and make it accept a message as well as a condition:

#ifndef NDEBUG
# define ASSERT( isOK, message ) \
if ( !(isOK) ) { \
 (void)printf(“ERROR!! Assert ‘%s’ failed on line %d “ \
  “in file ‘%s’\n%s\n”, \
     #isOK, __LINE__, __FILE__, #message); \
  __asm { int 3 } \
 }
#else
# define ASSERT( unused, message ) do {} while ( false )
#endif

Again the stringize operator helps us to stuff the message we want into the printf statement. We could call it a day now, but I am a very lazy coder… I do not want to be forced to put messages into the assert, sometimes I just want to assert.

Of course it is possible to write an ASSERT(condition) and an ASSERTm(condition, message) macro, but did I mention I am a forgetful coder too? I’d much rather have a single ASSERT statement that can do both.

The first thing that comes to mind is the fact I could do this easily with a function:

void MyAssert(bool isOK, char const *message=””) {
if ( !isOK ) {
 (void)printf(“ERROR!! Assert ‘%s’ failed on line %d “
  “in file ‘%s’\n%s\n”,
  __LINE__, __FILE__, message);
 __asm { int 3 } \
}
}

So maybe if I declared another function:

void NoAssert(bool isOK, char const *message=””) {}

And then defined assert as:

#ifndef NDEBUG
# define ASSERT MyAssert
#else
# define ASSERT NoAssert
#endif

While this seems like a quick solution, I have completely lost my extra debug information! The line information is the same now for every assert… oh… the compiler substitutes __LINE__ with the actual line number it is compiling at that moment, and since we are making a function call – all line numbers lead to the MyAssert function!

Alexandrescu demonstrates a great way around this problem [Alexandrescu]. (It is also a great article showing how you can take assertions to a higher level after this one, by making them throw exceptions!)

#ifndef NDEBUG
#define ASSERT \
struct MyAssert { \
MyAssert(bool isOK, char const *message=””) { \
 if ( !isOK ) { \
  (void)printf(“ERROR!! Assert failed in “ \
   “file ‘%s’\n%s\n”, __FILE__, message); \
   __asm { int 3 } \
  } \
 } \
} myAsserter = MyAssert
#endif

For some reason my Visual C++ 7.1 compiler will not accept the __LINE__ macro next to the __FILE__ macro in the code above. The strange thing is that the __FILE__ macro works fine, but with __LINE__ it complains:

error C2065: '__LINE__Var' : undeclared identifier

It is never easy, but I do not want to give up at this point. Since the macro is expanded as a single line into the place where we are calling it, and since the compiler apparently has no objection to me assigning __LINE__ as a default parameter in a constructor, let's try again:

#ifndef NDEBUG
#define ASSERT \
struct MyAssert { \
int mLine; \
MyAssert(int line=__LINE__) : mLine(line) {} \
MyAssert(bool isOK, char const *message=””) { \
 if ( !isOK ) { \
  (void)printf(“ERROR!! Assert failed on “ \
   “line %d in file ‘%s’\n%s\n”, \
   MyAssert().mLine, __FILE__, message); \
  __asm { int 3 } \
 } \
}\
} myAsserter = MyAssert
#endif

Now that we have our line information back, we are nearly there; as soon as we add a second assert, the compiler complains that we are redefining the struct MyAssert! If only we could keep the struct declaration local… and again Alexandrescu shows us how [Alexandrescu]:

#ifndef NDEBUG
#define ASSERT \
if ( false ) {} else struct LocalAssert { \
 int mLine; \
LocalAssert(int line=__LINE__) : mLine(line) {} \
LocalAssert(bool isOK, char const *message=””) { \
 if ( !isOK ) { \
  (void)printf(“ERROR!! Assert failed on “ \
   “line %d in file ‘%s’\n%s\n”, \
   LocalAssert().mLine, __FILE__, message); \
  __asm { int 3 } \
} \
} myAsserter = LocalAssert
#else
#define ASSERT \
if ( true ) {} else struct NoAssert { \
NoAssert(bool isOK, char const *message=””) {} \
} myAsserter = NoAssert
#endif

There is a lot of fun to be had with macros and sometimes it is possible to create the wildest incantations with them [Niebler/Alexandrescu]. I hope you are convinced that despite the fact that they can be considered evil, there is something magical about them as well.

As a final example I will show you how to create personal and customizable debug streams in the next article… all with macros.

[STL] – The Standard Template Library

< comes standard with your compiler but this one is very portable>

http://www.stlport.org

[BOOST] – Boost C++ Libraries

http://www.boost.org

[ACE] – The ADAPTIVE Communication Environment

http://www.cs.wustl/edu/~schmidt/ACE.html

[Niebler] – Eric Niebler

“Conditional Love: FOREACH Redux”

http://www.artima.com/cppsource/foreach.html

[Alexandrescu] – Andrei Alexandrescu

Assertions

http://www.cuj.com/documents/s=8248/cujcexp2104alexandr/

Whence and what art thou, execrable shape?

[John Milton 1608-1674]

The Preprocessor and the Compiler

Before the compiler interprets your code, the preprocessor handles it. Its task is to scan through your code and to look for preprocessor instructions; these can for example be used to replace certain tokens with string or numerical values, or to blank out complete sections of the code before the compiler sees it. You can recognize these instructions from the pound (#) symbol that needs to precede every preprocessor instruction.

We are going to examine these instructions and see how they are used in general. Most probably you have been using at least one of them without giving it much thought: ‘#include’. Still, this is an instruction that is handled by the preprocessor and not by the compiler. It tells it to replace the directive with the contents of the file named after it.

One of the problems a large C++ project can face is long compilation time. This can happen when ‘#include’ is used carelessly; to compile a single source, the preprocessor might (indirectly) be pasting thousands of lines of headers in front of it!

When you use third party libraries like STL-port or Boost, you will find that macros can be very useful for building different code configurations. If you have to write portable C++ code you won’t be able to live without them… however you will most probably have grown to dislike them as well.

Don’t be misled by the fact that preprocessor macros may look deceptively simple. As I’ve said before, with C++ things can become as complex as you want them to be, and to be frank, a lot of great code I have seen involved the use of macros one way or another. Maybe this is because they provide the possibility of extending the language in such a cheeky (and sneaky) way.

Let's not get ahead of ourselves. We'll first look at what the preprocessor is used for most: string substitution and conditional compilation.

The preprocessor literally changes your code (following the instructions you provide of course) and the result is a new source file, a temporary file that you cannot see but which is fed to the compiler. To specify which string tokens you want to have substituted you use the ‘#define’ directive.

For example, when you want to make use of arrays, you will have to specify how big you want one to be. By defining a MAX_STR_LEN token, you can define how big this array is once, instead of having to repeat this value throughout your code.

#define MAX_STR_LEN 80
int main(int argc, char const *argv[]) {
int anArray[MAX_STR_LEN];
for ( int idx=0; idx<MAX_STR_LEN; ++idx )
 anArray[idx]=0;
return 0;
}

It is usually not a good idea to use ‘#define’ as a substitute for constants; the preprocessor merely does a string substitution and doesn’t perform any typechecking. Depending on your debugger it can make it difficult to interpret values during a debug session.

In this case it would have been better to use a constant value:

static int const MAX_STR_LEN=80;

There are programmers that use ‘#define’ to specify constants, so be wary when you detect these. Still I think it is better to use a ‘#define’ then it is to litter your values magically throughout the code.

Imagine that the maximum string length ise shrunk to 72,.and somewhere in the code there is a for-loop that was overlooked, and would still loop until 80. An overflow has been created and worse yet, this may only become clear when the application is run in optimized mode! The loop will modify a section of the memory, causing your application to crash in a mysterious way… oh the agony when you discover the overlooked for-loop.

Sometimes string substitution can be used to help makes things clearer as well… though some consider the following deviation to be distracting:

#define EVER ; ;

for ( EVER ) { …}

When you use the preprocessor for string substitution it can do more than simply replace tokens with values. It is possible to quote strings that were passed as a parameter and you can concatenate two strings together into one.

The stringizing operator (#) substitutes the macro variable following it with its value and puts quotes around it.

For example:

#define LOG(x) std::cout << #x << std::endl

When used like:

LOG(Hello World);

will be substituted into and presented to the compiler as:

std::cout << “Hello World” << std::endl;

With the concatenation operator (##) you can tie separate strings into a new single identifier. There are many useful things you can do with this and we’ll actually need this operator when we implement customizable streams.

It is also possible to drive things to extremes. There is a company I know of that requires in its coding standard that you use their ‘Simplified Hungarian naming convention’. This means that a function that takes a const reference to an object MyClass doesn’t look like:

void foo ( MyClass const &obj );

But in their code looks like:

void foo ( rcMyClass obj );

While this might save you some typing effort, I wouldn’t recommend making such drastic changes to the C++ language. Still as an example… how did it ever get this far?

#define DECLARE_HUNGARIAN( cls ) typedef cls const & rc##cls; \
      typedef cls *       p##cls;

Now you’ve made the following code possible:

DECLARE_HUNGARIAN( MyClass )
pMyObject bar();

Macro Functions

The ‘#define’ directive is very versatile and powerful, given the simple fact that it can replace one string with another string: we can create macro functions.

#define SQUARE(x) ( (x) * (x) )

The MIN and MAX macros are also often quoted as examples:

#define MIN(x,y) ( (x) < (y) ? (x) : (y) )
#define MAX(x,y) ( (x) > (y) ? (x) : (y) )

You have to remember that all this does is string substitution, and any form of type checking is completely lacking!

An important note is that the opening parenthesis for the parameter list must immediately follow the macro name. There are no spaces allowed, since the preprocessor will otherwise consider it to be a regular string substitution.

In case you wonder why the parameters are all wrapped in parenthesis again, consider what would happen if we’d defined SQUARE as:

#define SQUARE(x) ( x * x )

Now why does the following give a result of 11 instead of 25?

int n = SQUARE( 2 + 3 );

Ouch this is not what we intended:

int n = 2 + 3 * 2 + 3;

But using parenthesis it is correct again:

int n = (2 + 3) * (2 + 3)

One more way to use ‘#define’ is to declare that a particular token is defined. This token can be used in combination with the precompiler commands “#if”, “#elif”, “#else” and “#endif” to test whether or not the preprocessor should include the code that follows the directive.

To see if a token is defined you use “#if defined” or “#elif defined” and to see if a token is not defined you use “#if !defined” or “#elif !defined”.  You can use the logical ‘&&’ and ‘||’ operators to concatenate instructions.

If for some reason you would like to remove a token from the table the preprocessor stores it in, you can undefine it with ‘#undef’.

A common use is to define a token DEBUG when compiling non-optimized code. If you use the Microsoft Developer Environment, a token _DEBUG is automatically defined for your project’s Debug configuration.

#include <stdio.h>
#define MYDEBUG
static int const MAX_STR_LEN 80;

int main(int argc, char const *argv[]) {
int anArray[MAX_STR_LEN];
for (int idx=0; idx<MAX_STR_LEN; ++idx) {
#ifdef MYDEBUG
 (void)printf(“%d “, idx);
#endif
 anArray[idx]=0;
}
}

First the precompiler runs into the ‘#include’ instruction, so it reads the ‘stdio.h’ file (which it can find using your project’s header include path) and pastes it into the temporary source file it is going to feed to the compiler. Next it encounters the ‘#define’ instruction and it stores the MYDEBUG token in a lookup table.

Finally when it comes across the ‘#ifdef’ instruction it checks whether MYDEBUG was defined in its lookup table and when this is the case it will continue to write everything it finds until the ‘#endif’ instruction into an intermediate source file.

When it cannot find the token it will check whether the next instruction is another comparison “#elif”, tells it to follow that route otherwise “#else” or that the end of the block was reached “#endif”.

If you look at the macros used to configure STL-Port (STL), Boost (BOOST) or ACE (ACE), things can become rather complex. Handy as macros can be, they do not make the code easer to read (and thus understand). Here is a snippet from the boost thread class:

class BOOST_THREAD_DECL thread : private noncopyable {
...
private:
#if defined(BOOST_HAS_WINTHREADS)
   void* m_thread;
   unsigned int m_id;
#elif defined(BOOST_HAS_PTHREADS)
private:
   pthread_t m_thread;
#elif defined(BOOST_HAS_MPTASKS)
   MPQueueID m_pJoinQueueID;
   MPTaskID m_pTaskID;
#endif
   bool m_joinable;
};

Because the macros are obfuscating which variables are needed here (because different platforms offer different facilities), it is easy to overlook that on Linux this would filter into:

private:
private:
   pthread_t m_thread;
   bool m_joinable;
};

When you want your code to be portable across different platforms, preprocessor macros will help you to maintain a single source tree. Unfortunately your eyes will have to deal with all possibilities, instead of the single one that your compiler might be choking on.

When there are so many trees it becomes difficult to see the forest.

As your application grows, you will have to organize your code among multiple source and header files. All these sources are compiled into object files, which are linked together into possibly a single executable.

Now that you are using multiple classes, many header files will have to be included into each source file. Sometimes header files will include other header files, and it might be possible that one header file will be included multiple times into a single source file.

Let’s create the ubiquitous Animal class from which we’ll derive a Hippopotamus and a Crocodile. Both classes will have to include the Animal header to be able to derive from Animal. To make things easier for whoever wants to play with a Hippopotamus and/or a Crocodile, we’ll include the Animal class in both respective header files.

Now if you are going to use them together, you’ll be including the Animal header twice. Unless you make sure it is included only once, the compiler will start complaining about multiple definitions. This is why we need inclusion guards:

#ifndef _ANIMAL_H
#define _ANIMAL_H
... // your code goes here
#endif

When the preprocessor tries to include the animal header more than once, it will find that _ANIMAL_H is already defined in its definitions table and skip the header. There is a preprocessor directive that takes care of this for the Microsoft compiler: ‘#pragma once’, but you have to remember that this makes your headers non-portable. So why not stick to inclusion guards instead?

Displaying the Intermediate Form

One of the problems with macros is that it can be very hard to deduce what the state of the preprocessor will be when it reaches a certain directive. If you’ve tried porting STL-port across different platforms, you will know what I am talking about: somewhere at the start a definition is put into the preprocessor’s table, cascading through different header files, down to the point where you are interested to see whether a piece is included in the final source that goes to the compiler or not.

Oh the hairs I would have pulled out of my head if it had not been possible to tell the compiler to show us what it sees. Start a shell and make sure you can use your compiler from the command line. If you are using the Microsoft compiler the following command will dump the output from the preprocessor :

cl /EP myfile.cpp

When you are using gcc it can be as simple as:

gcc –E myfile.cpp

Just invoke the help on the compiler to see which command line argument you’ll need. Remember, as your project grows more complex, you will have to provide the inclusion paths to headers that are not present in the same directory.

Most compilers come standard with a number of macros predefined: __DATE__ , __TIME__ , __LINE__ and __FILE__ .  These macros are very useful when you have to debug different builds. The date and time macros are translated to the date and moment the source was compiled. The line macro translates to the line number it appeared on in the source file and the file macro is translated to the actual filename of the source.

You will see that these macros come in handy when we start customizing some assert functionality.

Macro Troubles

Hopefully you are aware that macros are evil and can cause you a lot of headaches. Even though they have their clear benefits, they can cause a lot of trouble as well. There are four types of problems you can expect when using them.

Macros are not type-safe. When you find that typesafety might be an issue when you are implementing a macro function, you might want to consider replacing it with a templated function.

Macros have to be defined on one line. Things can become pretty complex and hard to read if your macro function extends over several lines. (You can make your macro span several lines by adding a backslash character (\) at the end of every line, except for the last).

Macros perform simple string substitution. This means that there is no such thing as a macro function call; the code defined in the macro is going to be pasted wherever that macro is used. This can cause considerable bloat in your source.

Because macros are expanded inline, not all debuggers can display the contents of the macro during a debug session. This means that you have no means to verify the way your macro function is being executed. This can lead to a lot of pain, only to discover you’ve forgotten a couple of parentheses!

As rough and coarse they may be, there are many nice tricks you can perform with preprocessor macros. Just take a look at the excellent crafted BOOST_FOREACH [Niebler] macro.

You will find a whole new dimension when you are able to combine macros and templates in meaningful ways. Soon I will be able to present to you the Active Object pattern and a nice macro that simplifies the implementation of this pattern using the ACE [ACE] library.

But first things first. Next time we’ll create a custom assert.

References

[STL] – The Standard Template Library

< comes standard with your compiler but this one is very portable>

http://www.stlport.org

[BOOST] – Boost C++ Libraries

http://www.boost.org

[ACE] – The ADAPTIVE Communication Environment

http://www.cs.wustl/edu/~schmidt/ACE.html

[Niebler] – Eric Niebler

“Conditional Love: FOREACH Redux”

http://www.artima.com/cppsource/foreach.html

[Alexandrescu] – Andrei Alexandrescu

Assertions

http://www.cuj.com/documents/s=8248/cujcexp2104alexandr/

Multithreading is becoming an increasingly important part of modern programming. One reason for this is that multithreading enables a program to make the best use of available CPU cycles, thus allowing very efficient programs to be written. Another reason is that multithreading is a natural choice for handling event-driven code, which is so common in today’s highly distributed, networked, GUI-based environments. Of course, the fact that the most widely used operating system, Windows, supports multithreading is also a factor. Whatever the reasons, the increased use of multithreading is changing the way that programmers think about the fundamental architecture of a program. Although C++ does not contain built-in support for multithreaded programs, it is right at home in this arena.

Because of its growing importance, this chapter explores using C++ to create multithreaded programs. It does so by developing two multithreaded applications. The first is a thread control panel, which you can use to control the execution of threads within a program. This is both an interesting demonstration of multithreading and a practical tool that you can use when developing multithreaded applications. The second example shows how to apply multithreading to a practical example by creating a modified version of the garbage collector from Chapter 2 that runs in a background thread.

This chapter also serves another purpose: it shows how adept C++ is at interfacing directly to the operating system. In some other languages, such as Java, there is a layer of processing between your program and the OS. This layer adds overhead that can be unacceptable for some types of programs, such as those used in a real-time environment. In sharp contrast, C++ has direct access to low-level functionality provided by the operating system. This is one of the reasons C++ can produce higher performance code.

What Is Multithreading?

Before beginning, it is necessary to define precisely what is meant by the term multithreading. Multithreading is a specialized form of multitasking. In general, there are two types of multitasking: process-based and thread-based. A process is, in essence, a program that is executing. Thus, process-based multitasking is the feature that allows your computer to run two or more programs concurrently. For example, it is process-based multitasking that allows you to run a word processor at the same time you are using a spreadsheet or browsing the Internet. In process-based multitasking, a program is the smallest unit of code that can be dispatched by the scheduler.

A thread is a dispatchable unit of executable code. The name comes from the concept of a “thread of execution.” In a thread-based multitasking environment, all processes have at least one thread, but they can have more. This means that a single program can perform two or more tasks concurrently. For instance, a text editor can be formatting text at the same time that it is printing, as long as these two actions are being performed by two separate threads. The differences between process-based and thread-based multitasking can be summarized like this: Process-based multitasking handles the concurrent execution of programs. Thread-based multitasking deals with the concurrent execution of pieces of the same program.

In the preceding discussions, it is important to clarify that true concurrent execution is possible only in a multiple-CPU system in which each process or thread has unrestricted access to a CPU. For single CPU systems, which constitute the vast majority of systems in use today, only the appearance of simultaneous execution is achieved. In a single CPU system, each process or thread receives a portion of the CPU’s time, with the amount of time determined by several factors, including the priority of the process or thread. Although truly concurrent execution does not exist on most computers, when writing multithreaded programs, you should assume that it does. This is because you can’t know the precise order in which separate threads will be executed, or if they will execute in the same sequence twice. Thus, its best to program as if true concurrent execution is the case.

Multithreading changes the fundamental architecture of a program. Unlike a single-threaded program that executes in a strictly linear fashion, a multithreaded program executes portions of itself concurrently. Thus, all multithreaded programs include an element of parallelism. Consequently, a major issue in multithreaded programs is managing the interaction of the threads.

As explained earlier, all processes have at least one thread of execution, which is called the main thread. The main thread is created when your program begins. In a multithreaded program, the main thread creates one or more child threads. Thus, each multithreaded process starts with one thread of execution and then creates one or more additional threads. In a properly designed program, each thread represents a single logical unit of activity.

The principal advantage of multithreading is that it enables you to write very efficient programs because it lets you utilize the idle time that is present in most programs. Most I/O devices, whether they are network ports, disk drives, or the keyboard, are much slower than the CPU. Often, a program will spend a majority of its execution time waiting to send or receive data. With the careful use of multithreading, your program can execute another task during this idle time. For example, while one part of your program is sending a file over the Internet, another part can be reading keyboard input, and still another can be buffering the next block of data to send.

Why Doesn’t C++ Contain Built-In Support for Multithreading?

C++ does not contain any built-in support for multithreaded applications. Instead, it relies entirely upon the operating system to provide this feature. Given that both Java and C# provide built-in support for multithreading, it is natural to ask why this isn’t also the case for C++. The answers are efficiency, control, and the range of applications to which C++ is applied. Let’s examine each.

By not building in support for multithreading, C++ does not attempt to define a “one size fits all” solution. Instead, C++ allows you to directly utilize the multithreading features provided by the operating system. This approach means that your programs can be multithreaded in the most efficient means supported by the execution environment. Because many multitasking environments offer rich support for multithreading, being able to access that support is crucial to the creation of high-performance, multithreaded programs.

Using operating system functions to support multithreading gives you access to the full range of control offered by the execution environment. Consider Windows. It defines a rich set of thread-related functions that enable finely grained control over the creation and management of a thread. For example, Windows has several ways to control access to a shared resource, including semaphores, mutexes, event objects, waitable timers, and critical sections. This level of flexibility cannot be easily designed into a language because the capabilities of operating systems differ. Thus, language-level support for multithreading usually means offering only a “lowest common denominator” of features. With C++, you gain access to all the features that the operating system provides. This is a major advantage when writing high-performance code.

C++ was designed for all types of programming, from embedded systems in which there is no operating system in the execution environment to highly distributed, GUI-based end-user applications and everything in between. Therefore, C++ cannot place significant constraints on its execution environment. Building in support for multithreading would have inherently limited C++ to only those environments that supported it and thus prevented C++ from being used to create software for nonthreaded environments.

In the final analysis, not building in support of multithreading is a major advantage for C++ because it enables programs to be written in the most efficient way possible for the target execution environment. Remember, C++ is all about power. In the case of multithreading, it is definitely a situation in which “less is more.”

What Operating System and Compiler?

Because C++ relies on the operating system to provide support for multithreaded programming, it is necessary to choose an operating system as the target for the multithreaded applications in this chapter. Because Windows is the most widely used operating system in the world, it is the operating system used in this chapter. However, much of the information can be generalized to any OS that supports multithreading.

Because Visual C++ is arguably the most widely used compiler for producing Windows programs, it is the compiler required by the examples in this chapter. The importance of this is made apparent in the following section. However, if you are using another compiler, the code can be easily adapted to accommodate it.

NOTE

Windows offers a wide array of Application Programming Interface (API) functions that support multithreading. Many readers will be at least somewhat familiar with the multithreading functions offered by Windows, but for those who are not, an overview of those used in this chapter is presented here. Keep in mind that Windows provides many other multithreading-based functions that you might want to explore on your own.

To use Windows’ multithreading functions, you must include <windows.h> in your program.

To create a thread, the Windows API supplies the CreateThread( ) function. Its prototype is shown here:

  HANDLE CreateThread(LPSECURITY_ATTRIBUTES secAttr,
                            SIZE_T stackSize,
                            LPTHREAD_START_ROUTINE threadFunc,
                            LPVOID param,
                            DWORD flags,
                            LPDWORD threadID);

Here, secAttr is a pointer to a set of security attributes pertaining to the thread. However, if secAttr is NULL, then the default security descriptor is used.

Each thread has its own stack. You can specify the size of the new thread’s stack in bytes using the stackSize parameter. If this integer value is zero, then the thread will be given a stack that is the same size as the creating thread. In this case, the stack will be expanded, if necessary. (Specifying zero is the common approach taken to thread stack size.)

Each thread of execution begins with a call to a function, called the thread function, within the creating process. Execution of the thread continues until the thread function returns. The address of this function (that is, the entry point to the thread) is specified in threadFunc. All thread functions must have this prototype:

  DWORD WINAPI threadfunc(LPVOID param);

Any argument that you need to pass to the new thread is specified in CreateThread( )’s param. This 32-bit value is received by the thread function in its parameter. This parameter may be used for any purpose. The function returns its exit status.

The flags parameter determines the execution state of the thread. If it is zero, the thread begins execution immediately. If it is CREATE_SUSPEND, the thread is created in a suspended state, awaiting execution. (It may be started using a call to ResumeThread( ), discussed later.)

The identifier associated with a thread is returned in the long integer pointed to by threadID.

The function returns a handle to the thread if successful or NULL if a failure occurs. The thread handle can be explicitly destroyed by calling CloseHandle( ). Otherwise, it will be destroyed automatically when the parent process ends.

As just explained, a thread of execution terminates when its entry function returns. The process may also terminate the thread manually, using either TerminateThread( ) or ExitThread( ), whose prototypes are shown here:

  BOOL TerminateThread(HANDLE thread, DWORD status);
  VOID ExitThread(DWORD status);

For TerminateThread( ), thread is the handle of the thread to be terminated. ExitThread( ) can only be used to terminate the thread that calls ExitThread( ). For both functions, status is the termination status. TerminateThread( ) returns nonzero if successful and zero otherwise.

Calling ExitThread( ) is functionally equivalent to allowing a thread function to return normally. This means that the stack is properly reset. When a thread is terminated using TerminateThread( ), it is stopped immediately and does not perform any special cleanup activities. Also, TerminateThread( ) may stop a thread during an important operation. For these reasons, it is usually best (and easiest) to let a thread terminate normally when its entry function returns.

The Visual C++ Alternatives to CreateThread( ) and ExitThread( )

Although CreateThread( ) and ExitThread( ) are the Windows API functions used to create and terminate a thread, we won’t be using them in this chapter! The reason is that when these functions are used with Visual C++ (and possibly other Windows-compatible compilers), they can result in memory leaks, the loss of a small amount of memory. For Visual C++, if a multithreaded program utilizes C/C++ standard library functions and uses CreateThread( ) and ExitThread( ), then small amounts of memory are lost. (If your program does not use the C/C++ standard library, then no such losses will occur.) To eliminate this problem, you must use functions defined by the C/C++ runtime library to start and stop threads rather than those specified by the Win32 API. These functions parallel CreateThread( ) and ExitThread( ), but do not generate a memory leak.

Note

The Visual C++ alternatives to CreateThread( ) and ExitThread( ) are _beginthreadex( ) and _endthreadex( ). Both require the header file <process.h>. Here is the prototype for _beginthreadex( ):

  uintptr_t _beginthreadex(void *secAttr, unsigned stackSize,
                                  unsigned (__stdcall *threadFunc)(void *),
                                  void *param, unsigned flags,
                                  unsigned *threadID);

As you can see, the parameters to _beginthreadex( ) parallel those to CreateThread( ). Furthermore, they have the same meaning as those specified by CreateThread( ). secAttr is a pointer to a set of security attributes pertaining to the thread. However, if secAttr is NULL, then the default security descriptor is used. The size of the new thread’s stack, in bytes, is passed in stackSize parameter. If this value is zero, then the thread will be given a stack that is the same size as the main thread of the process that creates it.

The address of the thread function (that is, the entry point to the thread) is specified in threadFunc. For _beginthreadex( ), a thread function must have this prototype:

  unsigned __stdcall threadfunc(void * param);

This prototype is functionally equivalent to the one for CreateThread( ), but it uses different type names. Any argument that you need to pass to the new thread is specified in the param parameter.

The flags parameter determines the execution state of the thread. If it is zero, the thread begins execution immediately. If it is CREATE_SUSPEND, the thread is created in a suspended state, awaiting execution. (It may be started using a call to ResumeThread( ).) The identifier associated with a thread is returned in the double word pointed to by threadID.

The function returns a handle to the thread if successful or zero if a failure occurs. The type uintptr_t specifies a Visual C++ type capable of holding a pointer or handle.

The prototype for _endthreadex( ) is shown here:

  void _endthreadex(unsigned status);

It functions just like ExitThread( ) by stopping the thread and returning the exit code specified in status.

Because the most widely used compiler for Windows is Visual C++, the examples in this chapter will use _beginthreadex( ) and _endthreadex( ) rather their equivalent API functions. If you are using a compiler other than Visual C++, simply substitute CreateThread( ) and EndThread( ).

When using _beginthreadex( ) and _endthreadex( ), you must remember to link in the multithreaded library. This will vary from compiler to compiler. Here are some examples. When using the Visual C++ command-line compiler, include the –MT option. To use the multithreaded library from the Visual C++ 6 IDE, first activate the Project | Settings property sheet. Then, select the C/C++ tab. Next, select Code Generation from the Category list box and then choose Multithreaded in the Use Runtime Library list box. For Visual C++ 7 .NET IDE, select Project | Properties. Next, select the C/C++ entry and highlight Code Generation. Finally, choose Multi-threaded as the runtime library.

Suspending and Resuming a Thread

A thread of execution can be suspended by calling SuspendThread( ). It can be resumed by calling ResumeThread( ). The prototypes for these functions are shown here:

  DWORD SuspendThread(HANDLE hThread);
  DWORD ResumeThread(HANDLE hThread);

For both functions, the handle to the thread is passed in hThread.

Each thread of execution has associated with it a suspend count. If this count is zero, then the thread is not suspended. If it is nonzero, the thread is in a suspended state. Each call to SuspendThread( ) increments the suspend count. Each call to ResumeThread( ) decrements the suspend count. A suspended thread will resume only when its suspend count has reached zero. Therefore, to resume a suspended thread implies that there must be the same number of calls to ResumeThread( ) as there have been calls to SuspendThread( ).

Both functions return the thread’s previous suspend count or –1 if an error occurs.

In Windows, each thread has associated with it a priority setting. A thread’s priority determines how much CPU time a thread receives. Low priority threads receive little time. High priority threads receive a lot. Of course, how much CPU time a thread receives has a profound impact on its execution characteristics and its interaction with other threads currently executing in the system.

In Windows, a thread’s priority setting is the combination of two values: the overall priority class of the process and the priority setting of the individual thread relative to that priority class. That is, a thread’s actual priority is determined by combining the process’s priority class with the thread’s individual priority level. Each is examined next.

By default, a process is given a priority class of normal, and most programs remain in the normal priority class throughout their execution lifetime. Although neither of the examples in this chapter changes the priority class, a brief overview of the thread priority classes is given here in the interest of completeness.

Windows defines six priority classes, which correspond to the value shown here, in order of highest to lowest priority:

Programs are given the NORMAL_PRIORITY_CLASS by default. Usually, you won’t need to alter the priority class of your program. In fact, changing a process’ priority class can have negative consequences on the overall performance of the computer system. For example, if you increase a program’s priority class to REALTIME_PRIORITY_CLASS, it will dominate the CPU. For some specialized applications, you may need to increase an application’s priority class, but usually you won’t. As mentioned, neither of the applications in this chapter changes the priority class.

In the event that you do want to change the priority class of a program, you can do by calling SetPriorityClass( ). You can obtain the current priority class by calling GetPriorityClass( ). The prototypes for these functions are shown here:

  DWORD GetPriorityClass(HANDLE hApp);
  BOOL SetPriorityClass(HANDLE hApp, DWORD priority);

Here, hApp is the handle of the process. GetPriorityClass( ) returns the priority class of the application or zero on failure. For SetPriorityClass( ), priority specifies the process’s new priority class.

For any given priority class, each individual thread’s priority determines how much CPU time it receives within its process. When a thread is first created, it is given normal priority, but you can change a thread’s priority—even while it is executing.

You can obtain a thread’s priority setting by calling GetThreadPriority( ). You can increase or decrease a thread’s priority using SetThreadPriority( ). The prototypes for these functions are shown here:

  BOOL SetThreadPriority(HANDLE hThread, int priority);
  int GetThreadPriority(HANDLE hThread);

For both functions, hThread is the handle of the thread. For SetThreadPriority( ), priority is the new priority setting. If an error occurs, SetThreadPriority( ) returns zero. It returns nonzero otherwise. For GetThreadPriority( ), the current priority setting is returned. The priority settings are shown here, in order of highest to lowest:

These values are increments or decrements that are applied relative to the priority class of the process. Through the combination of a process’ priority class and thread priority, Windows supports 31 different priority settings for application programs.

GetThreadPriority( ) returns THREAD_PRIORITY_ERROR_RETURN if an error occurs.

For the most part, if a thread has the NORMAL_PRIORITY class, you can freely experiment with changing its priority setting without fear of catastrophically affecting overall system performance. As you will see, the thread control panel developed in the next section allows you to alter the priority setting of a thread within a process (but does not change its priority class).

It is possible to control the execution of the main thread. To do so, you will need to acquire its handle. The easiest way to do this is to call GetCurrentThread( ), whose prototype is shown here:

  HANDLE GetCurrentThread(void);

This function returns a pseudohandle to the current thread. It is called a pseudohandle because it is a predefined value that always refers to the current thread rather than specifically to the calling thread. It can, however, be used any place that a normal thread handle can.

When using multiple threads or processes, it is sometimes necessary to coordinate the activities of two or more. This process is called synchronization. The most common use of synchronization occurs when two or more threads need access to a shared resource that must be used by only one thread at a time. For example, when one thread is writing to a file, a second thread must be prevented from doing so at the same time. Another reason for synchronization is when one thread is waiting for an event that is caused by another thread. In this case, there must be some means by which the first thread is held in a suspended state until the event has occurred. Then the waiting thread must resume execution.

There are two general states that a task may be in. First, it may be executing (or ready to execute as soon as it obtains its time slice). Second, a task may be blocked, awaiting some resource or event, in which case its execution is suspended until the needed resource is available or the event occurs.

If you are not familiar with the synchronization problem or its most common solution, the semaphore, the next section discusses it.

Windows must provide special services that allow access to a shared resource to be synchronized, because without help from the operating system, there is no way for one process or thread to know that it has sole access to a resource. To understand this, imagine that you are writing programs for a multitasking operating system that does not provide any synchronization support. Further imagine that you have two concurrently executing threads, A and B, both of which, from time to time, require access to some resource R (such as a disk file) that must be accessed by only one thread at a time. As a means of preventing one thread from accessing R while the other is using it, you try the following solution. First, you establish a variable called flag that is initialized to zero and can be accessed by both threads. Then, before using each piece of code that accesses R, you wait for flag to be cleared, then set flag, access R, and finally, clear flag. That is, before either thread accesses R, it executes this piece of code:

while(flag) ; // wait for flag to be cleared
flag = 1; // set flag
// ... access resource R ...
flag = 0; // clear the flag

The idea behind this code is that neither thread will access R if flag is set. Conceptually, this approach is in the spirit of the correct solution. However, in actual fact it leaves much to be desired for one simple reason: it won’t always work! Let’s see why.

Using the code just given, it is possible for both processes to access R at the same time. The while loop is, in essence, performing repeated load and compare instructions on flag or, in other words, it is testing flag’s value. When flag is cleared, the next line of code sets flag’s value. The trouble is that it is possible for these two operations to be performed in two different time slices. Between the two time slices, the value of flag might have been accessed by the other thread, thus allowing R to be used by both threads at the same time. To understand this, imagine that thread A enters the while loop and finds that flag is zero, which is the green light to access R. However, before it can set flag to 1, its time slice expires and thread B resumes execution. If B executes its while, it too will find that flag is not set and assume that it is safe to access R. However, when A resumes it will also begin accessing R. The crucial aspect of the problem is that the testing and setting of flag do not comprise one uninterruptible operation. Rather, as just illustrated, they can be separated by a time slice. No matter how you try, there is no way, using only application-level code, that you can absolutely guarantee that one and only one thread will access R at one time.

The solution to the synchronization problem is as elegant as it is simple. The operating system (in this case Windows) provides a routine that in one uninterrupted operation, tests and, if possible, sets a flag. In the language of operating systems engineers, this is called a test and set operation. For historical reasons, the flags used to control access to a shared resource and provide synchronization between threads (and processes) are called semaphores. The semaphore is at the core of the Windows synchronization system.

Windows supports several types of synchronization objects. The first type is the classic semaphore. When using a semaphore, a resource can be completely synchronized, in which case one and only one thread or process can access it at any one time, or the semaphore can allow no more than a small number of processes or threads access at any one time. Semaphores are implemented using a counter that is decremented when a task is granted the semaphore and incremented when the task releases it.

The second synchronization object is the mutex semaphore, or just mutex, for short. A mutex synchronizes a resource such that one and only one thread or process can access it at any one time. In essence, a mutex is a special case version of a standard semaphore.

The third synchronization object is the event object. It can be used to block access to a resource until some other thread or process signals that it can be used. (That is, an event object signals that a specified event has occurred.)

The fourth synchronization object is the waitable timer. A waitable timer blocks a thread’s execution until a specific time. You can also create timer queues, which are lists of timers.

You can prevent a section of code from being used by more than one thread at a time by making it into a critical section using a critical section object. Once a critical section is entered by one thread, no other thread may use it until the first thread has left the critical section.

The only synchronization object used in this chapter is the mutex, which is described in the following section. However, all synchronization objects defined by Windows are available to the C++ programmer. As explained, this is one of the major advantages that results from C++’s reliance on the operating system to handle multithreading: all multithreading features are at your command.

As explained, a mutex is a special-case semaphore that allows only one thread to access a resource at any given time. Before you can use a mutex, you must create one using CreateMutex( ), whose prototype is shown here:

HANDLE CreateMutex(LPSECURITY_ATTRIBUTES secAttr,
BOOL acquire,
LPCSTR name);

Here, secAttr is a pointer to the security attributes. If secAttr is NULL, the default security descriptor is used.

If the creating thread desires control of the mutex, then acquire must be true. Otherwise, pass false.

The name parameter points to a string that becomes the name of the mutex object. Mutexes are global objects, which may be used by other processes. As such, when two processes each open a mutex using the same name, both are referring to the same mutex. In this way, two processes can be synchronized. The name may also be NULL, in which case the semaphore is localized to one process.

The CreateMutex( ) function returns a handle to the semaphore if successful or NULL on failure. A mutex handle is automatically closed when the main process ends. You can explicitly close a mutex handle when it is no longer needed by calling CloseHandle( ).

Once you have created a semaphore, you use it by calling two related functions: WaitForSingleObject( ) and ReleaseMutex( ). The prototypes for these functions are shown here:

  DWORD WaitForSingleObject(HANDLE hObject, DWORD howLong);
  BOOL ReleaseMutex(HANDLE hMutex);

WaitForSingleObject( ) waits on a synchronization object. It does not return until the object becomes available or a time-out occurs. For use with mutexes, hObject will be the handle of a mutex. The howLong parameter specifies, in milliseconds, how long the calling routine will wait. Once that time has elapsed, a time-out error will be returned. To wait indefinitely, use the value INFINITE. The function returns WAIT_OBJECT_0 when successful (that is, when access is granted). It returns WAIT_TIMEOUT when time-out is reached.

ReleaseMutex( ) releases the mutex and allows another thread to acquire it. Here, hMutex is the handle to the mutex. The function returns nonzero if successful and zero on failure.

To use a mutex to control access to a shared resource, wrap the code that accesses that resource between a call to WaitForSingleObject( ) and ReleaseMutex( ), as shown in this skeleton. (Of course, the time-out period will differ from application to application.)

if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT) {
  // handle time-out error
}
// access the resource

ReleaseMutex(hMutex);

Generally, you will want to choose a time-out period that will be more than enough to accommodate the actions of your program. If you get repeated time-out errors when developing a multithreaded application, it usually means that you have created a deadlock condition. Deadlock occurs when one thread is waiting on a mutex that another thread never releases.

Creating a Thread Control Panel

When developing multithreaded programs, it is often useful to experiment with various priority settings. It is also useful to be able to dynamically suspend and resume a thread, or even terminate a thread. As you will see, it is quite easy, using the thread functions just described, to create a thread control panel that allows you to accomplish these things. Further, you can use the control panel while your multithreaded program is running. The dynamic nature of the thread control panel allows you to easily change the execution profile of a thread and observe the results.

The thread control panel developed in this section is capable of controlling one thread. However, you can create as many panels as needed, with each controlling a different thread. For the sake of simplicity, the control panel is implemented as a modeless dialog box that is owned by the desktop, not the application whose thread it controls.

The thread control panel is capable of performing the following actions:

• Setting a thread’s priority
  
• Suspending a thread
  
• Resuming a thread
  
• Terminating a thread

It also displays the current priority setting of the thread. The thread control dialog box is shown in Figure 3-1.

As stated, the control panel is as a modeless dialog box. As you know, when a modeless dialog box is activated, the rest of the application is still active. Thus, the control panel runs independently of the application for which it is being used.

Figure 3-1.  The Thread Control dialog box

The code for the thread control panel is shown here. This file is called tcp.cpp.

// A thread control panel.
#include <map>
#include <windows.h>
#include "panel.h"
using namespace std;
const int NUMPRIORITIES = 5;
const int OFFSET = 2;
// Array of strings for priority list box.
char priorities[NUMPRIORITIES][80] = {
  "Lowest",
  "Below Normal",
  "Normal",
  "Above Normal",
  "Highest"
};
// A Thread Control Panel Class.
class ThrdCtrlPanel {
  // Information about the thread under control.
  struct ThreadInfo {
   HANDLE hThread; //  handle of thread
   int priority;   //  current priority
   bool suspended; //  true if suspended
   ThreadInfo(HANDLE ht, int p, bool s) {
     hThread = ht;
     priority = p;
     suspended = s;
   }
  };
  // This map holds a ThreadInfo for each
  // active thread control panel.
  static map<HWND, ThreadInfo> dialogmap;
public:
  // Construct a control panel.
  ThrdCtrlPanel(HINSTANCE hInst, HANDLE hThrd);
  // The control panel's callback function.
  static LRESULT CALLBACK ThreadPanel(HWND hwnd, UINT message,
                        WPARAM wParam, LPARAM lParam);
};
// Define static member dialogmap.
map<HWND, ThrdCtrlPanel::ThreadInfo>
  ThrdCtrlPanel::dialogmap;
// Create a thread control panel. ThrdCtrlPanel::ThrdCtrlPanel(HINSTANCE hInst,
                           HANDLE hThrd)
{
  ThreadInfo ti(hThrd,
               GetThreadPriority(hThrd)+OFFSET,
               false);
  // Owner window is desktop.
  HWND hDialog = CreateDialog(hInst, "ThreadPanelDB",
                     NULL,
                     (DLGPROC) ThreadPanel);
  // Put info about this dialog box in the map.
  dialogmap.insert(pair<HWND, ThreadInfo>(hDialog, ti));
  // Set the control panel's title.
  char str[80] = "Control Panel for Thread ";
  char str2[4];
  _itoa(dialogmap.size(), str2, 10);
  strcat(str, str2);
  SetWindowText(hDialog, str);
  // Offset each dialog box instance.
  MoveWindow(hDialog, 30*dialogmap.size(),
          30*dialogmap.size(),
          300, 250, 1);
  // Update priority setting in the list box.
  SendDlgItemMessage(hDialog, IDD_LB, LB_SETCURSEL,
                       (WPARAM) ti.priority, 0);
  // Increase priority to ensure control. You can
  // change or remove this statement based on your
  // execution environment.
  SetThreadPriority(GetCurrentThread(),
                  THREAD_PRIORITY_ABOVE_NORMAL);
}
// Thread control panel dialog box callback function.
LRESULT CALLBACK ThrdCtrlPanel::ThreadPanel(HWND hwnd,
                                     UINT message,
                                     WPARAM wParam,
                                     LPARAM lParam)
{
  int i;
  HWND hpbRes, hpbSus, hpbTerm;
  switch(message) {
   case WM_INITDIALOG:
     // Initialize priority list box.
     for(i=0; i<NUMPRIORITIES i++) {
       SendDlgItemMessage(hwnd, IDD_LB,
           LB_ADDSTRING, 0, (LPARAM) priorities[i]);
       }
       // Set suspend and resume buttons for thread.
       hpbSus = GetDlgItem(hwnd, IDD_SUSPEND);
       hpbRes = GetDlgItem(hwnd, IDD_RESUME);
       EnableWindow(hpbSus, true);  // enable Suspend
       EnableWindow(hpbRes, false); // disable Resume
       return 1;
   case WM_COMMAND:
     map<HWND, ThreadInfo>::iterator p = dialogmap.find(hwnd);
   switch(LOWORD(wParam)) {
     case IDD_TERMINATE:
       TerminateThread(p->second.hThread, 0);
       // Disable Terminate button.
       hpbTerm = GetDlgItem(hwnd, IDD_TERMINATE); }
       EnableWindow(hpbTerm, false); // disable
       // Disable Suspend and Resume buttons.
       hpbSus = GetDlgItem(hwnd, IDD_SUSPEND);
       hpbRes = GetDlgItem(hwnd, IDD_RESUME);
       EnableWindow(hpbSus, false); // disable Suspend
       EnableWindow(hpbRes, false); // disable Resume
       return 1;
     case IDD_SUSPEND:
       SuspendThread(p->second.hThread);
       // Set state of the Suspend and Resume buttons.
       hpbSus = GetDlgItem(hwnd, IDD_SUSPEND);
       hpbRes = GetDlgItem(hwnd, IDD_RESUME);
       EnableWindow(hpbSus, false); // disable Suspend
       EnableWindow(hpbRes, true);  // enable Resume
       p->second.suspended = true;
       return 1;
     case IDD_RESUME:
       ResumeThread(p->second.hThread);
       // Set state of the Suspend and Resume buttons.
       hpbSus = GetDlgItem(hwnd, IDD_SUSPEND);
       hpbRes = GetDlgItem(hwnd, IDD_RESUME); /'
       EnableWindow(hpbSus, true);  // enable Suspend /'
       EnableWindow(hpbRes, false); // disable Resume
       p->second.suspended = false;
       return 1;
     case IDD_LB:
       // If a list box entry was clicked,
       // then change the priority.
       if(HIWORD(wParam)==LBN_DBLCLK) {
        p->second.priority = SendDlgItemMessage(hwnd,
                             IDD_LB, LB_GETCURSEL,/'
                             0, 0);
       SetThreadPriority(p->second.hThread,
                                   p->second.priority-OFFSET);
       }
       return 1;
     case IDCANCEL:
       // If thread is suspended when panel is closed,
       // then resume thread to prevent deadlock.
       if(p->second.suspended) {
          ResumeThread(p->second.hThread);
         p->second.suspended = false;
       }
       // Remove this thread from the list.
       dialogmap.erase(hwnd);
       // Close the panel.
       DestroyWindow(hwnd);?
       return 1;
       }
 }
  return 0;
}

The control panel requires the following resource file, called tcp.rc:

#include <windows.h>
#include "panel.h"
ThreadPanelDB DIALOGEX 20, 20, 140, 110
CAPTION "Thread Control Panel"
STYLE WS_BORDER | WS_VISIBLE | WS_POPUP | WS_CAPTION | WS_SYSMENU
{
  DEFPUSHBUTTON "Done", IDCANCEL, 55, 80, 33, 14
  PUSHBUTTON "Terminate", IDD_TERMINATE, 10, 20, 42, 12
  PUSHBUTTON "Suspend", IDD_SUSPEND, 10, 35, 42, 12
  PUSHBUTTON "Resume", IDD_RESUME, 10, 50, 42, 12
  LISTBOX IDD_LB, 65, 20, 63, 42, LBS_NOTIFY | WS_VISIBLE |
         WS_BORDER | WS_VSCROLL | WS_TABSTOP
  CTEXT "Thread Priority", IDD_TEXT1, 65, 8, 64, 10
  CTEXT "Change State", IDD_TEXT2, 0, 8, 64, 10
}

The control panel uses the following header file called panel.h:

#define IDD_LB           200
#define IDD_TERMINATE    202
#define IDD_SUSPEND      204
#define IDD_RESUME       206
#define IDD_TEXT1        208
#define IDD_TEXT2        209

To use the thread control panel, follow these steps:

1. Include tcp.cpp in your program.
2. Include tcp.rc in your program’s resource file.
3. Create the thread or threads that you want to control.
4. Instantiate a ThrdCtrlPanel object for each thread.

Each ThrdCtrlPanel object links a thread with a dialog box that controls it. For large projects in which multiple files need access to ThrdCtrlPanel, you will need to use a header file called tcp.h that contains the declaration for ThrdCtrlPanel. Here is tcp.h:

// A header file for the ThrdCtrlPanel class.
class ThrdCtrlPanel {
public:
  // Construct a control panel.
  ThrdCtrlPanel(HINSTANCE hInst, HANDLE hThrd);
  // The control panel's callback function.
  static LRESULT CALLBACK ThreadPanel(HWND hwnd, UINT message,
                        WPARAM wParam, LPARAM lParam);
};

Let’s take a closer look at the thread control panel. It begins by defining the following global definitions:

const int NUMPRIORITIES = 5;
const int OFFSET = 2;
// Array of strings for priority list box.
char priorities[NUMPRIORITIES][80] = {
  "Lowest",
  "Below Normal",
  "Normal",
  "Above Normal",
  "Highest"
};

The priorities array holds strings that correspond to a thread’s priority setting. It initializes the list box inside the control panel that displays the current thread priority. The number of priorities is specified by NUMPRIORITIES, which is 5 for Windows. Thus, NUMPRIORITIES defines the number of different priorities that a thread may have. (If you adapt the code for use with another operating system, a different value might be required.) Using the control panel, you can set a thread to one of the following priorities:

  THREAD_PRIORITY_HIGHEST

  THREAD_PRIORITY_ABOVE_NORMAL

  THREAD_PRIORITY_NORMAL

  THREAD_PRIORITY_BELOW_NORMAL

  THREAD_PRIORITY_LOWEST

The other two thread priority settings:

  THREAD_PRIORITY_TIME_CRITICAL

  THREAD_PRIORITY_IDLE

are not supported because, relative to the control panel, they are of little practical value. For example, if you want to create a time-critical application, you are better off making its priority class time-critical.

OFFSET defines an offset that will be used to translate between list box indexes and thread priorities. You should recall that normal priority has the value zero. In this example, the highest priority is THREAD_PRIORITY_HIGHEST, which is 2. The lowest priority is THREAD_PRIORITY_LOWEST, which is –2. Because list box indexes begin at zero, the offset is used to convert between indexes and priority settings.

Next, the ThrdCtrlPanel class is declared. It begins as shown here:

// A Thread Control Panel Class.
class ThrdCtrlPanel {
  // Information about the thread under control.
  struct ThreadInfo {
   HANDLE hThread; // handle of thread
   int priority;   // current priority
   bool suspended; // true if suspended
   ThreadInfo(HANDLE ht, int p, bool s) {
     hThread = ht;
     priority = p;
     suspended = s;
   }
  };
  // This map holds a ThreadInfo for each
  // active thread control panel.
  static map<HWND, ThreadInfo> dialogmap;

Information about the thread under control is contained within a structure of type ThreadInfo. The handle of the thread is stored in hThread. Its priority is stored in priority. If the thread is suspended, then suspended will be true. Otherwise, suspended will be false.

The static member dialogmap is an STL map that links the thread information with the handle of the dialog box used to control that thread. Because there can be more than one thread control panel active at any given time, there must be some way to determine which thread is associated with which panel. It is dialogmap that provides this linkage.

The ThrdCtrlPanel constructor is shown here. The constructor is passed the instance handle of the application and the handle of the thread being controlled. The instance handle is needed to create the control panel dialog box.

// Create a thread control panel. ThrdCtrlPanel::ThrdCtrlPanel(HINSTANCE hInst,
                            HANDLE hThrd)
{
  ThreadInfo ti(hThrd,
               GetThreadPriority(hThrd)+OFFSET,
               false);
  // Owner window is desktop.
  HWND hDialog = CreateDialog(hInst, "ThreadPanelDB",
                      NULL,
                     (DLGPROC) ThreadPanel);
  // Put info about this dialog box in the map.
  dialogmap.insert(pair<HWND, ThreadInfo>(hDialog, ti));
  // Set the control panel's title.
  char str[80] = "Control Panel for Thread ";
  char str2[4];
  _itoa(dialogmap.size(), str2, 10);
  strcat(str, str2);
  SetWindowText(hDialog, str);
  // Offset each dialog box instance.
  MoveWindow(hDialog, 30*dialogmap.size(),
            30*dialogmap.size(),
            300, 250, 1);
  // Update priority setting in the list box.
  SendDlgItemMessage(hDialog, IDD_LB, LB_SETCURSEL,
                         (WPARAM) ti.priority, 0);
  // Increase priority to ensure control. You can
  // change or remove this statement based on your
  // execution environment.
  SetThreadPriority(GetCurrentThread(),
                   THREAD_PRIORITY_ABOVE_NORMAL);
}

The constructor begins by creating a ThreadInfo instance called ti that contains the initial settings for the thread. Notice that the priority is obtained by calling GetThreadPriority( ) for the thread being controlled. Next, the control panel dialog box is created by calling CreateDialog( ). CreateDialog( ) is a Windows API function that creates a modeless dialog box, which makes it independent of the application that creates it. The handle of this dialog box is returned and stored in hDialog. Next, hDialog and the thread information contained in ti are stored in dialogmap. Thus, the thread is linked with the dialog box that controls it.

Next, the title of the dialog box is set to reflect the number of the thread. The number of the thread is obtained based on the number of entries in dialogmap. An alternative that you might want to try implementing is to explicitly pass a name for each thread to the ThrdCtrlPanel constructor. For the purposes of this chapter, simply numbering each thread is sufficient.

Next, the control panel’s position on the screen is offset a bit by calling MoveWindow( ), another Windows API function. This enables multiple panels to be displayed without each one fully covering the one before it. The thread’s priority setting is then displayed in the priority list box by calling the Windows API function SendDlgItemMessage( ).

Finally, the current thread has its priority increased to above normal. This ensures that the application receives enough CPU time to be responsive to user input no matter what is the priority level of the thread under control. This step may not be needed in all cases. You can experiment to find out.

ThreadPanel( ) is the Windows callback function that responds to user interaction with the thread control panel. Like all dialog box callback functions, it receives a message each time the user changes the state of a control. It is passed the handle of the dialog box in which the action occurred, the message, and any additional information required by the message. Its general mode of operation is the same as that for any other callback function used by a dialog box. The following discussion describes what happens for each message.

When the thread control panel dialog box is first created, it receives a WM_INITDIALOG message, which is handled by this case sequence:

caseWM_INITDIALOG:
  // Initialize priority list box.
  for(i=0; i<NUMPRIORITIES i++) {
   SendDlgItemMessage(hwnd, IDD_LB,
       LB_ADDSTRING, 0, (LPARAM) priorities[i]);
   }
   // Set Suspend and Resume buttons for thread.
   hpbSus = GetDlgItem(hwnd, IDD_SUSPEND);
   hpbRes = GetDlgItem(hwnd, IDD_RESUME);
   EnableWindow(hpbSus, true);  // enable Suspend
   EnableWindow(hpbRes, false); // disable Resume
   return 1;

This initializes the priority list box and sets the Suspend and Resume buttons to their initial states, which are Suspend enabled and Resume disabled.

Each user interaction generates a WM_COMMAND message. Each time this message is received, an iterator to this dialog box’s entry in dialogmap is retrieved, as shown here:

case WM_COMMAND:
  map<HWND, ThreadInfo>::iterator p = dialogmap.find(hwnd);

The information pointed to by p will be used to properly process each action. Because p is an iterator for a map, it points to an object of type pair, which is a structure defined by the STL. This structure contains two fields: first and second. These fields correspond to the information that comprises the key and the value, respectively. In this case, the handle is the key and the thread information is the value.

A code indicating precisely what action has occurred is contained in the low-order word of wParam, which is used to control a switch statement that handles the remaining messages. Each is described next.

When the user presses the Terminate button, the thread under control is stopped. This is handled by this case sequence:

case IDD_TERMINATE:
  TerminateThread(p->second.hThread, 0);
  // Disable Terminate button.
  hpbTerm = GetDlgItem(hwnd, IDD_TERMINATE);
  EnableWindow(hpbTerm, false); // disable
  // Disable Suspend and Resume buttons.
  hpbSus = GetDlgItem(hwnd, IDD_SUSPEND);
  hpbRes = GetDlgItem(hwnd, IDD_RESUME);
  EnableWindow(hpbSus, false); // disable Suspend
  EnableWindow(hpbRes, false); // disable Resume
  return 1;

The thread is stopped with a call to TerminateThread( ). Notice how the handle for the thread is obtained. As explained, because p is an iterator for a map, it points to an object of type pair that contains the key in its first field and the value in its second field. This is why the thread handle is obtained by the expression p->second.hThread. After the thread is stopped, the Terminate button is disabled.

Once a thread has been terminated, it cannot be resumed. Notice that the control panel uses TerminateThread( ) to halt execution of a thread. As mentioned earlier, this function must be used with care. If you use the control panel to experiment with threads of your own, you will want to make sure that no harmful side effects are possible.

When the user presses the Suspend button, the thread is suspended. This is accomplished by the following sequence:

case IDD_SUSPEND:
  SuspendThread(p->second.hThread);
  // Set state of the Suspend and Resume buttons.
  hpbSus = GetDlgItem(hwnd, IDD_SUSPEND);
  hpbRes = GetDlgItem(hwnd, IDD_RESUME);
  EnableWindow(hpbSus, false); // disable Suspend
  EnableWindow(hpbRes, true);  // enable Resume
  p->second.suspended = true;
  return 1;

The thread is suspended by a call to SuspendThread( ). Next, the state of the Suspend and Resume buttons are updated such that Resume is enabled and Suspend is disabled. This prevents the user from attempting to suspend a thread twice.

A suspended thread is resumed when the Resume button is pressed. It is handled by this code:

case IDD_RESUME:
  ResumeThread(p->second.hThread);
  // Set state of the Suspend and Resume buttons.
  hpbSus = GetDlgItem(hwnd, IDD_SUSPEND);
  hpbRes = GetDlgItem(hwnd, IDD_RESUME);
  EnableWindow(hpbSus, true);  // enable Suspend
  EnableWindow(hpbRes, false); // disable Resume
  p->second.suspended = false;
  return 1;

The thread is resumed by a call to ResumeThread( ), and the Suspend and Resume buttons are set appropriately.

To change a thread’s priority, the user double-clicks an entry in the Priority list box. This event is handled as shown next:

case IDD_LB:
  // If a list box entry was double-clicked,
  // then change the priority.
  if(HIWORD(wParam)==LBN_DBLCLK) {
   p->second.priority = SendDlgItemMessage(hwnd,
                        IDD_LB, LB_GETCURSEL,
                        0, 0);
   SetThreadPriority(p->second.hThread,
                     p->second.priority-OFFSET);
  }
  return 1;

List boxes generate various types of notification messages that describe the precise type of event that occurred. Notification messages are contained in the high-order word of wParam. One of these messages is LBN_DBLCLK, which means that the user double-clicked an entry in the box. When this notification is received, the index of the entry is retrieved by calling the Windows API function SendDlgItemMessage( ), requesting the current selection. This value is then used to set the thread’s priority. Notice that OFFSET is subtracted to normalize the value of the index.

Finally, when the user closes the thread control panel dialog box, the IDCANCEL message is sent. It is handled by the following sequence:

case IDCANCEL:
  // If thread is suspended when panel is closed,
  // then resume thread to prevent deadlock.
  if(p->second.suspended) {
   ResumeThread(p->second.hThread);
   p->second.suspended = false;
  }
  // Remove this thread from the list.
  dialogmap.erase(hwnd);
  // Close the panel.
  DestroyWindow(hwnd);
  return 1;

If the thread was suspended, it is restarted. This is necessary to avoid accidentally deadlocking the thread. Next, this dialog box’s entry in dialogmap is removed. Finally, the dialog box is removed by calling the Windows API function DestroyWindow( ).

Here is a program that includes the thread control panel and demonstrates its use. Sample output is shown in Figure 3-2. The program creates a main window and defines two child threads. When started, these threads simply count from 0 to 50,000, displaying the count in the main window. These threads can be controlled by activating a thread control panel.

To use the program, first begin execution of the threads by selecting Start Threads from the Threads menu (or by pressing F2) and then activate the thread control panels by selecting Control Panels from the Threads menu (or by pressing F3). Once the control panels are active, you can experiment with different priority settings and so on.

Figure 3-2.  Sample output from the thread control panel sample program

NOTE

// Demonstrate the thread control panel.
#include <windows.h>
#include <process.h>
#include "thrdapp.h"
#include "tcp.cpp"
const int MAX = 500000;
LRESULT CALLBACK WindowFunc(HWND, UINT, WPARAM, LPARAM);
unsigned __stdcall MyThread1(void * param);
unsigned __stdcall MyThread2(void * param);
char str[255]; // holds output strings
unsigned tid1, tid2; // thread IDs
HANDLE hThread1, hThread2; // thread handles
HINSTANCE hInst; // instance handle
int WINAPI WinMain(HINSTANCE hThisInst, HINSTANCE hPrevInst,
                  LPSTR args, int winMode)
{
  HWND hwnd;
  MSG msg;
  WNDCLASSEX wcl;
  HACCEL hAccel;
  // Define a window class.
  wcl.cbSize = sizeof(WNDCLASSEX);
  wcl.hInstance = hThisInst;     // handle to this instance
  wcl.lpszClassName = "MyWin";   // window class name
  wcl.lpfnWndProc = WindowFunc;  // window function
  wcl.style = 0;                 // default style
  wcl.hIcon = LoadIcon(NULL, IDI_APPLICATION); // large icon
  wcl.hIconSm = NULL; // use small version of large icon
  wcl.hCursor = LoadCursor(NULL, IDC_ARROW); // cursor style
  wcl.lpszMenuName = "ThreadAppMenu"; // main menu
  wcl.cbClsExtra = 0; // no extra memory needed
  wcl.cbWndExtra = 0;
  // Make the window background white.
  wcl.hbrBackground = (HBRUSH) GetStockObject(WHITE_BRUSH);
  // Register the window class.
  if(!RegisterClassEx(&wcl)) return 0;
  /* Now that a window class has been registered, a window
    can be created. */
  hwnd = CreateWindow(
   wcl.lpszClassName, // name of window class
   "Using a Thread Control Panel", // title
   WS_OVERLAPPEDWINDOW, // window style - normal
   CW_USEDEFAULT, // X coordinate - let Windows decide
   CW_USEDEFAULT, // Y coordinate - let Windows decide
   260,           // width
   200,           // height
   NULL,          // no parent window
   NULL,          // no override of class menu
   hThisInst,     // instance handle
   NULL           // no additional arguments
  );
  hInst = hThisInst; // save instance handle
  // Load the keyboard accelerators.
  hAccel = LoadAccelerators(hThisInst, "ThreadAppMenu");
  // Display the window.
  ShowWindow(hwnd, winMode);
  UpdateWindow(hwnd);
  // Create the message loop.
  while(GetMessage(&msg, NULL, 0, 0))
  {
   if(!TranslateAccelerator(hwnd, hAccel, &msg)) {  
     TranslateMessage(&msg); // translate keyboard messages
     DispatchMessage(&msg); // return control to Windows
   }
  }
  return msg.wParam;
}
/* This function is called by Windows and is passed
  messages from the message queue.
*/
LRESULT CALLBACK WindowFunc(HWND hwnd, UINT message,
                           WPARAM wParam, LPARAM lParam)
{
  int response;
  switch(message) {
   case WM_COMMAND:
     switch(LOWORD(wParam)) {
       case IDM_THREAD: // create the threads
         hThread1 = (HANDLE) _beginthreadex(NULL, 0,
                              MyThread1, (void *) hwnd,
                              0, &tid1);
         hThread2 = (HANDLE) _beginthreadex(NULL, 0,
                              MyThread2, (void *) hwnd,
                              0, &tid2);
         break;
       case IDM_PANEL: // activate control panel
         ThrdCtrlPanel(hInst, hThread1);
         ThrdCtrlPanel(hInst, hThread2);
         break;
       case IDM_EXIT:
         response = MessageBox(hwnd, "Quit the Program?",
                               "Exit", MB_YESNO);
         if(response == IDYES) PostQuitMessage(0);
         break;
       case IDM_HELP:
         MessageBox(hwnd,
                    "F1: Help\nF2: Start Threads\nF3: Panel",
                    "Help", MB_OK);
         break;
     }
     break;
   case WM_DESTROY: // terminate the program
     PostQuitMessage(0);
     break;
   default:
    return DefWindowProc(hwnd, message, wParam, lParam);
  }
  return 0;
}
// First thread.
unsigned __stdcall MyThread1(void * param)
{
  int i;
  HDC hdc;
  for(i=0; i<MAX; i++) {
   wsprintf(str, "Thread 1: loop # %5d ", i);
   hdc = GetDC((HWND) param);
   TextOut(hdc, 1, 1, str, lstrlen(str));
   ReleaseDC((HWND) param, hdc);
  }
  return 0;
}
// Second thread.
unsigned __stdcall MyThread2(void * param)
{
  int i;
  HDC hdc;
  for(i=0; i<MAX; i++) {
   wsprintf(str, "Thread 2: loop # %5d ", i);
   hdc = GetDC((HWND) param);
   TextOut(hdc, 1, 20, str, lstrlen(str));
   ReleaseDC((HWND) param, hdc);
  }
  return 0;
}

This program requires the header file thrdapp.h, shown here:

#define IDM_THREAD      100
#define IDM_HELP        101
#define IDM_PANEL       102
#define IDM_EXIT        103

The resource file required by the program is shown here:

#include <windows.h>
#include "thrdapp.h"
#include "tcp.rc"
ThreadAppMenu MENU
{
  POPUP "&Threads" {
   MENUITEM "&Start Threads\tF2", IDM_THREAD
   MENUITEM "&Control Panels\tF3", IDM_PANEL
   MENUITEM "E&xit\tCtrl+X", IDM_EXIT
  }
  MENUITEM "&Help", IDM_HELP
}
ThreadAppMenu ACCELERATORS
{
  VK_F1, IDM_HELP, VIRTKEY
  VK_F2, IDM_THREAD, VIRTKEY
  VK_F3, IDM_PANEL, VIRTKEY
  "^X", IDM_EXIT
}

Although controlling threads using the thread control panel is useful when developing multithreaded programs, ultimately it is using threads that makes them important. Toward this end, this chapter shows a multithreaded version of the GCPtr garbage collector class originally developed in Chapter 2. Recall that the version of GCPtr shown in Chapter 2 collected unused memory each time a GCPtr object went out of scope. Although this approach is fine for some applications, often a better alternative is have the garbage collector run as a background task, recycling memory whenever free CPU cycles are available. The implementation developed here is designed for Windows, but the same basic techniques apply to other multithreaded environments.

To convert GCPtr into a background task is actually fairly easy, but it does involve a number of changes. Here are the main ones:

1. Member variables that support the thread must be added to GCPtr. These variables include the thread handle, the mutex handle, and an instance counter that keeps track of the number of GCPtr objects in existence.
2. The constructor for GCPtr must begin the garbage collection thread. The constructor must also create the mutex that controls synchronization. This must happen only once, when the first GCPtr object is created.
3. Another exception must be defined that will be used to indicate a time-out condition.
4. The GCPtr destructor must no longer call collect( ). Garbage collection is handled by the garbage collection thread.
5. A function called gc( ) that serves as the thread entry point for the garbage collector must be defined.
6. A function called isRunning( ) must be defined. It returns true if the garbage collection is in use.
7. The member functions of GCPtr that access the garbage collection list contained in gclist must be synchronized so that only one thread at a time can access the list.

The following sections show the changes.

The multithreaded version of GCPtr requires that the following member variables be added:

// These support multithreading.
unsigned tid; // thread id
static HANDLE hThrd;    // thread handle
static HANDLE hMutex;   // handle of mutex
static int instCount;   // counter of GCPtr objects

The ID of the thread used by the garbage collector is stored in tid. This member is unused except in the call to _beginthreadex( ). The handle to the thread is stored in hThrd. The handle of the mutex used to synchronize access to GCPtr is stored in hMutex. A count of GCPtr objects in existence is maintained in instCount. The last three are static because they are shared by all instances of GCPtr. They are defined like this, outside of GCPtr:

template <class T, int size>
  int GCPtr<T, size>::instCount = 0;
template <class T, int size>
  HANDLE GCPtr<T, size>::hMutex = 0;
template <class T, int size>
  HANDLE GCPtr<T, size>::hThrd = 0;

In addition to its original duties, the multithreaded GCPtr( ) must create the mutex, start the garbage collector thread, and update the instance counter. Here is the updated version:

// Construct both initialized and uninitialized objects. GCPtr(T *t=NULL) {
  // When first object is created, create the mutex
  // and register shutdown().
  if(hMutex==0) {
   hMutex = CreateMutex(NULL, 0, NULL);
   atexit(shutdown);
  }
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  list<GCInfo<T> >::iterator p;
  p = findPtrInfo(t);
  // If t is already in gclist, then
  // increment its reference count.
  // Otherwise, add it to the list.
  if(p != gclist.end())
   p->refcount++; // increment ref count
  else {
   // Create and store this entry.
   GCInfo<T> gcObj(t, size);
   gclist.push_front(gcObj);
  }
  addr = t;
  arraySize = size;
  if(size > 0) isArray = true;
  else isArray = false;
  // Increment instance counter for each new object.
  instCount++;
  // If the garbage collection thread is not
  // currently running, start it running.
  if(hThrd==0) {
   hThrd = (HANDLE) _beginthreadex(NULL, 0, gc,
           (void *) 0, 0, (unsigned *) &tid);
   // For some applications, it will be better
   // to lower the priority of the garbage collector
   // as shown here:
   //
   // SetThreadPriority(hThrd,
   //                   THREAD_PRIORITY_BELOW_NORMAL);
  }
  ReleaseMutex(hMutex);
}

Let’s examine this code closely. First, if hMutex is zero, it means that this is the first GCPtr object to be created and no mutex has yet been created for the garbage collector. If this is the case, the mutex is created and its handle is assigned to hMutex. At the same time, the function shutdown( ) is registered as a termination function by calling atexit( ).

It is important to note that in the multithreaded garbage collector, shutdown( ) serves two purposes. First, as in the original version of GCPtr, shutdown( ) frees any unused memory that has not been released because of a circular reference. Second, when a program using the multithreaded garbage collector ends, it stops the garbage collection thread. This means that there might still be dynamically allocated objects that haven’t been freed. This is important because these objects might have destructors that need to be called. Because shutdown( ) releases all remaining objects, it also releases these objects.

Next, the mutex is acquired by calling WaitForSingleObject( ). This is necessary to prevent two threads from accessing gclist at the same time. Once the mutex has been acquired, a search of gclist is made, looking for any preexisting entry that matches the address in t. If one is found, its reference count is incremented. If no preexising entry matches t, a new GCInfo object is created that contains this address, and this object is added to gclist. Then, addr, arraySize, and isArray are set. These actions are the same as in the original version of GCPtr.

Next, instCount is incremented. Recall that instCount is initialized to zero. Incrementing it each time an object is created keeps track of how many GCPtr objects are in existence. As long as this count is above zero, the garbage collector will continue to execute.

Next, if hThrd is zero (as it is initially), then no thread has yet been created for the garbage collector. In this case, _beginthreadex( ) is called to begin the thread. A handle to the thread is then assigned to hThrd. The thread entry function is called gc( ), and it is examined shortly.

Finally, the mutex is released and the constructor returns. It is important to point out that each call to WaitForSingleObject( ) must be balanced by a call to ReleaseMutex( ), as shown in the GCPtr constructor. Failure to release the mutex will cause deadlock.

As you probably noticed in the code for GCPtr( ) described in the preceding section, if the mutex cannot be acquired after 10 seconds, then a TimeOutExc is thrown. Frankly, 10 seconds is a very long time, so a time-out shouldn’t ever happen unless something disrupts the task scheduler of the operating system. However, in the event it does occur, your application code may want to catch this exception. The TimeOutExc class is shown here:

// Exception thrown when a time-out occurs
// when waiting for access to hMutex.
//
class TimeOutExc {
  // Add functionality if needed by your application.
};

Notice that it contains no members. Its existence as a unique type is sufficient for the purposes of this chapter. Of course, you can add functionality if desired.

Unlike the single-threaded version of the GCPtr destructor, the multithreaded version of ~GCPtr( ) does not call collect( ). Instead, it simply decrements the reference count of the memory pointed to by the GCPtr that is going out of scope. The actual collection of garbage (if any exists) is handled by the garbage collection thread. The destructor also decrements the instance counter, instCount.

The multithreaded version of ~GCPtr( ) is shown here:

// Destructor for GCPtr.
template <class T, int size>
GCPtr<T, size>::~GCPtr() {
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  list<GCInfo<T> >::iterator p;
  p = findPtrInfo(addr);
  if(p->refcount) p->refcount--; // decrement ref count
  // Decrement instance counter for each object
  // that is destroyed.
  instCount--;
  ReleaseMutex(hMutex);
}

The entry function for the garbage collector is called gc( ), and it is shown here:

// Entry point for garbage collector thread.
template <class T, int size>
unsigned __stdcall GCPtr<T, size>::gc(void * param) {
  #ifdef DISPLAY
   cout << "Garbage collection started.\n";
  #endif
  while(isRunning()) {
     collect();
  }
  collect(); // collect garbage on way out
  // Release and reset the thread handle so
  // that the garbage collection thread can
  // be restarted if necessary.
  CloseHandle(hThrd);
  hThrd = 0;
  #ifdef DISPLAY
   cout << "Garbage collection terminated for "
        << typeid(T).name() << "\n";
  #endif
  return 0;
}

The gc( ) function is quite simple: it runs as long as the garbage collector is in use. The isRunning( ) function returns true if instCount is greater than zero (which means that the garbage collector is still needed) and false otherwise. Inside the loop, collect( ) is called continuously. This approach is suitable for demonstrating the multithreaded garbage collector, but it is probably too inefficient for real-world use. You might want to experiment with calling collect( ) less often, such as only when memory runs low. You could also experiment by calling the Windows API function Sleep( ) after each call to collect( ). Sleep( ) pauses the execution of the calling thread for a specified number of milliseconds. While sleeping, a thread does not consume CPU time.

When isRunning( ) returns false, the loop ends, causing gc( ) to eventually end, which stops the garbage collection thread. Because of the multithreading, it is possible that there will still be an entry on gclist that has not yet been freed even though isRunning( ) returns false. To handle this case, a final call to collect( ) is made before gc( ) ends.

Finally, the thread handle is released via a call to the Windows API function CloseHandle( ), and its value is set to zero. Setting hThrd to zero enables the GCPtr constructor to restart the thread if later in the program new GCPtr objects are created.

The isRunning( ) function is shown here:

// Returns true if the collector is still in use.
static bool isRunning() { return instCount > 0; }

It simply compares instCount to zero. As long as instCount is greater than 0, at least one GCPtr pointer is still in existence and the garbage collector is still needed.

Many of the functions in GCPtr access gclist, which holds the garbage collection list. Access to gclist must be synchronized to prevent two or more threads from attempting to use it at the same time. The reason for this is easy to understand. If access were not synchronized, then, for example, one thread might be obtaining an iterator to the end of the list at the same time that another thread is adding or deleting an element from the list. In this case, the iterator would be invalid. To prevent such problems, each sequence of code that accesses gclist must be guarded by a mutex. The copy constructor for GCPtr shown here is one example:

// Copy constructor.
GCPtr(const GCPtr &ob) {
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  list<GCInfo<T> >::iterator p;
  p = findPtrInfo(ob.addr);
  p->refcount++; // increment ref count
  addr = ob.addr;
  arraySize = ob.arraySize;
  if(arraySize > 0) isArray = true;
  else isArray = false;
  instCount++; // increase instance count for copy
  ReleaseMutex(hMutex);
}

Notice that the first thing that the copy constructor does is acquire the mutex. Once acquired, it creates a copy of the object and adjusts the reference count for the memory being pointed to. On its way out, the copy constructor releases the mutex. This same basic method is applied to all functions that access gclist.

There are two other changes that you must make to the original version of the garbage collector. First, recall that the original version of GCPtr defined a static variable called first that indicated when the first GCPtr was created. This variable is no longer needed because hMutex now performs this function. Thus, remove first from GCPtr. Because it is a static variable, you will also need to remove its definition outside of GCPtr.

In the original, single-threaded version of the garbage collector, if you defined the DISPLAY macro, you could watch the garbage collector in action. Most of that code has been removed in the multithreaded version because multithreading causes the output to be scrambled and unintelligible in most cases. For the multithreaded version, defining DISPLAY simply lets you know when the garbage collector has started and when it has stopped.

The entire multithreaded version of the garbage collector is shown here. Call this file gcthrd.h.

// A garbage collector that runs as a back ground task.
#include <iostream>
#include <list>
#include <typeinfo>
#include <cstdlib>
#include <windows.h>
#include <process.h>
using namespace std;
// To watch the action of the garbage collector, define DISPLAY.
// #define DISPLAY
// Exception thrown when an attempt is made to
// use an Iter that exceeds the range of the
// underlying object.
//
class OutOfRangeExc {
  // Add functionality if needed by your application.
};
// Exception thrown when a time-out occurs
// when waiting for access to hMutex.
//
class TimeOutExc {
  // Add functionality if needed by your application.
};
// An iterator-like class for cycling through arrays
// that are pointed to by GCPtrs. Iter pointers
// ** do not ** participate in or affect garbage
// collection. Thus, an Iter pointing to
// some object does not prevent that object
// from being recycled.
//
template <class T> class Iter {
  T *ptr;   // current pointer value
  T *end;   // points to element one past end
  T *begin; // points to start of allocated array
  unsigned length; // length of sequence
public:
  Iter() {
   ptr = end = begin = NULL;
   length = 0;
  }
  Iter(T *p, T *first, T *last) {
   ptr = p;
   end = last;
   begin = first;
   length = last - first;
  }
  // Return length of sequence to which this
  // Iter points.
  unsigned size() { return length; }
  // Return value pointed to by ptr.
  // Do not allow out-of-bounds access.
  T &operator*() {
   if( (ptr >= end) || (ptr < begin) )
     throw OutOfRangeExc();
   return *ptr;
  }
  // Return address contained in ptr.
  // Do not allow out-of-bounds access.
  T *operator->() {
   if( (ptr >= end) || (ptr < begin) )
     throw OutOfRangeExc();
   return ptr;
  }
  // Prefix ++.
  Iter operator++() {
   ptr++;
   return *this;
  }
  // Prefix --.
  Iter operator--() {
   ptr--;
   return *this;
  }
  // Postfix ++.
  Iter operator++(int notused) {
   T *tmp = ptr;
   ptr++;
   return Iter<T>(tmp, begin, end);
  }
  // Postfix --.
  Iter operator--(int notused) {
   T *tmp = ptr;
   ptr--;
   return Iter<T>(tmp, begin, end);
  }
  // Return a reference to the object at the
  // specified index. Do not allow out-of-bounds
  // access.
  T &operator[](int i) {
   if( (i < 0) || (i >= (end-begin)) )
     throw OutOfRangeExc();
   return ptr[i];
  }
  // Define the relational operators.
  bool operator==(Iter op2) {
   return ptr == op2.ptr;
  }
  bool operator!=(Iter op2) {
   return ptr != op2.ptr;
  }
  bool operator<(Iter op2) {
   return ptr < op2.ptr;
  }
  bool operator<=(Iter op2) {
   return ptr <= op2.ptr;
  }
  bool operator>(Iter op2) {
   return ptr > op2.ptr;
  }
  bool operator>=(Iter op2) {
   return ptr >= op2.ptr;
  }
  // Subtract an integer from an Iter.
  Iter operator-(int n) {
   ptr -= n;
   return *this;
  }
  // Add an integer to an Iter.
  Iter operator+(int n) {
   ptr += n;
   return *this;
  }
  // Return number of elements between two Iters.
  int operator-(Iter<T> &itr2) {
   return ptr - itr2.ptr;
 }
};
// This class defines an element that is stored
// in the garbage collection information list.
//
template <class T> class GCInfo {
public:
  unsigned refcount; // current reference count
  T *memPtr; // pointer to allocated memory
  /* isArray is true if memPtr points
    to an allocated array. It is false
    otherwise. */
  bool isArray; // true if pointing to array
  /* If memPtr is pointing to an allocated
    array, then arraySize contains its size */
  unsigned arraySize; // size of array
  // Here, mPtr points to the allocated memory.
  // If this is an array, then size specifies
  // the size of the array.
  GCInfo(T *mPtr, unsigned size=0) {
   refcount = 1;
   memPtr = mPtr;
   if(size != 0)
     isArray = true;
   else
     isArray = false;
   arraySize = size;
  }
};
// Overloading operator== allows GCInfos to be compared.
// This is needed by the STL list class.
template <class T> bool operator==(const GCInfo<T> &ob1,
               const GCInfo<T> &ob2) {
  return (ob1.memPtr == ob2.memPtr);
}
// GCPtr implements a pointer type that uses
// garbage collection to release unused memory.
// A GCPtr must only be used to point to memory
// that was dynamically allocated using new.
// When used to refer to an allocated array,
// specify the array size.
//
template <class T, int size=0> class GCPtr {
  // gclist maintains the garbage collection list.
  static list<GCInfo<T> > gclist;
  // addr points to the allocated memory to which
  // this GCPtr pointer currently points.
  T *addr;
  /* isArray is true if this GCPtr points
    to an allocated array. It is false
    otherwise. */
  bool isArray; // true if pointing to array
  // If this GCPtr is pointing to an allocated
  // array, then arraySize contains its size.
  unsigned arraySize; // size of the array
  // These support multithreading.
  unsigned tid; // thread id
  static HANDLE hThrd; // thread handle
  static HANDLE hMutex; // handle of mutex
  static int instCount; // counter of GCPtr objects
  // Return an iterator to pointer info in gclist.
  typename list<GCInfo<T> >::iterator findPtrInfo(T *ptr);
public:
  // Define an iterator type for GCPtr<T>.
  typedef Iter<T> GCiterator;
  // Construct both initialized and uninitialized objects.
  GCPtr(T *t=NULL) {
   // When first object is created, create the mutex
   // and register shutdown().
   if(hMutex==0) {
     hMutex = CreateMutex(NULL, 0, NULL);
     atexit(shutdown);
   }
   if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
     throw TimeOutExc();
   list<GCInfo<T> >::iterator p;
   p = findPtrInfo(t);
   // If t is already in gclist, then
   // increment its reference count.
   // Otherwise, add it to the list.
   if(p != gclist.end())
     p->refcount++; // increment ref count
   else {
     // Create and store this entry.
     GCInfo<T> gcObj(t, size);
     gclist.push_front(gcObj);
   }
   addr = t;
   arraySize = size;
   if(size > 0) isArray = true;
   else isArray = false;
   // Increment instance counter for each new object.
   instCount++;
   // If the garbage collection thread is not
   // currently running, start it running.
   if(hThrd==0) {
     hThrd = (HANDLE) _beginthreadex(NULL, 0, gc,
             (void *) 0, 0, (unsigned *) &tid);
   // For some applications, it will be better
   // to lower the priority of the garbage collector
   // as shown here:
   //
   // SetThreadPriority(hThrd,
   //                   THREAD_PRIORITY_BELOW_NORMAL);
  }
  ReleaseMutex(hMutex);
}
// Copy constructor.
GCPtr(const GCPtr &ob) {
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  list<GCInfo<T> >::iterator p;
  p = findPtrInfo(ob.addr);
  p->refcount++; // increment ref count
  addr = ob.addr;
  arraySize = ob.arraySize;
  if(arraySize > 0) isArray = true;
  else isArray = false;
  instCount++; // increase instance count for copy
  ReleaseMutex(hMutex);
}
// Destructor for GCPTr.
~GCPtr();
// Collect garbage. Returns true if at least
// one object was freed.
static bool collect();
// Overload assignment of pointer to GCPtr.
T *operator=(T *t);
// Overload assignment of GCPtr to GCPtr.
GCPtr &operator=(GCPtr &rv);
// Return a reference to the object pointed
// to by this GCPtr.
T &operator*() {
  return *addr;
}
// Return the address being pointed to.
T *operator->() { return addr; }
// Return a reference to the object at the
// index specified by i.
T &operator[](int i) {
  return addr[i];
}
// Conversion function to T *.
operator T *() { return addr; }
// Return an Iter to the start of the allocated memory. Iter<T> begin() {
  int size;
  if(isArray) size = arraySize;
  else size = 1;
  return Iter<T>(addr, addr, addr + size);
}
// Return an Iter to one past the end of an allocated array.
Iter<T> end() {
  int size;
  if(isArray) size = arraySize;
  else size = 1;
  return Iter<T>(addr + size, addr, addr + size);
}
// Return the size of gclist for this type
// of GCPtr.
  static int gclistSize() {
   if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
     throw TimeOutExc();
   unsigned sz = gclist.size();
   ReleaseMutex(hMutex);
   return sz;
  }
  // A utility function that displays gclist.
  static void showlist();
  // The following functions support multithreading.
  //
  // Returns true if the collector is still in use.
  static bool isRunning() { return instCount > 0; }
  // Clear gclist when program exits.
  static void shutdown();
  // Entry point for garbage collector thread.
  static unsigned __stdcall gc(void * param);
};
// Create storage for the static variables.
template <class T, int size>
  list<GCInfo<T> > GCPtr<T, size>::gclist;
template <class T, int size>
  int GCPtr<T, size>::instCount = 0;
template <class T, int size>
  HANDLE GCPtr<T, size>::hMutex = 0;
template <class T, int size>
  HANDLE GCPtr<T, size>::hThrd = 0;
// Destructor for GCPtr.
template <class T, int size>
GCPtr<T, size>::~GCPtr() {
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  list<GCInfo<T> >::iterator p;
  p = findPtrInfo(addr);
  if(p->refcount) p->refcount--; // decrement ref count
  // Decrement instance counter for each object
  // that is destroyed.
  instCount--;
  ReleaseMutex(hMutex);
}
// Collect garbage. Returns true if at least
// one object was freed.
template <class T, int size>
bool GCPtr<T, size>::collect() {
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  bool memfreed = false;
  list<GCInfo<T> >::iterator p;
  do {
   // Scan gclist looking for unreferenced pointers.
   for(p = gclist.begin(); p != gclist.end(); p++) {
     // If in-use, skip.
     if(p->refcount > 0) continue;
     memfreed = true;
     // Remove unused entry from gclist.
     gclist.remove(*p);
     // Free memory unless the GCPtr is null.
     if(p->memPtr) {
       if(p->isArray) {
         delete[] p->memPtr; // delete array
       }
       else {
         delete p->memPtr; // delete single element
       }
     }
     // Restart the search.
     break;
   }
  } while(p != gclist.end());
  ReleaseMutex(hMutex);
  return memfreed;
}
// Overload assignment of pointer to GCPtr.
template <class T, int size>
T * GCPtr<T, size>::operator=(T *t) {
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  list<GCInfo<T> >::iterator p;
  // First, decrement the reference count
  // for the memory currently being pointed to.
  p = findPtrInfo(addr);
  p->refcount--;
  // Next, if the new address is already
  // existent in the system, increment its
  // count. Otherwise, create a new entry
  // for gclist.
  p = findPtrInfo(t);
  if(p != gclist.end())
   p->refcount++;
  else {
   // Create and store this entry.
   GCInfo<T> gcObj(t, size);
   gclist.push_front(gcObj);
  }
  addr = t; // store the address.
  ReleaseMutex(hMutex);
  return t;
}
// Overload assignment of GCPtr to GCPtr.
template <class T, int size>
GCPtr<T, size> & GCPtr<T, size>::operator=(GCPtr &rv) {
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  list<GCInfo<T> >::iterator p;
  // First, decrement the reference count
  // for the memory currently being pointed to.
  p = findPtrInfo(addr);
  p->refcount--;
  // Next, increment the reference count of
  // of the new object.
  p = findPtrInfo(rv.addr);
  p->refcount++; // increment ref count
  addr = rv.addr;// store the address.
  ReleaseMutex(hMutex);
  return rv;
}
// A utility function that displays gclist.
template <class T, int size>
void GCPtr<T, size>::showlist() {
  if(WaitForSingleObject(hMutex, 10000)==WAIT_TIMEOUT)
   throw TimeOutExc();
  list<GCInfo<T> >::iterator p;
  cout << "gclist<" << typeid(T).name() << ", "
      << size << ">:\n";
  cout << "memPtr     refcount    value\n";
  if(gclist.begin() == gclist.end()) {
   cout << "           -- Empty --\n\n";
   return;
  }
  for(p = gclist.begin(); p != gclist.end(); p++) {
   cout <<  "[" << (void *)p->memPtr << "]"
        << "     " << p->refcount << "      ";
   if(p->memPtr) cout << "  " << *p->memPtr;
   else cout << "   ---";
   cout << endl;
  }
  cout << endl;
  ReleaseMutex(hMutex);
}
// Find a pointer in gclist.
template <class T, int size>
typename list<GCInfo<T> >::iterator
  GCPtr<T, size>::findPtrInfo(T *ptr) {
  list<GCInfo<T> >::iterator p;
  // Find ptr in gclist.
  for(p = gclist.begin(); p != gclist.end(); p++)
   if(p->memPtr == ptr)
     return p;
  return p;
}
// Entry point for garbage collector thread.
template <class T, int size>
unsigned __stdcall GCPtr<T, size>::gc(void * param) {
  #ifdef DISPLAY
   cout << "Garbage collection started.\n";
  #endif
  while(isRunning()) {
     collect();
  }
  collect(); // collect garbage on way out
  // Release and reset the thread handle so
  // that the garbage collection thread can
  // be restarted if necessary.
  CloseHandle(hThrd);
  hThrd = 0;
  #ifdef DISPLAY
   cout << "Garbage collection terminated for "
        << typeid(T).name() << "\n";
  #endif
  return 0;
}
// Clear gclist when program exits.
template <class T, int size>
void GCPtr<T, size>::shutdown() {
  if(gclistSize() == 0) return; // list is empty
  list<GCInfo<T> >::iterator p;
  #ifdef DISPLAY
   cout << "Before collecting for shutdown() for "
        << typeid(T).name() << "\n";
  #endif
  for(p = gclist.begin(); p != gclist.end(); p++) {
   // Set all remaining reference counts to zero.
   p->refcount = 0;
  }
  collect();
  #ifdef DISPLAY
   cout << "After collecting for shutdown() for "
        << typeid(T).name() << "\n";
  #endif
}

To use the multithreaded garbage collector, include gcthrd.h in your program. Then, use GCPtr in the same way as described in Chapter 2. When you compile the program, you must remember to link in the multithreaded libraries, as explained earlier in this chapter in the section describing _beginthreadex( ) and endthreadex( ).

To see the effects of the multithreaded garbage collector, try this version of the load test program originally shown in Chapter 2:

// Demonstrate the multithreaded garbage collector. #include <iostream>
#include <new>
#include "gcthrd.h"
using namespace std;
// A simple class for load testing GCPtr.
class LoadTest {
  int a, b;
public:
  double n[100000]; // just to take-up memory
  double val;
  LoadTest() { a = b = 0; }
  LoadTest(int x, int y) {
   a = x;
   b = y;
   val = 0.0;
  }

  friend ostream &operator<(ostream &strm, LoadTest &obj);
};
// Create an insertor for LoadTest.
ostream &operator<(ostream &strm, LoadTest &obj) {
  strm << "(" << obj.a << " " << obj.b << ")";
  return strm;
}
int main() {
  GCPtr<LoadTest> mp;
  int i;
  for(i = 1; i < 2000; i++) {
   try {
     mp = new LoadTest(i, i);
     if(!(i%100))
       cout << "gclist contains " << mp.gclistSize()
            << " entries.\n";
   } catch(bad_alloc xa) {
     // For most users, this exception won't
     // ever occur.
     cout << "Last object: " << *mp << endl;
     cout << "Length of gclist: "
          << mp.gclistSize() << endl;
   }
  }
  return 0;
}

Here is a sample run. (Of course, your output may vary.) This output was produced with the display option turned on by defining DISPLAY within gcthrd.h.

Garbage collection started.
gclist contains 42 entries.
gclist contains 35 entries.
gclist contains 29 entries.
gclist contains 22 entries.
gclist contains 18 entries.
gclist contains 11 entries.
gclist contains 4 entries.
gclist contains 51 entries.
gclist contains 47 entries.
gclist contains 40 entries.
gclist contains 33 entries.
gclist contains 26 entries.
gclist contains 19 entries.
gclist contains 15 entries.
gclist contains 10 entries.
gclist contains 3 entries.
gclist contains 53 entries.
gclist contains 46 entries.
gclist contains 42 entries.
Before collecting for shutdown() for class LoadTest
After collecting for shutdown() for class LoadTest

As you can see, because collect( ) is running in the background, gclist never gets very large, even though thousands of objects are being allocated and abandoned.

Some Things to Try

Creating successful multithreaded programs can be quite challenging. One reason for this is the fact that multithreading requires that you think of programs in parallel rather than linear terms. Furthermore, at runtime, threads interact in ways that are often difficult to anticipate. Thus, you might be surprised (or even bewildered) by the actions of a multithreaded program. The best way to get good at multithreading is to play with it. Toward this end, here are some ideas that you might want to try.

Try adding another list box to the thread control panel that lets the user adjust the priority class of the thread in addition to its priority value. Try adding various synchronization objects to the control panel that can be turned on or off under user control. This will let you experiment with different synchronization options.

For the multithreaded garbage collector, try collecting garbage less often, such as when gclist reaches a certain size or after free memory drops to a predetermined point. Alternatively, you could use a waitable timer to activate garbage collection on a regular basis. Finally, you might want to experiment with the garbage collector’s priority class and settings to find which level is optimal for your use.

Introduction

In a previous series of articles named “Pointer Perfect,” I looked at how data stored in computer memory is accessible through pointers. The code you write for your application in the form of functions (these can be global or class member functions) is very much accessible through pointers in the same way, and I will introduce you to the syntax and usage of these function pointers in this article.

Function pointers are great for implementing callbacks and are very useful when you want to introduce late binding in your application. They help you parse configuration files, help you read protocols and can help you store a function call in an object when you want to delay or record the call (very useful in an undo/redo system).

Most C++ books treat function pointers superficially, which is very unfortunate; maybe this is because their syntax looks a bit weird when you first start using them. I hope to be able to convince you that the right function pointer at the right moment in the right place will make your code clearer, cleaner and easier to understand. Once you get past the odd syntax and come to understand the power of calling functions through pointers, a whole new level of abstraction will open up to you.

There is nothing like a quick example to take you straight to the heart of a topic. Here is a simple code example that uses a function pointer.

// main.cpp

#include

int IncOne(int var) {

return ++var;

}

int main(int argc, char *argv[]) {

// creating pointer to function

int (*inc_one)(int) = &IncOne;

// use the function the standard way

int result = IncOne(1);

(void)printf(“result is: %d\n”, result);

// utilize the function pointer

result = inc_one(1);

(void)printf(“result is: %d\n”, result);

return 0;

}

When you run this simple example, you will notice that both times the result printed is "2" -- as expected, of course. So what has the compiler come up with for us? Let’s take a peek into the debugger at the value stored in inc_one.

int (*inc_one)(int) = &IncOne;

00411A9E mov dword ptr [inc_one],offset IncOne (411523h)

It holds the address 0x00411523, and looking at the memory at that position we find the following line:

0041126C jmp IncOne (411A40h)

Our code is ordered to jump to 0x411A40, where we of course will find the code of our IncOne() function:

int IncOne(int var)

{

00411A40 push ebp

00411A41 mov ebp,esp

...

}

So what does the assembly in the debugger look like when we make a normal function call to IncOne() ?

int result=IncOne(1);

00411AA5 push 1

00411AA7 call IncOne (41126Ch)

Hold on! The debugger tells us that we go to 0x0041126c, where we are made to jump to IncOne (0x00422A40). So what happens when we call the function using the function pointer inc_one?

result=inc_one(1);

00411AC3 mov esi,esp

00411AC5 push 1

00411AC7 call dword ptr [inc_one]

Exactly the same thing! The content of inc_one is 0x0041126C, which, when called, makes our code jump to IncOne (0x00422A40), where the function is executed. This basically covers the whole concept of function pointers. All that is left now are the many (strange) forms in which they can appear.

The function pointer in our quick example points to the address of an ordinary C function. There are no special considerations for us to make in this case.

The code you compile to create your executable takes up a certain space in the computer's memory, where your data and functions will reside during its execution. Just like the data accessible through pointers, we have seen that functions are accessible in the very same way. The only thing a compiler has to know is how to interpret the address to which a pointer is pointing; this is where things can become slightly confusing, as we run into the often odd syntax of function pointers.

Just like regular pointers, function pointers are variables that need to be declared and defined. In the quick example you saw that inc_one is our function pointer variable, holding the pointer to a function that returns an int and that takes an int as a parameter.

To give you another example, if you declare the following function:

void AnotherFunction(std::string const &argument, float value);

Then you would assign the address of this function to a function pointer variable like this:

void (*fncptr)(std::string const&,float) = &AnotherFunction;

Hopefully you can see a pattern emerging here. The function declaration is basically being repeated, with the function name replaced by a "*varName," and only the types of the parameters are named. The retrieval of the address of a function works just like the address retrieval of a variable; you can use the address dereference operator "&."

Personally, I find the above demonstrated way of defining a function pointer a bit hard to read. When you need more variables to hold pointers to the same function, it can become quite laborious and sensitive to typing errors, too. Not to mention the fact that when the function definition changes, you would have to chase down and change every function pointer pointing to the changed function as well.

So here we will find the use of the typedef keyword very useful:

typedef int (*FncPtr)(int);

When we stick to the example, we can replace the add_one definition with:

FncPtr inc_one = &IncOne;

So you see that it is really easy to declare function pointers. Just as with normal pointers, you either use the pointer directly or you use it by dereferencing the pointer explicitly:

int result1 = inc_one(1);

int result2 = (*inc_one)(1);

Making the function call through a pointer or just the plain way will yield not very noticeable differences. It's quite nice to be able to abstract a function call into a variable, isn’t it?

Passing a function pointer as an argument to a function is quite essential when you want to implement callback functions. Although we won’t be looking at the implementation and usage of callback functions until later on, let’s take a look at the syntax right now.

The benefit of passing a function pointer as an argument to another function lies in the fact that this allows us to dictate which function that other function has to execute. There is nothing really different from what we have seen before, except for the fact that it looks slightly different.

// a raw declaration

void foo(int (*FPtr)(char const*));

// using a typedef

typedef int (*FuncPtr)(char const*);

void foo(FuncPtr fptr);

Did you recognize the function passed in through a pointer to foo? It is a function that takes a char const pointer as an argument and returns an int.

int func(char const *param);

Another tricky syntax is the raw declaration of a function that returns a function pointer.

// a raw declaration

int (*getFuncPtr1(int ID))(char const*);

// using a typedef

typedef int (*FuncPtr)(char const*);

FuncPtr getFuncPtr2(int ID);

It is pretty clear that the usage of a typedef clears things up a lot in this case. Did you notice that getFuncPtr1 returns a pointer to the same function (func) we had actually already declared before?

Since they are stored as variables, it is possible to have an array of function pointers -- but mixing the two guarantees a confusing syntax when you are going to do it all "raw." The beauty of function pointer arrays comes from the fact that you can bind functions to indices, which in turn could come from an enumeration you declared earlier on. This way you can create statements like: int res = (*opArray[PLUS])(a,b);.

// a raw declaration

int (*funcArray1[10])(char const*);

// using a typedef

typedef int (*FuncPtr)(char const*);

FuncPtr funcArray2[10];

// an example assignment

funcArray1[0] = funcArray2[5] = &func;

// example usage

int result1 = (*funcArray1[0])(“a test”);

int result2 = (*funcArray2[5])(“and then some”);

Let’s try to make this even more interesting and take a look at how we define pointers to templated functions. First we need a templated function to point at:

template T Inc(T var) {

return ++var;

}

Unfortunately the C++ standard doesn’t allow us to make template declarations in the scope of function bodies, so we cannot define a pointer to a templated function like this in main():

template T (*IncPtr)(T) = &Inc;

It is important to understand how compilers instantiate templates as well. They only instantiate templated code when it is needed, and they will not even detect a syntax error if the templated function is never called (a lot of clever and tricky meta template programming makes good use of this compiler behavior). It doesn’t make sense, and hopelessly complicates things for compiler builders, when you try to declare a templated pointer at a point where the compiler is hard at work instantiating code (as in function bodies). When you make a function call, data is going to be moved onto the memory stack, and the compiler needs to know which parameters to use. By trying to template the pointer, we are denying it that very information, and it won’t be able to continue the compilation.

So what is it we can do with the templated function Inc() we have? When we tell the compiler how we are planning to use the function, defining a function pointer to it works fine:

int main(int argc, char *argv[]) {

// Use Inc to increase an integer

int (*incN)(int) = &Inc;

int nres = incN(1);

(void)printf(“result is: %d\n”, nres);

// Use Inc to increase a float

float (*incF)(float) = &Inc;

float fres = incF(1.f);

(void)printf(“result is: %f\n”, fres);

}

When you run this example you will see that it works fine.

So is there no way we can delay the type definition of the function we want to define a function pointer to? Well, there is one location where this is possible: inside a templated function:

template

T Foo(T var) {

T (*incPtr)(T) = &Inc ;

return incPtr(var); }

Adding the following line to our example shows that it works fine:

int foores = Foo (1);

(void)printf(“result is: %d\n”, result);

When you think about it, it actually makes sense, because by the time Foo is instantiated, typename T is known by the compiler, and it has no problem instantiating the function pointer to Inc.

There is much more to function pointers than actually meets the eye. In the next article I will take a look at class member function pointers and place them in the same context I have done with the regular function pointers in this article. Finally, in the third article you will find a callback implementation example, function pointers mixed with calling conventions and an introduction to C++ functors.

In the previous article, Jun Nakamura introduced you to the use of regular function pointers, but when you write C++ code, you will be interested in C++ class member function pointers too. It is time to look at how to declare pointers to the members of classes you write for your applications.

Class Member Function Pointer Syntax

The declaration of a C++ member function pointer is a bit trickier than the regular ones we have seen so far and I have to say they look pretty strange as well.

You might wonder what the use of a member function pointer is. One of the uses I have found for it is in a protocol definition I wrote for a server application. The protocol is described in a static struct, where string messages are tied to pointers to the member functions in the protocol class that can handle specific messages. This ties the abstract knowledge of the messages to the lower functionality in the protocol class. Here is a section of that code:

static struct RQRSTable {
  unsigned int         privileges;
  ProtocolImpl::RQType requestType; 
  HandleFunc           function;
  string               header;
} rqrsTable[] =
{
// LOGIN -------------------------------------------------
// (CLT)RQ::LOGIN::<`username(str)`>
//   example RQ::LOGIN::`Jun`
  {
   Read | Write | Admin,  // privileges
   ProtocolImpl::Request, // request type 
   &ProtocolImpl::login,  // function
   “CLT::RS::LOGIN”       // header
  },
  ...
};

By now you should be able to see that &ProtocolImpl::login is the function pointer stored in this struct. It describes which function has to be called for which header. A simple loop in a parser function can extrapolate the header from a message, look it up in the struct and execute the attached function by making a call to
rqrsTable[idx].function().

Though a function pointer to a member function looks a bit more complex, it shouldn’t be too difficult to understand how they work now. Here is the function pointed at by the example:

bool ProtocolImpl::login(string const &msg, RQRSTable const *rt);

And this is the typedef I used to define the function pointer as used in the example struct:

typedef bool (ProtocolImpl::*HandleFunc)
                 (string const&, struct RQRSTable*);

It all doesn’t look that different from the regular function pointer syntax when you take a closer look at it. The main difference lies in the fact that you have to specify the class scope of the function pointer, so that the compiler understands that the function pointer is aimed at the member of a class.

Of course there are more ways to declare a member function in a class, so let’s use this simple class definition to try them out:

class MyClass {
public:
  MyClass() : m_value(0) {}
  void SetValue(int value) { m_value=value; }
  int GetValue() const { return m_value; }
  inline void InlineFoo() { (void)printf(“inlined\n”); }

static void foo(char const *msg, int value)
  { (void)printf(“%s %d\n”, msg, value); }
private:
  int m_value;
};

The function pointer comparable to the one used in the example struct is one that points to void MyClass::SetValue(int):

// raw declaration and assignment
void (MyClass::*svalue)(int) = &MyClass::SetValue;

// utilizing a typedef
typedef void (MyClass:*SValue)(int);
SValue svalue = &MyClass::SetValue;

So you see that the function pointer to a member function only needs ‘MyClass::’ in front of the variable name to declare it (which is probably the reason why it instinctively looks a bit weird). Member functions can have more identities than this one so let’s see how we define pointers to the other functions.

// raw declaration and assignment
int (MyClass::*gvalue)() const = &MyClass::GetValue;

// utilizing a typedef
typedef void (MyClass::GValue)() const;
GValue gvalue = &MyClass::GetValue;

A const member function pointer is defined the same way we have been declaring function pointers up to now: just add const.

// raw declaration and assignment
void (MyClass::*inlfoo)() = &MyClass::InlineFoo;

// utilizing a typedef
typedef void (MyClass::*InlFoo)();
InlFoo infloo = &MyClass::InlineFoo;

The function pointer above may come as a small surprise, because you would expect the code of an inlined member function to be pasted into where we normally would find the function call. However when you declare a member function pointer to an inlined function, the compiler creates a body for that function so that it can be executed when you call that member function pointer.

// raw declaration and assignment
void (*foo)(char const*, int) = &MyClass::foo;

// utilizing a typedef
typedef void (*FooPtr)(char const*, int);
FooPtr foo = &MyClass::foo;

Can you guess which member function is being pointed at by FooPtr without having to go back to the declaration of MyClass?

It is pointing at: ‘static void foo (char const * msg, int val );’ Again this may come a bit unexpected, but pointers to static member functions are declared just like the regular function pointers. And when you think about it… static member functions can be used just like regular functions, with them main difference being the fact that you have to provide the class scope (‘MyClass::’) when calling them.

Defining member function pointers is one thing; now let’s see how we use them. There are some specifics you have to be aware of when calling member functions in objects. Let’s write some code that tests the above defined member function pointers.

int main (int argc, char *argv[]) { =
  MyClass myclass;
  SValue svalue = &MyClass::SetValue;
  (myclass.*svalue)(0x1234);

  GValue gvalue = &MyClass::GetValue;
  int res = (myclass.*gvalue)();
  (void)printf(“result is 0x%d\n”, res);

  InlineFoo inlinefoo = &MyClass::InlineFoo; 
  (myclass.*inlinefoo)();

  FooPtr fooptr = &MyClass::foo;
  Fooptr(“result is: “, (myclass.*gvalue)());
}

It will generate the following output:

result is 0x00001234
inlined
result is: 4660

When you plan to use a member function pointer you will need an object of the class you are going to use it on. The syntax boils down to (myobject.*fncptr)(), where <MYOBJECT.> is the name of the instantiated class and <*FNCPTR> is the name of the used member function pointer.

How do member function pointers hold up in the face of Polymorphism? Will the function in a derived class be executed when we use a member function pointer containing the address of the baseclass function? Let me show you what I am getting at.

A typical way to make good use of polymorphism is to have a collection of base class pointers that are pointing to instantiated derived objects. To do this, you have to create the derived object and use the pointer to its baseclass:

class Base {
public:
virtual ~Base()=0;
virtual int foo() const=0;
};

class Deriv1 : public Base { public: int foo() { return 0; } };
class Deriv2 : public Base { public: int foo() { return 1; } };

// somewhere in your code
Base *ptr1 = new Deriv1;
int result = ptr1->foo(); // result will be 0

One of the great benefits of polymorphic classes is that you don’t have to be familiar with their implementation, only with their interface as it is declared in the baseclass. In the example above we know that there is a function called foo() but we don’t have to know what it exactly does. This can be a very useful concept for example in a game where there could be a list of game objects that all implement a run() function. The main game loop can call this run function on every game object, without having to know it is dealing with physics, A.I. or particle system objects. This also means you can add new game objects that implement different behaviors (and/or visuals) without having to make changes to the main code base.

So basically my question is: “When I use a member function pointer to Base::run() and use it on a Base* pointer that actually points to a derived game object… will the code in that game object be executed or will the code in the base object be executed?” A flipside question is whether it is possible to combine the member function pointer to Base::run() on a pointer (or reference) to a derived game object… thus not directly on Base itself. Let’s try this out with our Base and Deriv1 and Deriv2 example.

typedef int (Base::*BaseFooPtr)();
// ... later
BaseFooPtr fooptr = &Base::foo;
// ... test1 – try the BaseFooPtr on Base* to a Deriv1 object.
Base *baseptr = new Deriv1;
int result1 = (baseptr->*fooptr)();
// ... test2 – try the BaseFooPtr on a Deriv2 object.
Deriv2 myDeriv2;
Int result2 = (myDeriv2.*fooptr)();

Running this code you will find that member function pointers behave the same way you would expect normal function calls to behave in the face of polymorphism… answering both of my questions. The results are the same as when we wouldn’t have used a member function pointer but the regular functions calls instead. Thus result1 is 0 and result2 is 1!

It is very well possible that you want to pass a member function pointer to a function or return one from a function. We have seen that all we need to do is add the ‘MyClass::’ scope in front of the variable name, so lets look at how this translates to function parameters and return values. Let’s place the example function we’ve used before into class MyClass:

int MyClass::func(char const *param);

Here are some functions that accept a pointer to this member function:

// a raw declaration
void foo(int (MyClass::*FPtr)(char const*));

// using a typedef
typedef int (MyClass::*FuncPtr)(char const*);
void foo(FuncPtr fptr);

If you compare these function declarations with the ones in the previous article, you will see that indeed all you need to add is ‘MyClass::’. Declaring a function that returns a function pointer, we do the exact same thing:

// a raw declaration
int (MyClass::*getFuncPtr1(int ID))(char const*);

// using a typedef
typedef int (MyClass::*FuncPtr)(char const*);
FuncPtr GetFuncPtr2(int ID);

I honestly think that the raw declaration above (possibly combined with a couple of function pointers as parameters) is a good candidate for usage in an obfuscated C++ coding contest.

Do you understand the following function declaration?

char const* const ( MyClass::*FuncAt(
   void (MyClass::*Fptr1)(char, char),
   float (MyClass::*Fptr2)(int) ))(char const*, int);

Lets not even go there ;-) !

Member Function Pointer Arrays

Similar to the previous member function pointers described before; in order to create member function pointer arrays, we only need to add the class scope to the regular function pointer array declaration.

// a raw declaration
int (MyClass::*funcArray1[10])(char const*);

// using a typedef
typedef int (MyClass::*FuncPtr)(char const*);
FuncPtr funcArray2[10];

// initializing ome
funcArray1[0] = &MyClass::func;

// and finally making use of it
MyClass myClass;
int result1 = (MyClass.*funcArray1[0])(“a test”);

Now that we have seen the many forms function pointers can take, it is quite understandable that many C++ programming books treat this topic superficially. I hope I was able to shed some light in this rather shaded corner of the language and in the concluding article, I will show you the effect calling conventions have on function pointers, provide you with an example and introduce you to C++ functors.

In previous articles, Jun Nakamura introduced using regular function pointers, C++ class member function pointers, and declaring pointers to the members of classes. In this article, he writes about calling conventions, callback functions, and begins to talk about using functors.

There are many programming languages out there and a lot of them come with very useful libraries and APIs. It is possible to tie all these different libraries (coded in different languages) together in your main application.

Maybe you want to develop the user interface in Visual Basic, need a performance sensitive engine coded in C and C++ and have some legacy functionality of which nobody understands the implementation anymore running in Fortran. As you might have guessed, I have actually worked for a company that strung applications together that used libraries like these.

Different languages use different calling conventions because there are many ways to implement function calls on a computer. The main issue here is the order in which function parameters are passed to the function when it is called. These parameters are put onto the memory stack so that the function that is about to execute has access to them. The next issue is whether the caller or the called function will clean up these parameters.

Though I don’t want to go too deep into calling conventions, stacks etcetera, let me give you a small overview.

Alright, here is an overview of how different some Windows calling conventions can be (__pascal, __fortran and __syscall are no longer supported):

__cdecl
Argument Passing: right to left
Stack Maintenance: Calling function pops arguments from the stack
Name Decoration (C only): ‘_’ prefixed to function names (e.g. ‘_foo’)

__stdcall
Argument Passing: right to left
Stack Maintenance: Called function pops its own arguments from the stack
Name Decoration (C only): ‘_’ prefixed to function name, ‘@’ appended followed by the number of decimal bytes in the argument list. (e.g. ‘_foo@10’)

__fastcall (applies to Intel CPUs, this is the default calling convention for Borland)
Argument Passing: First two DWORD arguments are passed in ECX and EDX, the rest is passed right to left
Stack Maintenance: Called function pops its own arguments from the stack
Name Decoration (C only): ‘@’ is prefixed to the name, ‘@’ appended followed by the number decimal bytes in the argument list. (e.g. ‘@foo@10’)

thiscall (used automatically by C++ code)
Argument Passing: ‘this’ pointer put in ECX, arguments passed right to left
Stack Maintenance: Calling function pops arguments from the stack
Name Decoration: None

You see that there are many ways leading to Rome, and this is just on a Windows machine. What is interesting for this article though, is how we declare a function pointer to the following function definition:

void __stdcall Convention(int value, char const *string)
{
  (void)printf(“%d, ‘%s’\n”, value, string);
}

Again, the answer here is simple; we simply integrate the calling convention we need into the function pointer declaration:

void (__stdcall *ConvPtr)(int, char const*) = &Convention;

The principle remains the same whether it is a member function, a function argument, etc. Just bolt what you need into the declaration.

When your linker is giving you errors that it cannot resolve external symbols while you know that you are linking with the correct libraries; be sure to check which calling conventions are being used.

One of the great concepts of function pointers is that of the callback function. As you have seen it is pretty easy to transform the identity of a function into a pointer, which can point to different implementations of a function with that same identity (they all return the same type and accept the same type of parameters in the same sequence). This means that as long as you create a function that returns the right argument and takes the right argument(s), you can insert your own functionality into other people’s code.

An excellent example of this is a library that can read and render Macromedia Flash files, but has to run on a lot of different platforms including game consoles. Since memory management is radically different from console to console (there are no malloc or free functions standard on a Nintendo GameCube), the library allows you to register your own memory allocation and deallocation callback functions with it. Whenever it needs a piece of memory, it will use these callbacks, using your memory manager that implements the functionality they need. The library can focus on what it does best: playing .swf files and you can take care of the platform specific details without having to make any changes to the library.

Let’s look at an example a bit closer to home: qsort. By now you should be able to understand the following function declaration:

void qsort( void *base
             , size_t num
             , size_t width
             , int (__cdecl *comp)
                      (const void* e1, const void* e2)
          );

You will find it in <stdlib.h> and it is a quicksort implementation that sorts the items in base for you, according to your specification. Now how do you specify it to order your items when it doesn’t know anything about the type of the elements? Simple: provide it with a callback function that tells qsort how to compare two elements with each other.

The base address of your list of items is given to qsort through the void *base parameter. It can then figure out how to iterate through the items in the list, because you tell it how many items it contains with num and how big each item is with width. Finally the callback function you provide tells qsort whether an item is smaller than, bigger than, or equal to the other item.

The following example (for Microsoft only, because of the use of _stricmp which is not part of the ANSI standard) reads and sorts the command line parameters using qsort and a callback function.

#include <stdlib.h>
#include <string.h>
#include <stdio.h>

int comp(void const *arg1, void const *args) {
  // case insensitive comparison
  return _stricmp( *(char**)arg1, *(char**)arg2);
}

int main(int argc, char const *argv[])
{
  // remove application name from argv
  ++argv;
  --argc;
  // sort remaining arguments
  qsort((void*)argv, (size_t)argc, sizeof(char*), comp);
  // display result
  for (int idx=0; idx<argc; ++idx)
   (void)printf(“%s “, argv[idx]);
  (void)printf(“\n”);
}

Callback functions can also be very useful when you want to bind a token to a function. One of the examples I have shown you before in the previous article, contains a struct named RQRSTable. It contains a member named function and another one named header. Declared in a .cpp source file, structs like these allow you to configure your token/function binding centrally in the source code. They generally take on the following form:

static struct <StructName> {
  <member1 type> <member1 name>;
  ... 
  <memberN-1 type> <memberN-1 name>;
  <memberN type> <memberN name>;
} <array name>[] =
{ { <member value>, ..., <memberN-1 value>, <memberN value> }
, { <member value>, ..., <memberN-1 value>, <memberN value> }
...
};

Now that you have a static data object that can describe which function has to execute when a certain token is used. This can be very useful when you are parsing messages, upon which action has to be taken. If you don’t want to iterate to the array sequentially, you can always store the data in a hash table (like std::map) upon initialization and use the token as a key.

The function pointers in these structs are also callback functions. This is because, just like qsort, the function using them binds data to functions dynamically at runtime. This level of abstraction is very powerful because it allows you to create generic functions like qsort, platform independent libraries etc.

C++ has more tricks up its sleeve though. Allow me introduce you to functors.

Regular function pointers are quite easy to use, but as soon as you start using member function pointers, you need an object to use them on. They are no good to you otherwise.

You can also store both of them in a Functor and treat that functor object as a replacement function instead.

How does an object behave like a function? You overload operator () in a polymorphic MyFunctor base class from which we will implement derived functors. This way our main application can deal with MyFunctor without having to know what kind of specific derived implementations we have provided it. You can give it functors with extra debugging functionality or performance enhanced ones etc. The application won’t care; it will just call operator ().

// the abstract baseclass
class MyFunctor {
public:
  virtual ~MyFunctor() {}
  virtual int operator ()(char const *str)=0;
};

// derived implementation
template <class T> class DerFunctor : public MyFunctor {
public:
  DerFunctor(T* pObj, int (T::*funcPtr)(const char*))
     : m_funcPtr(funcPtr), m_pObject(pObj) {}

  int operator ()(char const *str) {
     return (m_pObject->*m_funcPtr)(str);
  }
private:
  int (T::*m_funcPtr)(const char*); // member func.ptr.
  T* m_pObject;                     // ptr. to object.
};

The constructor of DerFunctor takes a pointer to the object it can use the member function pointer on, which it receives as an argument as well. When we call operator () on an instantiated DerFunctor, it then executes that member function pointer on that object. Easy, isn’t it?

Here is how we can make good use of this.

class Dummy1 {
public:
  int Run(char const *str) { /*...*/ return 0; }
};

class Dummy2 {
public:
  int Run(char const *str) { /*...*/ return 1;
};

int main (int argc, char const *argv[]) {
  // here are the objects
  Dummy1 dummy1; 
  Dummy2 dummy2;
  // here are the functors
  DerFunctor<Dummy1> functor1(&dummy1, &Dummy1::Run);
  DerFunctor<Dummy2> functor2(&dummy2, &Dummy2::Run);
  // put them in an array to make it more interesting \
  MyFunctor* vtable[] = { &functor1, &functor2 };

  // make the call
  int res1 = functor1(“this is a test”);
  int res2 = (*vtable[1])(“this is a test”);
}

This functor example is extremely simplified and there is a lot more to be discussed. The base class I provided here for example, isn’t really generic and you won’t be able to reuse it really. Since these articles were about function pointers I will save the functors for another one.

Abstract

As a developer we often find ourselves surrounded by problems that actually have nothing to do with our productivity or even the project we're working on. One of them is the issue of compatibility between the Dynamic Link Libraries developed using different tools. Recently, while working on a project, I faced this problem, and in this article I'd  like to present my analysis. We'll also talk about writing DLLs that are easy for us develop and don't cause others to face similar problems when they try to use them.

I assume that you're familiar with using Microsoft Visual C++ and Borland C++ Builder, because these are the tools I'll use to expose the nature of problem and the solution.

Some people may argue that they can't imagine why someone would ever need to use DLLs written using one tool in some different tool. An elegant solution would be to have a special build of the DLL for every other tool that can consume the DLL; but, like many other people, I don't find it appealing. Moreover, there are circumstances where you're bound to work on these issues, such as:

• You do not have the source to the DLL, or even the import library. Don't know what an import library is? Don't worry; we'll talk about that shortly.
  
  
• You have existing applications to maintain and, to add a specific feature, you company has purchased a library. The source is, of course, not available, and you still need to figure out how to call the function when linker gives up saying there are unresolved externs.

I can add more to this list but I believe the above two points give you the idea. So let's see what the problem is, apart from understanding the terminology used in the context and finding a working solution for all of these problems. What I explain here will be specific to the tools I've been using, but I'm sure problems related to other tools won't be much different.

DLL Conventions: Issues and Solutions, Part I - A simple problem
(Page 2 of 4 )

Before we move on I'll explain a generic problem that you might have experienced first hand in your career as a developer, but dismissed because someone did that for you, or you took an entirely different approach to solve that problem.

Say you just downloaded the PDFLib PDF library and purchased the license to it. Prior to your purchase, you tried the sample applications and they all just compiled happily. Now when the development started, you realized that you'll be developing the applications that use the library in Borland C++ Builder 6.0 rather than Visual C++ 6.0, in which all the samples were written and compiled. If you've been through such a situation you can surely appreciate the description of the problem above.

Let's now analyze and find the cause and solution to the problem. If you're reading this just to gain some knowledge, then you'll surely find the basic terminology discussion beneficial.

A Dynamic Link Library (DLL) is a file that contains C Style functions or whole C++ classes that you can use for developing your applications to lessen your development effort and to save time when testing problems in a normal SDLC.

Any function that is visible outside the DLL and is intended for use by external client applications is said to be an export from the DLL. Consequently any client using this function from the DLL is said to have an import from the DLL. Sometimes we call all exported C Style functions and Classes to be exported symbols as a collection.

An import library is a file with a .lib extension and provides the compiler with enough information to resolve function call references if you choose to link implicitly at compile time. You may choose to load the DLL at runtime (using LoadLibrary API) and resolve and call functions then, by locating them in the DLL (using GetProcAddress API).

The import library is the key element if you're linking implicitly, and in most cases this poses a greater problem, as we'll see shortly. Also required is the header file and the DLL you're trying to use.

So now let's recap all we've discussed until now and then we shall move to analysis of the problem. While using third party DLLs in an environment which poses certain problems in the usage, we start with three elements (please note that we're stretching only to implicit linking, and that too with DLLs exporting C style functions, and explicit linking is not in the scope of our discussion right now. But we shall discuss it in the next article of this series):

1. The DLL built with any tool and exporting C Style functions only.
   
   
2. A header file that provides prototypes to all the functions exported by the DLL.
   
   
3. The import library that is emitted by the compiler when the DLL is built.

With these three ingredients we can have all the functions and classes at our disposal and use them freely in our code. We shall have real life problems so that we can see it all happen; so we'll be using a DLL built with Microsoft Visual C++ 6.0 in Borland C++ Builder 6.0. This case will be similar to the problem mentioned above (the PDFLib case).

DLL Conventions: Issues and Solutions, Part I - Where is the actual problem?
(Page 3 of 4 )

In a world where several vendors compete to make fabulous developer tools, it is certainly impossible to have interoperability, especially when there are no standards in place. In short, calling a DLL produced by Visual C++ would be not much different than calling a DLL built with Borland C++ Builder. But to my surprise, Borland and Microsoft disagree on several issues regarding the techniques they follow and embed in the developer tools they produce.

For instance, Borland and Microsoft disagree on file formats for intermediate object files (.OBJ files) and import library files (Visual C++ uses the COFF library format while Borland uses OMF). COFF stands for Common Object File Format and OMF stands for Object Metafile Format. This means that you can't add a Microsoft generated import library to a Borland C++ Builder project. But we developers owe a big thanks to Borland for providing the IMPLIB (Import Library) utility, which means the file format differences are no longer an issue of great concern.

Further the two C++ compilers produced by these two companies also disagree on naming conventions of the exported symbols produced as a result of linking the final DLL or Libraries. This is the root cause of most problems which we developers face while we try to bridge the gap between the two.

Each exported function/symbol in a DLL or OBJect file bears a linker name. The linker uses this linker name to resolve function references that remained unresolved during compile time in order to make the final output executable or DLL. The linker generates an unresolved external error if it is unable to find a function with a linker name in the program's code itself or in the list of import libraries provided to it.

As far as the linker names are concerned, Borland and Microsoft compilers disagree on the scheme that is used to generate the linker name. For example, the Microsoft Visual C++ compiler sometimes decorates exported __stdcall functions, while the Borland C++ Builder expects that only imported __cdecl functions be decorated. If you don't understand what __stdcall and __cdecl mean, don't worry; we'll be discussing them shortly in detail.

So "How does that creates problems for us developers?" might be the question coming to your mind. Okay, let's talk about that in plain words. Say you've created a DLL in VC++ that exports a function Foo() which uses the __stdcall convention. The linker name generated for this function looks like _Foo@4. When you try using this DLL in the Borland environment, the Borland linker first expects the .lib file (import library) to be in OMF format, and then looks for a name Foo only because it is not expecting to see a decorated name for a function using the __stdcall calling convention. Okay I told you that __cdecl and __stdcall are calling conventions, but let's leave them here before we discuss them in detail. Next the Borland compiler reports an unresolved external for the name Foo.

DLL Conventions: Issues and Solutions, Part I - In the Next Article
(Page 4 of 4 )

We can try to solve these problems in different ways depending on how the Visual C++ DLL was developed. Don't worry if you don't know about that too, because we have a lot of tools at our disposal that make it visible to us.

So in the next part of this series we'll discuss what these Calling Conventions are and how can we identify exported symbols and the used calling convention. And later we will discuss how to solve the problem.

This article presented the roadblocks that developers encounter while a Visual C++ DLL is to be used from a C++ Builder project.

You might have noticed that we're discussing only "How to call C style functions in a DLL" and there is not a word about classes exported by DLLs, but in future articles we shall discuss them to the extent possible. This is done intentionally because Visual C++ DLLs present more problems, because linker names for classes' member functions are mangled. The name mangling scheme is employed in order to support function overloading.

But again, there are differences in the schemes that different vendors adopt to mangle member names. The ANSI C++ standard does not govern the specifications of how a compiler should mangle class member names. Today, in absence of a strict standard in place, all the vendors have each developed their own techniques for name mangling, and the resulting conventions are certainly not compatible. But surely we now have ways to eradicate these subtle issues.

In the previous part of this series we saw the basic issues encountered when we try to use DLLs in an environment different from the one in which they were developed. We discussed the problems with plain C style functions exported from the DLLs, and the cause of these problems.

In this part we will elaborate on the calling conventions and how to resolve these differences, after we learn how to identify which calling conventions are in use for a specific exported function. Near the end we'll also take a look at the different tools and utilities available to help accomplish these tasks easily.

We'll also write some dummy DLLs and analyze them to get a firm grasp and clear understanding of the problems and the way we solve them.

This is something that happens at a very low level, say at the time your C or C++ code is compiled to native CPU instructions, and comes into the picture then. A good understanding of calling conventions can help you write better code, debug the code better, and finally enable you to use a source level debugger like Softice. But this is not something we'd like to get into. So we'll limit the discussion to our purpose -- how calling conventions affect functions exported from a DLL, and what benefit we get if we can find the calling convention used for a specific export.

When a function is invoked, whether it resides in a DLL or in your own source files, it receives its arguments/parameters through the stack. These arguments/parameters are set up for the called function by the calling function. We can use these parameters, but how does this frame of stack values get cleaned up? Of course it'll be done by either the caller or the callee. And this, finally, is specified by the specific calling convention used. You may have seen a few in action, but never took the time to understand what they actually are. Never mind, below is a list of keywords that will refresh your memory.

__pascal, __fortran, and __syscall,  __cdecl, __stdcall, __fastcall

Out of these PASCAL, FORTRAN and SYSCALL are obsolete and their use, even if supported, is discouraged. When we use the CDECL calling convention, the calling function is responsible for cleaning up the stack that it set up before the call was made, whereas in STDCALL and FASTCALL, the callee or the called function is responsible for the cleanup of stack.

Apart from the listed ones THISCALL ( thiscall ) is another convention which is the default calling convention used by C++ member functions that do not use variable arguments. Under thiscall, the callee cleans the stack, and as this is not a keyword, unlike other calling conventions, you can't explicitly specify it. To put it simply, you can assume it to be used whenever a class member function is called which uses the this pointer (that's right, static members don't use thiscall). Essentially, the thiscall convention applies to C++ only.

So now that you understand what these __cdecl and __stdcall mean, let's move on to identifying the convention used in functions exported to a DLL. For the purpose of demonstration you may use the DemoDLL project (as well as the compiled binaries) provided as a download with the article.

DLL Conventions: Issues and Solutions - Part II - How to identify exported symbols
(Page 2 of 4 )

You can use any tool that dumps information about a DLL import/export, such as tdump from Borland, or Dependency Walker (which comes bundled with Visual Studio). I use Depends.exe most of the time; I used it to view the exports from the MSVC as well as the BCB DLL. Below are the screen shots for the same. Figure 1 shows the exports for the DLL built with Borland C++ builder and Figure 2 shows the exports for the DLL built with Visual C++ Compiler.

Fig 1: Exports from the BCB built DemoDLL.dll

Fig 2: Exports from the MSVC built DemoDLL.dll

In order to see the true linker names you should turn the undecorated feature to off, as shown in Figure 3.

Fig 3: Turn undercoating OFF in order to view true linker names

DLL Conventions: Issues and Solutions - Part II - Solving the problem
(Page 3 of 4 )

From the first two figures above, you can clearly make out the different linker names generated by the Visual C++ Compiler and the Borland C++ Compiler. From the first figure you may see the symbols that are exported by the Borland built DLL, and they're exactly the same ones that any application developed in Borland Builder that uses this DLL would expect in the import library at link time.

But why are they different even when they're built from the same source? Yes, you guessed right! It's due to the differences in name mangling/name decoration techniques that these different compilers follow. To start with the analysis I'll first state a few facts on which our analysis will be based. The facts are:

• The default calling convention for Visual C++ 6.0 is __cdecl, that is, if you don't specify or omit the calling convention (see figure 4 below) it is assumed to be __cdecl.

Fig 4: Where to look for calling convention

For instance, __declspec(dllexport) int MyFoo(void); uses __stdcall.

• VC++ compiler always decorates function names that use the __stdcall calling convention. In specific cases where a module definition file has explicitly been used while building the DLL, the functions with __stdcall calling convention are not decorated or mangled. Essentially, one has less work to do if a .def file is used while building the DLL.
  
  If you wish to provide the operability between different compilers, you can consider using a .def file to explicitly define the exported symbols. In figure 2 you can observe that the FooSTDCALL function name has been decorated to _FooSTDCALL@0. It can also be observed that the last number is usually the number of bytes that the caller have to push on the stack before calling this DLL method; but it's just an observation, and I'm not sure if it is the same in all cases. Had the DLL been built using a module definition file (.def), the exported name will appear to be FooSTDCALL without the leading underscore and the trailing @XX.

• Borland C++ builder expects __cdecl function names to be decorated by prep ending an underscore.

Now that we have seen the problem in action, let's talk about the solution. The aim is to be able to use the DLL created in VC++ (with or without a .def file), which is accompanied by the header file for using that DLL in Borland C++ builder.

Essentially, based on the observations you made, you can now identify the calling convention used (by using Depends.exe and the DLL header file) and whether a .def file was used during the DLL build process (that is, the __stdcall functions are not decorated). Based on this, your approach to use the DLL in Borland Builder will vary. To proceed further, let's make a table of a single function on which we'll base our analysis.

Table 1: Comparison of the generated/expected linker names

DLL Conventions: Issues and Solutions - Part II - Use IMPLIB
(Page 4 of 4 )

Next, if you find that all exported symbols use the __stdcall and a .def has indeed been used while building the VC++ DLL, you may directly use the IMPLIB utility to generate a Borland (OMF) compatible import library. We can now simply add the generated .lib file along with the DLL header file to the Borland builder project, and use the imported functions as we wish. To use IMPLIB, follow the syntax at command prompt as under:

:>IMPLIB <libfile name to generate> <VC++ DLL name>

But if any function uses the __cdecl calling convention, or the .def was not used while building the VC++ DLL, then you're bound to do some more work before using the DLL in Borland Builder project. This is due to the fact that __cdecl names are decorated and, in the absence of the .def file, the __stdcall names are also decorated.

Here you first need to resolve the naming issues manually, and then create the import library from this modified information. To do so, you'll need the IMPDEF utility and build. There are command line tools that ship with Borland C++ builder that ease this task for you, but still you'll need to do some manual work. If we see this process in two steps, the first one would be to generate a .def file from the VC++ DLL (using the IMPDEF utility) and edit it, and the second one would be to build the .lib file using the above mentioned IMPLIB utility. The syntax to use for IMPDEF is as shown below:

:> IMPDEF <def file name> <VC++ DLL File name>

In order to make the names compatible you'll need to edit them so that they're the same as expected by the Borland Linker. After you've generated a def file you can edit it using notepad or any standard editor. Just provide an alias name for each export/linker name you wish to modify. For example the line containing FooCDECL will be changed to _FooCDECL = FooCDECL.You may ignore the @1 @2 numbers at the end of lines. Here the name at the left of = sign is the name expected by the Borland Linker whereas the name at the right is the true linker name exported by the VC++ Compiler. By providing the alias manually you've just made them equivalent.

And finally to create an import library from this aliased definition file you again use the IMPLIB utility as shown below:

:> IMPLIB <lib file name to generate> <aliased .def file name>

When you add this generated lib to your Borland project, all unresolved externals will be found by the linker, and it will be happy to link them in your code.

This article explained the different calling conventions in use with the most prominent compilers available today, and the differences between them. We also observed the differences due to non-availability of standards for the naming conventions for symbols exported from DLLs, and finally learned how to use available tools to analyze and bridge these gaps in order to use the DLLs built with VC++ 6.0 in Borland C++ Builder projects.

Worth mentioning is the COFF2OMF utility, which does most of this work you. It is available with the command line tools in the Borland Bin directory. But again, there is no guarantee that it will do all the work for you. The points that you learned and observed here will surely help you handle similar problems with DLLs. In case you have any suggestions or questions, feel free to write to me at Digvijay.Chauhan@gmail.com.