intrusive_ptr

Boost , ,

intrusive_ptr class template

Введение
Синопсис
Члены
Свободные функции

Introduction

Шаблон класса<intrusive_ptr>хранит указатель на объект со встроенным счетчиком ссылок. Каждый новый<intrusive_ptr>экземпляр увеличивает количество ссылок, используя неквалифицированный вызов функции<intrusive_ptr_add_ref>, передавая ей указатель в качестве аргумента. Точно так же, когда<intrusive_ptr>разрушается, он вызывает<intrusive_ptr_release>; эта функция отвечает за разрушение объекта, когда его количество ссылок падает до нуля. Ожидается, что пользователь предоставит соответствующие определения этих двух функций. На компиляторах, поддерживающих аргументно-зависимый поиск,<intrusive_ptr_add_ref>и<intrusive_ptr_release>должны быть определены в пространстве имен, соответствующем их параметру; в противном случае определения должны идти в пространстве имен<boost>. Библиотека предоставляет шаблон базового класса помощника<intrusive_ref_counter>, который может помочь добавить поддержку<intrusive_ptr>к типам пользователей.

Шаблон класса параметризован на<T>, тип объекта, на который указывается.<intrusive_ptr<T>>может быть неявно преобразован в<intrusive_ptr<U>>, когда<T*>может быть неявно преобразован в<U*>.

Основные причины использования<intrusive_ptr>:

• Некоторые существующие фреймворки или ОС предоставляют объектам встроенные ссылки;
• Отпечаток памятиintrusive_ptrтакой же, как и соответствующий необработанный указатель;
• intrusive_ptr<T>может быть построен из произвольного исходного указателя типаT *.

Как правило, если не очевидно, что<intrusive_ptr>лучше соответствует вашим потребностям, чем<shared_ptr>, сначала попробуйте<shared_ptr>-ориентированный дизайн.

Synopsis

