mxm::smart< T > Class Template Reference
[modularMX Runtime Platform Core]

modularMX smart pointer implementation - please read Thread Safety note below. More...

#include <mxmSmartHandle.h>

Inheritance diagram for mxm::smart< T >:

mxmSmartHandleCore mxmObject List of all members.

Public Member Functions

 smart ()
 [Not synchronized] Constructs a default-state-handle: null-handle (=> alone), no lock.
 smart (const smart< T > &other)
 [Synchronized via target group's lock] Copy constructor.
 smart (T *handlee)
 [Not synchronized] Constructor immediately assigning a dumb handlee pointer.
 ~smart ()
 [Synchronized]
smart< T > & operator= (const smart< T > &other)
 [*** Synchronized, but SAFETY BREACH] Assignment operator.
smart< T > & operator= (T *handlee)
 [*** Synchronized, but SAFETY BREACH] Assigns handlee object.
T * operator-> (void) const
 [Not synchronized] Dereference operator.
T & operator * (void) const
 [Not synchronized] Dereference operator.
bool operator== (const smart< T > &other) const
 [Not synchronized] Comparison.
template<class NewT>
 operator smart (void) const
 [Synchronized] Dynamic type cast: This is advanced magic stuff for inheritance-based type conversion between smart handles for different, but related handle types.

Private Member Functions

void deleteHandlee (void)
 [Not synchronized] (Re)implemented.

Detailed Description

template<class T>
class mxm::smart< T >

modularMX smart pointer implementation - please read Thread Safety note below.

Author:
[khe] Kai Hergenroether

Semantics

The used smart pointer semantics is shared: By passing an object allocated on the heap to a smart pointer, you thereby create the first smart handle for that handlee object. This handle can then be copied by various methods, for example by assigning it to other, type-compatible smart handles or by passing it as parameter into methods. All the resulting copies, that all refer to the same one handlee object on the heap, are said to form a handle group. The moment the handlee was passed to the first of the handles, ownership over it was transfered from the current context to this handle group. At the time the last member of the group dies, the handlee object is automatically deleted.

Smart handles have the following benefits:

Note that the terms smart pointer and smart handle will in the following be used synonymously.

Ownership

Null-ness

In analogy to null-pointers, mxm smart pointers can also be null-handles. null-handles result from

null-handle Properties

Testing for null-ness

To test whether or not a given smart handle is a null handle, either use null() or the overloaded ! operator as in

    if(!handle) {

      // _handle_ is _null_ handle
    }
  
An implicit conversion to bool was not included in the class to avoid the risk of comparing smart handles with different template arguments and thus incomatible types. So don't use
    if(handle) 
     handle->doSomething();
  

Multithreaded Scenarios

As of 20070328, mxm smart handles provide synchronization mechanisms to allow safe operation in multithreaded scenarios. Such scenarios can for example be found

How to use Thread Protection?

Note that the handlee object itself will not be protected by the smart handle group. If you spread the members of a given handle group out over multiple threads that then use the respective handlee object as a shared resource, you yourself are responsible of providing adequate synchronization when accessing it.

Thread Safety (!!! IMPORTANT !!!)

This section is only relevant for the special case in which you intend to use a given smart handle instance as a shared resource itself, meaning: in case you wish to access it simultaneously from multiple threads (the handle, not the handlee object!). This might for example be the case if you have used smart pointers to tie together a complex object structure that is then accessed by multiple threads without having access locks preventing the threads from simultaneously following (dereferencing) the object references.

The thread safety semantics for a given smart handle object are the same as for the boost::shared_ptr implementation, and defined as follows:

Usage Practices

Implementation (Advanced)

To deliver the above straightforward, boost::shared_ptr-compatible thread safety semantics, the following conventions were used for the implementation:

To summarize, since all potentially malicious operations are non-const, it is safe to simultaneously activate const operations on the same given smart handle object.

Notes

Templates and code bloat

Although this class is a C++ template class, the main functionality is inherited from the non-template mxmSmartHandleCore. Only the code needed to implement type-safety remains here, hopefully minimzing code expansion.

Administrative Datastructure

This implementation currently uses a doublelinked list to link together all handles for a given "handlee" object. Since we do not intend to instantiate vast numbers of handles per handled object, this makes sense.


Member Function Documentation

template<class T>
mxm::smart< T > & mxm::smart< T >::operator= T *  handlee  ) 
 

[*** Synchronized, but SAFETY BREACH] Assigns handlee object.

Before assigning the new handlee object, the handle is reset to default state: null-handle (=> alone), no lock.

template<class T>
mxm::smart< T > & mxm::smart< T >::operator= const smart< T > &  other  ) 
 

[*** Synchronized, but SAFETY BREACH] Assignment operator.

Before joining the new handle group, the handle is reset to default state: null-handle (=> alone), no lock.


The documentation for this class was generated from the following file:
Generated on Fri Jun 29 17:21:07 2007 for MxPEG SDK by  doxygen 1.4.6