Threading Related

These functions abstract threading related aspects. More...

Macros
#define	ruMutexTryLock(m)   ruMutexTryLockLoc(m, __FILE__, __func__, __LINE__)
#define	ruMutexLock(m)   ruMutexLockLoc(m, __FILE__, __func__, __LINE__)
#define	ruMutexUnlock(m)   ruMutexUnlockLoc(m, __FILE__, __func__, __LINE__)
#define	ruCounterInc(counter, value)   ruCounterIncValue(counter, value, NULL)
#define	ruCounterRead(counter)   ruCounterIncValue(counter, 0, NULL)
#define	ruCountSet(counter, value)   ruCountSetValue(counter, value, NULL)

Typedefs
typedef void *	ruTrace
typedef unsigned long	ru_tid
typedef pthread_t	ruThreadId
typedef void *	ruThread
typedef void *	ruCount
typedef void *(*	ruStartFunc) (void *context)
typedef void *	ruCond
	Opaque object abstracting condition signaling.
typedef void *	ruMutex
	Opaque object abstracting object locking.

Functions
RUAPI void	ruBacktraceInit (perm_chars exePath)
	Sets the path to the current executable.
RUAPI ruList	ruBacktrace (int32_t *code)
	Returns a list of ruTrace elements ordered so that the caller is last.
RUAPI void	ruTraceLog (trans_chars tag, int32_t skip)
	Logs a backtrace.
RUAPI perm_chars	ruTraceStr (ruTrace rt)
	Returns an optimized string representation of the given ruTrace object.
RUAPI perm_chars	ruTraceFilePath (ruTrace rt)
	Returns the full path to the filename of the given ruTrace object if set.
RUAPI perm_chars	ruTraceFileName (ruTrace rt)
	Returns the basename of the filename of the given ruTrace object if set.
RUAPI perm_chars	ruTraceFunc (ruTrace rt)
	Returns the function name of the given ruTrace object if set.
RUAPI uint32_t	ruTraceLine (ruTrace rt)
	Returns the line number of the given ruTrace object if set.
RUAPI perm_ptr	ruTraceOffset (ruTrace rt)
	Returns the offset from the given function of the given ruTrace object if set.
RUAPI perm_ptr	ruTraceAddr (ruTrace rt)
	Returns the instruction pointer of the given ruTrace object.
RUAPI ru_tid	ruThreadGetId (void)
RUAPI void	ruThreadSetName (trans_chars name)
RUAPI perm_chars	ruThreadGetName (void)
RUAPI ruThread	ruThreadCreate (ruStartFunc start, alloc_chars name, void *usrCtx)
RUAPI ruThread	ruThreadCreateBg (ruStartFunc start, alloc_chars name, void *usrCtx)
	Creates a new thread with background priority.
RUAPI bool	ruThreadFinished (ruThread tid, int32_t *code)
	Whether thraed has finished and is joinable.
RUAPI ruThreadId	ruThreadNativeId (ruThread tid, int32_t *code)
	Returns the thread id of the given ruThread.
RUAPI bool	ruThreadWait (ruThread tid, sec_t tosecs, void **exitVal)
RUAPI int	ruThreadJoin (ruThread tid, void **exitVal)
RUAPI int32_t	ruThreadKill (ruThread tid)
RUAPI ruCond	ruCondInit (void)
	Initialize a new ruCond condition variable.
RUAPI ruCond	ruCondFree (ruCond c)
	Free up given ruCond object.
RUAPI void	ruCondSignal (ruCond c)
	Unblock a thread waiting for the given condition variable.
RUAPI void	ruCondWaitTil (ruCond c, ruMutex m, int32_t msTimeout)
	Wait on the given condition variable or the given timeout.
RUAPI void	ruCondWait (ruCond c, ruMutex m)
	Wait on the given condition variable.
RUAPI ruMutex	ruMutexInit (void)
	Initialize a new ruMutex.
RUAPI bool	ruMutexTryLockLoc (ruMutex m, trans_chars filePath, trans_chars func, int32_t line)
	Tries to aquire a lock for the given ruMutex without blocking.
