Ticket #1897: shared_ptr.htm.patch

shared_ptr.htm

@@ -146 +146 @@
   template<class T, class U>
     bool <A href="#comparison" >operator&lt;</A>(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws
 
+  template&lt;class T, class... Args&gt;
+    shared_ptr&lt;T&gt; <a href="#object_creation">make_shared</a>( Args &amp;&amp; ... args );
+
+  template&lt;class T, class A, class... Args&gt;
+    shared_ptr&lt;T&gt; <a href="#object_creation">allocate_shared</a>( A const &amp; a, Args &amp;&amp; ... args );
+
   template&lt;class T&gt; void <A href="#free-swap" >swap</A>(shared_ptr&lt;T&gt; &amp; a, shared_ptr&lt;T&gt; &amp; b); // never throws
 
   template&lt;class T&gt; T * <A href="#get_pointer" >get_pointer</A>(shared_ptr&lt;T&gt; const &amp; p); // never throws
@@ -437 +443 @@
                                 also implement their <STRONG>operator&lt;</STRONG> in terms of their contained 
                                 subobjects' <STRONG>operator&lt;</STRONG>.</EM></P>
                 <P><EM>The rest of the comparison operators are omitted by design.]</EM></P>
+                <h3><a name="object_creation">object creation</a></h3>
+                <pre>template&lt;class T, class... Args&gt;
+    shared_ptr&lt;T&gt; make_shared( Args &amp;&amp; ... args );
+template&lt;class T, class A, class... Args&gt;
+    shared_ptr&lt;T&gt; allocate_shared( A const &amp; a, Args &amp;&amp; ... args );</pre>
+                <blockquote>
+                        <p><b>Requires:</b> The expression <code>new( pv ) T( std::forward&lt;Args&gt;(args)... )</code>,
+                                where <code>pv</code> is a <code>void*</code> pointing to storage suitable
+                                to hold an object of type <code>T</code>,
+                                shall be well-formed.  <code>A</code> shall be an <em>Allocator</em>,
+                                as described in section 20.1.5 (<stong>Allocator requirements</strong>) of the C++ Standard.
+                                The copy constructor and destructor of <code>A</code> shall not throw.</p>
+                        <p><b>Effects:</b> Allocates memory suitable for an object of type <code>T</code>
+                                and constructs an object in it via the placement new expression <code>new( pv ) T()</code>
+                                or <code>new( pv ) T( std::forward&lt;Args&gt;(args)... )</code>.
+                                <code>allocate_shared</code> uses a copy of <code>a</code> to allocate memory.
+                                If an exception is thrown, has no effect.</p>
+                        <p><b>Returns:</b> A <code>shared_ptr</code> instance that stores and owns the address
+                                of the newly constructed object of type <code>T</code>.</p>
+                        <p><b>Postconditions:</b> <code>get() != 0 &amp;&amp; use_count() == 1</code>.</p>
+                        <p><b>Throws:</b> <code>bad_alloc</code>, or an exception thrown from <code>A::allocate</code>
+                                or the constructor of <code>T</code>.</p>
+                        <p><b>Notes:</b> This implementation allocates the memory required for the
+                        returned <code>shared_ptr</code> and an object of type <code>T</code> in a single
+                        allocation. This provides efficiency equivalent to an intrusive smart pointer.</p>
+                        <p>The prototypes shown above are used if your compiler supports rvalue references
+                        and variadic templates.  They perfectly forward the <code>args</code> parameters to
+                        the constructors of <code>T</code>.</p>
+                        <p>Otherwise, the implementation will fall back on
+                        forwarding the arguments to the constructors of <code>T</code> as const references.
+                        If you need to pass a non-const reference to a constructor of <code>T</code>,
+                        you may do so by wrapping the parameter in a call to <code>boost::ref</code>.
+                        In addition, you will be
+                        limited to a maximum of 9 arguments (not counting the allocator argument of
+                        allocate_shared).</p>
+                </blockquote>
                 <h3><a name="free-swap">swap</a></h3>
                 <pre>template&lt;class T&gt;
   void swap(shared_ptr&lt;T&gt; &amp; a, shared_ptr&lt;T&gt; &amp; b); // never throws</pre>