Boost C++ Libraries

boost::interprocess::intrusive_ptr is the generalization of boost::intrusive_ptr<> to allow non-raw pointers as intrusive pointer members. As the well-known boost::intrusive_ptr we must specify the pointee type but we also must also specify the pointer type to be stored in the intrusive_ptr:

//!The intrusive_ptr class template stores a pointer to an object
//!with an embedded reference count. intrusive_ptr is parameterized on
//!T (the type of the object pointed to) and VoidPointer(a void pointer type
//!that defines the type of pointer that intrusive_ptr will store).
//!intrusive_ptr<T, void *> defines a class with a T* member whereas
//!intrusive_ptr<T, offset_ptr<void> > defines a class with a offset_ptr<T> member.
//!Relies on unqualified calls to:
//!
//!void intrusive_ptr_add_ref(T * p);
//!void intrusive_ptr_release(T * p);
//!
//!with (p != 0)
//!
//!The object is responsible for destroying itself.
template<class T, class VoidPointer>
class intrusive_ptr;

So boost::interprocess::intrusive_ptr<MyClass, void*> is equivalent to boost::intrusive_ptr<MyClass>. But if we want to place the intrusive_ptr in shared memory we must specify a relative pointer type like boost::interprocess::intrusive_ptr<MyClass, boost::interprocess::offset_ptr<void> >

#include <boost/interprocess/managed_shared_memory.hpp>
#include <boost/interprocess/smart_ptr/intrusive_ptr.hpp>

using namespace boost::interprocess;

namespace N {

//A class that has an internal reference count
class reference_counted_class
{
   private:
   //Non-copyable
   reference_counted_class(const reference_counted_class  &);
   //Non-assignable
   reference_counted_class & operator=(const reference_counted_class &);
   //A typedef to save typing
   typedef managed_shared_memory::segment_manager segment_manager;
   //This is the reference count
   unsigned int m_use_count;
   //The segment manager allows deletion from shared memory segment
   offset_ptr<segment_manager> mp_segment_manager;

   public:
   //Constructor
   reference_counted_class(segment_manager *s_mngr)
   : m_use_count(0), mp_segment_manager(s_mngr){}
   //Destructor
   ~reference_counted_class(){}

   public:
   //Returns the reference count
   unsigned int use_count() const
   {  return m_use_count;   }

   //Adds a reference
   inline friend void intrusive_ptr_add_ref(reference_counted_class * p)
   {  ++p->m_use_count; }

   //Releases a reference
   inline friend void intrusive_ptr_release(reference_counted_class * p)
   {  if(--p->m_use_count == 0)  p->mp_segment_manager->destroy_ptr(p); }
};

}  //namespace N {

//A class that has an intrusive pointer to reference_counted_class
class intrusive_ptr_owner
{
   typedef intrusive_ptr<N::reference_counted_class,
                           offset_ptr<void> > intrusive_ptr_t;
   intrusive_ptr_t m_intrusive_ptr;

   public:
   //Takes a pointer to the reference counted class
   intrusive_ptr_owner(N::reference_counted_class *ptr)
      : m_intrusive_ptr(ptr){}
};

int main()
{
   //Remove shared memory on construction and destruction
   struct shm_remove
   {
      shm_remove() { shared_memory_object::remove("MySharedMemory"); }
      ~shm_remove(){ shared_memory_object::remove("MySharedMemory"); }
   } remover;

   //Create shared memory
   managed_shared_memory shmem(create_only, "MySharedMemory", 10000);

   //Create the unique reference counted object in shared memory
   N::reference_counted_class *ref_counted =
      shmem.construct<N::reference_counted_class>
         ("ref_counted")(shmem.get_segment_manager());

   //Create an array of ten intrusive pointer owners in shared memory
   intrusive_ptr_owner *intrusive_owner_array =
      shmem.construct<intrusive_ptr_owner>
         (anonymous_instance)[10](ref_counted);

   //Now test that reference count is ten
   if(ref_counted->use_count() != 10)
      return 1;

   //Now destroy the array of intrusive pointer owners
   //This should destroy every intrusive_ptr and because of
   //that reference_counted_class will be destroyed
   shmem.destroy_ptr(intrusive_owner_array);

   //Now the reference counted object should have been destroyed
   if(shmem.find<intrusive_ptr_owner>("ref_counted").first)
      return 1;
   //Success!
   return 0;
}

