MADNESS  0.10.1
Public Types | Public Member Functions | Static Private Member Functions | Private Attributes | Friends | List of all members
madness::RemoteReference< T > Class Template Reference

Simple structure used to manage references/pointers to remote instances. More...

#include <worldref.h>

Collaboration diagram for madness::RemoteReference< T >:
Collaboration graph
[legend]

Public Types

typedef TpointerT
 
typedef detail::ptr_traits< T >::reference referenceT
 

Public Member Functions

 RemoteReference ()
 Makes a non-shared (no reference count) null pointer. More...
 
 RemoteReference (const RemoteReference< T > &other)
 Copy constructor. More...
 
template<typename U >
 RemoteReference (const RemoteReference< U > &other)
 Copy conversion constructor. More...
 
 RemoteReference (World &w, const std::shared_ptr< T > &p)
 Construct a remote reference to p. More...
 
 ~RemoteReference ()
 
pointerT get () const
 Reference pointer accessor. More...
 
const std::shared_ptr< T > & get_shared () const
 Reference shared_ptr accessor. More...
 
Worldget_world () const
 Owning world accessor. More...
 
bool is_local () const
 Locally owned reference. More...
 
 operator bool () const
 Boolean conversion operator. More...
 
referenceT operator* () const
 Reference object accessor. More...
 
pointerT operator-> () const
 Reference object pointer accessor. More...
 
RemoteReference< T > & operator= (const RemoteReference< T > &other)
 Copy conversion assignment operator. More...
 
template<typename U >
RemoteReference< T > & operator= (const RemoteReference< U > &other)
 Copy conversion assignment operator. More...
 
ProcessID owner () const
 Reference owner accessor. More...
 
void reset ()
 Release this reference. More...
 
template<typename Archive >
void serialize (const Archive &ar) const
 Serialize the remote reference. More...
 
template<typename U >
void swap (RemoteReference< U > &other)
 Swap references. More...
 
bool unique () const
 Get uniqueness. More...
 
long use_count () const
 Reference count accessor. More...
 

Static Private Member Functions

static void reset_handler (const AmArg &arg)
 

Private Attributes

detail::RemoteCounter counter_
 Remote reference counter. More...
 
pointerT pointer_
 World pointer. More...
 

Friends

template<typename >
class RemoteReference
 
std::ostream & operator<< (std::ostream &out, const RemoteReference< T > &ref)
 Add the remote reference to the given std::ostream, out. More...
 

Detailed Description

template<typename T>
class madness::RemoteReference< T >

Simple structure used to manage references/pointers to remote instances.

This class was intended only for internal use and is still rather poorly thought through, however, it seems to fill a wider need.

Note
Do not serialize via wrap_opaque().
Ownership of a reference is transferred when serialized on a remote node. You should not attempt to send a remote reference to more than one node except from the owning node. If you do serialize more than once, this will cause an invalid memory access on the owning node.
!!! It is YOUR RESPONSIBILITY to release the reference count. This can be done by sending the remote reference back to the owner or by calling reset(). If this is not done, you will have a memory leak.

Member Typedef Documentation

◆ pointerT

template<typename T >
typedef T* madness::RemoteReference< T >::pointerT

◆ referenceT

template<typename T >
typedef detail::ptr_traits<T>::reference madness::RemoteReference< T >::referenceT

Constructor & Destructor Documentation

◆ RemoteReference() [1/4]

template<typename T >
madness::RemoteReference< T >::RemoteReference ( )
inline

Makes a non-shared (no reference count) null pointer.

◆ RemoteReference() [2/4]

template<typename T >
madness::RemoteReference< T >::RemoteReference ( World w,
const std::shared_ptr< T > &  p 
)
inline

Construct a remote reference to p.

Parameters
wThe world that p belongs to.
pThe shared_ptr that is to be referenced.
Note
p must be locally addressable pointer

◆ RemoteReference() [3/4]

template<typename T >
madness::RemoteReference< T >::RemoteReference ( const RemoteReference< T > &  other)
inline

Copy constructor.

Parameters
otherThe reference to be copied

◆ RemoteReference() [4/4]

template<typename T >
template<typename U >
madness::RemoteReference< T >::RemoteReference ( const RemoteReference< U > &  other)
inline

Copy conversion constructor.

Template Parameters
UThe remote reference type to be copied
Parameters
otherThe reference to be copied
Note
U* must be implicitly convertible to T*

◆ ~RemoteReference()

template<typename T >
madness::RemoteReference< T >::~RemoteReference ( )
inline

Member Function Documentation

◆ get()

template<typename T >
pointerT madness::RemoteReference< T >::get ( ) const
inline

Reference pointer accessor.

Returns
The referenced pointer
Exceptions
MadnessExceptionIf the pointer is not local

References madness::RemoteReference< T >::counter_, madness::detail::RemoteCounter::is_local(), MADNESS_ASSERT, and madness::RemoteReference< T >::pointer_.

Referenced by madness::FutureImpl< T >::set_handler().

◆ get_shared()

template<typename T >
const std::shared_ptr<T>& madness::RemoteReference< T >::get_shared ( ) const
inline

Reference shared_ptr accessor.

Returns
A const reference to the references shared pointer
Exceptions
MadnessExceptionIf the pointer is not local

References madness::RemoteReference< T >::counter_, madness::detail::RemoteCounter::get_shared(), madness::detail::RemoteCounter::is_local(), MADNESS_ASSERT, and T().

◆ get_world()

template<typename T >
World& madness::RemoteReference< T >::get_world ( ) const
inline

Owning world accessor.

Returns
A reference to the world that owns the pointer
Exceptions
MadnessExceptionIf the reference is uninitialized

References madness::RemoteReference< T >::counter_, and madness::detail::RemoteCounter::get_world().

