Simbody
3.7
|
Smart pointer with deep copy semantics but with the copying delayed until an attempt is made to write on the contained object. More...
Public Types | |
typedef T | element_type |
Type of the contained object. More... | |
typedef T * | pointer |
Type of a pointer to the contained object. More... | |
typedef T & | reference |
Type of a reference to the contained object. More... | |
Public Member Functions | |
Constructors | |
CloneOnWritePtr () noexcept | |
Default constructor stores a nullptr and sets use count to zero. More... | |
CloneOnWritePtr (std::nullptr_t) noexcept | |
Constructor from nullptr is the same as the default constructor. More... | |
CloneOnWritePtr (T *x) | |
Given a pointer to a writable heap-allocated object, take over ownership of that object. More... | |
CloneOnWritePtr (const T *x) | |
Given a pointer to a read-only object, create a new heap-allocated copy of that object via its clone() method and make this CloneOnWritePtr the owner of the copy. More... | |
CloneOnWritePtr (const T &x) | |
Given a read-only reference to an object, create a new heap-allocated copy of that object via its clone() method and make this CloneOnWritePtr object the owner of the copy. More... | |
CloneOnWritePtr (const CloneOnWritePtr &src) noexcept | |
Copy constructor is deep but deferred so very fast here; the new CloneOnWritePtr object initially shares the source object, but if either source or destination are written to subsequently a deep copy is made and the objects become disconnected. More... | |
template<class U > | |
CloneOnWritePtr (const CloneOnWritePtr< U > &src) noexcept | |
Copy construction from a compatible CloneOnWritePtr. More... | |
CloneOnWritePtr (CloneOnWritePtr &&src) noexcept | |
Move constructor is very fast and leaves the source empty. More... | |
template<class U > | |
CloneOnWritePtr (CloneOnWritePtr< U > &&src) noexcept | |
Move construction from a compatible CloneOnWritePtr. More... | |
Assignment | |
CloneOnWritePtr & | operator= (const CloneOnWritePtr &src) noexcept |
Copy assignment replaces the currently-held object by a deferred copy of the object held in the source container. More... | |
template<class U > | |
CloneOnWritePtr & | operator= (const CloneOnWritePtr< U > &src) noexcept |
Copy assignment from a compatible CloneOnWritePtr. More... | |
CloneOnWritePtr & | operator= (CloneOnWritePtr &&src) noexcept |
Move assignment replaces the currently-held object by the source object, leaving the source empty. More... | |
template<class U > | |
CloneOnWritePtr & | operator= (CloneOnWritePtr< U > &&src) noexcept |
Move assignment from a compatible CloneOnWritePtr. More... | |
CloneOnWritePtr & | operator= (const T &x) |
This form of assignment replaces the currently-held object by a heap-allocated copy of the source object, created using its clone() method. More... | |
CloneOnWritePtr & | operator= (T *x) noexcept |
This form of assignment replaces the currently-held object by the given source object and takes over ownership of the source object. More... | |
Destructor | |
~CloneOnWritePtr () noexcept | |
Destructor decrements the reference count and deletes the object if the count goes to zero. More... | |
Accessors | |
const T * | get () const noexcept |
Return a const pointer to the contained object if any, or nullptr . More... | |
T * | upd () |
Clone if necessary to ensure the contained object is not shared, then return a writable pointer to the contained (and now unshared) object if any, or nullptr . More... | |
const T & | getRef () const |
Return a const reference to the contained object. More... | |
T & | updRef () |
Clone if necessary to ensure the contained object is not shared, then return a writable reference to the contained (and now unshared) object. More... | |
const T * | operator-> () const |
Dereference a const pointer to the contained object. More... | |
T * | operator-> () |
Clone if necessary, then dereference a writable pointer to the contained object. More... | |
const T & | operator* () const |
This "dereference" operator returns a const reference to the contained object. More... | |
T & | operator* () |
Clone if necessary, then return a writable reference to the contained object. More... | |
Utility Methods | |
void | reset () noexcept |
Make this container empty, decrementing the use count of the contained object (if any), and deleting it if this was the last use. More... | |
void | reset (T *x) |
Replace the contents of this container with the supplied heap-allocated object, taking over ownership of that object and deleting the current one first if necessary. More... | |
void | swap (CloneOnWritePtr &other) noexcept |
Swap the contents of this CloneOnWritePtr with another one, with ownership changing hands but no copying performed. More... | |
long | use_count () const noexcept |
Return count of how many CloneOnWritePtr objects are currently sharing the referenced object. More... | |
bool | unique () const noexcept |
Is this the only user of the referenced object? Note that this means there is exactly one; if the managed pointer is null unique() returns false . More... | |
bool | empty () const noexcept |
Return true if this container is empty, which is the state the container is in immediately after default construction and various other operations. More... | |
operator bool () const noexcept | |
This is a conversion to type bool that returns true if the container is non-null (that is, not empty). More... | |
T * | release () |
(Advanced) Remove the contained object from management by this container and transfer ownership to the caller. More... | |
void | detach () |
(Advanced) Force the contained object to be unique, that is, not shared with any other container. More... | |
Friends | |
template<class U > | |
class | CloneOnWritePtr |
Related Functions | |
(Note that these are not member functions.) | |
template<class T > | |
void | swap (CloneOnWritePtr< T > &p1, CloneOnWritePtr< T > &p2) |
This is an overload of the STL std::swap() algorithm which uses the cheap built-in swap() member of the CloneOnWritePtr class. More... | |
template<class charT , class traits , class T > | |
std::basic_ostream< charT, traits > & | operator<< (std::basic_ostream< charT, traits > &os, const CloneOnWritePtr< T > &p) |
Output the system-dependent representation of the pointer contained in a CloneOnWritePtr object. More... | |
template<class T , class U > | |
bool | operator== (const CloneOnWritePtr< T > &lhs, const CloneOnWritePtr< U > &rhs) |
Compare for equality the managed pointers contained in two compatible CloneOnWritePtr containers. More... | |
template<class T > | |
bool | operator== (const CloneOnWritePtr< T > &lhs, std::nullptr_t) |
Comparison against nullptr ; same as lhs.empty() . More... | |
template<class T > | |
bool | operator== (std::nullptr_t, const CloneOnWritePtr< T > &rhs) |
Comparison against nullptr ; same as rhs.empty() . More... | |
template<class T , class U > | |
bool | operator< (const CloneOnWritePtr< T > &lhs, const CloneOnWritePtr< U > &rhs) |
Less-than operator for two compatible CloneOnWritePtr containers, comparing the pointers, not the objects they point to. More... | |
template<class T > | |
bool | operator< (const CloneOnWritePtr< T > &lhs, std::nullptr_t) |
Less-than comparison against a nullptr . More... | |
template<class T > | |
bool | operator< (std::nullptr_t, const CloneOnWritePtr< T > &rhs) |
Less-than comparison of a nullptr against this container. More... | |
template<class T , class U > | |
bool | operator!= (const CloneOnWritePtr< T > &lhs, const CloneOnWritePtr< U > &rhs) |
Pointer inequality test defined as !(lhs==rhs) . More... | |
template<class T > | |
bool | operator!= (const CloneOnWritePtr< T > &lhs, std::nullptr_t) |
nullptr inequality test defined as !(lhs==nullptr) . More... | |
template<class T > | |
bool | operator!= (std::nullptr_t, const CloneOnWritePtr< T > &rhs) |
nullptr inequality test defined as !(nullptr==rhs) . More... | |
template<class T , class U > | |
bool | operator> (const CloneOnWritePtr< T > &lhs, const CloneOnWritePtr< U > &rhs) |
Pointer greater-than test defined as rhs < lhs . More... | |
template<class T > | |
bool | operator> (const CloneOnWritePtr< T > &lhs, std::nullptr_t) |
nullptr greater-than test defined as nullptr < lhs . More... | |
template<class T > | |
bool | operator> (std::nullptr_t, const CloneOnWritePtr< T > &rhs) |
nullptr greater-than test defined as rhs < nullptr . More... | |
template<class T , class U > | |
bool | operator>= (const CloneOnWritePtr< T > &lhs, const CloneOnWritePtr< U > &rhs) |
Pointer greater-or-equal test defined as !(lhs < rhs) . More... | |
template<class T > | |
bool | operator>= (const CloneOnWritePtr< T > &lhs, std::nullptr_t) |
nullptr greater-or-equal test defined as !(lhs < nullptr) . More... | |
template<class T > | |
bool | operator>= (std::nullptr_t, const CloneOnWritePtr< T > &rhs) |
nullptr greater-or-equal test defined as !(nullptr < rhs) . More... | |
template<class T , class U > | |
bool | operator<= (const CloneOnWritePtr< T > &lhs, const CloneOnWritePtr< U > &rhs) |
Pointer less-or-equal test defined as !(rhs < lhs) (note reversed arguments). More... | |
template<class T > | |
bool | operator<= (const CloneOnWritePtr< T > &lhs, std::nullptr_t) |
nullptr less-or-equal test defined as !(nullptr < lhs) (note reversed arguments). More... | |
template<class T > | |
bool | operator<= (std::nullptr_t, const CloneOnWritePtr< T > &rhs) |
nullptr less-or-equal test defined as !(rhs < nullptr) (note reversed arguments). More... | |
Smart pointer with deep copy semantics but with the copying delayed until an attempt is made to write on the contained object.
This is like std::shared_ptr
when an object is being read, but like SimTK::ClonePtr when the object is written. Like SimTK::ClonePtr, CloneOnWritePtr supports copy and assignment operations, by insisting that the contained object have a clone()
method that returns a pointer to a heap-allocated deep copy of the concrete object. The API is modeled as closely as possible to the C++11 std::shared_ptr
and std::unique_ptr
. However, it always uses a default deleter. Also, the get() method is modified to return a const pointer to avoid accidental copying, with upd() (update) added to return a writable pointer.
This class is entirely inline and has no computational or space overhead beyond the cost of dealing with the reference count, except when a copy has to be made due to a write attempt.
T | The type of the contained object, which must have a clone() method. May be an abstract or concrete type. |
typedef T SimTK::CloneOnWritePtr< T >::element_type |
Type of the contained object.
typedef T* SimTK::CloneOnWritePtr< T >::pointer |
Type of a pointer to the contained object.
typedef T& SimTK::CloneOnWritePtr< T >::reference |
Type of a reference to the contained object.
|
inlinenoexcept |
Default constructor stores a nullptr
and sets use count to zero.
No heap allocation is performed. The empty() method will return true when called on a default-constructed CloneOnWritePtr.
|
inlinenoexcept |
Constructor from nullptr
is the same as the default constructor.
This is an implicit conversion that allows nullptr
to be used to initialize a CloneOnWritePtr.
|
inlineexplicit |
Given a pointer to a writable heap-allocated object, take over ownership of that object.
The use count will be one unless the pointer was null in which case it will be zero.
|
inlineexplicit |
Given a pointer to a read-only object, create a new heap-allocated copy of that object via its clone()
method and make this CloneOnWritePtr the owner of the copy.
Ownership of the original object is not affected. If the supplied pointer is null, the resulting CloneOnWritePtr is as though default constructed, otherwise the use count will be one.
|
inlineexplicit |
Given a read-only reference to an object, create a new heap-allocated copy of that object via its clone()
method and make this CloneOnWritePtr object the owner of the copy.
Ownership of the original object is not affected. The use count will be one after construction.
|
inlinenoexcept |
Copy constructor is deep but deferred so very fast here; the new CloneOnWritePtr object initially shares the source object, but if either source or destination are written to subsequently a deep copy is made and the objects become disconnected.
If the source container is empty this one will be as though default constructed.
|
inlinenoexcept |
Copy construction from a compatible CloneOnWritePtr.
Type U*
must be implicitly convertible to type T*
.
|
inlinenoexcept |
Move constructor is very fast and leaves the source empty.
The use count is unchanged. If the source was empty this one will be as though default constructed.
|
inlinenoexcept |
Move construction from a compatible CloneOnWritePtr.
Type U*
must be implicitly convertible to type T*
.
|
inlinenoexcept |
Destructor decrements the reference count and deletes the object if the count goes to zero.
|
inlinenoexcept |
Copy assignment replaces the currently-held object by a deferred copy of the object held in the source container.
The copy will be created upon a subsequent write using the source object's clone()
method. If the source container is empty this one will be empty after the assignment. Nothing happens if the source and destination were already managing the same object.
|
inlinenoexcept |
Copy assignment from a compatible CloneOnWritePtr.
Type U*
must be implicitly convertible to type T*
.
|
inlinenoexcept |
Move assignment replaces the currently-held object by the source object, leaving the source empty.
The currently-held object's use count will be reduced by one and deleted if this was the last use. Nothing happens if the source and destination are the same containers. If they are different but are sharing the same object then the use count is reduced by one.
|
inlinenoexcept |
Move assignment from a compatible CloneOnWritePtr.
Type U* must be implicitly convertible to type T*.
|
inline |
This form of assignment replaces the currently-held object by a heap-allocated copy of the source object, created using its clone()
method.
The use count of the currently-held object (if any) is decremented and the object is deleted if this was the last reference to it. On return the use count of this container will be one.
|
inlinenoexcept |
This form of assignment replaces the currently-held object by the given source object and takes over ownership of the source object.
The use count of the currently-held object is decremented and the object is deleted if this was the last reference to it.
|
inlinenoexcept |
|
inline |
Clone if necessary to ensure the contained object is not shared, then return a writable pointer to the contained (and now unshared) object if any, or nullptr
.
If you only need read access, use get() instead to avoid the potentially expensive cloning. Note that you need write access to this container in order to get write access to the object it contains.
|
inline |
Return a const reference to the contained object.
No cloning is needed so this is very fast. Don't call this if this container is empty.
|
inline |
Clone if necessary to ensure the contained object is not shared, then return a writable reference to the contained (and now unshared) object.
Don't call this if this container is empty.
|
inline |
Dereference a const pointer to the contained object.
This will fail if the container is empty.
const
operator will only be invoked if it is applied to a const
container; otherwise the non-const method will be called and an unwanted copy may be performed. Use getRef() instead if you have a writable container but don't need write access to the contained object.
|
inline |
Clone if necessary, then dereference a writable pointer to the contained object.
This will fail if the container is empty.
|
inline |
This "dereference" operator returns a const reference to the contained object.
This will fail if the container is empty.
const
method will only be invoked if it is applied to a const
container; otherwise the non-const method will be called and an unwanted copy may be performed. Use getRef() instead if you have a writable container but don't need write access to the contained object.
|
inline |
Clone if necessary, then return a writable reference to the contained object.
This will fail if the container is empty.
|
inlinenoexcept |
Make this container empty, decrementing the use count of the contained object (if any), and deleting it if this was the last use.
The container is restored to its default-constructed state.
|
inline |
Replace the contents of this container with the supplied heap-allocated object, taking over ownership of that object and deleting the current one first if necessary.
Nothing happens if the supplied pointer is the same as the one already being managed. Otherwise, on return the use count will be one if the supplied pointer was non-null or else zero.
|
inlinenoexcept |
Swap the contents of this CloneOnWritePtr with another one, with ownership changing hands but no copying performed.
This is very fast; no heap activity occurs. Both containers must have been instantiated with the identical type.
|
inlinenoexcept |
Return count of how many CloneOnWritePtr objects are currently sharing the referenced object.
There is never more than one holding an object for writing. If the pointer is null the use count is zero.
|
inlinenoexcept |
Is this the only user of the referenced object? Note that this means there is exactly one; if the managed pointer is null unique()
returns false
.
|
inlinenoexcept |
Return true if this container is empty, which is the state the container is in immediately after default construction and various other operations.
|
inlineexplicitnoexcept |
This is a conversion to type bool that returns true if the container is non-null (that is, not empty).
|
inline |
(Advanced) Remove the contained object from management by this container and transfer ownership to the caller.
Clone if necessary to ensure that the contained object is not being shared with any other container, then extract the object from this container, leaving the container empty. A writable pointer to the object is returned. No object destruction occurs.
|
inline |
(Advanced) Force the contained object to be unique, that is, not shared with any other container.
(Normally this is done automatically when necessary; this method is like useful mostly for debugging.) If the referenced object is being shared (that is, use_count()>1), clone it and replace the pointer with the newly cloned object. This CloneOnWritePtr will have a use count of zero or one after this call; other sharers of the object will see the shared use count reduced by one. If this is empty() or unique() already then nothing happens. Note that you have to have write access to this container in order to detach it.
|
related |
This is an overload of the STL std::swap() algorithm which uses the cheap built-in swap() member of the CloneOnWritePtr class.
(This function is defined in the SimTK
namespace.)
|
related |
Output the system-dependent representation of the pointer contained in a CloneOnWritePtr object.
This is equivalent to os << p.get();
.
|
related |
Compare for equality the managed pointers contained in two compatible CloneOnWritePtr containers.
Returns true
if the pointers refer to the same object or if both are null. It must be possible for one of the pointer types T*
and U*
to be implicitly converted to the other.
|
related |
Comparison against nullptr
; same as lhs.empty()
.
|
related |
Comparison against nullptr
; same as rhs.empty()
.
|
related |
Less-than operator for two compatible CloneOnWritePtr containers, comparing the pointers, not the objects they point to.
Returns true
if the lhs pointer tests less than the rhs pointer. A null pointer tests less than any non-null pointer. It must be possible for one of the pointer types T*
and U*
to be implicitly converted to the other.
|
related |
Less-than comparison against a nullptr
.
A null pointer tests less than any non-null pointer and equal to another null pointer, so this method always returns false
.
|
related |
Less-than comparison of a nullptr
against this container.
A null pointer tests less than any non-null pointer and equal to another null pointer, so this method returns true
unless the container is empty.
|
related |
Pointer inequality test defined as !(lhs==rhs)
.
|
related |
nullptr
inequality test defined as !(lhs==nullptr)
.
|
related |
nullptr
inequality test defined as !(nullptr==rhs)
.
|
related |
Pointer greater-than test defined as rhs < lhs
.
|
related |
nullptr
greater-than test defined as nullptr < lhs
.
|
related |
nullptr
greater-than test defined as rhs < nullptr
.
|
related |
Pointer greater-or-equal test defined as !(lhs < rhs)
.
|
related |
nullptr
greater-or-equal test defined as !(lhs < nullptr)
.
|
related |
nullptr
greater-or-equal test defined as !(nullptr < rhs)
.
|
related |
Pointer less-or-equal test defined as !(rhs < lhs)
(note reversed arguments).
|
related |
nullptr
less-or-equal test defined as !(nullptr < lhs)
(note reversed arguments).
|
related |
nullptr
less-or-equal test defined as !(rhs < nullptr)
(note reversed arguments).