A class representing a basic POSIX thread. More...

#include <PosixThread.hxx>

Public Types
using	PosixEntry = std::function<pthread::ExitValue (pthread::ThreadArg)>
	POSIX style entry function with a single input parameter and return value.

using	Entry = std::function<void (void)>
	Entry function without parameters for use with member functions or lambdas.

Public Member Functions
	PosixThread () noexcept
	Creates an empty thread object.

	PosixThread (PosixEntry entry, pthread::ThreadArg arg, const std::string_view name={})
	Creates a thread running in the provided PosixEntry function.

	PosixThread (Entry entry, const std::string_view name={})
	Creates a thread running in the provided simple Entry function.

	PosixThread (PosixThread &&other) noexcept

PosixThread &	operator= (PosixThread &&other) noexcept

bool	joinable () const
	Returns whether a thread is attached to this object (and needs to be joined).

pthread::ExitValue	join ()
	Blocks until the associated thread returns.

std::optional< pthread::ExitValue >	tryJoin ()
	Attempts to immediately joins the associated thread.

std::optional< pthread::ExitValue >	joinTimed (const RealTime ts)
	Waits for the associated thread to return for a given time period.

void	detach ()
	Detach a joinable thread.

const std::string &	name () const
	Returns a friendly name for the thread.

pthread::ID	id () const
	Returns an opaque thread ID object for the thread represented by this object.

bool	isCallerThread () const
	Returns whether the caller itself is the associated thread.

void	kill (const Signal sig)
	Wrapper around cosmos::pthread::kill().

Protected Member Functions
std::string	buildName (const std::string_view name, size_t nr) const

void	assertJoinConditions ()

void	reset ()

Protected Attributes
std::optional< pthread_t >	m_pthread
	POSIX thread handle.

std::string	m_name
	Friendly name of the thread.

Detailed Description

A class representing a basic POSIX thread.

Threads are created at construction time already and enter the specified entry function right away. There is no further modeling of the thread state beyond the joined state.

A PosixThread can either be empty or in a joinable state. An empty thread has no resources associated and no operations can be performed on it. Only in the joinable state can another thread perform a join operation which will block until the other thread exits. After the join operation is complete the state of the object will become empty again. A thread that exits before somebody joins it is still in the joinable state. A joinable thread must be joined before the associated PosixThread object is destroyed or move-assigned to.

A thread that is created in joinable state can be detached. This causes the thread object to become empty but the associated thread will continue running independently. No other thread needs to (or can) join a detached thread and its resources will be cleaned up automatically once the detached thread exits.

This class currently supports two types of entry points for threads:

PosixEntry: This is a thin wrapper around the low level POSIX thread entry function which receives a single void* and returns a single void*. The return value can be collected at join time. This entry variant can be used to interact with threads from other libraries or for very simple thread operations. Since the argument and return types aren't safe (need to be casted) it should only be used if really necessary.
Entry: This is a plain void (void) entry function. To pass data to the thread use e.g. std::bind to make the thread enter a member function, use a lambda with captures or similar.

PosixThread is a move-only type. It cannot be copied. The ownership can be transfer via std::move but be carefully that a thread that is not yet joined cannot be moved into, this will cause std::abort() to be called.

Definition at line 52 of file PosixThread.hxx.

Member Typedef Documentation

◆ Entry

using cosmos::PosixThread::Entry = std::function<void (void)>

Entry function without parameters for use with member functions or lambdas.

Definition at line 63 of file PosixThread.hxx.

◆ PosixEntry

using cosmos::PosixThread::PosixEntry = std::function<pthread::ExitValue (pthread::ThreadArg)>

POSIX style entry function with a single input parameter and return value.

Definition at line 61 of file PosixThread.hxx.

Constructor & Destructor Documentation

◆ PosixThread() [1/4]

cosmos::PosixThread::PosixThread ( )

inlinenoexcept

Creates an empty thread object.

This will simply create an empty thread object without invoking any system calls. Performing any operations on it will fail. joinable() will return false.

Definition at line 73 of file PosixThread.hxx.

73{}

◆ PosixThread() [2/4]

cosmos::PosixThread::PosixThread	(	PosixEntry	entry,
		pthread::ThreadArg	arg,
		const std::string_view	name = {} )

Creates a thread running in the provided PosixEntry function.

All necessary resources will be allocated and the thread will enter the given entry function.

On error cosmos::ApiError will be thrown.

Parameters

[in]	arg	The single parameter passed to the entry function.
[in]	name	An optional friendly name for the thread that is used in logging or possible in operating system facilities to more easily identify threads. If this is not specified then an automatically generated name will be used.

