Teuchos::OpaqueWrapper< Opaque > Class Template Reference
[Teuchos Memory Management Utilities]

Base class for wrapped opaque objects. More...

#include <Teuchos_OpaqueWrapper.hpp>

Inheritance diagram for Teuchos::OpaqueWrapper< Opaque >:

Teuchos::OpaqueWrapperWithFree< Opaque, OpaqueFree > List of all members.

Public Member Functions

 OpaqueWrapper (Opaque opaque)
 
 operator Opaque () const
 
Opaque operator() () const
 

Protected Attributes

Opaque opaque_

Related Functions

(Note that these are not member functions.)

RCP< OpaqueWrapper< Opaque > > opaqueWrapper (Opaque opaque)
 Helper function created a new OpaqueWrapper object without a free function.
RCP< OpaqueWrapper< Opaque > > opaqueWrapper (Opaque opaque, OpaqueFree opaqueFree)
 Helper function created a new OpaqueWrapper object with a free function.

Detailed Description

template<class Opaque>
class Teuchos::OpaqueWrapper< Opaque >

Base class for wrapped opaque objects.

This base class allows opaque objects to be wrapped by a real object that you can then take an address off. This is needed in order to wrap an opaque object in a RCP for example.

For example, MPI uses the opaque object idiom for handling things like MPI_Comm, and MPI_Op. Some implementations implement these opaque object handles and just integers. This causes many problems with used with the RCP (just try wrapping an MPI_Comm object directly in a RCP and see what happens yourself and see what happens).

For example, to wrap MPI_COMM_WORLD in a RCP, you would do opaqueWrapper(MPI_COMM_WORLD) and that is it.

Consider what would happen if you tried to directly wrap the MPI_Comm MPI_COMM_WORLD in a RCP. On some implementations like MPICH, MPI_Comm is just a typedef to an integer and MPI_COMM_WORLD is just a define to a literal interger. In this case, the expression rcp(&MPI_COMM_WORLD) would not even compile (try this on your version of MPICH). To make this compile, we might try something like:

  Teuchos::RCP<MPI_Comm> getMpiCommPtr()
  {
    MPI_Comm comm = MPI_COMM_WORLD;
    return Teuchos::rcp(&comm,false);
  }

Of course the above code would result in a disaster when the stack variable comm, which is just an integer in MPICH, was destroyed and reclaimed. The RCP returned from getMpiCommPtr() would contain a raw pointer an int object that was now being used for something else and would no longer have the integer value of a valid MPI_Comm object.

The following implementation would most likely work but is pretty ugly:

  Teuchos::RCP<MPI_Comm> getMpiCommPtr()
  {
    MPI_Comm *comm = new MPI_Comm(MPI_COMM_WORLD);
    return Teuchos::rcp(&comm);
  }

The above implementation of getMPiCommPtr() would work with MPICH but it is unclear how this would work with other implementations of MPI (but it should work for these also). However, this is pretty ugly to do.

There are other issues that crop up also when you play these types of games.

Therefore, just use opaqueWrapper() create wrap opaque objects in RCP objects and be sure that this will go smoothly.

Definition at line 105 of file Teuchos_OpaqueWrapper.hpp.


Constructor & Destructor Documentation

template<class Opaque>
Teuchos::OpaqueWrapper< Opaque >::OpaqueWrapper ( Opaque  opaque  )  [inline]

Definition at line 108 of file Teuchos_OpaqueWrapper.hpp.


Member Function Documentation

template<class Opaque>
Teuchos::OpaqueWrapper< Opaque >::operator Opaque (  )  const [inline]

Definition at line 112 of file Teuchos_OpaqueWrapper.hpp.

template<class Opaque>
Opaque Teuchos::OpaqueWrapper< Opaque >::operator() (  )  const [inline]

Definition at line 115 of file Teuchos_OpaqueWrapper.hpp.


Friends And Related Function Documentation

template<class Opaque>
RCP< OpaqueWrapper< Opaque > > opaqueWrapper ( Opaque  opaque  )  [related]

Helper function created a new OpaqueWrapper object without a free function.

Definition at line 175 of file Teuchos_OpaqueWrapper.hpp.

template<class Opaque>
RCP< OpaqueWrapper< Opaque > > opaqueWrapper ( Opaque  opaque,
OpaqueFree  opaqueFree 
) [related]

Helper function created a new OpaqueWrapper object with a free function.

Definition at line 188 of file Teuchos_OpaqueWrapper.hpp.


The documentation for this class was generated from the following file:
Generated on Wed May 12 21:40:34 2010 for Teuchos - Trilinos Tools Package by  doxygen 1.4.7