51Degrees Device Detection C/C++  4.5

A device detection library that is used natively or by 51Degrees products

Search

Documentation

Threading

• Common

Detailed Description

Defines multi threading macros if the FIFTYONE_DEGREES_NO_THREADING compiler directive is not explicitly requesting single threaded operation.

Collaboration diagram for Threading:

Structs
struct	fiftyoneDegreesSignal
	A signal used to limit the number of items that can be created by the pool. More...
struct	fiftyoneDegreesInterlockDoubleWidth
	Double width (64 or 128 depending on the architecture) compare and exchange. More...

Macros
#define	FIFTYONE_DEGREES_THREAD   pthread_t
	A thread created with the FIFTYONE_DEGREES_THREAD_CREATE macro.
#define	FIFTYONE_DEGREES_SIGNAL_CREATE(s)
	Creates a new signal that can be used to wait for other operations to complete before continuing.
#define	FIFTYONE_DEGREES_SIGNAL_CLOSE(s)
	Frees the handle provided to the macro.
#define	FIFTYONE_DEGREES_SIGNAL_SET(s)
	Signals a thread waiting for the signal to proceed.
#define	FIFTYONE_DEGREES_SIGNAL_WAIT(s)
	Waits for the signal to become set by another thread.
#define	FIFTYONE_DEGREES_MUTEX_CREATE(m)
	Creates a new mutex at the pointer provided.
#define	FIFTYONE_DEGREES_MUTEX_CLOSE(m)
	Frees the mutex at the pointer provided.
#define	FIFTYONE_DEGREES_MUTEX_LOCK(m)
	Locks the mutex at the pointer provided.
#define	FIFTYONE_DEGREES_MUTEX_UNLOCK(m)
	Unlocks the mutex at the pointer provided.
#define	FIFTYONE_DEGREES_MUTEX_VALID(m)
	Returns true if the mutex is valid.
#define	FIFTYONE_DEGREES_THREAD_CREATE(t, m, s)
	Creates a new thread with the following parameters:
#define	FIFTYONE_DEGREES_THREAD_JOIN(t)
	Joins the thread provided to the current thread waiting indefinitely for the operation to complete.
#define	FIFTYONE_DEGREES_THREAD_CLOSE(t)
	Closes the thread passed to the macro.
#define	FIFTYONE_DEGREES_THREAD_EXIT   pthread_exit(NULL)
	Exits the calling thread.
#define	FIFTYONE_DEGREES_INTERLOCK_INC(v)
	Increments the value and returns the final value.
#define	FIFTYONE_DEGREES_INTERLOCK_DEC(v)
	Decrements the value and returns the final value.
#define	FIFTYONE_DEGREES_INTERLOCK_EXCHANGE(d, e, c)
	Replaces the destination value with the exchange value, only if the destination value matched the comparand.
#define	FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_64(d, e, c)
	64 bit compare and swap.
#define	FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_PTR(d, e, c)
	Replaces the destination pointer with the exchange pointer, only if the destination pointer matched the comparand.
#define	FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_DW(d, e, c)
#define	FIFTYONE_DEGREES_IS_LOCK_FREE   __atomic_is_lock_free(sizeof(fiftyoneDegreesInterlockDoubleWidth), NULL)

Typedefs
typedef void *(*	FIFTYONE_DEGREES_THREAD_ROUTINE) (void *)
	A thread method passed to the FIFTYONE_DEGREES_THREAD_CREATE macro.
typedef pthread_mutex_t	fiftyoneDegreesMutex
	MUTEX AND THREADING MACROS.

Functions
bool	fiftyoneDegreesThreadingGetIsThreadSafe ()
	Determines if the methods that should be thread safe have been compiled so they are thread safe.
void	fiftyoneDegreesMutexCreate (fiftyoneDegreesMutex *mutex)
	Initialises the mutex passed to the method.
void	fiftyoneDegreesMutexClose (fiftyoneDegreesMutex *mutex)
	Closes the mutex passed to the method.
void	fiftyoneDegreesMutexLock (fiftyoneDegreesMutex *mutex)
	Locks the mutex passed to the method.
void	fiftyoneDegreesMutexUnlock (fiftyoneDegreesMutex *mutex)
	Unlocks the mutex passed to the method.
fiftyoneDegreesSignal *	fiftyoneDegreesSignalCreate ()
	Initialises the signal pointer by setting the condition first followed by the mutex if the condition was set correctly.
void	fiftyoneDegreesSignalClose (fiftyoneDegreesSignal *signal)
	Closes the signal ensuring there is a lock on the signal before destroying the signal.
void	fiftyoneDegreesSignalSet (fiftyoneDegreesSignal *signal)
	If the signal has not been destroyed then sends a signal to a waiting thread that the signal has been set and one can continue.
void	fiftyoneDegreesSignalWait (fiftyoneDegreesSignal *signal)
	Wait for a signal to be set.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_INTERLOCK_DEC

