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. More...

typedef void *	ruMutex
	Opaque object abstracting object locking. More...

Functions
RUAPI void	ruBacktraceInit (perm_chars exePath)
	Sets the path to the current executable. More...

RUAPI ruList	ruBacktrace (int32_t *code)
	Returns a list of ruTrace elements ordered so that the caller is last. More...

RUAPI void	ruTraceLog (trans_chars tag, int32_t skip)
	Logs a backtrace. More...

RUAPI perm_chars	ruTraceStr (ruTrace rt)
	Returns an optimized string representation of the given ruTrace object. More...

RUAPI perm_chars	ruTraceFilePath (ruTrace rt)
	Returns the full path to the filename of the given ruTrace object if set. More...

RUAPI perm_chars	ruTraceFileName (ruTrace rt)
	Returns the basename of the filename of the given ruTrace object if set. More...

RUAPI perm_chars	ruTraceFunc (ruTrace rt)
	Returns the function name of the given ruTrace object if set. More...

RUAPI uint32_t	ruTraceLine (ruTrace rt)
	Returns the line number of the given ruTrace object if set. More...

RUAPI perm_ptr	ruTraceOffset (ruTrace rt)
	Returns the offset from the given function of the given ruTrace object if set. More...

RUAPI perm_ptr	ruTraceAddr (ruTrace rt)
	Returns the instruction pointer of the given ruTrace object. More...

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. More...

RUAPI bool	ruThreadFinished (ruThread tid, int32_t *code)
	Whether thraed has finished and is joinable. More...

RUAPI ruThreadId	ruThreadNativeId (ruThread tid, int32_t *code)
	Returns the thread id of the given ruThread. More...

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. More...

RUAPI ruCond	ruCondFree (ruCond c)
	Free up given ruCond object. More...

RUAPI void	ruCondSignal (ruCond c)
	Unblock a thread waiting for the given condition variable. More...

RUAPI void	ruCondWaitTil (ruCond c, ruMutex m, int32_t msTimeout)
	Wait on the given condition variable or the given timeout. More...

RUAPI void	ruCondWait (ruCond c, ruMutex m)
	Wait on the given condition variable. More...

RUAPI ruMutex	ruMutexInit (void)
	Initialize a new ruMutex. More...

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. More...

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. More...

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. More...

RUAPI ruMutex	ruMutexFree (ruMutex m)
	Free up given ruMutex object. More...

RUAPI ruCount	ruCounterNew (int64_t initialCount)
	Returns a new thread safe counter initialized to given value. More...

RUAPI int64_t	ruCounterIncValue (ruCount counter, int64_t value, int32_t *code)
	Increments the counter by given value and returns the new value. More...

RUAPI int64_t	ruCountSetValue (ruCount counter, int64_t value, int32_t *code)
	Sets the counter to given value and returns the previous value. More...

RUAPI ruCount	ruCountFree (ruCount counter)
	Frees given counter. More...

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

Parameters

tid	Thread id to send kill signal to

Returns: RUE_OK if the given thread id was valid

◆ 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.

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.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ruCounterInc

◆ ruCounterRead

◆ ruCountSet

◆ ruMutexLock

◆ ruMutexTryLock

◆ ruMutexUnlock

Typedef Documentation

◆ ru_tid

◆ ruCond

◆ ruCount

◆ ruMutex

◆ ruStartFunc

◆ ruThread

◆ ruThreadId

◆ ruTrace

Function Documentation

◆ ruBacktrace()

◆ ruBacktraceInit()

◆ ruCondFree()

◆ ruCondInit()

◆ ruCondSignal()

◆ ruCondWait()

◆ ruCondWaitTil()

◆ ruCounterIncValue()

◆ ruCounterNew()

◆ ruCountFree()

◆ ruCountSetValue()

◆ ruMutexFree()

◆ ruMutexInit()

◆ ruMutexLockLoc()

◆ ruMutexTryLockLoc()

◆ ruMutexUnlockLoc()

◆ ruThreadCreate()

◆ ruThreadCreateBg()

◆ ruThreadFinished()

◆ ruThreadGetId()

◆ ruThreadGetName()

◆ ruThreadJoin()

◆ ruThreadKill()

◆ ruThreadNativeId()

◆ ruThreadSetName()

◆ ruThreadWait()

◆ ruTraceAddr()

◆ ruTraceFileName()

◆ ruTraceFilePath()

◆ ruTraceFunc()

◆ ruTraceLine()

◆ ruTraceLog()

◆ ruTraceOffset()

◆ ruTraceStr()