qbatomic.h.3		qbatomic.h.3
	qbatomic.h(3) libqb qbatomic .h(3)		qbatomic.h(3) libqb qbatomic .h(3)
	NAME		NAME
	qbatomic.h -		qbatomic.h -
	Basic atomic integer and pointer operations.		Basic atomic integer and pointer operations'.
	SYNOPSIS		SYNOPSIS
	#include <stdint.h>		#include <stdint.h>
	#include <qb/qbdefs.h>		#include <qb/qbdefs.h>
			#include <qb/qbconfig.h>
	Defines		Defines
	#define qb_atomic_int_get(atomic) ((int32_t)*(atomic))		#define qb_atomic_int_get(atomic)
	#define qb_atomic_int_set(atomic, newval) ((void) (*(atomic) = (ne		#define qb_atomic_int_set(atomic, newval)
	wval)))		#define qb_atomic_pointer_get(atomic)
	#define qb_atomic_pointer_get(atomic) ((void*)*(atomic))		#define qb_atomic_pointer_set(atomic, newval)
	#define qb_atomic_pointer_set(atomic, newval) ((void) (*(atomic) =
	(newval)))
	#define qb_atomic_int_inc(atomic) (qb_atomic_int_add ((atomic), 1) )		#define qb_atomic_int_inc(atomic) (qb_atomic_int_add ((atomic), 1) )
	Atomically increments the integer pointed to by atomic by 1.		Atomically increments the integer pointed to by atomic by 1'.
	#define qb_atomic_int_dec_and_test(atomic) (qb_atomic_int_exchange _and_add ((atomic), -1) == 1)		#define qb_atomic_int_dec_and_test(atomic) (qb_atomic_int_exchange _and_add ((atomic), -1) == 1)
	Atomically decrements the integer pointed to by atomic by 1.		Atomically decrements the integer pointed to by atomic by 1'.
	Functions		Functions
	void qb_atomic_init (void)		void qb_atomic_init (void)
	int32_t qb_atomic_int_exchange_and_add (volatile int32_t QB_GNUC_MAY _ALIAS *atomic, int32_t val)		int32_t qb_atomic_int_exchange_and_add (volatile int32_t QB_GNUC_MAY _ALIAS *atomic, int32_t val)
	Atomically adds val to the integer pointed to by atomic.		Atomically adds val to the integer pointed to by atomic'.
	void qb_atomic_int_add (volatile int32_t QB_GNUC_MAY_ALIAS *atomic, int32_t val)		void qb_atomic_int_add (volatile int32_t QB_GNUC_MAY_ALIAS *atomic, int32_t val)
	Atomically adds val to the integer pointed to by atomic.		Atomically adds val to the integer pointed to by atomic'.
	int32_t qb_atomic_int_compare_and_exchange (volatile int32_t QB_GNUC _MAY_ALIAS *atomic, int32_t oldval, int32_t newval)		int32_t qb_atomic_int_compare_and_exchange (volatile int32_t QB_GNUC _MAY_ALIAS *atomic, int32_t oldval, int32_t newval)
	Compares oldval with the integer pointed to by atomic and if the y are equal, atomically exchanges *atomic with newval.		Compares oldval with the integer pointed to by atomic and if the y are equal, atomically exchanges *atomic with newval'.
	int32_t qb_atomic_pointer_compare_and_exchange (volatile void *QB_GN UC_MAY_ALIAS *atomic, void *oldval, void *newval)		int32_t qb_atomic_pointer_compare_and_exchange (volatile void *QB_GN UC_MAY_ALIAS *atomic, void *oldval, void *newval)
	Compares oldval with the pointer pointed to by atomic and if the y are equal, atomically exchanges *atomic with newval.		Compares oldval with the pointer pointed to by atomic and if the y are equal, atomically exchanges *atomic with newval'.
	int32_t qb_atomic_int_get (volatile int32_t QB_GNUC_MAY_ALIAS *atomi c)		int32_t qb_atomic_int_get (volatile int32_t QB_GNUC_MAY_ALIAS *atomi c)
	Reads the value of the integer pointed to by atomic.		Reads the value of the integer pointed to by atomic'.
	void qb_atomic_int_set (volatile int32_t QB_GNUC_MAY_ALIAS *atomic, int32_t newval)		void qb_atomic_int_set (volatile int32_t QB_GNUC_MAY_ALIAS *atomic, int32_t newval)
	Sets the value of the integer pointed to by atomic.		Sets the value of the integer pointed to by atomic'.
	void * qb_atomic_pointer_get (volatile void *QB_GNUC_MAY_ALIAS *atom ic)		void * qb_atomic_pointer_get (volatile void *QB_GNUC_MAY_ALIAS *atom ic)
	Reads the value of the pointer pointed to by atomic.		Reads the value of the pointer pointed to by atomic'.
	void qb_atomic_pointer_set (volatile void *QB_GNUC_MAY_ALIAS *atomic , void *newval)		void qb_atomic_pointer_set (volatile void *QB_GNUC_MAY_ALIAS *atomic , void *newval)
	Sets the value of the pointer pointed to by atomic.		Sets the value of the pointer pointed to by atomic'.
	Detailed Description		Detailed Description
	Basic atomic integer and pointer operations.		Basic atomic integer and pointer operations'.
	The following functions can be used to atomically access integers an		The following functions can be used to atomically access integers an
	d pointers. They are implemented as inline assembler function on most platf		d pointers'. They are implemented as inline assembler function on most plat
	orms and use slower fall-backs otherwise. Using them can sometimes save you		forms and use slower fall-backs otherwise'. Using them can sometimes save y
	from		ou
	using a performance-expensive pthread_mutex to protect the integer o		from using a performance-expensive pthread_mutex to protect the inte
	r pointer.		ger or pointer'.
	The most important usage is reference counting. Using qb_atomic_int_ inc() and qb_atomic_int_dec_and_test() makes reference counting a very fast operation.		The most important usage is reference counting'. Using qb_atomic_int _inc() and qb_atomic_int_dec_and_test() makes reference counting a very fas t operation'.
	You must not directly read integers or pointers concurrently accesse		You must not directly read integers or pointers concurrently accesse
	d by multiple threads, but use the atomic accessor functions instead. That		d by multiple threads, but use the atomic accessor functions instead'. That
	is, always use qb_atomic_int_get() and qb_atomic_pointer_get() for read out		is, always use qb_atomic_int_get() and qb_atomic_pointer_get() for read ou
	s.		ts'.
	They provide the neccessary synchonization mechanisms like memory ba		They provide the neccessary synchonization mechanisms like memory ba
	rriers to access memory locations concurrently.		rriers to access memory locations concurrently'.
	If you are using those functions for anything apart from simple refe		If you are using those functions for anything apart from simple refe
	rence counting, you should really be aware of the implications of doing tha		rence counting, you should really be aware of the implications of doing tha
	t. There are literally thousands of ways to shoot yourself in the foot. So		t'. There are literally thousands of ways to shoot yourself in the foot'. S
	if in		o if
	doubt, use a pthread_mutex. If you don't know, what memory barriers		in doubt, use a pthread_mutex'. If you don't know, what memory barri
	are, do not use anything but qb_atomic_int_inc() and qb_atomic_int_dec_and_		ers are, do not use anything but qb_atomic_int_inc() and qb_atomic_int_dec_
	test().		and_test()'.
	It is not safe to set an integer or pointer just by assigning to it,		It is not safe to set an integer or pointer just by assigning to it,
	when it is concurrently accessed by other threads with the following funct		when it is concurrently accessed by other threads with the following funct
	ions. Use qb_atomic_int_compare_and_exchange() or		ions'. Use qb_atomic_int_compare_and_exchange() or
	qb_atomic_pointer_compare_and_exchange() respectively.		qb_atomic_pointer_compare_and_exchange() respectively'.
	Define Documentation		Define Documentation
	#define qb_atomic_int_dec_and_test(atomic) (qb_atomic_int_exchange_and _add ((atomic), -1) == 1)		#define qb_atomic_int_dec_and_test(atomic) (qb_atomic_int_exchange_and _add ((atomic), -1) == 1)
	Atomically decrements the integer pointed to by atomic by 1. Paramet ers:		Atomically decrements the integer pointed to by atomic by 1'. Parame ters:
	atomic a pointer to an integer		atomic a pointer to an integer
	Returns:		Returns:
	QB_TRUE if the integer pointed to by atomic is 0 after decrement ing it		QB_TRUE if the integer pointed to by atomic is 0 after decrement ing it
	#define qb_atomic_int_get(atomic) ((int32_t)*(atomic))		#define qb_atomic_int_get(atomic) Value:
			((void) sizeof (char* [sizeof (*(atomic)) == sizeof (int32_t) ? 1 :
			-1]), (qb_atomic_int_get) ((volatile int32_t QB_GNUC_MAY_ALIAS *) (volati
			le void *) (atomic)))
	#define qb_atomic_int_inc(atomic) (qb_atomic_int_add ((atomic), 1))		#define qb_atomic_int_inc(atomic) (qb_atomic_int_add ((atomic), 1))
	Atomically increments the integer pointed to by atomic by 1. Paramet		Atomically increments the integer pointed to by atomic by 1'. Parame
	ers:		ters:
	atomic a pointer to an integer.		atomic a pointer to an integer'.
			#define qb_atomic_int_set(atomic, newval) Value:
			((void) sizeof (char* [sizeof (*(atomic)) == sizeof (int32_t) ? 1 :
			-1]), (qb_atomic_int_set) ((volatile int32_t QB_GNUC_MAY_ALIAS *) (volati
			le void *) (atomic), (newval)))
			#define qb_atomic_pointer_get(atomic) Value:
			((void) sizeof (char* [sizeof (*(atomic)) == sizeof (void*) ? 1 : -1
			]), (qb_atomic_pointer_get) ((volatile void* QB_GNUC_MAY_ALIAS *) (volati
			le void *) (atomic)))
			#define qb_atomic_pointer_set(atomic, newval) Value:
			((void) sizeof (char* [sizeof (*(atomic)) == sizeof (void*) ? 1 : -1
			]), (qb_atomic_pointer_set) ((volatile void* QB_GNUC_MAY_ALIAS *) (volati
			le void *) (atomic), (newval)))
	#define qb_atomic_int_set(atomic, newval) ((void) (*(atomic) = (newval
	)))
	#define qb_atomic_pointer_get(atomic) ((void*)*(atomic))
	#define qb_atomic_pointer_set(atomic, newval) ((void) (*(atomic) = (ne
	wval)))
	Function Documentation		Function Documentation
	void qb_atomic_init (void)		void qb_atomic_init (void)
	void qb_atomic_int_add (volatile int32_t QB_GNUC_MAY_ALIAS * atomic, int		void qb_atomic_int_add (volatile int32_t QB_GNUC_MAY_ALIAS *atomic, int3
	32_t val)		2_tval)
	Atomically adds val to the integer pointed to by atomic. Also acts a		Atomically adds val to the integer pointed to by atomic'. Also acts
	s a memory barrier.		as a memory barrier'.
	Parameters:		Parameters:
	atomic a pointer to an integer		atomic a pointer to an integer
	val the value to add to *atomic		val the value to add to *atomic
	int32_t qb_atomic_int_compare_and_exchange (volatile int32_t QB_GNUC_MAY		int32_t qb_atomic_int_compare_and_exchange (volatile int32_t QB_GNUC_MAY
	_ALIAS * atomic, int32_t oldval, int32_t newval)		_ALIAS *atomic, int32_toldval, int32_tnewval)
	Compares oldval with the integer pointed to by atomic and if they ar		Compares oldval with the integer pointed to by atomic and if they ar
	e equal, atomically exchanges *atomic with newval. Also acts as a memory ba		e equal, atomically exchanges *atomic with newval'. Also acts as a memory b
	rrier.		arrier'.
	Parameters:		Parameters:
	atomic a pointer to an integer		atomic a pointer to an integer
	oldval the assumed old value of *atomic		oldval the assumed old value of *atomic
	newval the new value of *atomic		newval the new value of *atomic
	Returns:		Returns:
	QB_TRUE, if *atomic was equal oldval. QB_FALSE otherwise.		QB_TRUE, if *atomic was equal oldval'. QB_FALSE otherwise'.
	int32_t qb_atomic_int_exchange_and_add (volatile int32_t QB_GNUC_MAY_ALI		int32_t qb_atomic_int_exchange_and_add (volatile int32_t QB_GNUC_MAY_ALI
	AS * atomic, int32_t val)		AS *atomic, int32_tval)
	Atomically adds val to the integer pointed to by atomic. It returns		Atomically adds val to the integer pointed to by atomic'. It returns
	the value of *atomic just before the addition took place. Also acts as a me		the value of *atomic just before the addition took place'. Also acts as a
	mory barrier.		memory barrier'.
	Parameters:		Parameters:
	atomic a pointer to an integer		atomic a pointer to an integer
	val the value to add to *atomic		val the value to add to *atomic
	Returns:		Returns:
	the value of *atomic before the addition.		the value of *atomic before the addition'.
	int32_t qb_atomic_int_get (volatile int32_t QB_GNUC_MAY_ALIAS * atomic)		int32_t qb_atomic_int_get (volatile int32_t QB_GNUC_MAY_ALIAS *atomic)
	Reads the value of the integer pointed to by atomic. Also acts as a		Reads the value of the integer pointed to by atomic'. Also acts as a
	memory barrier.		memory barrier'.
	Parameters:		Parameters:
	atomic a pointer to an integer		atomic a pointer to an integer
	Returns:		Returns:
	the value of atomic		the value of atomic
	void qb_atomic_int_set (volatile int32_t QB_GNUC_MAY_ALIAS * atomic, int		void qb_atomic_int_set (volatile int32_t QB_GNUC_MAY_ALIAS *atomic, int3
	32_t newval)		2_tnewval)
	Sets the value of the integer pointed to by atomic. Also acts as a m		Sets the value of the integer pointed to by atomic'. Also acts as a
	emory barrier.		memory barrier'.
	Parameters:		Parameters:
	atomic a pointer to an integer		atomic a pointer to an integer
	newval the new value		newval the new value
	int32_t qb_atomic_pointer_compare_and_exchange (volatile void *QB_GNUC_M		int32_t qb_atomic_pointer_compare_and_exchange (volatile void *QB_GNUC_M
	AY_ALIAS * atomic, void * oldval, void * newval)		AY_ALIAS *atomic, void *oldval, void *newval)
	Compares oldval with the pointer pointed to by atomic and if they ar		Compares oldval with the pointer pointed to by atomic and if they ar
	e equal, atomically exchanges *atomic with newval. Also acts as a memory ba		e equal, atomically exchanges *atomic with newval'. Also acts as a memory b
	rrier.		arrier'.
	Parameters:		Parameters:
	atomic a pointer to a void*		atomic a pointer to a void*
	oldval the assumed old value of *atomic		oldval the assumed old value of *atomic
	newval the new value of *atomic		newval the new value of *atomic
	Returns:		Returns:
	QB_TRUE if atomic was equal oldval, else QB_FALSE.		QB_TRUE if atomic was equal oldval, else QB_FALSE'.
	void* qb_atomic_pointer_get (volatile void *QB_GNUC_MAY_ALIAS * atomic)		void* qb_atomic_pointer_get (volatile void *QB_GNUC_MAY_ALIAS *atomic)
	Reads the value of the pointer pointed to by atomic. Also acts as a		Reads the value of the pointer pointed to by atomic'. Also acts as a
	memory barrier.		memory barrier'.
	Parameters:		Parameters:
	atomic a pointer to a void*.		atomic a pointer to a void*'.
	Returns:		Returns:
	the value to add to atomic.		the value to add to atomic'.
	void qb_atomic_pointer_set (volatile void *QB_GNUC_MAY_ALIAS * atomic, v		void qb_atomic_pointer_set (volatile void *QB_GNUC_MAY_ALIAS *atomic, vo
	oid * newval)		id *newval)
	Sets the value of the pointer pointed to by atomic. Also acts as a m		Sets the value of the pointer pointed to by atomic'. Also acts as a
	emory barrier.		memory barrier'.
	Parameters:		Parameters:
	atomic a pointer to a void*		atomic a pointer to a void*
	newval the new value		newval the new value
	Author		Author
	Generated automatically by Doxygen for libqb from the source code.		Generated automatically by Doxygen for libqb from the source code'.
	Version 0.4.1 Mon Jan 31 2011 qbatomic .h(3)		Version 0.8.1 Thu Jan 5 2012 qbatomic .h(3)
End of changes. 38 change blocks.
	91 lines changed or deleted		104 lines changed or added
This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/