#define FIFTYONE_DEGREES_INTERLOCK_DEC

(

v

)

Value:

(__atomic_add_fetch(v, -1, __ATOMIC_SEQ_CST))

Decrements the value and returns the final value.

Parameters

v	the value to decrement

Returns

value after decrementing

◆ FIFTYONE_DEGREES_INTERLOCK_EXCHANGE

#define FIFTYONE_DEGREES_INTERLOCK_EXCHANGE	(		d,
			e,
			c )

Value:

__sync_val_compare_and_swap(&d,c,e)

Replaces the destination value with the exchange value, only if the destination value matched the comparand.

Returns the value of d before the swap.

Parameters

d	the destination to swap
e	the exchange value
c	the comparand

◆ FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_64

#define FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_64	(		d,
			e,
			c )

Value:

FIFTYONE_DEGREES_INTERLOCK_EXCHANGE(d,e,c)

64 bit compare and swap.

Replaces the destination value with the exchange value, only if the destination value matched the comparand. Returns the value of d before the swap.

Parameters

d	the destination to swap
e	the exchange value
c	the comparand

◆ FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_DW

#define FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_DW	(		d,
			e,
			c )

Value:

(__atomic_compare_exchange( \

(fiftyoneDegreesInterlockDoubleWidth*)&d, \

(fiftyoneDegreesInterlockDoubleWidth*)&c, \

(fiftyoneDegreesInterlockDoubleWidth*)&e, \

false, \

__ATOMIC_SEQ_CST, \

__ATOMIC_SEQ_CST))

◆ FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_PTR

#define FIFTYONE_DEGREES_INTERLOCK_EXCHANGE_PTR	(		d,
			e,
			c )

Value:

FIFTYONE_DEGREES_INTERLOCK_EXCHANGE(d,e,c)

Replaces the destination pointer with the exchange pointer, only if the destination pointer matched the comparand.

Returns the value of d before the swap.

Parameters

d	the destination to swap
e	the exchange value
c	the comparand

◆ FIFTYONE_DEGREES_INTERLOCK_INC

#define FIFTYONE_DEGREES_INTERLOCK_INC

(

v

)

Value:

(__atomic_add_fetch(v, 1, __ATOMIC_SEQ_CST))

Increments the value and returns the final value.

Parameters

v	the value to decrement

Returns

value after incrementing

◆ FIFTYONE_DEGREES_MUTEX_CLOSE

#define FIFTYONE_DEGREES_MUTEX_CLOSE

(

m

)

Value:

fiftyoneDegreesMutexClose(&m)

Frees the mutex at the pointer provided.

A slim reader writer lock holds no resources, so there is nothing to free on Windows.

Parameters

m	mutex to close

◆ FIFTYONE_DEGREES_MUTEX_CREATE

#define FIFTYONE_DEGREES_MUTEX_CREATE

(

m

)

Value:

fiftyoneDegreesMutexCreate(&m)

Creates a new mutex at the pointer provided.

Parameters

m	mutex to create

◆ FIFTYONE_DEGREES_MUTEX_LOCK

#define FIFTYONE_DEGREES_MUTEX_LOCK

(

m

)

Value:

fiftyoneDegreesMutexLock(m)

Locks the mutex at the pointer provided.

Parameters

m	mutex to lock

◆ FIFTYONE_DEGREES_MUTEX_UNLOCK

#define FIFTYONE_DEGREES_MUTEX_UNLOCK

(

m

)

Value:

fiftyoneDegreesMutexUnlock(m)

Unlocks the mutex at the pointer provided.

Parameters

m	mutex to unlock

◆ FIFTYONE_DEGREES_MUTEX_VALID

#define FIFTYONE_DEGREES_MUTEX_VALID

(

m

)

Value:

fiftyoneDegreesMutexValid(m)

Returns true if the mutex is valid.

Parameters

m	mutex to check

Returns

true if valid

◆ FIFTYONE_DEGREES_SIGNAL_CLOSE

#define FIFTYONE_DEGREES_SIGNAL_CLOSE

(

s

)

Value:

fiftyoneDegreesSignalClose(s)

Frees the handle provided to the macro.

Parameters

s	signal to close

◆ FIFTYONE_DEGREES_SIGNAL_CREATE

#define FIFTYONE_DEGREES_SIGNAL_CREATE

(

s

)

Value:

s = fiftyoneDegreesSignalCreate()

Creates a new signal that can be used to wait for other operations to complete before continuing.

Parameters

s	signal to create

◆ FIFTYONE_DEGREES_SIGNAL_SET

#define FIFTYONE_DEGREES_SIGNAL_SET

(

s

)

Value:

fiftyoneDegreesSignalSet(s)

Signals a thread waiting for the signal to proceed.

Parameters

s	signal to set

