diff options
author | Boris Kolpackov <boris@codesynthesis.com> | 2010-05-11 12:20:11 +0200 |
---|---|---|
committer | Boris Kolpackov <boris@codesynthesis.com> | 2010-05-11 12:20:11 +0200 |
commit | 2e501c68a8641a2b3c430b55f13491a9c1c5d0f5 (patch) | |
tree | 49c2748443fe3c1f01108756b647440e0647a11b /documentation/cxx/hybrid | |
parent | 161beba6cdb0d91b15ad19fa8b3e51d986203915 (diff) |
Add support for custom allocators
New example: examples/cxx/hybrid/allocator.
Diffstat (limited to 'documentation/cxx/hybrid')
-rw-r--r-- | documentation/cxx/hybrid/guide/index.xhtml | 121 |
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> |