IMP  2.0.0
The Integrative Modeling Platform
IMP::base::Pointer< O > Struct Template Reference

A reference counted pointer to an object. More...

#include <IMP/base/Pointer.h>

+ Inheritance diagram for IMP::base::Pointer< O >:

Public Types

typedef internal::PointerBase
< internal::RefCountedPointerTraits
< O > > 
P
 

Public Member Functions

template<class Any >
 Pointer (const Any &o)
 
template<class OT >
Pointer< O > & operator= (const internal::PointerBase< OT > &o)
 
template<class OT >
Pointer< O > & operator= (OT *o)
 
Pointer< O > & operator= (nullptr_t o)
 
Pointer< O > & operator= (const P &o)
 

Detailed Description

template<class O>
struct IMP::base::Pointer< O >

Any time you store an Object in a C++ program, you should use a Pointer, rather than a raw C++ pointer. Using a pointer manages the reference counting and makes sure that the object is not deleted prematurely when, for example, all Python references go away and that it is deleted properly if an exception is thrown during the function. Use the IMP_NEW() macro to aid creation of pointers to new objects.

For example, when implementing a Restraint that uses a PairScore, store the PairScore like this:

Pointer<PairScore> ps_;

When creating Object instances in C++, you should write code like:

em::FitRestraint* create_fit_restraint(std::string mapname,
const ParticlesTemp &ps) {
IMP_NEW(core::LeavesRefiner, lr, (atom::Hierarchy::get_traits()));
IMP::Pointer<em::DensityMap> map= em::read_map("file_name.mrc");
IMP_NEW(em::FitRestraint, fr, (ps, map, lr));
return fr.release();
}

which is equivalent to

IMP::em::FitRestraint* create_fit_restraint(std::string mapname,
const ParticlesTemp &ps) {
Pointer<core::LeavesRefiner> lr
= new core::LeavesRefiner(atom::Hierarchy::get_traits());
IMP::Pointer<IMP::em::DensityMap> map
= em::read_map("file_name.mrc");
Pointer<em::FitRestraint> fr= new em::FitRestraint(ps, map, lr));
return fr.release();
}

There are several important things to note in this code:

  • the use of Pointer::release() on the return. Otherwise, when the reference counted pointer goes out of scope, it will unref the em::FitRestraint, notice the count is 0, and delete it, before passing the (now invalid) pointer back to the calling function
  • the use of reference counted pointers everywhere. This ensures that if, for example, em::read_map() throws an exception since the file name is invalid, the core::LeavesRefiner will be deleted properly.
Note
Do not pass Pointers as arguments to functions, pass raw C++ pointers instead.
Use an IMP::WeakPointer to break cycles or to point to non-ref-counted objects.
Parameters
[in]OThe type of IMP::RefCounted-derived object to point to

Definition at line 73 of file base/Pointer.h.


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