Mutex, events, threads, and process objects based on pthreads. More...

Classes
class	Event
	Event object for signalling other threads. More...

class	Mutex
	A lightweight mutual exclusion lock. More...

class	Process
	Static functions for retrieving information about the running process. More...

class	RingBuffer
	Thread-safe circular ring buffer queue. More...

class	Thread
	Thread class for launching an asynchronous operating-system dependent thread. More...

Typedefs
typedef void (	ThreadEntryFunction) (void *user_param)
	Function pointer typedef representing a thread's main entry point. More...

Detailed Description

Mutex, events, threads, and process objects based on pthreads.

Class Documentation

◆ Event

class Event

Event object for signalling other threads.

Public Member Functions
	Event (bool auto_reset=true)
	Event constructor. More...

	~Event ()
	Destructor. More...

void	Wake ()
	Raise the event. More...

void	Reset ()
	Reset the event status to un-raised. More...

bool	Query ()
	Query the status of this event. More...

bool	Wait ()
	Wait until this event is raised. More...

bool	Wait (const timespec &timeout)
	Wait for a specified amount of time until this event is raised or timeout occurs. More...

bool	Wait (uint64_t timeout)
	Wait for a specified number of milliseconds until this event is raised or timeout occurs. More...

bool	WaitNs (uint64_t timeout)
	Wait for a specified number of nanoseconds until this event is raised or timeout occurs. More...

bool	WaitUs (uint64_t timeout)
	Wait for a specified number of microseconds until this event is raised or timeout occurs. More...

pthread_cond_t *	GetID ()
	Get the Event object. More...

Protected Attributes
pthread_cond_t	mID

Mutex	mQueryMutex

bool	mQuery

bool	mAutoReset

Constructor & Destructor Documentation

◆ Event()

Event::Event ( bool auto_reset = true )

inline

Event constructor.

By default, it will automatically be reset when it's raised.

Parameters

auto_reset Once this event has been raised, should it automatically be reset?

◆ ~Event()

Event::~Event ( )

inline

Destructor.

Member Function Documentation

◆ GetID()

pthread_cond_t* Event::GetID ( )

inline

Get the Event object.

◆ Query()

bool Event::Query ( )

inline

Query the status of this event.

Returns: True if the event is raised, false if not.

◆ Reset()

void Event::Reset ( )

inline

Reset the event status to un-raised.

◆ Wait() [1/3]

bool Event::Wait ( )

inline

Wait until this event is raised.

It is likely this will block this thread (and will never timeout).

See also: Wake

◆ Wait() [2/3]

bool Event::Wait ( const timespec & timeout )

inline

Wait for a specified amount of time until this event is raised or timeout occurs.

See also: Wake

◆ Wait() [3/3]

bool Event::Wait ( uint64_t timeout )

inline

Wait for a specified number of milliseconds until this event is raised or timeout occurs.

See also: Wake

◆ WaitNs()

bool Event::WaitNs ( uint64_t timeout )

inline

Wait for a specified number of nanoseconds until this event is raised or timeout occurs.

See also: Wake

◆ WaitUs()

bool Event::WaitUs ( uint64_t timeout )

inline

Wait for a specified number of microseconds until this event is raised or timeout occurs.

See also: Wake

◆ Wake()

void Event::Wake ( )

inline

Raise the event.

Any threads waiting on this event will be woken up.

Member Data Documentation

◆ mAutoReset

bool Event::mAutoReset

protected

◆ mID

pthread_cond_t Event::mID

protected

◆ mQuery

bool Event::mQuery

protected

◆ mQueryMutex

Mutex Event::mQueryMutex

protected

◆ Mutex

class Mutex

A lightweight mutual exclusion lock.

It is very fast to check if the mutex is available, lock it, and release it. However, if the mutex is unavailable when you attempt to lock it, execution of the thread will stop until it becomes available.

Public Member Functions
	Mutex ()
	Constructor. More...

	~Mutex ()
	Destructor. More...

bool	AttemptLock ()
	If the lock is free, aquire it. More...

void	Lock ()
	Aquire the lock, whenever it becomes available. More...

void	Unlock ()
	Release the lock. More...

void	Sync ()
	Wait for the lock, then release it immediately. More...

pthread_mutex_t *	GetID ()
	Get the mutex object. More...

Protected Attributes
pthread_mutex_t	mID

Constructor & Destructor Documentation

◆ Mutex()

Mutex::Mutex ( )

inline

Constructor.

◆ ~Mutex()

Mutex::~Mutex ( )

inline

Destructor.

Member Function Documentation

◆ AttemptLock()

bool Mutex::AttemptLock ( )

