ThreadSafeRef

Engine/source/platform/threads/threadSafeRefCount.h

Reference to a concurrently reference-counted object.

Public Types

enum

ETag {
  TAG_PreserveOld 
  TAG_PreserveNew 
  TAG_Set 
  TAG_Unset 
  TAG_SetOrFail 
  TAG_UnsetOrFail 
  TAG_FailIfSet 
  TAG_FailIfUnset 
}

ThreadSafeRef< T >

ThisType

Protected Attributes

T *volatile

mPtr

Public Functions

ThreadSafeRef()

ThreadSafeRef(const ThisType & ref)

ThreadSafeRef(T * ptr)

~ThreadSafeRef()

bool

isTagged()

operator T*()

bool

operator!()

bool

operator!=(const ThisType & ref)

bool

operator!=(T * ptr)

T &

operator*()

T *

operator->()

ThisType &

operator=(const ThisType & ref)

ThisType &

operator=(T * ptr)

bool

operator==(const ThisType & ref)

bool

operator==(T * ptr)

T *

ptr()

void

setTag()

bool

trySetFromTo(const ThisType & oldVal, const ThisType & newVal, ETag tag)

bool

trySetFromTo(T * oldVal, const ThisType & newVal, ETag tag)

bool

trySetFromTo(T * oldVal, T *const volatile & newVal, ETag tag)

Update the reference from pointing to oldVal to point to newVal.

Public Static Functions

T *

safeRead(T *const volatile & refPtr)

void

unsafeWrite(ThisType & ref, T * ptr)

Update ref to point to ptr but do not release an existing reference held by ref nor do the operation in a thread-safe way.

Protected Static Functions

T *

getTaggedPtr(T * ptr)

T *

getUntaggedPtr(T * ptr)

bool

isTaggedPtr(T * ptr)

Detailed Description

Reference to a concurrently reference-counted object.

This class takes care of the reference-counting as well as protecting the reference itself from concurrent operations.

Tagging allows the pointer contained in the reference to be flagged. Tag state is preserved through updates to the reference.

note:
If you directly assign a freshly created object with a reference count of zero to a ThreadSafeRef, make absolutely sure the ThreadSafeRef is accessed only by a single thread. Otherwise there's a risk of the object being released and freed in midst of trying to set the reference.

Public Types

ETag

Enumerator

TAG_PreserveOld: Preserve existing tagging state when changing pointer.
TAG_PreserveNew: Preserve tagging state of new pointer when changing pointer.
TAG_Set: Set tag when changing pointer; okay if already set.
TAG_Unset: Unset tag when changing pointer; okay if already unset.
TAG_SetOrFail: Set tag when changing pointer; fail if already set.
TAG_UnsetOrFail: Unset tag when changing pointer; fail if already unset.
TAG_FailIfSet: Fail changing pointer when currently tagged.
TAG_FailIfUnset: Fail changing pointer when currently untagged.

typedef ThreadSafeRef< T > ThisType

Protected Attributes

T *volatile mPtr

Public Functions

ThreadSafeRef()

ThreadSafeRef(const ThisType & ref)

ThreadSafeRef(T * ptr)

~ThreadSafeRef()

isTagged()

operator T*()

operator!()

operator!=(const ThisType & ref)

operator!=(T * ptr)

operator*()

operator->()

operator=(const ThisType & ref)

operator=(T * ptr)

operator==(const ThisType & ref)

operator==(T * ptr)

ptr()

setTag()

trySetFromTo(const ThisType & oldVal, const ThisType & newVal, ETag tag)

trySetFromTo(T * oldVal, const ThisType & newVal, ETag tag)

trySetFromTo(T * oldVal, T *const volatile & newVal, ETag tag)

Update the reference from pointing to oldVal to point to newVal.

Do so in a thread-safe way.

This operation will only succeed, if, when doing the pointer-swapping, the reference still points to oldVal. If, however, the reference has been changed in the meantime by another thread, the operation will fail.

Parameters:

oldVal	The pointer assumed to currently be contained in this ThreadSafeRef.
newVal	The pointer to store in this ThreadSafeRef.
tag	Operation to perform on the reference's tag field.

return:

true, if the reference now points to newVal.

Public Static Functions

safeRead(T *const volatile & refPtr)

unsafeWrite(ThisType & ref, T * ptr)

Update ref to point to ptr but do not release an existing reference held by ref nor do the operation in a thread-safe way.

This method is only for when you absolutely know that your thread is the only thread operating on a reference and you are keeping track of reference counts yourself.

Parameters:

ref	The reference to update.
ptr	The new pointer to store in ref.

Protected Static Functions

getTaggedPtr(T * ptr)

getUntaggedPtr(T * ptr)

isTaggedPtr(T * ptr)