From 2e501c68a8641a2b3c430b55f13491a9c1c5d0f5 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 11 May 2010 12:20:11 +0200
Subject: Add support for custom allocators

New example: examples/cxx/hybrid/allocator.
---
 documentation/cxx/serializer/guide/index.xhtml | 114 ++++++++++++++++++++++++-
 1 file changed, 112 insertions(+), 2 deletions(-)

(limited to 'documentation/cxx/serializer/guide/index.xhtml')

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,
-- 
cgit v1.1