inline

If the lock is free, aquire it.

Otherwise, return without waiting for it to become available.

Returns: True if the lock was aquired, false if not.

◆ GetID()

pthread_mutex_t* Mutex::GetID ( )

inline

Get the mutex object.

◆ Lock()

void Mutex::Lock ( )

inline

Aquire the lock, whenever it becomes available.

This could mean just a few instructions if the lock is already free, or to block the thread if it isn't.

◆ Sync()

void Mutex::Sync ( )

inline

Wait for the lock, then release it immediately.

Use this in situations where you are waiting for an event to occur.

◆ Unlock()

void Mutex::Unlock ( )

inline

Release the lock.

Member Data Documentation

◆ mID

pthread_mutex_t Mutex::mID

protected

◆ Process

class Process

Static functions for retrieving information about the running process.

Static Public Member Functions
static pid_t	GetID ()
	Get this process ID (PID) More...

static pid_t	GetParentID ()
	Get the parent's process ID. More...

static std::string	GetCommandLine (pid_t pid=-1)
	Retrieve the command line of the process with the specified PID, or of this calling process if PID is -1 (which is the default). More...

static std::string	GetExecutablePath (pid_t pid=-1)
	Retrieve the absolute path of the process with the specified PID, or of this calling process if PID is -1 (which is the default). More...

static std::string	GetExecutableDir (pid_t pid=-1)
	Retrieve the directory that the process executable resides in. More...

static std::string	GetWorkingDir (pid_t pid=-1)
	Retrieve the current working directory of the process. More...

static void	Fork ()
	Duplicate the calling process. More...

Member Function Documentation

◆ Fork()

static void Process::Fork ( )

static

Duplicate the calling process.

◆ GetCommandLine()

static std::string Process::GetCommandLine ( pid_t pid = -1 )

static

Retrieve the command line of the process with the specified PID, or of this calling process if PID is -1 (which is the default).

◆ GetExecutableDir()

static std::string Process::GetExecutableDir ( pid_t pid = -1 )

static

Retrieve the directory that the process executable resides in.

For example, if the process executable is located at /usr/bin/exe, then GetExecutableDir() would return the path /usr/bin. If the specified PID is -1, then the calling process will be used.

◆ GetExecutablePath()

static std::string Process::GetExecutablePath ( pid_t pid = -1 )

static

Retrieve the absolute path of the process with the specified PID, or of this calling process if PID is -1 (which is the default).

This path will include the process' filename.

◆ GetID()

static pid_t Process::GetID ( )

static

Get this process ID (PID)

◆ GetParentID()

static pid_t Process::GetParentID ( )

static

Get the parent's process ID.

◆ GetWorkingDir()

static std::string Process::GetWorkingDir ( pid_t pid = -1 )

static

Retrieve the current working directory of the process.

If the specified PID is -1, then the calling process will be used.

◆ RingBuffer

class RingBuffer

Thread-safe circular ring buffer queue.

Public Types
enum	Flags { Read = (1 << 0), ReadOnce = (1 << 1) \| Read, ReadLatest = (1 << 2) \| Read, ReadLatestOnce = (1 << 3) \| ReadLatest, Write = (1 << 4), Threaded = (1 << 5), ZeroCopy = (1 << 6) }
	Ring buffer flags. More...

Public Member Functions
	RingBuffer (uint32_t flags=Threaded)
	Construct a new ring buffer. More...

	~RingBuffer ()
	Destructor. More...

bool	Alloc (uint32_t numBuffers, size_t size, uint32_t flags=0)
	Allocate memory for a set of buffers, where each buffer has the specified size. More...

void	Free ()
	Free the buffer allocations. More...

void *	Peek (uint32_t flags)
	Get the next read/write buffer without advancing the position in the queue. More...

void *	Next (uint32_t flags)
	Get the next read/write buffer and advance the position in the queue. More...

uint32_t	GetFlags () const
	Get the flags of the ring buffer. More...

void	SetFlags (uint32_t flags)
	Set the ring buffer's flags. More...

void	SetThreaded (bool threaded)
	Enable or disable multi-threading. More...

Protected Attributes
uint32_t	mNumBuffers

uint32_t	mLatestRead

uint32_t	mLatestWrite

uint32_t	mFlags

void **	mBuffers

size_t	mBufferSize

bool	mReadOnce

Mutex	mMutex

Member Enumeration Documentation

◆ Flags

enum RingBuffer::Flags

Ring buffer flags.

