Namespaces
namespace	internal

namespace	mpl

namespace	tbb

namespace	ThisThread

namespace	thread_pool

namespace	Threading

Classes
class	Backtrace

class	EnvSettings

struct	JoinFunction

struct	JoinFunction< void, JoinArg >

struct	JoinFunction< void, void >

class	PackagedTask
	The task class is supplied to thread_pool. More...

struct	ScopeDestructor

class	Singleton
	Singleton object that allows a deleter class to be specified. More...

class	Task
	The task class is supplied to thread_pool. More...

class	Task< RetT, void >
	The task class is supplied to thread_pool. More...

class	Task< void, void >
	The task class is supplied to thread_pool. More...

class	TaskFuture
	The task class is supplied to thread_pool. More...

class	TaskGroup

class	TaskManager

class	TaskRunManager

class	TaskSubQueue

class	TemplateAutoLock

class	ThreadData

class	ThreadPool

class	Timer

class	UserTaskQueue

class	VTask
	VTask is the abstract class stored in thread_pool. More...

class	VUserTaskQueue

Typedefs
using	AutoLock = TemplateAutoLock< Mutex >

using	RecursiveAutoLock = TemplateAutoLock< RecursiveMutex >

template<typename FuncT , typename... ArgTypes>
using	ResultOf_t = typename std::result_of< FuncT(ArgTypes...)>::type

template<typename T >
using	decay_t = typename std::decay< T >::type

template<bool B, typename T = void>
using	enable_if_t = typename std::enable_if< B, T >::type

template<typename Tp , typename Arg = Tp>
using	TBBTaskGroup = TaskGroup< Tp, Arg >

using	tbb_global_control_t = tbb::global_control

using	tbb_task_group_t = tbb::task_group

using	tbb_task_arena_t = tbb::task_arena

using	Thread = std::thread

using	NativeThread = std::thread::native_handle_type

using	Pid_t = std::thread::id

using	Condition = std::condition_variable

using	ThreadId = Thread::id

template<typename Tp >
using	Future = std::future< Tp >

template<typename Tp >
using	SharedFuture = std::shared_future< Tp >

template<typename Tp >
using	Promise = std::promise< Tp >

using	Mutex = std::mutex

using	RecursiveMutex = std::recursive_mutex

template<typename Tp >
using	EnvChoice = std::tuple< Tp, std::string, std::string >

template<typename Tp >
using	EnvChoiceList = std::set< EnvChoice< Tp > >

Functions
std::string	Demangle (const char *_str)

std::string	Demangle (const std::string &_str)

template<typename Tp >
std::string	Demangle ()

template<typename Tp , typename MutexTp = Mutex, size_t N = 4>
MutexTp &	TypeMutex (const unsigned int &_n=0)

std::ostream &	operator<< (std::ostream &os, const Timer &t)

template<typename... Args>
void	ConsumeParameters (Args &&...)

template<typename Tp >
Tp	GetEnv (const std::string &env_id, Tp _default=Tp())

template<>
bool	GetEnv (const std::string &env_id, bool _default)

template<typename Tp >
Tp	GetEnv (const std::string &env_id, Tp _default, const std::string &msg)

template<typename Tp >
Tp	GetEnv (const std::string &env_id, const EnvChoiceList< Tp > &_choices, Tp _default)

template<typename Tp >
Tp	GetChoice (const EnvChoiceList< Tp > &_choices, const std::string &str_var)

void	PrintEnv (std::ostream &os=std::cout)

Detailed Description

Class Description:

This class provides a mechanism to create a mutex and locks/unlocks it. Can be used by applications to implement in a portable way a mutexing logic. Usage Example:

 #include "Threading.hh"
 #include "AutoLock.hh"

 /// defined somewhere -- static so all threads see the same mutex
 static Mutex aMutex;

 /// somewhere else:
 /// The AutoLock instance will automatically unlock the mutex when it
 /// goes out of scope. One typically defines the scope within { } if
 /// there is thread-safe code following the auto-lock

 {
     AutoLock l(&aMutex);
     ProtectedCode();
 }

 UnprotectedCode();

 /// When ProtectedCode() is calling a function that also tries to lock
 /// a normal AutoLock + Mutex will "deadlock". In other words, the
 /// the mutex in the ProtectedCode() function will wait forever to
 /// acquire the lock that is being held by the function that called
 /// ProtectedCode(). In this situation, use a RecursiveAutoLock +
 /// RecursiveMutex, e.g.

 /// defined somewhere -- static so all threads see the same mutex
 static RecursiveMutex aRecursiveMutex;

 /// this function is sometimes called directly and sometimes called
 /// from SomeFunction_B(), which also locks the mutex
 void SomeFunction_A()
 {
     /// when called from SomeFunction_B(), a Mutex + AutoLock will
     /// deadlock
     RecursiveAutoLock l(&aRecursiveMutex);
     /// do something
 }

 void SomeFunction_B()
 {

     {
         RecursiveAutoLock l(&aRecursiveMutex);
         SomeFunction_A();
     }

     UnprotectedCode();
 }

Author: Andrea Dotti (15 Feb 2013): First Implementation

Update: Jonathan Madsen (9 Feb 2018): Replaced custom implementation with inheritance from C++11 unique_lock, which inherits the following member functions:

unique_lock(unique_lock&& other) noexcept;
explicit unique_lock(mutex_type& m);
unique_lock(mutex_type& m, std::defer_lock_t t) noexcept;
unique_lock(mutex_type& m, std::try_to_lock_t t);
unique_lock(mutex_type& m, std::adopt_lock_t t);
template <typename Rep, typename Period> unique_lock(mutex_type& m, const std::chrono::duration<Rep,Period>& timeout_duration);
template<typename Clock, typename Duration> unique_lock(mutex_type& m, const std::chrono::time_point<Clock,Duration>& timeout_time);
void lock();
void unlock();
bool try_lock();
template <typename Rep, typename Period> bool try_lock_for(const std::chrono::duration<Rep,Period>&);
template <typename Rep, typename Period> bool try_lock_until(const std::chrono::time_point<Clock,Duration>&);
void swap(unique_lock& other) noexcept;
mutex_type* release() noexcept;
mutex_type* mutex() const noexcept;
bool owns_lock() const noexcept;
explicit operator bool() const noexcept;
unique_lock& operator=(unique_lock&& other);

Note that AutoLock is defined also for a sequential Tasking build but below regarding implementation (also found in Threading.hh)

     NOTE ON Tasking SERIAL BUILDS AND MUTEX/UNIQUE_LOCK
     ==================================================

Mutex and RecursiveMutex are always C++11 std::mutex types however, in serial mode, using MUTEXLOCK and MUTEXUNLOCK on these types has no effect – i.e. the mutexes are not actually locked or unlocked

Additionally, when a Mutex or RecursiveMutex is used with AutoLock and RecursiveAutoLock, respectively, these classes also suppressing the locking and unlocking of the mutex. Regardless of the build type, AutoLock and RecursiveAutoLock inherit from std::unique_lock<std::mutex> and std::unique_lock<std::recursive_mutex>, respectively. This means that in situations (such as is needed by the analysis category), the AutoLock and RecursiveAutoLock can be passed to functions requesting a std::unique_lock. Within these functions, since std::unique_lock member functions are not virtual, they will not retain the dummy locking and unlocking behavior --> An example of this behavior can be found below

Jonathan R. Madsen (February 21, 2018)

Typedef Documentation

◆ AutoLock

using PTL::AutoLock = typedef TemplateAutoLock<Mutex>

Definition at line 479 of file AutoLock.hh.

◆ Condition

using PTL::Condition = typedef std::condition_variable

Definition at line 43 of file Threading.hh.

◆ decay_t

template<typename T >

using PTL::decay_t = typedef typename std::decay<T>::type

Definition at line 54 of file Globals.hh.

◆ enable_if_t

template<bool B, typename T = void>

using PTL::enable_if_t = typedef typename std::enable_if<B, T>::type

Definition at line 57 of file Globals.hh.

◆ EnvChoice

template<typename Tp >

using PTL::EnvChoice = typedef std::tuple<Tp, std::string, std::string>

Definition at line 50 of file Utility.hh.

◆ EnvChoiceList

template<typename Tp >

