Plank AtomicPX class

Extended atomic pointer. More...

Typedefs
typedef struct PlankAtomicPX *	PlankAtomicPXRef
	An opaque reference to the Plank AtomicPX object (atomic pointer with an extended tag of data).
Functions
static PlankAtomicPXRef	pl_AtomicPX_CreateAndInit ()
	Creates and initialises a Plank AtomicPX object and return an oqaque reference to it.
static PlankAtomicPXRef	pl_AtomicPX_Create ()
	Create a Plank AtomicPX object and return an oqaque reference to it.
static PlankResult	pl_AtomicPX_Init (PlankAtomicPXRef p)
	Initialise a Plank AtomicPX object.
static PlankResult	pl_AtomicPX_DeInit (PlankAtomicPXRef p)
	Deinitialise a Plank AtomicPX object.
static PlankResult	pl_AtomicPX_Destroy (PlankAtomicPXRef p)
	Destroy a Plank AtomicPX object.
static PlankP	pl_AtomicPX_Get (PlankAtomicPXRef p)
	Get the current pointer.
static PlankP	pl_AtomicPX_GetUnchecked (PlankAtomicPXRef p)
	Get the current value nonatomically.
static PlankUL	pl_AtomicPX_GetExtra (PlankAtomicPXRef p)
	Get the current value of the extra "tag".
static PlankUL	pl_AtomicPX_GetExtraUnchecked (PlankAtomicPXRef p)
	Get the current value of the extra "tag" nonatomically.
static PlankP	pl_AtomicPX_SwapAll (PlankAtomicPXRef p, PlankP newPtr, PlankUL newExtra, PlankUL *oldExtra)
	Swap the current pointer with a new pointer and change the tag.
static PlankP	pl_AtomicPX_Swap (PlankAtomicPXRef p, PlankP newPtr)
	Swap the current pointer with a new pointer.
static void	pl_AtomicPX_SwapOther (PlankAtomicPXRef p1, PlankAtomicPXRef p2)
	Swap over two values.
static void	pl_AtomicPX_SetAll (PlankAtomicPXRef p, PlankP newPtr, PlankUL newExtra)
	Set the current pointer to a new pointer and change the tag.
static void	pl_AtomicPX_Set (PlankAtomicPXRef p, PlankP newPtr)
	Set the current pointer to a new pointer.
static PlankP	pl_AtomicPX_Add (PlankAtomicPXRef p, PlankL operand)
	Offset current pointer.
static PlankP	pl_AtomicPX_Subtract (PlankAtomicPXRef p, PlankL operand)
	Offset current pointer in a negative direct.
static PlankP	pl_AtomicPX_Increment (PlankAtomicPXRef p)
	Increment the current pointer by 1 byte.
static PlankP	pl_AtomicPX_Decrement (PlankAtomicPXRef p)
	Decrement the current pointer by 1 byte.
static PlankB	pl_AtomicPX_CompareAndSwap (PlankAtomicPXRef p, PlankP oldPtr, PlankUL oldExtra, PlankP newPtr, PlankUL newExtra)
	Swap the current values with new values if specified old values are still current.

---

Detailed Description

Extended atomic pointer.

This combines a pointer and an extra "tag" which can be written in a single atomic operation. This can help avoid the "ABA problem" in certain lock-free data structures.

The default is to use the extra tag as a counter such that the counter is incremented each time the stored pointer us set.

---

Typedef Documentation

typedef struct PlankAtomicPX* PlankAtomicPXRef

An opaque reference to the Plank AtomicPX object (atomic pointer with an extended tag of data).

---

Function Documentation

static PlankP pl_AtomicPX_Add	(	PlankAtomicPXRef	p,
		PlankL	operand
	)		[static]

Offset current pointer.

This also increments the extra tag by 1.

Parameters:

p	The Plank AtomicPX object.
operand	The number of bytes by which to offset.

Returns:

The new pointer.

static PlankB pl_AtomicPX_CompareAndSwap	(	PlankAtomicPXRef	p,
		PlankP	oldPtr,
		PlankUL	oldExtra,
		PlankP	newPtr,
		PlankUL	newExtra
	)		[static]

Swap the current values with new values if specified old values are still current.

This is the most important atomic operation for each atomic class, many other operations are based on this. If the operation fails the user would generally try again by getting the old pointer again and retrying to write the new pointer (e.g., in a loop) until successful. If there are no other threads contending to write the pointer the operation should succeed without blocking.

This swaps both the pointer AND the extra tag but importantly both "old" values must match the currenty stored values for the swap to take place. This is the most important function for helping avoid the ABA problem.

Parameters:

p	The Plank AtomicPX object.
oldPtr	The expected old pointer being currently stored.
oldExtra	The expected old extra tag being currently stored.
newPtr	The new pointer to attempt to store.
newExtra	The new extra tag to attempt to store.

Returns:

true if the swap was successful, otherwise false.

static PlankAtomicPXRef pl_AtomicPX_Create

(

)

[static]

Create a Plank AtomicPX object and return an oqaque reference to it.

In this case both the pointer and the extra tag are set to 0.