boost::interprocess::scoped_ptr<> is the big brother of boost::scoped_ptr<>, which adds a custom deleter to specify how the pointer passed to the scoped_ptr must be destroyed. Also, the pointer typedef of the deleter will specify the pointer type stored by scoped_ptr.

//!scoped_ptr stores a pointer to a dynamically allocated object.
//!The object pointed to is guaranteed to be deleted, either on destruction
//!of the scoped_ptr, or via an explicit reset. The user can avoid this
//!deletion using release().
//!scoped_ptr is parameterized on T (the type of the object pointed to) and
//!Deleter (the functor to be executed to delete the internal pointer).
//!The internal pointer will be of the same pointer type as typename
//!Deleter::pointer type (that is, if typename Deleter::pointer is
//!offset_ptr<void>, the internal pointer will be offset_ptr<T>).
template<class T, class Deleter>
class scoped_ptr;

scoped_ptr<> comes handy to implement rollbacks with exceptions: if an exception is thrown or we call return in the scope of scoped_ptr<> the deleter is automatically called so that the deleter can be considered as a rollback function. If all goes well, we call release() member function to avoid rollback when the scoped_ptr goes out of scope.

#include <boost/interprocess/managed_shared_memory.hpp>
#include <boost/interprocess/smart_ptr/scoped_ptr.hpp>

using namespace boost::interprocess;

class my_class
{};

class my_exception
{};

//A functor that destroys the shared memory object
template<class T>
class my_deleter
{
   private:
   //A typedef to save typing
   typedef managed_shared_memory::segment_manager segment_manager;
   //This my_deleter is created in the stack, not in shared memory,
   //so we can use raw pointers
   segment_manager *mp_segment_manager;

   public:
   //This typedef will specify the pointer type that
   //scoped_ptr will store
   typedef T *pointer;
   //Constructor
   my_deleter(segment_manager *s_mngr)
   : mp_segment_manager(s_mngr){}

   void operator()(pointer object_to_delete)
   {  mp_segment_manager->destroy_ptr(object_to_delete);  }
};

int main ()
{
   //Create shared memory
   //Remove shared memory on construction and destruction
   struct shm_remove
   {
      shm_remove() { shared_memory_object::remove("MySharedMemory"); }
      ~shm_remove(){ shared_memory_object::remove("MySharedMemory"); }
   } remover;

   managed_shared_memory shmem(create_only, "MySharedMemory", 10000);

   //In the first try, there will be no exceptions
   //in the second try we will throw an exception
   for(int i = 0; i < 2; ++i){
      //Create an object in shared memory
      my_class * my_object = shmem.construct<my_class>("my_object")();
      my_class * my_object2 = shmem.construct<my_class>(anonymous_instance)();
      shmem.destroy_ptr(my_object2);

      //Since the next shared memory allocation can throw
      //assign it to a scoped_ptr so that if an exception occurs
      //we destroy the object automatically
      my_deleter<my_class> d(shmem.get_segment_manager());

      BOOST_TRY{
         scoped_ptr<my_class, my_deleter<my_class> > s_ptr(my_object, d);
         //Let's emulate a exception capable operation
         //In the second try, throw an exception
         if(i == 1){
            throw(my_exception());
         }
         //If we have passed the dangerous zone
         //we can release the scoped pointer
         //to avoid destruction
         s_ptr.release();
      }
      BOOST_CATCH(const my_exception &){} BOOST_CATCH_END
      //Here, scoped_ptr is destroyed
      //so it we haven't thrown an exception
      //the object should be there, otherwise, destroyed
      if(i == 0){
         //Make sure the object is alive
         if(!shmem.find<my_class>("my_object").first){
            return 1;
         }
         //Now we can use it and delete it manually
         shmem.destroy<my_class>("my_object");
      }
      else{
         //Make sure the object has been deleted
         if(shmem.find<my_class>("my_object").first){
            return 1;
         }
      }
   }
   return 0;
}

Boost.Interprocess also offers the possibility of creating non-intrusive reference-counted objects in managed shared memory or mapped files.

Unlike boost::shared_ptr, due to limitations of mapped segments boost::interprocess::shared_ptr cannot take advantage of virtual functions to maintain the same shared pointer type while providing user-defined allocators and deleters. The allocator and the deleter are template parameters of the shared pointer.