using PTL::EnvChoiceList = typedef std::set<EnvChoice<Tp> >

Definition at line 55 of file Utility.hh.

◆ Future

template<typename Tp >

using PTL::Future = typedef std::future<Tp>

Definition at line 50 of file Threading.hh.

◆ Mutex

using PTL::Mutex = typedef std::mutex

Definition at line 57 of file Threading.hh.

◆ NativeThread

using PTL::NativeThread = typedef std::thread::native_handle_type

Definition at line 38 of file Threading.hh.

◆ Pid_t

using PTL::Pid_t = typedef std::thread::id

Definition at line 40 of file Threading.hh.

◆ Promise

template<typename Tp >

using PTL::Promise = typedef std::promise<Tp>

Definition at line 54 of file Threading.hh.

◆ RecursiveAutoLock

using PTL::RecursiveAutoLock = typedef TemplateAutoLock<RecursiveMutex>

Definition at line 480 of file AutoLock.hh.

◆ RecursiveMutex

using PTL::RecursiveMutex = typedef std::recursive_mutex

Definition at line 58 of file Threading.hh.

◆ ResultOf_t

template<typename FuncT , typename... ArgTypes>

using PTL::ResultOf_t = typedef typename std::result_of<FuncT(ArgTypes...)>::type

Definition at line 81 of file Backtrace.hh.

◆ SharedFuture

template<typename Tp >

using PTL::SharedFuture = typedef std::shared_future<Tp>

Definition at line 52 of file Threading.hh.

◆ tbb_global_control_t

using PTL::tbb_global_control_t = typedef tbb::global_control

Definition at line 123 of file ThreadData.hh.

◆ tbb_task_arena_t

using PTL::tbb_task_arena_t = typedef tbb::task_arena

Definition at line 125 of file ThreadData.hh.

◆ tbb_task_group_t

using PTL::tbb_task_group_t = typedef tbb::task_group

Definition at line 124 of file ThreadData.hh.

◆ TBBTaskGroup

template<typename Tp , typename Arg = Tp>

using PTL::TBBTaskGroup = typedef TaskGroup<Tp, Arg>

Definition at line 38 of file TBBTaskGroup.hh.

◆ Thread

using PTL::Thread = typedef std::thread

Definition at line 37 of file Threading.hh.

◆ ThreadId

using PTL::ThreadId = typedef Thread::id

Definition at line 46 of file Threading.hh.

Function Documentation

◆ ConsumeParameters()

template<typename... Args>

void PTL::ConsumeParameters ( Args && ... )

Definition at line 44 of file Utility.hh.

45{}

Referenced by PTL::ThreadPool::set_default_use_cpu_affinity(), PTL::ThreadPool::set_use_tbb(), PTL::Threading::SetPinAffinity(), and PTL::Threading::SetThreadPriority().

◆ Demangle() [1/3]

template<typename Tp >

std::string PTL::Demangle ( )

inline

Definition at line 135 of file Backtrace.hh.

{
    return Demangle(typeid(Tp).name());
}

Referenced by Demangle().

◆ Demangle() [2/3]

std::string PTL::Demangle ( const char * _str )

inline

Definition at line 109 of file Backtrace.hh.

{
#if defined(PTL_DEMANGLE_AVAILABLE)
    // demangling a string when delimiting
    int   _status = 0;
    char* _ret    = ::abi::__cxa_demangle(_str, nullptr, nullptr, &_status);
    if(_ret && _status == 0)
        return std::string(const_cast<const char*>(_ret));
    return _str;
#else
    return _str;
#endif
}

◆ Demangle() [3/3]

std::string PTL::Demangle ( const std::string & _str )

inline

Definition at line 126 of file Backtrace.hh.

{
    return Demangle(_str.c_str());
}

◆ GetChoice()

template<typename Tp >

Tp PTL::GetChoice	(	const EnvChoiceList< Tp > &	_choices,
		const std::string &	str_var
	)

Definition at line 315 of file Utility.hh.