Definition at line 66 of file PosixThread.cxx.

                                                                                          :
                m_name{buildName(name, ++num_threads)} {
 
        m_pthread = pthread_t{};
        try {
                create_thread(m_pthread.value(), new Context{entry, arg});
        } catch(...) {
                m_pthread.reset();
        }
}

◆ PosixThread() [3/4]

cosmos::PosixThread::PosixThread	(	Entry	entry,
		const std::string_view	name = {} )

explicit

Creates a thread running in the provided simple Entry function.

See also: PosixThread(PosixEntry, pthread::ThreadArg, const string_view)

Definition at line 77 of file PosixThread.cxx.

                                                               :
                m_name{buildName(name, ++num_threads)} {
        m_pthread = pthread_t{};
        try {
                create_thread(m_pthread.value(), new Context{entry, pthread::ThreadArg{0}});
        } catch(...) {
                m_pthread.reset();
        }
}

◆ PosixThread() [4/4]

cosmos::PosixThread::PosixThread ( PosixThread && other )

noexcept

Definition at line 87 of file PosixThread.cxx.

                                                     {
        *this = std::move(other);
}

◆ ~PosixThread()

cosmos::PosixThread::~PosixThread ( )

virtual

Definition at line 91 of file PosixThread.cxx.

                          {
        if (joinable()) {
                fatal_error(sprintf("Thread %s destroyed but not joined!", name().c_str()));
        }
}

Member Function Documentation

◆ assertJoinConditions()

void cosmos::PosixThread::assertJoinConditions ( )

protected

Definition at line 109 of file PosixThread.cxx.

                                       {
        if (!joinable()) {
                cosmos_throw (UsageError("Attempted to join non-joinable thread (empty or detached)"));
        } else if (isCallerThread()) {
                cosmos_throw (UsageError("Attempted to join self"));
        }
}

◆ buildName()

std::string cosmos::PosixThread::buildName	(	const std::string_view	name,
		size_t	nr ) const

protected

Definition at line 196 of file PosixThread.cxx.

                                                                           {
        if (!name.empty())
                return std::string{name};
        return std::string{"thread<" + std::to_string(nr) + ">"};
}

◆ detach()

void cosmos::PosixThread::detach ( )

Detach a joinable thread.

This call is only allowed if joinable() returns true. Otherwise a UsageError is thrown.

On success the associated thread is converted into a detached thread. The object will become an empty thread. The detached thread will continue running independently and will automatically be cleaned up once it exits. The detached thread cannot be joined any more.

Definition at line 180 of file PosixThread.cxx.

                         {
        // NOTE: in theory it is valid that a thread detaches itself, so let's
        // not use assertJoinConditions() here ATM.
        if (!joinable()) {
                cosmos_throw (UsageError("Attempted to detach a non-joinable thread (empty or already detached)"));
        }
 
        const auto res = ::pthread_detach(*m_pthread);
 
        if (const auto error = Errno{res}; error != Errno::NO_ERROR) {
                cosmos_throw (ApiError("pthread_detach()", error));
        }
 
        reset();
}

◆ id()

pthread::ID cosmos::PosixThread::id ( ) const

inline

Returns an opaque thread ID object for the thread represented by this object.

This call is only allowed if joinable() returns true.

The returned object serves the purpose of comparing different threads to each other. Any thread can obtain its own ID by calling pthread::getID().

The returned object can also be used to obtain the native thread handle.

Definition at line 183 of file PosixThread.hxx.

183{ return pthread::ID{*m_pthread}; }

◆ isCallerThread()

bool cosmos::PosixThread::isCallerThread ( ) const

inline

Returns whether the caller itself is the associated thread.

Definition at line 186 of file PosixThread.hxx.

                                    {
                return id() == pthread::get_id();
        }

◆ join()

pthread::ExitValue cosmos::PosixThread::join ( )

Blocks until the associated thread returns.

This call is only allowed if joinable() returns true i.e. if currently a joinable thread is attached to this object.

The call will block forever until the target thread ends execution which can happen either by the thread returning from its entry function of by the thread calling pthread::exit().

The returned value is the one returned from a PosixEntry style entry function, the value provided to pthread::exit() or ExitValue{0} in any other cases.

Definition at line 125 of file PosixThread.cxx.

                                   {
        assertJoinConditions();
 
        void *res = nullptr;
        const auto join_res = ::pthread_join(*m_pthread, &res);
 
        if (const auto error = Errno{join_res}; error != Errno::NO_ERROR) {
                cosmos_throw (ApiError("pthread_join()", error));
        }
 
        reset();
 
        return pthread::ExitValue{reinterpret_cast<intptr_t>(res)};
}

◆ joinable()

