ThreadSafeRef

Engine/source/platform/threads/threadSafeRefCount.h

Reference to a concurrently reference-counted object.

More...

Public Types

enum
ETag {
  TAG_PreserveOld 
  TAG_PreserveNew 
  TAG_Set 
  TAG_Unset 
  TAG_SetOrFail 
  TAG_UnsetOrFail 
  TAG_FailIfSet 
  TAG_FailIfUnset 
}
ThisType 

Protected Attributes

T *volatile

Public Functions

bool
bool
bool
operator!=(T * ptr)
operator=(T * ptr)
bool
operator==(T * ptr)
T *
ptr()
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)
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 *
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)