namespace boost {
  template<class T> class intrusive_ptr {
    public:
      typedef T element_type;
      intrusive_ptr(); // never throws
      intrusive_ptr(T * p, bool add_ref = true);
      intrusive_ptr(intrusive_ptr const & r);
      template<class Y> intrusive_ptr(intrusive_ptr<Y> const & r);
      ~intrusive_ptr();
      intrusive_ptr & operator=(intrusive_ptr const & r);
      template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> const & r);
      intrusive_ptr & operator=(T * r);
      void reset();
      void reset(T * r);
      void reset(T * r, bool add_ref);
      T & operator*() const; // never throws
      T * operator->() const; // never throws
      T * get() const; // never throws
      T * detach(); // never throws
      operator unspecified-bool-type() const; // never throws
      void swap(intrusive_ptr & b); // never throws
  };
  template<class T, class U>
    bool operator==(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws
  template<class T, class U>
    bool operator!=(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws
  template<class T>
    bool operator==(intrusive_ptr<T> const & a, T * b); // never throws
  template<class T>
    bool operator!=(intrusive_ptr<T> const & a, T * b); // never throws
  template<class T>
    bool operator==(T * a, intrusive_ptr<T> const & b); // never throws
  template<class T>
    bool operator!=(T * a, intrusive_ptr<T> const & b); // never throws
  template<class T, class U>
    bool operator<(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws
  template<class T> void swap(intrusive_ptr<T> & a, intrusive_ptr<T> & b); // never throws
  template<class T> T * get_pointer(intrusive_ptr<T> const & p); // never throws
  template<class T, class U>
    intrusive_ptr<T> static_pointer_cast(intrusive_ptr<U> const & r); // never throws
  template<class T, class U>
    intrusive_ptr<T> const_pointer_cast(intrusive_ptr<U> const & r); // never throws
  template<class T, class U>
    intrusive_ptr<T> dynamic_pointer_cast(intrusive_ptr<U> const & r); // never throws
  template<class E, class T, class Y>
    std::basic_ostream<E, T> & operator<< (std::basic_ostream<E, T> & os, intrusive_ptr<Y> const & p);
}

Members

element_type

typedef T element_type;

Предоставляет тип шаблонного параметра<T>.

constructors

intrusive_ptr(); // never throws

Пост-условия:<get() == 0>.

Бросает:ничего.

intrusive_ptr(T * p, bool add_ref = true);

Эффекты:<if(p != 0 && add_ref) intrusive_ptr_add_ref(p);>.

Постусловия:<get() == p>.

intrusive_ptr(intrusive_ptr const & r);
template<class Y> intrusive_ptr(intrusive_ptr<Y> const & r);

Эффекты:<if(r.get() != 0) intrusive_ptr_add_ref(r.get());>.

Постусловия:<get() == r.get()>.

destructor

~intrusive_ptr();

Эффекты:<if(get() != 0) intrusive_ptr_release(get());>.

assignment

intrusive_ptr & operator=(intrusive_ptr const & r);
template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> const & r);
intrusive_ptr & operator=(T * r);

Эффектыэквивалентны<intrusive_ptr(r).swap(*this)>.

Возвращение:<*this>.

reset

void reset();

Эффекты:Эквивалентно<intrusive_ptr().swap(*this)>.

void reset(T * r);

Эффектыэквивалентны<intrusive_ptr(r).swap(*this)>.

void reset(T * r, bool add_ref);

Эффекты:Эквивалент<intrusive_ptr(r, add_ref).swap(*this)>.

indirection

T & operator*() const; // never throws

Требования:<get() != 0>.

Возвращение:<*get()>.

Бросает:ничего.

T * operator->() const; // never throws

Требования:<get() != 0>.

Возвращение:<get()>.

Бросает:ничего.

get

T * get() const; // never throws

Возврат:хранимый указатель.

Бросает:ничего.

detach

T * detach(); // never throws

Возврат:хранимый указатель.

Бросает:ничего.

Пост-условия:<get() == 0>.

Примечания:Возвращенный указатель имеет повышенное количество ссылок. Это позволяет конвертировать<intrusive_ptr>обратно в необработанный указатель, без накладных расходов на производительность при приобретении и сбросе дополнительной ссылки. Его можно рассматривать как дополнение нессылочного конструктора.

Осторожность:Использование<detach>исключает безопасность автоматического подсчета ссылок, предоставляемого<intrusive_ptr>. Он должен использоваться только там, где это строго необходимо (например, при взаимодействии с существующим API) и когда последствия полностью понятны.

conversions

operator unspecified-bool-type () const; // never throws

Возврат:неопределенное значение, которое при использовании в булевом контексте эквивалентно<get() != 0>.

Бросает:ничего.

Примечания:Этот оператор преобразования позволяет использовать<intrusive_ptr>объекты в булевом контексте, например<if (p && p->valid()) {}>. Фактический целевой тип обычно указывает на функцию члена, избегая многих неявных ошибок преобразования.

swap

void swap(intrusive_ptr & b); // never throws

Эффекты:Обменяется содержанием двух умных указателей.

Бросает:ничего.

Free Functions

comparison

template<class T, class U>
  bool operator==(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws

Возвращение:<a.get() == b.get()>.

Бросает:ничего.

template<class T, class U>
  bool operator!=(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws

Возвращение:<a.get() != b.get()>.

Бросает:ничего.

template<class T, class U>
  bool operator==(intrusive_ptr<T> const & a, U * b); // never throws

Возвращение:<a.get() == b>.

Бросает:ничего.

template<class T, class U>
  bool operator!=(intrusive_ptr<T> const & a, U * b); // never throws

Возвращение:<a.get() != b>.

Бросает:ничего.

template<class T, class U>
  bool operator==(T * a, intrusive_ptr<U> const & b); // never throws

Возвращение:<a == b.get()>.

Бросает:ничего.

template<class T, class U>
  bool operator!=(T * a, intrusive_ptr<U> const & b); // never throws

Возвращение:<a != b.get()>.

Бросает:ничего.

template<class T, class U>
  bool operator<(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws

Возвращение:<std::less<T *>()(a.get(), b.get())>.

Бросает:ничего.

Примечания:Позволяет использовать<intrusive_ptr>объектов в качестве ключей в ассоциативных контейнерах.

swap

template<class T>
  void swap(intrusive_ptr<T> & a, intrusive_ptr<T> & b); // never throws

Эффекты:эквивалентно<a.swap(b)>.

Бросает:ничего.

Примечания:Соответствует интерфейсу<std::swap>. Предоставляется в качестве помощи для общего программирования.

get_pointer

template<class T>
  T * get_pointer(intrusive_ptr<T> const & p); // never throws

Возвращение:<p.get()>.

Бросает:ничего.

Примечания:Предоставляется в качестве вспомогательного средства для общего программирования. Используетсяmem_fn.

static_pointer_cast

template<class T, class U>
  intrusive_ptr<T> static_pointer_cast(intrusive_ptr<U> const & r); // never throws

Возвращение:<intrusive_ptr<T>(static_cast<T*>(r.get()))>.

Бросает:ничего.

const_pointer_cast

template<class T, class U>
  intrusive_ptr<T> const_pointer_cast(intrusive_ptr<U> const & r); // never throws

Возвращение:<intrusive_ptr<T>(const_cast<T*>(r.get()))>.

Бросает:ничего.

dynamic_pointer_cast

template<class T, class U>
  intrusive_ptr<T> dynamic_pointer_cast(intrusive_ptr<U> const & r);

Возвращение:<intrusive_ptr<T>(dynamic_cast<T*>(r.get()))>.

Бросает:ничего.

operator<<

template<class E, class T, class Y>
    std::basic_ostream<E, T> & operator<< (std::basic_ostream<E, T> & os, intrusive_ptr<Y> const & p);

Эффекты:<os << p.get();>.

Возвращение:<os>.

$Date$

<маленький>Копирайт &копия; 2003-2005, 2013 Питер Димов. Distributed under the Boost Software License, Version 1.0. См. сопроводительный файл LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt.[ORIG_END] -->

Статья intrusive_ptr раздела может быть полезна для разработчиков на c++ и boost.

:: Главная :: ::