RUAPI void	ruMutexLockLoc (ruMutex m, trans_chars filePath, trans_chars func, int32_t line)
	Aquire a lock for the given ruMutex blocking until it is given.
RUAPI void	ruMutexUnlockLoc (ruMutex m, trans_chars filePath, trans_chars func, int32_t line)
	Return the aquired mutex lock so other threads can use it.
RUAPI ruMutex	ruMutexFree (ruMutex m)
	Free up given ruMutex object.
RUAPI ruCount	ruCounterNew (int64_t initialCount)
	Returns a new thread safe counter initialized to given value.
RUAPI int64_t	ruCounterIncValue (ruCount counter, int64_t value, int32_t *code)
	Increments the counter by given value and returns the new value.
RUAPI int64_t	ruCountSetValue (ruCount counter, int64_t value, int32_t *code)
	Sets the counter to given value and returns the previous value.
RUAPI ruCount	ruCountFree (ruCount counter)
	Frees given counter.

Detailed Description

These functions abstract threading related aspects.

Macro Definition Documentation

ruCounterInc

#define ruCounterInc	(		counter,
			value
	)		ruCounterIncValue(counter, value, NULL)

Calls ruCounterIncValue without the code parameter

ruCounterRead

#define ruCounterRead

(

counter

)

ruCounterIncValue(counter, 0, NULL)

Calls ruCounterIncValue with 0 to simply return the current value

ruCountSet

#define ruCountSet	(		counter,
			value
	)		ruCountSetValue(counter, value, NULL)

Calls ruCountSetValue without the code parameter

ruMutexLock

#define ruMutexLock

(

m

)

ruMutexLockLoc(m, __FILE__, __func__, __LINE__)

ruMutexTryLock

#define ruMutexTryLock

(

m

)

ruMutexTryLockLoc(m, __FILE__, __func__, __LINE__)

ruMutexUnlock

#define ruMutexUnlock

(

m

)

ruMutexUnlockLoc(m, __FILE__, __func__, __LINE__)

Typedef Documentation

ru_tid

typedef unsigned long ru_tid

Thread Id type

ruCond

typedef void* ruCond

Opaque object abstracting condition signaling.

ruCount

typedef void* ruCount

Thread Safe Counter

ruMutex

typedef void* ruMutex

Opaque object abstracting object locking.

ruStartFunc

typedef void *(* ruStartFunc) (void *context)

Signature of a thread starting function.

ruThread

typedef void* ruThread

Thread Identifier

ruThreadId

typedef pthread_t ruThreadId

Native thread identifier

ruTrace

typedef void* ruTrace

Backtrace Element

Function Documentation

ruBacktrace()

RUAPI ruList ruBacktrace

(

int32_t *

code

)

Returns a list of ruTrace elements ordered so that the caller is last.

Parameters

code	(Optional) Stores RUE_OK on success or RUE_FEATURE_NOT_SUPPORTED when backtrace was not built in.

Returns

NULL on error or a list to be freed with ruListFree.

ruBacktraceInit()

RUAPI void ruBacktraceInit

(

perm_chars

exePath

)

Sets the path to the current executable.

Parameters

exePath

Optional for helping to find symbols.

ruCondFree()

RUAPI ruCond ruCondFree

(

ruCond

c

)

Free up given ruCond object.

Parameters

c	The condition variable to free.

Returns

NULL

ruCondInit()

RUAPI ruCond ruCondInit

(

void

)

Initialize a new ruCond condition variable.

Returns

The new condition variable or NULL in which case call ruLastError for details.

ruCondSignal()

RUAPI void ruCondSignal

(

ruCond

c

)

Unblock a thread waiting for the given condition variable.

Parameters

c	The condition variable to signal.

ruCondWait()

RUAPI void ruCondWait	(	ruCond	c,
		ruMutex	m
	)

Wait on the given condition variable.

This function blocks the current thread waiting on the given condition variable, unblocks the given mutex, and relocks it again.

Parameters

c	The condition variable to wait on.
m	The mutex to unblock and relock.

ruCondWaitTil()

RUAPI void ruCondWaitTil	(	ruCond	c,
		ruMutex	m,
		int32_t	msTimeout
	)

