c++boost.gif (8819 bytes)intrusive_ptr class template

Introduction
Synopsis
Members
Free Functions

Introduction

intrusive_ptr クラステンプレートは、 埋め込まれた参照カウントを持つオブジェクトのポインタを保持する。 intrusive_ptr のインスタンスが新しく構築される度に、 無条件で呼び出すことのできる関数 intrusive_ptr_add_ref を使って参照カウントを増加させる。 intrusive_ptr_add_ref にはそのポインタを引数として渡す。 同様に、intrusive_ptr は破棄される時に intrusive_ptr_release を呼び出す。 intrusive_ptr_release は、その参照カウントが 0 になったときに保持しているオブジェクトを破棄する責任を持つ。 ユーザにはこれら二つの関数を適切に定義することが期待される。 argument-dependent lookup をサポートするコンパイラに於いては、 intrusive_ptr_add_refintrusive_ptr_release はそのパラメータが所属するのと同じ ネームスペースの中で定義されるべきである。 コンパイラが argument-dependent lookup をサポートしていない場合は、 ネームスペース boost の中で定義する必要がある。

このクラステンプレートには、指し示すオブジェクトの型を表すパラメータ T を与える。 T * が暗黙の型変換により U * に変換可能であれば、 intrusive_ptr<T> は暗黙に intrusive_ptr<U> に変換できる。

intrusive_ptr を使う最大の根拠 :

一般的な原則として、 用途に対して shared_ptr よりも intrusive_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);
      template<class Y> intrusive_ptr & operator=(T * r);

      T & operator*() const; // never throws
      T * operator->() const; // never throws
      T * get() const; // 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> 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

Postconditions: get() == 0.

Throws: 無し。

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

Effects: if(p != 0 && add_ref) intrusive_ptr_add_ref(p);.

Postconditions: get() == p.

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

Effects: if(r.get() != 0) intrusive_ptr_add_ref(r.get());.

Postconditions: get() == r.get().

destructor

~intrusive_ptr();

Effects: if(get() != 0) intrusive_ptr_release(get());.

assignment

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

Effects: intrusive_ptr(r).swap(*this) と等価。

Returns: *this.

indirection

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

Requirements: get() != 0.

Returns: *get().

Throws: 無し。

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

Requirements: get() != 0.

Returns: get().

Throws: 無し。

get

T * get() const; // never throws

Returns: the stored pointer.

Throws: 無し。

conversions

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

Returns: ブール式中で用いられたときに、 get() != 0 と等価な明示的ではない値を返す。

Throws: 無し。

Notes: この型変換演算子は intrusive_ptr オブジェクトを、 if (p && p->valid()) {} のようなブール式中で使えるようにするためのものである。 実際に対象となる型は通常メンバ関数へのポインタであり、 型変換の落とし穴を回避するために用いる。

swap

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

Effects: 二つのスマートポインタの中身を交換する。

Throws: 無し。

Free Functions

comparison

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

Returns: a.get() == b.get().

Throws: 無し。

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

Returns: a.get() != b.get().

Throws: 無し。

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

Returns: a.get() == b.

Throws: 無し。

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

Returns: a.get() != b.

Throws: 無し。

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

Returns: a == b.get().

Throws: 無し。

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

Returns: a != b.get().

Throws: 無し。

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

Returns: std::less<T *>()(a.get(), b.get()).

Throws: 無し。

Notes: Allows intrusive_ptr objects to be used as keys in associative containers.

swap

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

Effects: a.swap(b) と等価。

Throws: 無し。

Notes: std::swap のインターフェースとの一貫性を図り、 ジェネリックプログラミングを支援する。

get_pointer

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

Returns: p.get().

Throws: 無し。

Notes: ジェネリックプログラミングを支援するために提供される。 mem_fn を通して利用する。

static_pointer_cast

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

Returns: intrusive_ptr<T>(static_cast<T*>(r.get())).

Throws: 無し。

dynamic_pointer_cast

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

Returns: intrusive_ptr<T>(dynamic_cast<T*>(r.get())).

Throws: 無し。

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);

Effects: os << p.get();.

Returns: os ( 出力ストリーム )


Copyright (c) 2003 Peter Dimov. 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.

Japanese Translation Copyright (C) 2003 Ryo Kobayashi.
オリジナルの、及びこの著作権表示が全ての複製の中に現れる限り、この文書の 複製、利用、変更、販売そして配布を認める。このドキュメントは「あるがまま」 に提供されており、いかなる明示的、暗黙的保証も行わない。また、 いかなる目的に対しても、その利用が適していることを関知しない。