1 files changed, 118 insertions, 3 deletions
diff --git a/documentation/cxx/hybrid/guide/index.xhtml b/documentation/cxx/hybrid/guide/index.xhtml
index 3d414ce..460e3b2 100644
--- a/documentation/cxx/hybrid/guide/index.xhtml
+++ b/documentation/cxx/hybrid/guide/index.xhtml
@@ -232,6 +232,7 @@
 	  <tr><th>3.5</th><td><a href="#3.5">64-bit Integer Type</a></td></tr>
           <tr><th>3.6</th><td><a href="#3.6">Parser and Serializer Reuse</a></td></tr>
 	  <tr><th>3.7</th><td><a href="#3.7">Support for Polymorphism</a></td></tr>
+	  <tr><th>3.8</th><td><a href="#3.8">Custom Allocators</a></td></tr>
         </table>
       </td>
     </tr>
@@ -1562,6 +1563,118 @@ $ xsde cxx-hybrid --generate-parser --generate-serializer \
   <p>For information on how to use object models with polymorphic types,
      refer to <a href="#4.10">Section 4.10, "Polymorphic Object Models"</a>.</p>
 
+  <h2><a name="3.8">3.8 Custom Allocators</a></h2>
+
+  <p>By default the XSD/e runtime and generated code use
+     the standard operators <code>new</code> and <code>delete</code>
+     to manage dynamic memory. However, it is possible to instead
+     use custom allocator functions provided by your application.
+     To achieve this, configure the XSD/e runtime library to use
+     custom allocator functions as well as pass the
+     <code>--custom-allocator</code> option to the XSD/e compiler
+     when translating your schemas. The signatures of the custom
+     allocator functions that should be provided by your application
+     are listed below. Their semantics should be equivalent to the
+     standard C <code>malloc()</code>, <code>realloc()</code>, and
+     <code>free()</code> functions.</p>
+
+  <pre class="c++">
+extern "C" void*
+xsde_alloc (size_t);
+
+extern "C" void*
+xsde_realloc (void*, size_t);
+
+extern "C" void
+xsde_free (void*);
+  </pre>
+
+  <p>Note also that when custom allocators are enabled, any
+     dynamically-allocated object of which the XSD/e runtime
+     or generated code assume ownership should be allocated
+     using the custom allocation function. Similarly, if your
+     application assumes ownership of any dynamically-allocated
+     object returned by the XSD/e runtime or the generated code,
+     then such an object should be disposed of using the custom
+     deallocation function. To help with these tasks the generated
+     <code>xml_schema</code> namespace defines the following two
+     helper functions and, if C++ exceptions are enabled, automatic
+     pointer class:</p>
+
+  <pre class="c++">
+namespace xml_schema
+{
+  void*
+  alloc (size_t);
+
+  void
+  free (void*);
+
+  struct alloc_guard
+  {
+    alloc_guard (void*);
+    ~alloc_guard ();
+
+    void*
+    get () const;
+
+    void
+    release ();
+
+  private:
+    ...
+  };
+}
+  </pre>
+
+  <p>If C++ exceptions are disabled, these functions are equivalent
+     to <code>xsde_alloc()</code> and <code>xsde_free()</code>.
+     If exceptions are enabled, <code>xml_schema::alloc()</code>
+     throws <code>std::bad_alloc</code> on memory allocation failure.</p>
+
+  <p>The following code fragment shows how to create and destroy a
+     dynamically-allocated object with custom allocators when C++
+     exceptions are disabled:</p>
+
+  <pre class="c++">
+void* v = xml_schema::alloc (sizeof (type));
+
+if (v == 0)
+{
+  // Handle out of memory condition.
+}
+
+type* x = new (v) type (1, 2);
+
+...
+
+if (x)
+{
+  x->~type ();
+  xml_schema::free (x);
+}
+  </pre>
+
+  <p>The equivalent code fragment for configurations with C++ exceptions
+     enabled is shown below:</p>
+
+  <pre class="c++">
+xml_schema::alloc_guard g (xml_schema::alloc (sizeof (type)));
+type* x = new (g.get ()) type (1, 2);
+g.release ();
+
+...
+
+if (x)
+{
+  x->~type ();
+  xml_schema::free (x);
+}
+  </pre>
+
+  <p>For a complete example that shows how to use custom allocators, see
+     the <code>allocator</code> example which can be found in the
+     <code>examples/cxx/hybrid/</code> directory of the XSD/e distribution.</p>
 
   <!-- Chapater 4 -->
 
@@ -1882,7 +1995,9 @@ private:
 
   <p>When you set a value of an element or attribute of a
      variable-length type, the object model assumes ownership of
-     the pointed to object. It expects you to allocate the object with
+     the pointed to object. Unless you are using custom allocators
+     (see <a href="#3.8">Section 3.8, "Custom Allocators"</a>),
+     the object model expects you to allocate such an object with
      operator <code>new</code> and will eventually delete it
      with operator <code>delete</code>. You can also request generation
      of detach functions with the <code>--generate-detach</code> compiler
@@ -1963,8 +2078,8 @@ people* con = new people;
 // Populate per and con.
 
 staff s;
-s->permanent (per) // Assumes ownership or per.
-s->contract (con)  // Assumes ownership or con.
+s->permanent (per) // Assumes ownership of per.
+s->contract (con)  // Assumes ownership of con.
   </pre>
 
   <h2><a name="4.3">4.3 Enumerations</a></h2>