Since the reference count and other auxiliary data needed by shared_ptr must be created also in the managed segment, and the deleter has to delete the object from the segment, the user must specify an allocator object and a deleter object when constructing a non-empty instance of shared_ptr, just like Boost.Interprocess containers need to pass allocators in their constructors.

Here is the declaration of shared_ptr:

template<class T, class VoidAllocator, class Deleter>
class shared_ptr;

With correctly specified parameters, Boost.Interprocess users can create objects in shared memory that hold shared pointers pointing to other objects also in shared memory, obtaining the benefits of reference counting. Let's see how to create a shared pointer in a managed shared memory:

#include <boost/interprocess/managed_shared_memory.hpp>
#include <boost/interprocess/smart_ptr/shared_ptr.hpp>
#include <boost/interprocess/allocators/allocator.hpp>
#include <boost/interprocess/smart_ptr/deleter.hpp>
#include <cassert>

using namespace boost::interprocess;

//This is type of the object we want to share
class MyType
{};

typedef managed_shared_memory::segment_manager segment_manager_type;
typedef allocator<void, segment_manager_type>  void_allocator_type;
typedef deleter<MyType, segment_manager_type>  deleter_type;
typedef shared_ptr<MyType, void_allocator_type, deleter_type> my_shared_ptr;

int main ()
{
   //Remove shared memory on construction and destruction
   struct shm_remove
   {
      shm_remove() { shared_memory_object::remove("MySharedMemory"); }
      ~shm_remove(){ shared_memory_object::remove("MySharedMemory"); }
   } remover;

   managed_shared_memory segment(create_only, "MySharedMemory", 4096);

   //Create a shared pointer in shared memory
   //pointing to a newly created object in the segment
   my_shared_ptr &shared_ptr_instance =
      *segment.construct<my_shared_ptr>("shared ptr")
         //Arguments to construct the shared pointer
         ( segment.construct<MyType>("object to share")()      //object to own
         , void_allocator_type(segment.get_segment_manager())  //allocator
         , deleter_type(segment.get_segment_manager())         //deleter
         );
   assert(shared_ptr_instance.use_count() == 1);

   //Destroy "shared ptr". "object to share" will be automatically destroyed
   segment.destroy_ptr(&shared_ptr_instance);

   return 0;
}

boost::interprocess::shared_ptr is very flexible and configurable (we can specify the allocator and the deleter, for example), but as shown the creation of a shared pointer in managed segments need too much typing.

To simplify this usage, boost::interprocess::shared_ptr header offers a shared pointer definition helper class (managed_shared_ptr) and a function (make_managed_shared_ptr) to easily construct a shared pointer from a type allocated in a managed segment with an allocator that will allocate the reference count also in the managed segment and a deleter that will erase the object from the segment.

These utilities will use a Boost.Interprocess allocator (boost::interprocess::allocator) and deleter (boost::interprocess::deleter) to do their job. The definition of the previous shared pointer could be simplified to the following:

typedef managed_shared_ptr<MyType, managed_shared_memory>::type my_shared_ptr;

And the creation of a shared pointer can be simplified to this:

my_shared_ptr sh_ptr = make_managed_shared_ptr
   (segment.construct<MyType>("object to share")(), segment);

Boost.Interprocess also offers a weak pointer named weak_ptr (with its corresponding managed_weak_ptr and make_managed_weak_ptr utilities) to implement non-owning observers of an object owned by shared_ptr.

Now let's see a detailed example of the use of shared_ptr: and weak_ptr

#include <boost/interprocess/managed_mapped_file.hpp>
#include <boost/interprocess/smart_ptr/shared_ptr.hpp>
#include <boost/interprocess/smart_ptr/weak_ptr.hpp>
#include <cassert>

using namespace boost::interprocess;

//This is type of the object we want to share
struct type_to_share
{};

//This is the type of a shared pointer to the previous type
//that will be built in the mapped file
typedef managed_shared_ptr<type_to_share, managed_mapped_file>::type shared_ptr_type;
typedef managed_weak_ptr<type_to_share, managed_mapped_file>::type   weak_ptr_type;

//This is a type holding a shared pointer
struct shared_ptr_owner
{
   shared_ptr_owner(const shared_ptr_type &other_shared_ptr)
      : shared_ptr_(other_shared_ptr)
   {}

   shared_ptr_owner(const shared_ptr_owner &other_owner)
      : shared_ptr_(other_owner.shared_ptr_)
   {}

