Top: Multithreading: Utilities

#include <pasync.h>

int pexchange(int* target, int value);
void* pexchange(void** target, void* value);
int pincrement(int* target);
int pdecrement(int* target);

template <class T> inline T* tpexchange(T** target, T* value);

void psleep(unsigned milliseconds);
pthread_id_t pthrself();
bool pthrequal(pthread_id_t id);

The atomic functions pexchange(), pincrement() and pdecrement() can be used in place of mutex locking in some simple situations. A typical usage of pexchange() in a multithreaded environment could be, for example, freeing a dynamic object and assigning NULL to the pointer atomically to prevent concurrent threads from freeing the same object more than once.

It is sometimes necessary to increment or decrement some shared counter and atomically compare it with some value. For example, you have a shared resource and you keep track of its usage by maintaining a reference counter. When this counter reaches 0 you want to free the shared resource. To avoid conflicts between concurrent threads you need to decrement the counter and atomically compare it with 0. In this situation you can use pdecrement() instead of time-consuming mutex locking. (For additional notes, see Portability and performance issues.)

int pexchange(int* target, int value) -- atomically exchanges two int values.

void* pexchange(void** target, void* value) -- atomically exchanges two pointers.

int pincrement(int* target) -- atomically increments the value of *target and returns the new value.

int pdecrement(int* target) -- atomically decrements the value of *target and returns the new value.

template <class T> T* tpexchange(T** target, T* value) -- is equivalent to pexchange() that adds compile-time type checking. Use this template to check the correspondence of pointer types of target and the returning value.

void psleep(unsigned milliseconds) -- suspends execution for the specified amount of time in milliseconds.

pthread_id_t pthrself() -- returns the thread ID of the calling thread.

bool pthrequal(pthread_id_t id) -- checks whether the calling thread has the given thread id.

See also: semaphore, mutex, thread