Wait on the given condition variable or the given timeout.

This function blocks the current thread waiting on the given condition variable, unblocks the given mutex, and relocks it again.

Parameters

c	The condition variable to wait on.
m	The mutex to unblock and relock.
msTimeout	Amount of millisecond to wait or 0 for infinitely

ruCounterIncValue()

RUAPI int64_t ruCounterIncValue	(	ruCount	counter,
		int64_t	value,
		int32_t *	code
	)

Increments the counter by given value and returns the new value.

Parameters

counter	Counter in question
value	value to increment counter by
code	Optional where error code will be stored

Returns

The new counter value

ruCounterNew()

RUAPI ruCount ruCounterNew

(

int64_t

initialCount

)

Returns a new thread safe counter initialized to given value.

Parameters

initialCount

Value to set at start

Returns

New ruCount free with ruCountFree

ruCountFree()

RUAPI ruCount ruCountFree

(

ruCount

counter

)

Frees given counter.

Parameters

counter

Counter to free

Returns

NULL

ruCountSetValue()

RUAPI int64_t ruCountSetValue	(	ruCount	counter,
		int64_t	value,
		int32_t *	code
	)

Sets the counter to given value and returns the previous value.

Parameters

counter	Counter in question
value	new value to set counter to
code	Optional where error code will be stored

Returns

The previous counter value

ruMutexFree()

RUAPI ruMutex ruMutexFree

(

ruMutex

m

)

Free up given ruMutex object.

Parameters

m	The mutex to free.

Returns

NULL

ruMutexInit()

RUAPI ruMutex ruMutexInit

(

void

)

Initialize a new ruMutex.

Returns

The new mutex or NULL in which case call ruLastError for details.

ruMutexLockLoc()

RUAPI void ruMutexLockLoc	(	ruMutex	m,
		trans_chars	filePath,
		trans_chars	func,
		int32_t	line
	)

Aquire a lock for the given ruMutex blocking until it is given.

The mutex is not meant to be reentrant, and is not on Windows. Meaning a thread calling ruMutexLock recursively will deadlock on the second call.

Parameters

m	The mutex to lock.
filePath	source file
func	function name
line	line number

ruMutexTryLockLoc()

RUAPI bool ruMutexTryLockLoc	(	ruMutex	m,
		trans_chars	filePath,
		trans_chars	func,
		int32_t	line
	)

Tries to aquire a lock for the given ruMutex without blocking.

Parameters

m	The mutex to lock.
filePath	source file
func	function name
line	line number

Returns

false if the mutex was locked. If true the acquired lock must be unlocked after use.

ruMutexUnlockLoc()

RUAPI void ruMutexUnlockLoc	(	ruMutex	m,
		trans_chars	filePath,
		trans_chars	func,
		int32_t	line
	)

Return the aquired mutex lock so other threads can use it.

Parameters

m	The mutex to unlock.
filePath	source file
func	function name
line	line number

ruThreadCreate()

RUAPI ruThread ruThreadCreate	(	ruStartFunc	start,
		alloc_chars	name,
		void *	usrCtx
	)

Creates a new thread

Parameters

start	The start function
name	The name of the thread must be alloced will be freed, or NULL
usrCtx	The start function's argument.

Returns

The thread identifier or NULL on failure in which case call ruLastError for details.

ruThreadCreateBg()

RUAPI ruThread ruThreadCreateBg	(	ruStartFunc	start,
		alloc_chars	name,
		void *	usrCtx
	)

Creates a new thread with background priority.

Parameters

start	The start function
name	The name of the thread must be alloced will be freed, or NULL
usrCtx	The start function's argument.

Returns

The thread identifier or NULL on failure in which case call ruLastError for details.

ruThreadFinished()

RUAPI bool ruThreadFinished	(	ruThread	tid,
		int32_t *	code
	)

Whether thraed has finished and is joinable.

Parameters

tid	Thread id of thread to join.
code	Optional where error code will be stored

Returns

true if joinable

ruThreadGetId()

RUAPI ru_tid ruThreadGetId

(

void

)

Returns the id of the running thread

Returns

thread id

ruThreadGetName()

