intrusive_ptr_object helpers

Go to the Boost-Extra Documentation Page.

Summary

Introduction

The boost::intrusive_ptr template is useful to handle objects with a reference count, but it does not offer any helper functions to create the reference counted objects.

The intrusive_ptr_object helpers try to offer such support.

Usage

To create an object which is reference counted:

Advantages of these Classes

You can create two different types of objects: a stack or composition object (as usual) or a heap object. A heap object can be referenced, the others cannot and you get an error at runtime.

You can pass a bare pointer of MyClass to other objects and they still can keep a reference by dynamically casting to the intrusive_ptr_object part of the object.

Synopsis

  namespace boost
  {
    class intrusive_ptr_object
    {
    public:
      intrusive_ptr_object() throw();
      virtual ~intrusive_ptr_object() = 0;
    
      void add_ref();
      void release();
    };

    class intrusive_ptr_base
    {
    public:
      virtual ~intrusive_ptr_base() = 0;
    };

    inline void intrusive_ptr_add_ref(intrusive_ptr_base *a);
    inline void intrusive_ptr_release(intrusive_ptr_base *a);

    template<class T> class intrusive_ptr_heap;
  }

Members

  intrusive_ptr_object

intrusive_ptr_object();

Postconditions: reference is zero (0)

Throws: nothing

~intrusive_ptr_object();

Preconditions: reference must be zero (0)

Throws: assertion if reference is not zero

add_ref();

Postconditions: reference is one more

Throws: nothing

Thread: this function is thread safe

release();

Effects: reference is one less

Postconditions: if the reference reached zero (0), the object is deleted

Throws: an assertion if the reference count is zero (0) on entry

Thread: this function is thread safe

  intrusive_ptr_base

~intrusive_ptr_base();

Effects: none

Throws: an assertion if the reference count is zero (0) on entry

  Helper functions

void intrusive_ptr_add_ref(intrusive_ptr_base *a);
void intrusive_ptr_release(intrusive_ptr_base *a);

Effects: calls the corresponding function of the intrusive_ptr_object

Note: these functions are implementation details but they still need to be defined publicly for the intrusive_ptr implementation to be capable to find them.

  Helper template

template<class T> class intrusive_ptr_heap;

Usage: create typedef's of a new classes derived from T and intrusive_ptr_object.

Note: this template will fail if class T has constructors with parameters.


Copyright (c) 2006 Alexis Wilke and Doug Barbieri

Permission to copy, use, modify, sell and distribute this document is granted provided
this copyright notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability for any purpose.