   shared_ptr_type shared_ptr_;
   //...
};

int main ()
{
   //Define file names
   const char *MappedFile  = "MyMappedFile";

   //Destroy any previous file with the name to be used.
   struct file_remove
   {
      file_remove(const char *MappedFile)
         : MappedFile_(MappedFile) { file_mapping::remove(MappedFile_); }
      ~file_remove(){ file_mapping::remove(MappedFile_); }
      const char *MappedFile_;
   } remover(MappedFile);
   {
      managed_mapped_file file(create_only, MappedFile, 65536);

      //Construct the shared type in the file and
      //pass ownership to this local shared pointer
      shared_ptr_type local_shared_ptr = make_managed_shared_ptr
         (file.construct<type_to_share>("object to share")(), file);
      assert(local_shared_ptr.use_count() == 1);

      //Share ownership of the object between local_shared_ptr and a new "owner1"
      shared_ptr_owner *owner1 =
         file.construct<shared_ptr_owner>("owner1")(local_shared_ptr);
      assert(local_shared_ptr.use_count() == 2);

      //local_shared_ptr releases object ownership
      local_shared_ptr.reset();
      assert(local_shared_ptr.use_count() == 0);
      assert(owner1->shared_ptr_.use_count() == 1);

      //Share ownership of the object between "owner1" and a new "owner2"
      shared_ptr_owner *owner2 =
         file.construct<shared_ptr_owner>("owner2")(*owner1);
      assert(owner1->shared_ptr_.use_count() == 2);
      assert(owner2->shared_ptr_.use_count() == 2);
      assert(owner1->shared_ptr_.get() == owner2->shared_ptr_.get());
      //The mapped file is unmapped here. Objects have been flushed to disk
   }
   {
      //Reopen the mapped file and find again all owners
      managed_mapped_file file(open_only, MappedFile);

      shared_ptr_owner *owner1 = file.find<shared_ptr_owner>("owner1").first;
      shared_ptr_owner *owner2 = file.find<shared_ptr_owner>("owner2").first;
      assert(owner1 && owner2);

      //Check everything is as expected
      assert(file.find<type_to_share>("object to share").first != 0);
      assert(owner1->shared_ptr_.use_count() == 2);
      assert(owner2->shared_ptr_.use_count() == 2);
      assert(owner1->shared_ptr_.get() == owner2->shared_ptr_.get());

      //Now destroy one of the owners, the reference count drops.
      file.destroy_ptr(owner1);
      assert(owner2->shared_ptr_.use_count() == 1);

      //Create a weak pointer
      weak_ptr_type local_observer1(owner2->shared_ptr_);
      assert(local_observer1.use_count() == owner2->shared_ptr_.use_count());

      {  //Create a local shared pointer from the weak pointer
      shared_ptr_type local_shared_ptr = local_observer1.lock();
      assert(local_observer1.use_count() == owner2->shared_ptr_.use_count());
      assert(local_observer1.use_count() == 2);
      }

      //Now destroy the remaining owner. "object to share" will be destroyed
      file.destroy_ptr(owner2);
      assert(file.find<type_to_share>("object to share").first == 0);

      //Test observer
      assert(local_observer1.expired());
      assert(local_observer1.use_count() == 0);

      //The reference count will be deallocated when all weak pointers
      //disappear. After that, the file is unmapped.
   }
   return 0;
}

In general, using Boost.Interprocess' shared_ptr and weak_ptr is very similar to their counterparts boost::shared_ptr and boost::weak_ptr, but they need more template parameters and more run-time parameters in their constructors.

Just like boost::shared_ptr can be stored in a STL container, shared_ptr can also be stored in Boost.Interprocess containers.

If a programmer just uses shared_ptr to be able to insert dynamically constructed objects into a container constructed in the managed segment, but he does not need to share the ownership of that object with other objects managed_unique_ptr is a much faster and easier to use alternative.

Unique ownership smart pointers are really useful to free programmers from manual resource liberation of non-shared objects. Boost.Interprocess' unique_ptr is much like scoped_ptr but it's moveable and can be easily inserted in Boost.Interprocess containers. Interprocess had its own unique_ptr implementation but from Boost 1.57, Boost.Interprocess uses the improved and generic boost::unique_ptr implementation. Here is the declaration of the unique pointer class:

template <class T, class D>
class unique_ptr;