Returns:

A Plank AtomicPX object as an opaque reference or PLANK_NULL.

static PlankAtomicPXRef pl_AtomicPX_CreateAndInit

(

)

[static]

Creates and initialises a Plank AtomicPX object and return an oqaque reference to it.

Returns:

A Plank AtomicPX object as an opaque reference or PLANK_NULL.

static PlankP pl_AtomicPX_Decrement

(

PlankAtomicPXRef

p

)

[static]

Decrement the current pointer by 1 byte.

This also increments the extra tag by 1.

Parameters:

p	The Plank AtomicPX object.

Returns:

The new pointer.

static PlankResult pl_AtomicPX_DeInit

(

PlankAtomicPXRef

p

)

[static]

Deinitialise a Plank AtomicPX object.

Parameters:

p	The Plank AtomicPX object.

Returns:

PlankResult_OK if successful, otherwise an error code.

static PlankResult pl_AtomicPX_Destroy

(

PlankAtomicPXRef

p

)

[static]

Destroy a Plank AtomicPX object.

Parameters:

p	The Plank AtomicPX object.

Returns:

PlankResult_OK if successful, otherwise an error code.

static PlankP pl_AtomicPX_Get

(

PlankAtomicPXRef

p

)

[static]

Get the current pointer.

The extra tag can be obtained using pl_AtomicPX_GetExtra() although for many algorithms the user doesn't need to know the value of the tag as it is simply used to make each write commit unique.

Parameters:

p	The Plank AtomicPX object.

Returns:

The value.

static PlankUL pl_AtomicPX_GetExtra

(

PlankAtomicPXRef

p

)

[static]

Get the current value of the extra "tag".

Many algorithms the user doesn't need to know the value of the tag as it is simply used to make each write commit unique.

Parameters:

p	The Plank AtomicPX object.

Returns:

The extra tag.

static PlankUL pl_AtomicPX_GetExtraUnchecked

(

PlankAtomicPXRef

p

)

[static]

Get the current value of the extra "tag" nonatomically.

Many algorithms the user doesn't need to know the value of the tag as it is simply used to make each write commit unique.

Parameters:

p	The Plank AtomicPX object.

Returns:

The extra tag.

static PlankP pl_AtomicPX_GetUnchecked

(

PlankAtomicPXRef

p

)

[static]

Get the current value nonatomically.

Parameters:

p	The Plank AtomicPX object.

Returns:

The value.

static PlankP pl_AtomicPX_Increment

(

PlankAtomicPXRef

p

)

[static]

Increment the current pointer by 1 byte.

This also increments the extra tag by 1.

Parameters:

p	The Plank AtomicPX object.

Returns:

The new pointer.

static PlankResult pl_AtomicPX_Init

(

PlankAtomicPXRef

p

)

[static]

Initialise a Plank AtomicPX object.

Parameters:

p	The Plank AtomicPX object.

Returns:

PlankResult_OK if successful, otherwise an error code.

static void pl_AtomicPX_Set	(	PlankAtomicPXRef	p,
		PlankP	newPtr
	)		[static]

Set the current pointer to a new pointer.

This also increments the extra tag by 1.

Parameters:

p	The Plank AtomicPX object.
newPtr	The new pointer to store.

static void pl_AtomicPX_SetAll	(	PlankAtomicPXRef	p,
		PlankP	newPtr,
		PlankUL	newExtra
	)		[static]

Set the current pointer to a new pointer and change the tag.

Parameters:

p	The Plank AtomicPX object.
newPtr	The new value to store.
newExtra	The new extra tag to store.

static PlankP pl_AtomicPX_Subtract	(	PlankAtomicPXRef	p,
		PlankL	operand
	)		[static]

Offset current pointer in a negative direct.

This also increments the extra tag by 1.

Parameters:

p	The Plank AtomicPX object.
operand	The number of bytes to subtract from the pointer.

Returns:

The new pointer.

static PlankP pl_AtomicPX_Swap	(	PlankAtomicPXRef	p,
		PlankP	newPtr
	)		[static]

Swap the current pointer with a new pointer.

This also increments the extra tag by 1.

Parameters:

p	The Plank AtomicPX object.
newPtr	The new pointer to store.

Returns:

The previously stored value.

static PlankP pl_AtomicPX_SwapAll	(	PlankAtomicPXRef	p,
		PlankP	newPtr,
		PlankUL	newExtra,
		PlankUL *	oldExtra
	)		[static]

Swap the current pointer with a new pointer and change the tag.

Parameters:

p	The Plank AtomicPX object.
newPtr	The new value to store.
newExtra	The new extra tag to store.
oldExtra	The old tage will be place here (you can pass PLANK_NULL if you don't need this).

Returns:

The previously stored value.

static void pl_AtomicPX_SwapOther	(	PlankAtomicPXRef	p1,
		PlankAtomicPXRef	p2
	)		[static]

Swap over two values.

The contents of p1 is copied to p2 and p2 is copied to p1 in an atomic operation.

Parameters:

p1	One Plank AtomicPX object.
p2	The other Plank AtomicPX object.