RUAPI perm_chars ruThreadGetName

(

void

)

Returns the current thread name or NULL

Returns

Must not be freed.

ruThreadJoin()

RUAPI int ruThreadJoin	(	ruThread	tid,
		void **	exitVal
	)

Waits for given thread to terminate

Parameters

tid	Thread id of thread to join.
exitVal	Where the threads return value will be store if not NULL.

Returns

0 on success

ruThreadKill()

RUAPI int32_t ruThreadKill

(

ruThread

tid

)

Sends a kill signal to the specified thread.

Note

Currently not supported on Android

No longer supported on Windows due to it's dysfunctionality.

See also

https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminatethread#remarks

Threads that were not killed due to RUE_FEATURE_NOT_SUPPORTED will clean up after themselves should they arrive at their end point.

Parameters

tid	Thread id to send kill signal to

Returns

RUE_OK if the given thread id was valid RUE_FEATURE_NOT_SUPPORTED if thread termination is not implemented

ruThreadNativeId()

RUAPI ruThreadId ruThreadNativeId	(	ruThread	tid,
		int32_t *	code
	)

Returns the thread id of the given ruThread.

Parameters

tid	ruThread to return the native id of.
code	Optional where error code will be stored

Returns

The native ruThread id o r 0 on error.

ruThreadSetName()

RUAPI void ruThreadSetName

(

trans_chars

name

)

Sets or clear name of the running thread

Parameters

name	New name to set or NULL to clear/free the exisiting name.

ruThreadWait()

RUAPI bool ruThreadWait	(	ruThread	tid,
		sec_t	tosecs,
		void **	exitVal
	)

Waits for given thread to terminate for tosecs seconds and kills it after that

Note

Killing is currently not supported on Android.

Killing is no longer supported on Windows due to it's dysfunctionality.

See also

https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminatethread#remarks

ruThreadKill

Parameters

tid	Thread id of thread to join.
tosecs	Number of seconds to wait before killing the thread.
exitVal	Where the threads return value will be store if not NULL and thread wasn't killed.

Returns

false if thread timed out

ruTraceAddr()

RUAPI perm_ptr ruTraceAddr

(

ruTrace

rt

)

Returns the instruction pointer of the given ruTrace object.

Parameters

rt	ruTrace object in question.

Returns

The instruction pointer.

ruTraceFileName()

RUAPI perm_chars ruTraceFileName

(

ruTrace

rt

)

Returns the basename of the filename of the given ruTrace object if set.

Parameters

rt	ruTrace object in question.

Returns

The string belongs to the given ruTrace object and must not be freed.

ruTraceFilePath()

RUAPI perm_chars ruTraceFilePath

(

ruTrace

rt

)

Returns the full path to the filename of the given ruTrace object if set.

Parameters

rt	ruTrace object in question.

Returns

The string belongs to the given ruTrace object and must not be freed.

ruTraceFunc()

RUAPI perm_chars ruTraceFunc

(

ruTrace

rt

)

Returns the function name of the given ruTrace object if set.

Parameters

rt	ruTrace object in question.

Returns

The string belongs to the given ruTrace object and must not be freed.

ruTraceLine()

RUAPI uint32_t ruTraceLine

(

ruTrace

rt

)

Returns the line number of the given ruTrace object if set.

Parameters

rt	ruTrace object in question.

Returns

Yields 0 if not set.

ruTraceLog()

RUAPI void ruTraceLog	(	trans_chars	tag,
		int32_t	skip
	)

Logs a backtrace.

Parameters

tag	Content to log in front of the trace values.
skip	Number of frames to skip usually 2 to skip ruTraceLog and ruBacktrace.

ruTraceOffset()

RUAPI perm_ptr ruTraceOffset

(

ruTrace

rt

)

Returns the offset from the given function of the given ruTrace object if set.

Parameters

rt	ruTrace object in question.

Returns

The offset location.

ruTraceStr()

RUAPI perm_chars ruTraceStr

(

ruTrace

rt

)

Returns an optimized string representation of the given ruTrace object.

Parameters

rt	ruTrace object in question.

Returns

The string belongs to the given ruTrace object and must not be freed.