◆ FIFTYONE_DEGREES_SIGNAL_WAIT

#define FIFTYONE_DEGREES_SIGNAL_WAIT

(

s

)

Value:

fiftyoneDegreesSignalWait(s)

Waits for the signal to become set by another thread.

Parameters

s	signal to wait on

◆ FIFTYONE_DEGREES_THREAD_CLOSE

#define FIFTYONE_DEGREES_THREAD_CLOSE

(

t

)

Closes the thread passed to the macro.

Parameters

t	thread to close

◆ FIFTYONE_DEGREES_THREAD_CREATE

#define FIFTYONE_DEGREES_THREAD_CREATE	(		t,
			m,
			s )

Value:

pthread_create(&t, NULL, m, s)

Creates a new thread with the following parameters:

Parameters

t	pointer to FIFTYONE_DEGREES_THREAD memory
m	the method to call when the thread runs
s	pointer to the state data to pass to the method

Returns

new thread

◆ FIFTYONE_DEGREES_THREAD_JOIN

#define FIFTYONE_DEGREES_THREAD_JOIN

(

t

)

Value:

pthread_join(t, NULL)

Joins the thread provided to the current thread waiting indefinitely for the operation to complete.

Parameters

t	pointer to a previously created thread

Typedef Documentation

◆ fiftyoneDegreesMutex

typedef pthread_mutex_t fiftyoneDegreesMutex

MUTEX AND THREADING MACROS.

Mutex used to synchronise access to data structures that could be used in parallel in a multi threaded environment. On Windows this is a slim reader writer lock taken only for exclusive access, which stays in user mode unless another thread holds it. The cache takes a lock for every item it hands out, so a lock that entered the kernel each time stops threads scaling.

Function Documentation

◆ fiftyoneDegreesMutexClose()

void fiftyoneDegreesMutexClose

(

fiftyoneDegreesMutex *

mutex

)

Closes the mutex passed to the method.

Parameters

mutex

to be closed.

◆ fiftyoneDegreesMutexCreate()

void fiftyoneDegreesMutexCreate

(

fiftyoneDegreesMutex *

mutex

)

Initialises the mutex passed to the method.

Parameters

mutex

to be initialised.

◆ fiftyoneDegreesMutexLock()

void fiftyoneDegreesMutexLock

(

fiftyoneDegreesMutex *

mutex

)

Locks the mutex passed to the method.

Parameters

mutex

to be locked.

◆ fiftyoneDegreesMutexUnlock()

void fiftyoneDegreesMutexUnlock

(

fiftyoneDegreesMutex *

mutex

)

Unlocks the mutex passed to the method.

Parameters

mutex

to be unlocked.

◆ fiftyoneDegreesSignalClose()

void fiftyoneDegreesSignalClose

(

fiftyoneDegreesSignal *

signal

)

Closes the signal ensuring there is a lock on the signal before destroying the signal.

This means that no other process can be waiting on the signal before it is destroyed. The destroyed field of the signal structure is set to true after the condition is destroyed. All methods that could subsequently try and get a lock on the signal MUST check the destroyed field before trying to get the lock.

Parameters

signal

to be closed.

◆ fiftyoneDegreesSignalCreate()

fiftyoneDegreesSignal * fiftyoneDegreesSignalCreate

(

)

Initialises the signal pointer by setting the condition first followed by the mutex if the condition was set correctly.

Destroyed is set to false to indicate to the other methods that the signal is still valid. The memory used by the signal should be part of another structure and will be released when that structure is released. If there is a problem creating the mutex the condition is also released.

Returns

new signal

◆ fiftyoneDegreesSignalSet()

void fiftyoneDegreesSignalSet

(

fiftyoneDegreesSignal *

signal

)

If the signal has not been destroyed then sends a signal to a waiting thread that the signal has been set and one can continue.

This possible because the condition will auto reset only enabling a signal thread to continue even if multi threads are waiting.

Parameters

signal

to be set.

◆ fiftyoneDegreesSignalWait()

void fiftyoneDegreesSignalWait

(

fiftyoneDegreesSignal *

signal

)

Wait for a signal to be set.

Only waits for the signal if the signal has not been destroyed. Locks the mutex before the signal is waited for. This ensures only one thread can be waiting on the signal at any one time.

Parameters

signal

pointer to the signal used to wait on.

◆ fiftyoneDegreesThreadingGetIsThreadSafe()

bool fiftyoneDegreesThreadingGetIsThreadSafe

(

)

Determines if the methods that should be thread safe have been compiled so they are thread safe.

In single threaded operation compiling without threading using the FIFTYONE_DEGREES_NO_THREADING directive results in performance improvements.

Returns

true if the library is thread safe, otherwise false.

Examples

Hash/ReloadFromFile.cpp, and Hash/ReloadFromMemory.cpp.

Have a data or code question? Get in touch and explore subscription options.