Using Threads

The HP aC++ run-time environment supports multi-threaded applications. The following HP aC++ libraries are thread-safe with the limitations cited below.

Rogue Wave Standard C++ Library 2.2.1 Rogue Wave Standard C++ Library 1.2.1 and Tools.h++ 7.0.6
  • libstd_v2.sl and libstd_v2.a
  • libCsup_v2.sl and libCsup_v2.a
  • libstd.sl and libstd.a
  • librwtool.sl and librwtool.a
  • libCsup.sl and libCsup.a
  • libstream.sl and libstream.a

Using Locks

To guarantee that your I/O results from one thread are not intermingled with I/O results from other threads, you must protect your I/O statements with locks. For example: 

// create a mutex and initialize it
pthread_mutex_t the_mutex;  
#ifdef _PTHREADS_DRAFT4     // for user threads
pthread_mutex_init(&the_mutex, pthread_mutexattr_default);
#else                       // for kernel threads 
pthread_mutex_init(&the_mutex, (pthread_mutexattr_t *)NULL);
#endif

pthread_mutex_lock(&the_mutex);
cout << "something" ... ;
pthread_mutex_unlock(&the_mutex);

Note that conditional compilation may be necessary to accommodate both the user threads and the kernel threads interfaces, as in the above example. An alternative might be to compose a buffer with an ostrstream and output with one write. The following example could be used with the cfront compatible libstream. 

ostrstream ostr;
ostr << "something" /*...*/ ;
ostr << " or another" /*...*/ << endl;
cout.write(ostr.str(), ostr.pcount());
ostr.rdbuf()->freeze(0);
Note that the above example works with with the new library, though with the deprecated ostrstream.

Or something similar can be done with the Rogue Wave Standard C++ Library 2.2.1 (libstd_v2) with standard ostringstream, as in the following example: 

ostringstream ostr;
ostr << "something" /*...*/ ;
ostr << " or another" /*...*/ << endl;
cout.write(ostr.str().c_str(), ostr.str().length());
Note that cout.flush() may be needed if sharing the file with stdio.

Required Command-line Options

To use the multi-thread safe capabilities of the Standard C++ Library , you need to specify the following options at both compile and link time. Note that options differ depending on which set of libraries you are using.

Rogue Wave Standard C++ Library 2.2.1 Rogue Wave Standard C++ Library 1.2.1 and Tools.h++ 7.0.6
  • -D_RWSTD_MULTI_THREAD
  • -D_REENTRANT
  • -lcma (This option applies only to user threads.)
  • -D__HPACC_THREAD_SAFE_RB_TREE (Code compiled with this option is binary incompatible with code that is not compiled with this option. Only HP aC++ version A.01.21 and subsequent versions and subsequent versions incorporate this option.)
  • -DRWSTD_MULTI_THREAD
  • -DRW_MULTI_THREAD (needed only for the Tools.h++ Library)
  • -D_REENTRANT
  • -lcma (This option applies only to user threads.)
  • -lpthread (This option applies only to kernel threads.)
  • -D_THREAD_SAFE (Unlike the other options in this table, this option is not required. You can use it with the cout, cin, cerr, and clog objects, if you are not using locks.)

WARNING: If you do not specify these options as described in the above table, a run-time error will be generated or multi-thread behavior will be incorrect.

Limitations

In most cases, thread safety does not imply that the same object can be shared between threads. In particular, when objects have user visible state, it would not make sense to share them between threads. Consider the following: 
void f(ostream &out, int x, int y) {
       out << setw(3) << x << setw(10) << y;
}
This function would not be thread safe if called from multiple threads with the same object, since the "width" in the shared object could be changed at any time. Therefore, such objects are not protected from interactions between multiple threads, and the result of sharing such an object between threads is undefined.

If the same object is shared between threads, a runtime crash, abort, or intermingled output may occur. With the Rogue Wave Standard C++ Library 2.2.1, output may be intermingled but no aborts will occur.

Using -D_THREAD_SAFE with the cfront Compatible libstream

There is an exception to the above rule for the cfront compatible libstream. For the frequently used objects cout, cin, cerr, and clog, you can specify the -D_THREAD_SAFE compile time flag for any file that includes <iostream.h>. In this case, a new instance of the object is transparently created for each thread that uses it. All instances share the same file descriptor. The f() function in the above example will now work, because it receives one new "out" object per thread. However, the results of two simultaneous executions of f() will be mixed in any order in the output.

Using -D_THREAD_SAFE with the global scope operator is not supported for cout, cin, cerr, and clog. For example, the following code would generate an error: 

::cout << endl;

Note, if you use locks, you need not use the -D_THREAD_SAFE compile time flag since you are now responsible for ensuring thread safety.

Differences between Standard iostreams and cfront Compatible libstream

The cfront compatible libstream supports locking for each insertion. Rogue Wave Standard C++ Library 1.2.1 and Tools.h++ 7.0.6 do not support locking but do provide a thread private buffer.

Visible differences would be as follows. In the case of standard iostreams, there is intermingling of each component being inserted. With cfront compatible iostreams, there is intermingling of complete buffers (depending on when endl or flush is called).

Using -D__HPACC_THREAD_SAFE_RB_TREE

The Rogue Wave Standard C++ Library 1.2.1 (libstd) and Tools.h++ 7.0.6 (librwtool) are not thread safe if the underlying implementation rb_tree class is involved. In other words, if the tree header file (which includes tree.cc) under /opt/aCC/include/ is used, these libraries are not thread safe. Most likely, it is indirectly referenced by including the standard C++ library container class map or set headers, or by including a RogueWave tools.h++ header like tvset.h, tpmset.h, tpmset.h, tvset.h, tvmset.h, tvmset.h, tpmap.h, tpmmap.h, tpmmap.h, tvmap.h, tvmmap.h.

Since changing the rb_tree implementation to make it thread safe would break binary compatibility, the preprocessing macro, __HPACC_THREAD_SAFE_RB_TREE, must be defined. Whether or not this macro is defined when compiling a file that includes the tree header, its use must be consistent. For example, a new object file compiled with the macro defined should not be linked with older ones that were compiled without the macro defined. Library providers whose library is built with the the macro defined may need to notify their users to also compile their source with the macro defined when the tree header is included.

Exception Handling

It is illegal to throw out of a thread.

The following example illustrates that you cannot catch an object which has been thrown in a different thread. To do so will result in a runtime abort since HP aC++ finds no available catch handler and terminate is called. 

#include <pthread.h>
void foo() {
   int i = 10;
   throw i;
}
int main() {
   pthread_t tid;
   try {
      ret=pthread_create(&tid, ???, (void*(*)(void*))foo, 0);
   }
   catch(int n) {}
}

For More Information

See documentation on using threads and writing multi-threaded applications.