bool cosmos::PosixThread::joinable ( ) const

inline

Returns whether a thread is attached to this object (and needs to be joined).

Definition at line 105 of file PosixThread.hxx.

                              {
                return m_pthread.has_value();
        }

◆ joinTimed()

std::optional< pthread::ExitValue > cosmos::PosixThread::joinTimed ( const RealTime ts )

Waits for the associated thread to return for a given time period.

This behaves similar to tryJoin() with the exception that the call blocks for a given time period before the operation fails and no value is returned.

Warning: The clock used for ts is the RealTimeClock, although the implementation (glibc) calculates an offset that will in turn be measured against MonotonicClock. So the timeout will be (somewhat) unaffected by discontinous changes to the realtime clock.

Definition at line 160 of file PosixThread.cxx.

                                                                      {
        assertJoinConditions();
 
        void *res = nullptr;
        const auto join_res = ::pthread_timedjoin_np(*m_pthread, &res, &ts);
 
        if (const auto error = Errno{join_res}; error != Errno::NO_ERROR) {
                if (error == Errno::TIMEDOUT) {
                        // couldn't join in time
                        return {};
                }
 
                cosmos_throw (ApiError("pthread_timedjoin_np()", error));
        }
 
        reset();
 
        return pthread::ExitValue{reinterpret_cast<intptr_t>(res)};
}

◆ kill()

void cosmos::PosixThread::kill ( const Signal sig )

inline

Wrapper around cosmos::pthread::kill().

Definition at line 191 of file PosixThread.hxx.

                                    {
                pthread::kill(id(), sig);
        }

◆ name()

const std::string & cosmos::PosixThread::name ( ) const

inline

Returns a friendly name for the thread.

If joinable() returns true then this returns a friendly name for the associated thread. Part of this will be the friendly name passed at construction time, or an automatically generated name otherwise.

If this is an empty thread then an empty string is returned.

Definition at line 170 of file PosixThread.hxx.

170{ return m_name; }

◆ operator=()

PosixThread & cosmos::PosixThread::operator= ( PosixThread && other )

noexcept

Definition at line 97 of file PosixThread.cxx.

                                                                {
        if (joinable()) {
                fatal_error("moving into not-yet-joined thread");
        }
        m_name = other.m_name;
        m_pthread = *(other.m_pthread);
 
        other.m_pthread.reset();
        other.m_name.clear();
        return *this;
}

◆ reset()

void cosmos::PosixThread::reset ( )

protected

Definition at line 117 of file PosixThread.cxx.

                        {
        if (m_pthread) {
                num_threads--;
                m_pthread.reset();
                m_name.clear();
        }
}

◆ tryJoin()

std::optional< pthread::ExitValue > cosmos::PosixThread::tryJoin ( )

Attempts to immediately joins the associated thread.

This behaves just like join() with the exception that it only polls once whether joining the thread is currently possible. If this is the case then the thread state is cleaned up and its return value returned. If joining is not possible then nothing is returned and the thread state is not changed. This call will not block.

Definition at line 140 of file PosixThread.cxx.

                                                   {
        assertJoinConditions();
 
        void *res = nullptr;
        const auto join_res = ::pthread_tryjoin_np(*m_pthread, &res);
 
        if (const auto error = Errno{join_res}; error != Errno::NO_ERROR) {
                if (error == Errno::BUSY) {
                        // cannot be joined yet
                        return {};
                }
 
                cosmos_throw (ApiError("pthread_tryjoin_np()", error));
        }
 
        reset();
 
        return pthread::ExitValue{reinterpret_cast<intptr_t>(res)};
}

Member Data Documentation

◆ m_name

std::string cosmos::PosixThread::m_name

protected

Friendly name of the thread.

Definition at line 209 of file PosixThread.hxx.

◆ m_pthread

std::optional<pthread_t> cosmos::PosixThread::m_pthread

protected

POSIX thread handle.

Definition at line 206 of file PosixThread.hxx.

The documentation for this class was generated from the following files:

include/thread/PosixThread.hxx
src/thread/PosixThread.cxx

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Entry

◆ PosixEntry

Constructor & Destructor Documentation

◆ PosixThread() [1/4]

◆ PosixThread() [2/4]

◆ PosixThread() [3/4]

◆ PosixThread() [4/4]

◆ ~PosixThread()

Member Function Documentation

◆ assertJoinConditions()

◆ buildName()

◆ detach()

◆ id()

◆ isCallerThread()

◆ join()

◆ joinable()

◆ joinTimed()

◆ kill()

◆ name()

◆ operator=()

◆ reset()

◆ tryJoin()

Member Data Documentation

◆ m_name

◆ m_pthread