Enumerator
Read	Read the next buffer.
ReadOnce	Read the next buffer, but only if it hasn't been read before.
ReadLatest	Read the latest buffer in the queue, skipping other buffers that may not have been read.
ReadLatestOnce	Combination of ReadOnce and ReadLatest flags.
Write	Write the next buffer.
Threaded	Buffers should be thread-safe (enabled by default).
ZeroCopy	Buffers should be allocated in mapped CPU/GPU zeroCopy memory (otherwise GPU only)

Constructor & Destructor Documentation

◆ RingBuffer()

RingBuffer::RingBuffer ( uint32_t flags = Threaded )

inline

Construct a new ring buffer.

◆ ~RingBuffer()

RingBuffer::~RingBuffer ( )

inline

Destructor.

Member Function Documentation

◆ Alloc()

bool RingBuffer::Alloc	(	uint32_t	numBuffers,
		size_t	size,
		uint32_t	flags = `0`
	)

inline

Allocate memory for a set of buffers, where each buffer has the specified size.

If the requested allocation is compatible with what was already allocated, this will return true without performing additional allocations. Otherwise, the previous buffers are released and new ones are allocated.

Returns: true if the allocations succeeded or was previously done. false if a memory allocation error occurred.

◆ Free()

void RingBuffer::Free ( )

inline

Free the buffer allocations.

◆ GetFlags()

uint32_t RingBuffer::GetFlags ( ) const

inline

Get the flags of the ring buffer.

◆ Next()

void* RingBuffer::Next ( uint32_t flags )

inline

Get the next read/write buffer and advance the position in the queue.

◆ Peek()

void* RingBuffer::Peek ( uint32_t flags )

inline

Get the next read/write buffer without advancing the position in the queue.

◆ SetFlags()

void RingBuffer::SetFlags ( uint32_t flags )

inline

Set the ring buffer's flags.

◆ SetThreaded()

void RingBuffer::SetThreaded ( bool threaded )

inline

Enable or disable multi-threading.

Member Data Documentation

◆ mBuffers

void** RingBuffer::mBuffers

protected

◆ mBufferSize

size_t RingBuffer::mBufferSize

protected

◆ mFlags

uint32_t RingBuffer::mFlags

protected

◆ mLatestRead

uint32_t RingBuffer::mLatestRead

protected

◆ mLatestWrite

uint32_t RingBuffer::mLatestWrite

protected

◆ mMutex

Mutex RingBuffer::mMutex

protected

◆ mNumBuffers

uint32_t RingBuffer::mNumBuffers

protected

◆ mReadOnce

bool RingBuffer::mReadOnce

protected

◆ Thread

class Thread

Thread class for launching an asynchronous operating-system dependent thread.

To make your own thread, provide a function pointer of the thread's entry point, or inherit from this class and implement your own Run() function.

Public Member Functions
	Thread ()
	Default constructor. More...

virtual	~Thread ()
	Destructor. More...

virtual void	Run ()
	User-implemented thread main() function. More...

bool	Start ()
	Start the thread. More...

bool	Start (ThreadEntryFunction entry, void *user_param=NULL)
	Start the thread, utilizing an entry function pointer provided by the user. More...

void	Stop (bool wait=false)
	Signal for the thread to stop running. More...

int	GetPriorityLevel ()
	Get this thread's priority level. More...

bool	SetPriorityLevel (int priority)
	Set this thread's priority level. More...

pthread_t *	GetThreadID ()
	Get thread identififer. More...

bool	LockAffinity (unsigned int cpu)
	Lock this thread to a CPU core. More...

Static Public Member Functions
static void	InitRealtime ()
	Prime the system for realtime use. More...

static int	GetMaxPriority ()
	Get the maximum priority level available. More...

static int	GetMinPriority ()
	Get the minimum priority level avaiable. More...

static int	GetPriority (pthread_t *thread=NULL)
	Get the priority level of the thread. More...

static int	SetPriority (int priority, pthread_t *thread=NULL)
	Set the priority level of the thread. More...

static void	Yield (unsigned int ms)
	Whatever thread you are calling from, yield the processor for the specified number of milliseconds. More...

static bool	SetAffinity (unsigned int cpu, pthread_t *thread=NULL)
	Lock the specified thread's affinity to a CPU core. More...

static int	GetCPU ()
	Look up which CPU core the thread is running on. More...

Static Protected Member Functions
static void *	DefaultEntry (void *param)

Protected Attributes
pthread_t	mThreadID

bool	mThreadStarted

Constructor & Destructor Documentation

◆ Thread()

Thread::Thread ( )

Default constructor.

◆ ~Thread()

virtual Thread::~Thread ( )

virtual

Destructor.

Automatically stops the thread.

Member Function Documentation

◆ DefaultEntry()

static void* Thread::DefaultEntry ( void * param )

