DGtal 2.0.0
|
Aim: This class encapsulates its parameter class to indicate that the given parameter is required to be duplicated (generally, this is done to have a longer lifetime than the function itself). On one hand, the user is reminded of the possible cost of duplicating the argument parameter, while he is also aware that the lifetime of the parameter is not a problem for the function. On the other hand, the Clone class is smart enough to enforce duplication only if needed. Substantial speed-up can be achieve through this mechanism. More...
#include <DGtal/base/Clone.h>
Data Structures | |
struct | TempPtr |
Internal class that is used for a late deletion of an acquired pointer. More... |
Public Member Functions | |
~Clone () | |
Clone (const Clone &other) | |
Clone (const T &t) | |
Clone (T *ptrT) | |
Clone (const CowPtr< T > &ptrT) | |
Clone (const CountedPtr< T > &ptrT) | |
Clone (T &&t) | |
operator T () const | |
operator CowPtr< T > () const | |
operator CountedPtr< T > () const | |
T * | operator& () const |
Protected Types | |
enum | Parameter { CONST_LEFT_VALUE_REF , LEFT_VALUE_REF , PTR , CONST_PTR , COW_PTR , COUNTED_PTR , RIGHT_VALUE_REF , COUNTED_PTR_OR_PTR , COUNTED_CONST_PTR_OR_CONST_PTR } |
Internal class that allows to distinguish the different types of parameters. More... |
Protected Member Functions | |
void | display (const std::string &method, Parameter p) const |
Private Member Functions | |
Clone () | |
Clone & | operator= (const Clone &other) |
Private Attributes | |
const Parameter | myParam |
Characterizes the type of the input parameter at clone instanciation. | |
const void *const | myPtr |
Stores the address of the input parameter for further use. |
Aim: This class encapsulates its parameter class to indicate that the given parameter is required to be duplicated (generally, this is done to have a longer lifetime than the function itself). On one hand, the user is reminded of the possible cost of duplicating the argument parameter, while he is also aware that the lifetime of the parameter is not a problem for the function. On the other hand, the Clone class is smart enough to enforce duplication only if needed. Substantial speed-up can be achieve through this mechanism.
Description of template class 'Clone'
(For a complete description, see Parameter passing, cloning and referencing).
The class Clone is used in methods or functions to encapsulate the parameter types. The following conversion from input parameter to data member or variable are sumed up in the following table:
Argument type: | const T& | T* | CountedPtr<T> | CowPtr<T> | T&& (c++11) |
---|---|---|---|---|---|
To:T | Dupl. O(N) | Acq. Dupl. O(N) | Dupl. O(N) | Dupl. O(N) | Move. O(1) |
To:T* | Dupl. O(N) | Acq. O(1) | Dupl. O(N) | Dupl. O(N) | Move. O(1) |
To:CowPtr<T> | Dupl. O(N) | Acq. O(1) | Lazy. O(1)/O(N) | Lazy. O(1)/O(N) | Move. O(1) |
with abbreviations:
move
constructor for your class.It is clear that worst case is duplication while sometimes Clone is constant time (while guaranteeing object invariance and life-time).
Clone<T>
instead of const
T
&
or const
T
*
in parameters is always recommended when the user duplicates the parameter and stores a clone of it as a data member for later use. The usage Clone<T>
instead of T
is recommended whenever T
is big (the object is sometimes duplicated twice). When the object is small, writing either Clone<T>
or T
is acceptable. If your member is a CowPtr<T>, then you should use a Clone<T> as parameter. Depending on your data member, we advise the following parameter definition when duplication is asked for.member type: | T | big T | CowPtr<T> | T* |
---|---|---|---|---|
parameter | T or Clone<T> | Clone<T> | Clone<T> | Clone<T> |
T*
means pointer acquisition. Hence the programmer should take care of deletion of the object. Otherwise, deletion is automatic for T
or CowPtr<T>
member. Furthermore, a conversion to a T*
requires the use of the address operator (operator&
) by the developer. If argument is Clone<T> a, and member name is b:member type: | T | T* | CowPtr<T> |
---|---|---|---|
member deletion: | automatic | manual | automatic |
conversion: | automatic: b(a) | address: b(&a) | automatic: b(a) |
T
and T*
) is that there is one less indirection.T | is any type. |
Type | Context | value | const ref | Clone |
---|---|---|---|---|
2xint | i7 2.4GHz | 48ms | 48ms | 59ms |
2xdouble | i7 2.4GHz | 48ms | 48ms | 49ms |
2xint | Xeon 2.67GHz | 54ms | 54ms | 54ms |
2xdouble | Xeon 2.67GHz | 54ms | 54ms | 53.5ms |
It can be used as follows. Consider this simple example where class A is a big object. Then we define three classes B1, B2 and B3, that uses some instance of A.
Sometimes it is also very important that the developper that uses the library is conscious that an object, say b, may require that an instance a given as parameter should have a lifetime longer than b itself (case for an instance of B1 above). Classes Clone, Alias, ConstAlias exist for these reasons. The classes above may be rewritten as follows.
A last question could be why are we not just passing the instance of A by value. This, for sure, would tell the developper that the instance is duplicated somehow. The problem is that it induces generally two duplications, and not only one ! It may be possible that the compiler optimizes things nicely but it is unclear if the compiler will always do it. Furthermore, sometimes, no duplication is needed (when duplicating a CowPtr for instance).
|
protected |
|
inline |
|
inline |
Copy constructor. The cloning is just forwarded.
other | the clone object to clone |
Definition at line 325 of file Clone.h.
References Clone(), myParam, and myPtr.
Referenced by Clone(), and operator=().
|
inline |
Constructor from an instance of T. The object is pointed in 'this'. It is duplicated (or not) when the user claims it.
t | any object of type T. |
Definition at line 333 of file Clone.h.
References CONST_LEFT_VALUE_REF, myParam, and myPtr.
|
inline |
|
inline |
|
inline |
Constructor from CountedPtr<T>. The object is pointed in 'this'. It is duplicated (or not) when the user claims it.
ptrT | any shared pointer to a object of type T. |
Definition at line 360 of file Clone.h.
References COUNTED_PTR, myParam, and myPtr.
|
inline |
Constructor from right-reference value. The object is pointed in 'this'. It is duplicated (or not) when the user claims it.
t | any shared pointer to a object of type T. |
Definition at line 369 of file Clone.h.
References myParam, myPtr, and RIGHT_VALUE_REF.
|
private |
Constructor. Forbidden.
|
inlineprotected |
Debug method for displaying what's happening when using Clone mechanism
method | the name of the conversion method |
p | the type of parameter |
Definition at line 279 of file Clone.h.
References CONST_LEFT_VALUE_REF, CONST_PTR, COUNTED_CONST_PTR_OR_CONST_PTR, COUNTED_PTR, COUNTED_PTR_OR_PTR, COW_PTR, LEFT_VALUE_REF, PTR, RIGHT_VALUE_REF, and DGtal::trace.
|
inline |
Cast operator to a smart pointer on T instance. The object is duplicated or not depending on the type of input parameter.
Definition at line 443 of file Clone.h.
References CONST_LEFT_VALUE_REF, COUNTED_PTR, COW_PTR, myParam, myPtr, PTR, and RIGHT_VALUE_REF.
|
inline |
Cast operator to a copy-on-write pointer on T instance. The object is duplicated or not depending on the type of input parameter.
Definition at line 414 of file Clone.h.
References CONST_LEFT_VALUE_REF, COUNTED_PTR, COW_PTR, myParam, myPtr, PTR, and RIGHT_VALUE_REF.
|
inline |
Cast operator to a T instance. The object is duplicated or not depending on the type of input parameter.
Definition at line 383 of file Clone.h.
References CONST_LEFT_VALUE_REF, COUNTED_PTR, COW_PTR, myParam, myPtr, PTR, and RIGHT_VALUE_REF.
|
inline |
Address operator that returns the address of the given T instance. The object is duplicated or not depending on the type of input parameter.
Definition at line 475 of file Clone.h.
References CONST_LEFT_VALUE_REF, COUNTED_PTR, COW_PTR, myParam, myPtr, PTR, and RIGHT_VALUE_REF.
|
private |
Assignment.
other | the object to copy. |
References Clone().
|
private |
Characterizes the type of the input parameter at clone instanciation.
Definition at line 497 of file Clone.h.
Referenced by Clone(), Clone(), Clone(), Clone(), Clone(), Clone(), operator CountedPtr< T >(), operator CowPtr< T >(), operator T(), and operator&().
|
private |
Stores the address of the input parameter for further use.
Definition at line 499 of file Clone.h.
Referenced by Clone(), Clone(), Clone(), Clone(), Clone(), Clone(), operator CountedPtr< T >(), operator CowPtr< T >(), operator T(), and operator&().