Add support for custom allocators

New example: examples/cxx/hybrid/allocator.

5 files changed, 352 insertions, 7 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>
diff --git a/documentation/cxx/parser/guide/index.xhtml b/documentation/cxx/parser/guide/index.xhtml
index 6a019c5..6805a9b 100644
--- a/documentation/cxx/parser/guide/index.xhtml
+++ b/documentation/cxx/parser/guide/index.xhtml
@@ -286,7 +286,8 @@
 	  <tr><th>5.5</th><td><a href="#5.5">64-bit Integer Type</a></td></tr>
 	  <tr><th>5.6</th><td><a href="#5.6">Parser Reuse</a></td></tr>
 	  <tr><th>5.7</th><td><a href="#5.7">Support for Polymorphism</a></td></tr>
-          <tr><th>5.8</th><td><a href="#5.8">A Minimal Example</a></td></tr>
+	  <tr><th>5.8</th><td><a href="#5.8">Custom Allocators</a></td></tr>
+          <tr><th>5.9</th><td><a href="#5.9">A Minimal Example</a></td></tr>
         </table>
       </td>
     </tr>
@@ -2842,7 +2843,116 @@ main ()
      on root elements requires a number of special actions as shown in
      the <code>polyroot</code> example.</p>
 
-  <h2><a name="5.8">5.8 A Minimal Example</a></h2>
+  <h2><a name="5.8">5.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>
+
+  <h2><a name="5.9">5.9 A Minimal Example</a></h2>
 
   <p>The following example is a re-implementation of the person
      records example presented in <a href="#3">Chapter 3,
diff --git a/documentation/cxx/serializer/guide/index.xhtml b/documentation/cxx/serializer/guide/index.xhtml
index 34ef798..e1fecb4 100644
--- a/documentation/cxx/serializer/guide/index.xhtml
+++ b/documentation/cxx/serializer/guide/index.xhtml
@@ -298,7 +298,8 @@
 	  <tr><th>6.5</th><td><a href="#6.5">64-bit Integer Type</a></td></tr>
           <tr><th>6.6</th><td><a href="#6.6">Serializer Reuse</a></td></tr>
 	  <tr><th>6.7</th><td><a href="#6.7">Support for Polymorphism</a></td></tr>
-	  <tr><th>6.8</th><td><a href="#6.8">A Minimal Example</a></td></tr>
+	  <tr><th>6.8</th><td><a href="#6.8">Custom Allocators</a></td></tr>
+	  <tr><th>6.9</th><td><a href="#6.9">A Minimal Example</a></td></tr>
         </table>
       </td>
     </tr>
@@ -3664,7 +3665,116 @@ main ()
      on root elements requires a number of special actions as shown in
      the <code>polyroot</code> example.</p>
 
-  <h2><a name="6.8">6.8 A Minimal Example</a></h2>
+  <h2><a name="6.8">6.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>
+
+  <h2><a name="6.9">6.9 A Minimal Example</a></h2>
 
   <p>The following example is a re-implementation of the person
      records example presented in <a href="#4">Chapter 4,
diff --git a/documentation/xsde.1 b/documentation/xsde.1
index e578afa..a4b55dc 100644
--- a/documentation/xsde.1
+++ b/documentation/xsde.1
@@ -213,6 +213,11 @@ and
 .B unsigned
 .BR long .
 
+.IP "\fB\--custom-allocator\fR"
+Generate code that performs memory management using custom allocator
+functions provided by your application instead of the standard operator
+new/delete.
+
 .IP "\fB\--generate-inline\fR"
 Generate simple functions inline. This option triggers creation of the
 inline file.
diff --git a/documentation/xsde.xhtml b/documentation/xsde.xhtml
index d758905..859719e 100644
--- a/documentation/xsde.xhtml
+++ b/documentation/xsde.xhtml
@@ -195,6 +195,11 @@
         built-in XML Schema types are then mapped to <code><b>long</b></code>
         and <code><b>unsigned long</b></code>.</dd>
 
+    <dt><code><b>--custom-allocator</b></code></dt>
+    <dd>Generate code that performs memory management using custom allocator
+        functions provided by your application instead of the standard
+        operator new/delete.</dd>
+
     <dt><code><b>--generate-inline</b></code></dt>
     <dd>Generate simple functions inline. This option triggers creation
       of the inline file.</dd>