{
    auto asupper = [](std::string var) {
        for(auto& itr : var)
            itr = (char)std::toupper(itr);
        return var;
    };
 
    std::string upp_var = asupper(str_var);
    Tp          var     = Tp();
    // check to see if string matches a choice
    for(const auto& itr : _choices)
    {
        if(asupper(std::get<1>(itr)) == upp_var)
        {
            // record value defined by environment
            return std::get<0>(itr);
        }
    }
    std::istringstream iss(str_var);
    iss >> var;
    // check to see if string matches a choice
    for(const auto& itr : _choices)
    {
        if(var == std::get<0>(itr))
        {
            // record value defined by environment
            return var;
        }
    }
    // the value set in env did not match any choices
    std::stringstream ss;
    ss << "\n### Environment setting error @ " << __FUNCTION__ << " (line " << __LINE__
       << ")! Invalid selection \"" << str_var << "\". Valid choices are:\n";
    for(const auto& itr : _choices)
        ss << "\t\"" << std::get<0>(itr) << "\" or \"" << std::get<1>(itr) << "\" ("
           << std::get<2>(itr) << ")\n";
    std::cerr << ss.str() << std::endl;
    abort();
}

◆ GetEnv() [1/4]

template<>

bool PTL::GetEnv	(	const std::string &	env_id,
		bool	_default
	)

inline

Definition at line 180 of file Utility.hh.

{
    char* env_var = std::getenv(env_id.c_str());
    if(env_var)
    {
        std::string var = std::string(env_var);
        bool        val = true;
        if(var.find_first_not_of("0123456789") == std::string::npos)
            val = (bool) atoi(var.c_str());
        else
        {
            for(auto& itr : var)
                itr = (char)std::tolower(itr);
            if(var == "off" || var == "false")
                val = false;
        }
        // record value defined by environment
        EnvSettings::GetInstance()->insert<bool>(env_id, val);
        return val;
    }
    // record default value
    EnvSettings::GetInstance()->insert<bool>(env_id, false);
 
    // return default if not specified in environment
    return _default;
}

◆ GetEnv() [2/4]

template<typename Tp >

Tp PTL::GetEnv	(	const std::string &	env_id,
		const EnvChoiceList< Tp > &	_choices,
		Tp	_default
	)

Definition at line 246 of file Utility.hh.

{
    auto asupper = [](std::string var) {
        for(auto& itr : var)
            itr = (char)std::toupper(itr);
        return var;
    };
 
    char* env_var = std::getenv(env_id.c_str());
    if(env_var)
    {
        std::string str_var = std::string(env_var);
        std::string upp_var = asupper(str_var);
        Tp          var     = Tp();
        // check to see if string matches a choice
        for(const auto& itr : _choices)
        {
            if(asupper(std::get<1>(itr)) == upp_var)
            {
                // record value defined by environment
                EnvSettings::GetInstance()->insert(env_id, itr);
                return std::get<0>(itr);
            }
        }
        std::istringstream iss(str_var);
        iss >> var;
        // check to see if string matches a choice
        for(const auto& itr : _choices)
        {
            if(var == std::get<0>(itr))
            {
                // record value defined by environment
                EnvSettings::GetInstance()->insert(env_id, itr);
                return var;
            }
        }
        // the value set in env did not match any choices
        std::stringstream ss;
        ss << "\n### Environment setting error @ " << __FUNCTION__ << " (line "
           << __LINE__ << ")! Invalid selection for \"" << env_id
           << "\". Valid choices are:\n";
        for(const auto& itr : _choices)
            ss << "\t\"" << std::get<0>(itr) << "\" or \"" << std::get<1>(itr) << "\" ("
               << std::get<2>(itr) << ")\n";
        std::cerr << ss.str() << std::endl;
        abort();
    }
 
    std::string _name = "???";
    std::string _desc = "description not provided";
    for(const auto& itr : _choices)
        if(std::get<0>(itr) == _default)
        {
            _name = std::get<1>(itr);
            _desc = std::get<2>(itr);
            break;
        }
 
    // record default value
    EnvSettings::GetInstance()->insert(env_id, EnvChoice<Tp>(_default, _name, _desc));
 
    // return default if not specified in environment
    return _default;
}

◆ GetEnv() [3/4]

template<typename Tp >

Tp PTL::GetEnv	(	const std::string &	env_id,
		Tp	_default,
		const std::string &	msg
	)

Definition at line 212 of file Utility.hh.