unique_ptr can release the ownership of the stored pointer so it's useful also to be used as a rollback function. One of the main properties of the class is that is not copyable, but only moveable. When a unique pointer is moved to another one, the ownership of the pointer is transferred from the source unique pointer to the target unique pointer. If the target unique pointer owned an object, that object is first deleted before taking ownership of the new object.

Boost.Interprocess also offers auxiliary types to easily define and construct unique pointers that can be placed in managed segments and will correctly delete owned object from the segment: managed_unique_ptr and make_managed_unique_ptr utilities.

Here we see an example of the use unique_ptr including creating containers of such objects:

#include <boost/interprocess/managed_mapped_file.hpp>
#include <boost/interprocess/smart_ptr/unique_ptr.hpp>
#include <boost/interprocess/containers/vector.hpp>
#include <boost/interprocess/containers/list.hpp>
#include <boost/interprocess/allocators/allocator.hpp>
#include <cassert>

using namespace boost::interprocess;

//This is type of the object we'll allocate dynamically
struct MyType
{
   MyType(int number = 0)
      :  number_(number)
   {}
   int number_;
};

//This is the type of a unique pointer to the previous type
//that will be built in the mapped file
typedef managed_unique_ptr<MyType, managed_mapped_file>::type unique_ptr_type;

//Define containers of unique pointer. Unique pointer simplifies object management
typedef vector
   < unique_ptr_type
   , allocator<unique_ptr_type, managed_mapped_file::segment_manager>
   > unique_ptr_vector_t;

typedef list
   < unique_ptr_type
   , allocator<unique_ptr_type, managed_mapped_file::segment_manager>
   > unique_ptr_list_t;

int main ()
{
   //Define file names
   const char *MappedFile  = "MyMappedFile";

   //Destroy any previous file with the name to be used.
   struct file_remove
   {
      file_remove(const char *MappedFile)
         : MappedFile_(MappedFile) { file_mapping::remove(MappedFile_); }
      ~file_remove(){ file_mapping::remove(MappedFile_); }
      const char *MappedFile_;
   } remover(MappedFile);
   {
      managed_mapped_file file(create_only, MappedFile, 65536);

      //Construct an object in the file and
      //pass ownership to this local unique pointer
      unique_ptr_type local_unique_ptr (make_managed_unique_ptr
         (file.construct<MyType>("unique object")(), file));
      assert(local_unique_ptr.get() != 0);

      //Reset the unique pointer. The object is automatically destroyed
      local_unique_ptr.reset();
      assert(file.find<MyType>("unique object").first == 0);

      //Now create a vector of unique pointers
      unique_ptr_vector_t *unique_vector =
         file.construct<unique_ptr_vector_t>("unique vector")(file.get_segment_manager());

      //Speed optimization
      unique_vector->reserve(100);

      //Now insert all values
      for(int i = 0; i < 100; ++i){
         unique_ptr_type p(make_managed_unique_ptr(file.construct<MyType>(anonymous_instance)(i), file));
         unique_vector->push_back(boost::move(p));
         assert(unique_vector->back()->number_ == i);
      }

      //Now create a list of unique pointers
      unique_ptr_list_t *unique_list =
         file.construct<unique_ptr_list_t>("unique list")(file.get_segment_manager());

      //Pass ownership of all values to the list
      for(int i = 99; !unique_vector->empty(); --i){
         unique_list->push_front(boost::move(unique_vector->back()));
         //The unique ptr of the vector is now empty...
         assert(unique_vector->back() == 0);
         unique_vector->pop_back();
         //...and the list has taken ownership of the value
         assert(unique_list->front() != 0);
         assert(unique_list->front()->number_ == i);
      }
      assert(unique_list->size() == 100);

      //Now destroy the empty vector.
      file.destroy_ptr(unique_vector);
      //The mapped file is unmapped here. Objects have been flushed to disk
   }
   {
      //Reopen the mapped file and find again the list
      managed_mapped_file file(open_only, MappedFile);

      unique_ptr_list_t   *unique_list =
         file.find<unique_ptr_list_t>("unique list").first;
      assert(unique_list);
      assert(unique_list->size() == 100);

      unique_ptr_list_t::const_iterator list_it = unique_list->begin();
      for(int i = 0; i < 100; ++i, ++list_it){
         assert((*list_it)->number_ == i);
      }

      //Now destroy the list. All elements will be automatically deallocated.
      file.destroy_ptr(unique_list);
   }
   return 0;
}