staticprotected

◆ GetCPU()

static int Thread::GetCPU ( )

static

Look up which CPU core the thread is running on.

◆ GetMaxPriority()

static int Thread::GetMaxPriority ( )

static

Get the maximum priority level available.

◆ GetMinPriority()

static int Thread::GetMinPriority ( )

static

Get the minimum priority level avaiable.

◆ GetPriority()

static int Thread::GetPriority ( pthread_t * thread = NULL )

static

Get the priority level of the thread.

Parameters

thread The thread, or if NULL, the currently running thread.

◆ GetPriorityLevel()

int Thread::GetPriorityLevel ( )

Get this thread's priority level.

◆ GetThreadID()

pthread_t* Thread::GetThreadID ( )

inline

Get thread identififer.

◆ InitRealtime()

static void Thread::InitRealtime ( )

static

Prime the system for realtime use.

Mostly this is locking a large group of pages into memory.

◆ LockAffinity()

bool Thread::LockAffinity ( unsigned int cpu )

Lock this thread to a CPU core.

◆ Run()

virtual void Thread::Run ( )

virtual

User-implemented thread main() function.

◆ SetAffinity()

static bool Thread::SetAffinity	(	unsigned int	cpu,
		pthread_t *	thread = `NULL`
	)

static

Lock the specified thread's affinity to a CPU core.

Parameters

cpu	The CPU core to lock the thread to.
thread	The thread, or if NULL, the currently running thread.

◆ SetPriority()

static int Thread::SetPriority	(	int	priority,
		pthread_t *	thread = `NULL`
	)

static

Set the priority level of the thread.

Parameters

thread The thread, or if NULL, the currently running thread.

◆ SetPriorityLevel()

bool Thread::SetPriorityLevel ( int priority )

Set this thread's priority level.

◆ Start() [1/2]

bool Thread::Start ( )

Start the thread.

This will asynchronously call the Run() function.

Returns: False if an error occurred and the thread could not be started.

◆ Start() [2/2]

bool Thread::Start	(	ThreadEntryFunction	entry,
		void *	user_param = `NULL`
	)

Start the thread, utilizing an entry function pointer provided by the user.

Returns: False if an error occurred and the thread could not be started.

◆ Stop()

void Thread::Stop ( bool wait = false )

Signal for the thread to stop running.

If wait is true, Stop() will block until the thread has exited.

◆ Yield()

static void Thread::Yield ( unsigned int ms )

static

Whatever thread you are calling from, yield the processor for the specified number of milliseconds.

Accuracy may vary wildly the lower you go, and depending on the platform.

Member Data Documentation

◆ mThreadID

pthread_t Thread::mThreadID

protected

◆ mThreadStarted

bool Thread::mThreadStarted

protected

Typedef Documentation

◆ ThreadEntryFunction

typedef void*(* ThreadEntryFunction) (void *user_param)

Function pointer typedef representing a thread's main entry point.

A user-defined parameter is passed through such that the user can pass data or other value to their thread so that it can self-identify.

Classes

Typedefs

Detailed Description

Class Documentation

◆ Event

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ Event()

◆ ~Event()

Member Function Documentation

◆ GetID()

◆ Query()

◆ Reset()

◆ Wait() [1/3]

◆ Wait() [2/3]

◆ Wait() [3/3]

◆ WaitNs()

◆ WaitUs()

◆ Wake()

Member Data Documentation

◆ mAutoReset

◆ mID

◆ mQuery

◆ mQueryMutex

◆ Mutex

Public Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ Mutex()

◆ ~Mutex()

Member Function Documentation

◆ AttemptLock()

◆ GetID()

◆ Lock()

◆ Sync()

◆ Unlock()

Member Data Documentation

◆ mID

◆ Process

Static Public Member Functions

Member Function Documentation

◆ Fork()

◆ GetCommandLine()

◆ GetExecutableDir()

◆ GetExecutablePath()

◆ GetID()

◆ GetParentID()

◆ GetWorkingDir()

◆ RingBuffer

Public Types

Public Member Functions

Protected Attributes

Member Enumeration Documentation

◆ Flags

Constructor & Destructor Documentation

◆ RingBuffer()

◆ ~RingBuffer()

Member Function Documentation

◆ Alloc()

◆ Free()

◆ GetFlags()

◆ Next()

◆ Peek()

◆ SetFlags()

◆ SetThreaded()

Member Data Documentation

◆ mBuffers

◆ mBufferSize

◆ mFlags

◆ mLatestRead

◆ mLatestWrite

◆ mMutex

◆ mNumBuffers

◆ mReadOnce

◆ Thread

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Protected Attributes