{
    char* env_var = std::getenv(env_id.c_str());
    if(env_var)
    {
        std::string        str_var = std::string(env_var);
        std::istringstream iss(str_var);
        Tp                 var = Tp();
        iss >> var;
        std::cout << "Environment variable \"" << env_id << "\" enabled with "
                  << "value == " << var << ". " << msg << std::endl;
        // record value defined by environment
        EnvSettings::GetInstance()->insert<Tp>(env_id, var);
        return var;
    }
    // record default value
    EnvSettings::GetInstance()->insert<Tp>(env_id, _default);
 
    // return default if not specified in environment
    return _default;
}

◆ GetEnv() [4/4]

template<typename Tp >

Tp PTL::GetEnv	(	const std::string &	env_id,
		Tp	_default = `Tp()`
	)

Definition at line 155 of file Utility.hh.

{
    char* env_var = std::getenv(env_id.c_str());
    if(env_var)
    {
        std::string        str_var = std::string(env_var);
        std::istringstream iss(str_var);
        Tp                 var = Tp();
        iss >> var;
        // record value defined by environment
        EnvSettings::GetInstance()->insert<Tp>(env_id, var);
        return var;
    }
    // record default value
    EnvSettings::GetInstance()->insert<Tp>(env_id, _default);
 
    // return default if not specified in environment
    return _default;
}

◆ operator<<()

std::ostream & PTL::operator<<	(	std::ostream &	os,
		const Timer &	t
	)

inline

Definition at line 165 of file Timer.hh.

{
    // so fixed doesn't propagate
    std::stringstream ss;
    ss << std::fixed;
    if(t.IsValid())
    {
        ss << "Real=" << t.GetRealElapsed() << "s User=" << t.GetUserElapsed()
           << "s Sys=" << t.GetSystemElapsed() << "s";
 
        // avoid possible FPE error
        if(t.GetRealElapsed() > 1.0e-6)
        {
            double cpu_util =
                (t.GetUserElapsed() + t.GetSystemElapsed()) / t.GetRealElapsed() * 100.0;
            ss << std::setprecision(1);
            ss << " [Cpu=" << std::setprecision(1) << cpu_util << "%]";
        }
    }
    else
    {
        ss << "Real=****s User=****s Sys=****s";
    }
    os << ss.str();
 
    return os;
}

◆ PrintEnv()

void PTL::PrintEnv ( std::ostream & os = std::cout )

inline

Definition at line 359 of file Utility.hh.

{
    os << (*EnvSettings::GetInstance());
}

◆ TypeMutex()

template<typename Tp , typename MutexTp = Mutex, size_t N = 4>

MutexTp & PTL::TypeMutex ( const unsigned int & _n = 0 )

Definition at line 74 of file Threading.hh.

{
    static std::array<MutexTp, N> _mutex_array{};
    return _mutex_array[_n % N];
}

Referenced by PTL::ThreadPool::destroy_threadpool(), PTL::ThreadPool::initialize_threadpool(), PTL::ThreadPool::set_affinity(), PTL::ThreadPool::set_priority(), PTL::ThreadPool::start_thread(), PTL::ThreadPool::ThreadPool(), and PTL::UserTaskQueue::UserTaskQueue().

Namespaces

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ AutoLock

◆ Condition

◆ decay_t

◆ enable_if_t

◆ EnvChoice

◆ EnvChoiceList

◆ Future

◆ Mutex

◆ NativeThread

◆ Pid_t

◆ Promise

◆ RecursiveAutoLock

◆ RecursiveMutex

◆ ResultOf_t

◆ SharedFuture

◆ tbb_global_control_t

◆ tbb_task_arena_t

◆ tbb_task_group_t

◆ TBBTaskGroup

◆ Thread

◆ ThreadId

Function Documentation

◆ ConsumeParameters()

◆ Demangle() [1/3]

◆ Demangle() [2/3]

◆ Demangle() [3/3]

◆ GetChoice()

◆ GetEnv() [1/4]

◆ GetEnv() [2/4]

◆ GetEnv() [3/4]

◆ GetEnv() [4/4]

◆ operator<<()

◆ PrintEnv()

◆ TypeMutex()