scoped_array class templatescoped_array class templateThe scoped_array class template stores a pointer to a dynamically allocated -array. (Dynamically allocated arrays are allocated with the C++ new[] -expression.) The array pointed to is guaranteed to be deleted, -either on destruction of the scoped_array, or via an explicit reset.
- -The scoped_array template is a simple solution for simple -needs. It supplies a basic "resource acquisition is -initialization" facility, without shared-ownership or transfer-of-ownership -semantics. Both its name and enforcement of semantics (by being -noncopyable) -signal its intent to retain ownership solely within the current scope. -Because it is noncopyable, it is -safer than shared_array for pointers which should not be copied.
- -Because scoped_array is so simple, in its usual implementation -every operation is as fast as a built-in array pointer and it has no -more space overhead that a built-in array pointer.
- -It cannot be used in C++ standard library containers. -See shared_array -if scoped_array does not meet your needs.
- -It cannot correctly hold a pointer to a single object. -See scoped_ptr -for that usage.
- -A std::vector is an alternative to a scoped_array that is -a bit heavier duty but far more flexible. -A boost::array is an alternative that does not use dynamic allocation.
- -The class template is parameterized on T, the type of the object -pointed to. T must meet the smart pointer -common requirements.
- -namespace boost {
+
+ scoped_array
+
+
+
+ scoped_array
+ class template
+ The scoped_array class template stores a pointer to a dynamically
+ allocated array. (Dynamically allocated arrays are allocated with the C++ new[]
+ expression.) The array pointed to is guaranteed to be deleted, either on
+ destruction of the scoped_array, or via an explicit reset.
+ The scoped_array template is a simple solution for simple needs. It
+ supplies a basic "resource acquisition is initialization" facility, without
+ shared-ownership or transfer-of-ownership semantics. Both its name and
+ enforcement of semantics (by being
+ noncopyable) signal its intent to retain ownership solely within the
+ current scope. Because it is noncopyable,
+ it is safer than shared_array for pointers which should not be copied.
+ Because scoped_array is so simple, in its usual implementation every
+ operation is as fast as a built-in array pointer and it has no more space
+ overhead that a built-in array pointer.
+ It cannot be used in C++ standard library containers. See
+ shared_array if scoped_array does not meet your needs.
+ It cannot correctly hold a pointer to a single object. See scoped_ptr
+ for that usage.
+ A std::vector is an alternative to a scoped_array that is a bit
+ heavier duty but far more flexible. A boost::array is an alternative
+ that does not use dynamic allocation.
+ The class template is parameterized on T, the type of the object pointed
+ to. T must meet the smart pointer
+ common requirements.
+ Synopsis
+ namespace boost {
template<typename T> class scoped_array : noncopyable {
@@ -59,7 +44,7 @@ pointed to. T must meet the smart pointer
void reset(T * p = 0); // never throws
- T & operator[](std::size_t i) const; // never throws
+ T & operator[](std::ptrdiff_t i) const; // never throws
T * get() const; // never throws
void swap(scoped_array & b); // never throws
@@ -68,78 +53,59 @@ pointed to. T must meet the smart pointer
template<typename T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws
}
-
-Members
-
-
-element_type
-typedef T element_type;
-Provides the type of the stored pointer.
-
-constructors
-explicit scoped_array(T * p = 0); // never throws
-Constructs a scoped_array, storing a copy of p, which must
-have been allocated via a C++ new[] expression or be 0.
-T is not required be a complete type.
-See the smart pointer
-common requirements.
-
-destructor
-~scoped_array(); // never throws
-Deletes the array pointed to by the stored pointer.
-Note that delete[] on a pointer with a value of 0 is harmless.
-The guarantee that this does not throw exceptions depends on the requirement that the
-deleted array's objects' destructors do not throw exceptions.
-See the smart pointer common requirements.
-
-reset
-void reset(T * p = 0); // never throws
-If p is not equal to the stored pointer, deletes the array pointed to by the
-stored pointer and then stores a copy of p, which must have been allocated via a
-C++ new[] expression or be 0.
-The guarantee that this does not throw exceptions depends on the requirement that the
-deleted array's objects' destructors do not throw exceptions.
-See the smart pointer common requirements.
-
-subscripting
-T & operator[](std::size_t i) const; // never throws
-Returns a reference to element i of the array pointed to by the
-stored pointer.
-Behavior is undefined and almost certainly undesirable if the stored pointer is 0,
-or if i is less than 0 or is greater than or equal to the number of elements
-in the array.
-
-get
-T * get() const; // never throws
-Returns the stored pointer.
-T need not be a complete type.
-See the smart pointer
-common requirements.
-
-swap
-void swap(scoped_array & b); // never throws
-Exchanges the contents of the two smart pointers.
-T need not be a complete type.
-See the smart pointer
-common requirements.
-
-Free Functions
-
-swap
-template<typename T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws
-Equivalent to a.swap(b). Matches the interface of std::swap.
-Provided as an aid to generic programming.
-
-
-
-Revised 1 February 2002
-
-Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
-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.
-
-
-
+ Members
+
+ element_type
+ typedef T element_type;
+ Provides the type of the stored pointer.
+ constructors
+ explicit scoped_array(T * p = 0); // never throws
+ Constructs a scoped_array, storing a copy of p, which must have
+ been allocated via a C++ new[] expression or be 0. T is not
+ required be a complete type. See the smart pointer
+ common requirements.
+ destructor
+ ~scoped_array(); // never throws
+ Deletes the array pointed to by the stored pointer. Note that delete[] on
+ a pointer with a value of 0 is harmless. The guarantee that this does not throw
+ exceptions depends on the requirement that the deleted array's objects'
+ destructors do not throw exceptions. See the smart pointer
+ common requirements.
+ reset
+ void reset(T * p = 0); // never throws
+ If p is not equal to the stored pointer, deletes the array pointed to by the
+ stored pointer and then stores a copy of p, which must have been allocated via
+ a C++ new[] expression or be 0. The guarantee that this does not throw
+ exceptions depends on the requirement that the deleted array's objects'
+ destructors do not throw exceptions. See the smart pointer
+ common requirements.
+ subscripting
+ T & operator[](std::ptrdiff_t i) const; // never throws
+ Returns a reference to element i of the array pointed to by the stored
+ pointer. Behavior is undefined and almost certainly undesirable if the stored
+ pointer is 0, or if i is less than 0 or is greater than or equal to the
+ number of elements in the array.
+ get
+ T * get() const; // never throws
+ Returns the stored pointer. T need not be a complete type. See the smart
+ pointer common requirements.
+ swap
+ void swap(scoped_array & b); // never throws
+ Exchanges the contents of the two smart pointers. T need not be a
+ complete type. See the smart pointer common
+ requirements.
+ Free Functions
+ swap
+ template<typename T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws
+ Equivalent to a.swap(b). Matches the interface of std::swap.
+ Provided as an aid to generic programming.
+
+ Revised
+ 1 February 2002
+ Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
+ 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.
+
diff --git a/shared_array.htm b/shared_array.htm
index 3319553..7b904e9 100644
--- a/shared_array.htm
+++ b/shared_array.htm
@@ -1,47 +1,35 @@
-
-
-
-
-shared_array
-
-
-
-
-shared_array class template
-
-The shared_array class template stores a pointer to a dynamically allocated
-array. (Dynamically allocated array are allocated with the C++ new[]
-expression.) The object pointed to is guaranteed to be deleted when
-the last shared_array pointing to it is destroyed or reset.
-
-Every shared_array meets the CopyConstructible
-and Assignable requirements of the C++ Standard Library, and so
-can be used in standard library containers. Comparison operators
-are supplied so that shared_array works with
-the standard library's associative containers.
-
-Normally, a shared_array cannot correctly hold a pointer to a
-single dynamically allocated object. See shared_ptr
-for that usage.
-
-Because the implementation uses reference counting, shared_array will not work
-correctly with cyclic data structures. For example, if main() holds a shared_array
-to A, which directly or indirectly holds a shared_array back to A,
-A's use count will be 2. Destruction of the original shared_array
-will leave A dangling with a use count of 1.
-
-A shared_ptr to a std::vector is an alternative to a shared_array that is
-a bit heavier duty but far more flexible.
-
-The class template is parameterized on T, the type of the object
-pointed to. T must meet the smart pointer
-common requirements.
-
-Synopsis
-
-namespace boost {
+
+ shared_array
+
+
+
+ shared_array
+ class template
+ The shared_array class template stores a pointer to a dynamically
+ allocated array. (Dynamically allocated array are allocated with the C++ new[]
+ expression.) The object pointed to is guaranteed to be deleted when the last shared_array
+ pointing to it is destroyed or reset.
+ Every shared_array meets the CopyConstructible and Assignable
+ requirements of the C++ Standard Library, and so can be used in standard
+ library containers. Comparison operators are supplied so that shared_array
+ works with the standard library's associative containers.
+ Normally, a shared_array cannot correctly hold a pointer to a single
+ dynamically allocated object. See shared_ptr
+ for that usage.
+ Because the implementation uses reference counting, shared_array will not
+ work correctly with cyclic data structures. For example, if main() holds
+ a shared_array to A, which directly or indirectly holds a shared_array
+ back to A, A's use count will be 2. Destruction of the original shared_array
+ will leave A dangling with a use count of 1.
+ A shared_ptr to a std::vector is an alternative to a shared_array
+ that is a bit heavier duty but far more flexible.
+ The class template is parameterized on T, the type of the object pointed
+ to. T must meet the smart pointer
+ common requirements.
+ Synopsis
+ namespace boost {
template<typename T> class shared_array {
@@ -78,147 +66,114 @@ pointed to. T must meet the smart pointer
template<typename T> void swap(shared_array<T> & a, shared_array<T> & b); // never throws
}
-
-Members
-
-element_type
-typedef T element_type;
-Provides the type of the stored pointer.
-
-constructors
-
-explicit shared_array(T * p = 0);
-Constructs a shared_array, storing a copy of p, which
-must be a pointer to an array that was allocated via a C++ new[] expression or be 0.
-Afterwards, the use count is 1 (even if p == 0; see ~shared_array).
-The only exception which may be thrown by this constructor is std::bad_alloc.
-If an exception is thrown, delete[] p is called.
-
-template<typename D> shared_array(T * p, D d);
-Constructs a shared_array, storing a copy of p and of d.
-Afterwards, the use count is 1.
-D's copy constructor and destructor must not throw.
-When the the time comes to delete the array pointed to by p, the object
-d is used in the statement d(p). Invoking the object d with
-parameter p in this way must not throw.
-The only exception which may be thrown by this constructor is std::bad_alloc.
-If an exception is thrown, d(p) is called.
-
-shared_array(shared_array const & r); // never throws
-Constructs a shared_array, as if by storing a copy of the
-pointer stored in r. Afterwards, the use count
-for all copies is 1 more than the initial use count.
-
-destructor
-
-~shared_array(); // never throws
-Decrements the use count. Then, if the use count is 0,
-deletes the array pointed to by the stored pointer.
-Note that delete[] on a pointer with a value of 0 is harmless.
-T need not be a complete type.
-The guarantee that this does not throw exceptions depends on the requirement that the
-deleted object's destructor does not throw exceptions.
-See the smart pointer common requirements.
-
-assignment
-
-shared_array & operator=(shared_array const & r); // never throws
-Constructs a new shared_array as described above,
-then replaces this shared_array with the new one, destroying the replaced object.
-
-reset
-
-void reset(T * p = 0);
-Constructs a new shared_array as described above,
-then replaces this shared_array with the new one, destroying the replaced object.
-The only exception which may be thrown is std::bad_alloc. If
-an exception is thrown, delete[] p is called.
-
-template<typename D> void reset(T * p, D d);
-Constructs a new shared_array as described above,
-then replaces this shared_array with the new one, destroying the replaced object.
-D's copy constructor must not throw.
-The only exception which may be thrown is std::bad_alloc. If
-an exception is thrown, d(p) is called.
-
-indexing
-T & operator[](std::size_t i) const; // never throws
-Returns a reference to element i of the array pointed to by the stored pointer.
-Behavior is undefined and almost certainly undesirable if the stored pointer is 0,
-or if i is less than 0 or is greater than or equal to the number of elements
-in the array.
-
-get
-T * get() const; // never throws
-Returns the stored pointer.
-T need not be a complete type.
-See the smart pointer
-common requirements.
-
-unique
-bool unique() const; // never throws
-Returns true if no other shared_array is sharing ownership of
-the stored pointer, false otherwise.
-T need not be a complete type.
-See the smart pointer
-common requirements.
-
-use_count
-long use_count() const; // never throws
-Returns the number of shared_array objects sharing ownership of the
-stored pointer.
-T need not be a complete type.
-See the smart pointer
-common requirements.
-Because use_count is not necessarily efficient to implement for
-implementations of shared_array that do not use an explicit reference
-count, it might be removed from some future version. Thus it should
-be used for debugging purposes only, and not production code.
-
-swap
-void swap(shared_ptr & b); // never throws
-Exchanges the contents of the two smart pointers.
-T need not be a complete type.
-See the smart pointer
-common requirements.
-
-Free Functions
-
-comparison
-template<typename T>
+ Members
+ element_type
+ typedef T element_type;
+ Provides the type of the stored pointer.
+ constructors
+ explicit shared_array(T * p = 0);
+ Constructs a shared_array, storing a copy of p, which must be a
+ pointer to an array that was allocated via a C++ new[] expression or be
+ 0. Afterwards, the use count is 1 (even if p == 0; see
+ ~shared_array). The only exception which may be thrown by this
+ constructor is std::bad_alloc. If an exception is thrown, delete[] p
+ is called.
+ template<typename D> shared_array(T * p, D d);
+ Constructs a shared_array, storing a copy of p and of d.
+ Afterwards, the use count is 1. D's copy
+ constructor and destructor must not throw. When the the time comes to delete
+ the array pointed to by p, the object d is used in the statement d(p).
+ Invoking the object d with parameter p in this way must not
+ throw. The only exception which may be thrown by this constructor is std::bad_alloc.
+ If an exception is thrown, d(p) is called.
+ shared_array(shared_array const & r); // never throws
+ Constructs a shared_array, as if by storing a copy of the pointer stored
+ in r. Afterwards, the use count for all copies
+ is 1 more than the initial use count.
+ destructor
+ ~shared_array(); // never throws
+ Decrements the use count. Then, if the use count is 0,
+ deletes the array pointed to by the stored pointer. Note that delete[] on
+ a pointer with a value of 0 is harmless. T need not be a complete type.
+ The guarantee that this does not throw exceptions depends on the requirement
+ that the deleted object's destructor does not throw exceptions. See the smart
+ pointer common requirements.
+ assignment
+ shared_array & operator=(shared_array const & r); // never throws
+ Constructs a new shared_array as described above,
+ then replaces this shared_array with the new one, destroying the
+ replaced object.
+ reset
+ void reset(T * p = 0);
+ Constructs a new shared_array as described above,
+ then replaces this shared_array with the new one, destroying the
+ replaced object. The only exception which may be thrown is std::bad_alloc.
+ If an exception is thrown, delete[] p is called.
+ template<typename D> void reset(T * p, D d);
+ Constructs a new shared_array as described above,
+ then replaces this shared_array with the new one, destroying the
+ replaced object. D's copy constructor must not throw. The only exception
+ which may be thrown is std::bad_alloc. If an exception is thrown, d(p)
+ is called.
+ indexing
+ T & operator[](std::ptrdiff_t i) const; // never throws
+ Returns a reference to element i of the array pointed to by the stored
+ pointer. Behavior is undefined and almost certainly undesirable if the stored
+ pointer is 0, or if i is less than 0 or is greater than or equal to the
+ number of elements in the array.
+ get
+ T * get() const; // never throws
+ Returns the stored pointer. T need not be a complete type. See the smart
+ pointer common requirements.
+ unique
+ bool unique() const; // never throws
+ Returns true if no other shared_array is sharing ownership of the stored
+ pointer, false otherwise. T need not be a complete type. See the smart
+ pointer common requirements.
+ use_count
+ long use_count() const; // never throws
+ Returns the number of shared_array objects sharing ownership of the
+ stored pointer. T need not be a complete type. See the smart pointer
+ common requirements.
+ Because use_count is not necessarily efficient to implement for
+ implementations of shared_array that do not use an explicit reference
+ count, it might be removed from some future version. Thus it should be used for
+ debugging purposes only, and not production code.
+ swap
+ void swap(shared_ptr & b); // never throws
+ Exchanges the contents of the two smart pointers. T need not be a
+ complete type. See the smart pointer common
+ requirements.
+ Free Functions
+ comparison
+ template<typename T>
bool operator==(shared_array<T> const & a, shared_array<T> const & b); // never throws
template<typename T>
bool operator!=(shared_array<T> const & a, shared_array<T> const & b); // never throws
template<typename T>
bool operator<(shared_array<T> const & a, shared_array<T> const & b); // never throws
-Compares the stored pointers of the two smart pointers.
-T need not be a complete type.
-See the smart pointer
-common requirements.
-The operator< overload is provided to define an ordering so that shared_array
-objects can be used in associative containers such as std::map.
-The implementation uses std::less<T *> to perform the
-comparison. This ensures that the comparison is handled correctly, since the
-standard mandates that relational operations on pointers are unspecified (5.9 [expr.rel]
-paragraph 2) but std::less<> on pointers is well-defined (20.3.3 [lib.comparisons]
-paragraph 8).
-
-swap
-template<typename T>
+ Compares the stored pointers of the two smart pointers. T need not be a
+ complete type. See the smart pointer common
+ requirements.
+ The operator< overload is provided to define an ordering so that shared_array
+ objects can be used in associative containers such as std::map. The
+ implementation uses std::less<T *> to perform the comparison. This
+ ensures that the comparison is handled correctly, since the standard mandates
+ that relational operations on pointers are unspecified (5.9 [expr.rel]
+ paragraph 2) but std::less<> on pointers is well-defined (20.3.3
+ [lib.comparisons] paragraph 8).
+ swap
+ template<typename T>
void swap(shared_array<T> & a, shared_array<T> & b) // never throws
-Equivalent to a.swap(b). Matches the interface of std::swap.
-Provided as an aid to generic programming.
-
-
-
-Revised 8 February 2002
-
-Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
-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.
-
-
-
+ Equivalent to a.swap(b). Matches the interface of std::swap.
+ Provided as an aid to generic programming.
+
+ Revised
+ 8 February 2002
+ Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
+ 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.
+
diff --git a/shared_ptr.htm b/shared_ptr.htm
index 72c63f3..dce72c4 100644
--- a/shared_ptr.htm
+++ b/shared_ptr.htm
@@ -19,9 +19,9 @@
Smart Pointer Timings
Introduction
The shared_ptr class template stores a pointer to a dynamically allocated
- object. (Dynamically allocated objects are allocated with the C++ new expression.)
- The object pointed to is guaranteed to be deleted when the last shared_ptr
- pointing to it is destroyed or reset. See the example.
+ object, typically with a C++ new-expression . The object pointed to is
+ guaranteed to be deleted when the last shared_ptr pointing to it is
+ destroyed or reset. See the example.
Every shared_ptr meets the CopyConstructible and Assignable
requirements of the C++ Standard Library, and so can be used in standard
library containers. Comparison operators are supplied so that shared_ptr
@@ -29,11 +29,11 @@
Normally, a shared_ptr cannot correctly hold a pointer to a dynamically
allocated array. See shared_array for
that usage.
- Because the implementation uses reference counting, shared_ptr will not
- work correctly with cyclic data structures. For example, if main() holds
- a shared_ptr to A, which directly or indirectly holds a shared_ptr
- back to A, A's use count will be 2. Destruction of the original shared_ptr
- will leave A dangling with a use count of 1. Use weak_ptr
+
Because the implementation uses reference counting, cycles of shared_ptr instances
+ will not be reclaimed. For example, if main() holds a shared_ptr to
+ A, which directly or indirectly holds a shared_ptr back to A,
+ A's use count will be 2. Destruction of the original shared_ptr will
+ leave A dangling with a use count of 1. Use weak_ptr
to "break cycles."
The class template is parameterized on T, the type of the object pointed
to. shared_ptr and most of its member functions place no
@@ -148,10 +148,11 @@ void bad()
}
[It might be convenient to relax the requirements on shared_ptr's
- signature, allowing an additional, defaulted, template parameter. This would
- help in detecting possible ODR violations. On the other hand, using shared_ptr
- as an argument to a template template parameter requires an exact
- signature match.]
+ signature, allowing an additional, defaulted, template parameter; the parameter
+ can encode the threading model, for example. This would help in detecting
+ possible ODR violations. On the other hand, using shared_ptr as
+ an argument to a template template parameter requires an exact signature
+ match.]
Members
element_type
typedef T element_type;
@@ -229,16 +230,17 @@ void bad()
template<typename Y, typename D> shared_ptr(Y * p, D d);
Requirements: p must be convertible to T *. The copy
- constructor and destructor of D must not throw. The expression d(p)
- must be well-formed, must not invoke undefined behavior, and must not throw
- exceptions.
+ constructor and destructor of D must not throw. The expression d2(p),
+ where d2 is a copy of d, must be well-formed,
+ must not invoke undefined behavior, and must not throw exceptions.
Effects: Constructs a shared_ptr, storing a copy of p and d.
Postconditions: use count is 1.
Throws: std::bad_alloc.
Exception safety: If an exception is thrown, d(p) is called.
Notes: When the the time comes to delete the object pointed to by p,
- d(p) is invoked.
+ d2(p) is invoked, where d2 is the stored copy of
+ d.
[Custom deallocators allow a factory function returning a shared_ptr
to insulate the user from its memory allocation strategy. Since the deallocator
@@ -647,7 +649,7 @@ int * p = a.release();
implementation or a linked list implementation, or some other specific
implementation. This is not the intent.
- Revised
+
Revised
23 July 2002
Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
Copyright 2002 Peter Dimov. Permission to copy, use, modify, sell and