1. Introduction

Generally, a class library that offers "multi-threaded programming" can be separated into two different areas:

Types that support launching and controlling threads.
Types that support protecting data against corruption caused by uncontrolled concurrent access (racing conditions).

This is also true for this library (module) and hence this manual distinguishes these groups of types within the following chapters.

The portion of the module that is launching threads is in a very minimal and basic state of development. When the code was originally written, the goal was to "mimic" Java and C# thread classes, at least their minimal interface. This goal was meanwhile dropped, but still the classes have not been much developed.
If more sophisticated thread management is needed by an application, this module is not recommended. Or, some effort of extending it may be done. (In this case we're happy to receive your proposals in the case that your code complies to the license terms of ALib .)

In respect of to the other part of typical thread libraries, namely "locking data", we consider this library a little more advanced. The good news is of-course that any protection mechanism works in combination with any other thread libraries, may this be posix, Windows OS or threads imposed by the standard library of C++ 11 and later.

Attention: This module must not be omitted from an ALib Distribution if the using software does not make direct use of this module. If omitted, all other ALib Modules will silently (!) drop the protection of their resources against multi-threaded access.
In other words, this module has to be included in an ALib Distribution in the case that ALib is used in a multi-threaded environment!; If however, a single-threaded application is built, then omitting this module relieves all other ALib code from performing unnecessary mutex operations.; More details on this topic is found in chapter 2.4.4 Single Threaded Library Compilation of the Programmer's Manual of this library.

2. Bootstrapping and Termination

In case this module is used within a very limited ALib Distribution , please note the explanations found in the ALib Programmer's Manual, chapter 4.2 Bootstrapping Non-Camp Modules.

3. Thread Creation And Management

As explained in the introduction this module is not deemed to be very feature-rich in respect to the creation of threads. Especially as of today, there is no functionality on thread pools or similar organization of worker-threads. All that is available is

class Thread and
abstract class Runnable .

Their use is quite self-explanatory and documented with the types themselves.

It is no problem, to have threads started using different methods and libraries than the one found here, as long that such threads become "native" operation system threads. If later such a thread uses method Thread::GetCurrent ", a corresponding \ref alib::threads::Thread "Thread" object of \b %ALib is created internally and returned. This way, the externally created thread is automatically "registered" with \b %ALib . If not stated differently in the detailed documentation, from this point in time, the thread can be interfaced with \b %ALib classes in the same manner as if it was created using them. The same or similar should be \c true for the opposite situation. @section alib_threads_locks 4. Locks In the area of data protection and controlling concurrent access, this module provides the following types: - \ref alib::threads::ThreadLockNR "ThreadLockNR" <br> This is a very simple, non-recursive lock, based on standard library type <c>std::mutex</c>. - \ref alib::threads::ThreadLock "ThreadLock" <br> A lock that allows recursive locking. - \ref alib::threads::SmartLock "SmartLock" <br> A lock that becomes effective only more than one "interested party" registers with the lock. For details on the types, consult their reference documentation. All of them support - General deactivation if single-threaded use is assured - With debug builds, the source file and line number of the acquisition of the lock is noted. This helps to identify missing unlocks. - Their interfaces matches the one required by template class \ref alib::Owner "Owner" . This way, the locks can be used with macro \ref ALIB_OWN.<br> The latter is - for better readability - aliased by macro \ref ALIB_LOCK_WITH. In addition, macro \ref ALIB_LOCK is a shortcut to \ref ALIB_OWN "ALIB_OWN(*this)". @section alib_threads_optional 5. Optional Use When looking at the \ref alib_manual_modules_dependency_graph "module dependency graph" it can be noticed that even bigger, high-level modules do not depend on the inclusion of this module in the \ref alib_manual_modules_dist "ALib Distribution" . This does not mean that these modules are not implemented in a "thread safe fashion". In contrast, almost all modules are respecting thread safeness, however they do this only "optionally": While the dependency graph shows only \e mandatory dependencies, there are a lot of "optional dependencies" between other modules and this one. For example, class \ref alib::config::Configuration "Configuration" inherits from library class \ref alib::lang::PluginContainer "lang::PluginContainer" which, in case code selector symbol \b ALIB_THREADS evaluates to \c true, inherits from class \ref alib::threads::ThreadLock "ThreadLock" . Then class \b %Configuration uses macro \ref ALIB_LOCK to lock critical code sections against concurrent thread access. This macro is empty in the case this module is not included in the \ref alib_manual_modules_dist "ALib Distribution" . This way, single threaded applications may be using an \ref alib_manual_modules_dist "ALib Distribution" that excludes this module and have a (very small) gain in application footprint size and execution time.

Table of Contents

1. Introduction

2. Bootstrapping and Termination

3. Thread Creation And Management