Referenced by madness::RemoteReference< T >::reset().

◆ is_local()

template<typename T >
bool madness::RemoteReference< T >::is_local ( ) const
inline

Locally owned reference.

Returns
true if owner is equal to the current rank of the owning world, otherwise false
Exceptions
nothing

References madness::RemoteReference< T >::counter_, and madness::detail::RemoteCounter::is_local().

◆ operator bool()

template<typename T >
madness::RemoteReference< T >::operator bool ( ) const
inline

Boolean conversion operator.

Returns
true when the reference is initialized to a non zero value or uninitialized, otherwise false

References madness::RemoteReference< T >::counter_, and madness::detail::RemoteCounter::empty().

◆ operator*()

template<typename T >
referenceT madness::RemoteReference< T >::operator* ( ) const
inline

Reference object accessor.

Returns
A reference to the referenced object
Exceptions
MadnessExceptionIf the pointer is uninitialized
MadnessExceptionIf the pointer is not local

References madness::RemoteReference< T >::counter_, madness::detail::RemoteCounter::is_local(), MADNESS_ASSERT, and madness::RemoteReference< T >::pointer_.

◆ operator->()

template<typename T >
pointerT madness::RemoteReference< T >::operator-> ( ) const
inline

Reference object pointer accessor.

Returns
A pointer to the referenced object
Exceptions
MadnessExceptionIf the pointer is uninitialized
MadnessExceptionIf the pointer is not local

References madness::RemoteReference< T >::counter_, madness::detail::RemoteCounter::is_local(), MADNESS_ASSERT, and madness::RemoteReference< T >::pointer_.

◆ operator=() [1/2]

template<typename T >
RemoteReference<T>& madness::RemoteReference< T >::operator= ( const RemoteReference< T > &  other)
inline

Copy conversion assignment operator.

Parameters
otherThe reference to be copied

References madness::RemoteReference< T >::swap().

◆ operator=() [2/2]

template<typename T >
template<typename U >
RemoteReference<T>& madness::RemoteReference< T >::operator= ( const RemoteReference< U > &  other)
inline

Copy conversion assignment operator.

Template Parameters
UThe remote reference type to be copied
Parameters
otherThe reference to be copied
Note
U* must be implicitly convertible to T*

References madness::RemoteReference< T >::swap().

◆ owner()

template<typename T >
ProcessID madness::RemoteReference< T >::owner ( ) const
inline

Reference owner accessor.

Returns
rank of owning process, or -1 if not initialized
Exceptions
nothing

References madness::RemoteReference< T >::counter_, and madness::detail::RemoteCounter::owner().

Referenced by madness::RemoteReference< T >::reset().

◆ reset()

template<typename T >
void madness::RemoteReference< T >::reset ( )
inline

Release this reference.

This function will clear the reference and leave it in the default constructed state. If the reference is non-local, then a message is sent to the reference owner that releases the reference.

Warning
Only call this function for non-local references when it will not otherwise be returned to the reference owner as part of a message.

References madness::World::am, madness::RemoteReference< T >::counter_, madness::RemoteReference< T >::get_world(), madness::detail::RemoteCounter::has_owner(), madness::detail::RemoteCounter::is_local(), madness::new_am_arg(), madness::RemoteReference< T >::owner(), madness::WorldAmInterface::send(), and madness::RemoteReference< T >::swap().

Referenced by madness::FutureImpl< T >::set_handler().

◆ reset_handler()

template<typename T >
static void madness::RemoteReference< T >::reset_handler ( const AmArg arg)
inlinestaticprivate

References madness::arg().

◆ serialize()

template<typename T >
template<typename Archive >
void madness::RemoteReference< T >::serialize ( const Archive &  ar) const
inline

Serialize the remote reference.

Template Parameters
ArchiveThe serialization archive type
Parameters
arThe serialization archive object.

References madness::RemoteReference< T >::counter_, madness::RemoteReference< T >::pointer_, and madness::archive::wrap_opaque().

◆ swap()

template<typename T >
template<typename U >
void madness::RemoteReference< T >::swap ( RemoteReference< U > &  other)
inline

Swap references.

Exchange the value of this RemoteReference with other RemoteReference

Template Parameters
UThe type of the other remote reference.
Note
U* must be implicitly convertible to T*.

References madness::RemoteReference< T >::counter_, madness::RemoteReference< T >::pointer_, madness::swap(), and madness::detail::swap().

Referenced by madness::RemoteReference< T >::operator=(), madness::RemoteReference< T >::reset(), and madness::swap().

◆ unique()

template<typename T >
bool madness::RemoteReference< T >::unique ( ) const
inline

Get uniqueness.

Returns
True when the use count is equal to exactly 1.
Exceptions
nothing

References madness::RemoteReference< T >::counter_, and madness::detail::RemoteCounter::unique().

◆ use_count()

template<typename T >
long madness::RemoteReference< T >::use_count ( ) const
inline

Reference count accessor.

Returns
The total number of local and remote references.
Exceptions
nothing

References madness::RemoteReference< T >::counter_, and madness::detail::RemoteCounter::use_count().

Friends And Related Function Documentation

◆ RemoteReference

template<typename T >
template<typename >
friend class RemoteReference
friend

◆ operator<<

template<typename T >
std::ostream& operator<< ( std::ostream &  out,
const RemoteReference< T > &  ref 
)
friend

Add the remote reference to the given std::ostream, out.

Parameters
outThe output stream to add ref to.
refThe remote reference to add to the out stream

Member Data Documentation

◆ counter_

template<typename T >
detail::RemoteCounter madness::RemoteReference< T >::counter_
private

◆ pointer_

template<typename T >
pointerT madness::RemoteReference< T >::pointer_
mutableprivate

The documentation for this class was generated from the following file: