From 2e501c68a8641a2b3c430b55f13491a9c1c5d0f5 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 11 May 2010 12:20:11 +0200 Subject: Add support for custom allocators New example: examples/cxx/hybrid/allocator. --- documentation/cxx/hybrid/guide/index.xhtml | 121 ++++++++++++++++++++++++- documentation/cxx/parser/guide/index.xhtml | 114 ++++++++++++++++++++++- documentation/cxx/serializer/guide/index.xhtml | 114 ++++++++++++++++++++++- documentation/xsde.1 | 5 + documentation/xsde.xhtml | 5 + 5 files changed, 352 insertions(+), 7 deletions(-) (limited to 'documentation') 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 @@ 3.564-bit Integer Type 3.6Parser and Serializer Reuse 3.7Support for Polymorphism + 3.8Custom Allocators @@ -1562,6 +1563,118 @@ $ xsde cxx-hybrid --generate-parser --generate-serializer \

For information on how to use object models with polymorphic types, refer to Section 4.10, "Polymorphic Object Models".

+

3.8 Custom Allocators

+ +

By default the XSD/e runtime and generated code use + the standard operators new and delete + 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 + --custom-allocator 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 malloc(), realloc(), and + free() functions.

+ + 
+extern "C" void*
+xsde_alloc (size_t);
+
+extern "C" void*
+xsde_realloc (void*, size_t);
+
+extern "C" void
+xsde_free (void*);
+
+ +

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 + xml_schema namespace defines the following two + helper functions and, if C++ exceptions are enabled, automatic + pointer class:

+ + 
+namespace xml_schema
+{
+  void*
+  alloc (size_t);
+
+  void
+  free (void*);
+
+  struct alloc_guard
+  {
+    alloc_guard (void*);
+    ~alloc_guard ();
+
+    void*
+    get () const;
+
+    void
+    release ();
+
+  private:
+    ...
+  };
+}
+
+ +

If C++ exceptions are disabled, these functions are equivalent + to xsde_alloc() and xsde_free(). + If exceptions are enabled, xml_schema::alloc() + throws std::bad_alloc on memory allocation failure.

+ +

The following code fragment shows how to create and destroy a + dynamically-allocated object with custom allocators when C++ + exceptions are disabled:

+ + 
+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);
+}
+
+ +

The equivalent code fragment for configurations with C++ exceptions + enabled is shown below:

+ + 
+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);
+}
+
+ +

For a complete example that shows how to use custom allocators, see + the allocator example which can be found in the + examples/cxx/hybrid/ directory of the XSD/e distribution.

@@ -1882,7 +1995,9 @@ private:

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 Section 3.8, "Custom Allocators"), + the object model expects you to allocate such an object with operator new and will eventually delete it with operator delete. You can also request generation of detach functions with the --generate-detach 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.

4.3 Enumerations

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 @@ 5.564-bit Integer Type 5.6Parser Reuse 5.7Support for Polymorphism - 5.8A Minimal Example + 5.8Custom Allocators + 5.9A Minimal Example @@ -2842,7 +2843,116 @@ main () on root elements requires a number of special actions as shown in the polyroot example.

-

5.8 A Minimal Example

+

5.8 Custom Allocators

+ +

By default the XSD/e runtime and generated code use + the standard operators new and delete + 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 + --custom-allocator 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 malloc(), realloc(), and + free() functions.

+ + 
+extern "C" void*
+xsde_alloc (size_t);
+
+extern "C" void*
+xsde_realloc (void*, size_t);
+
+extern "C" void
+xsde_free (void*);
+
+ +

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 + xml_schema namespace defines the following two + helper functions and, if C++ exceptions are enabled, automatic + pointer class:

+ + 
+namespace xml_schema
+{
+  void*
+  alloc (size_t);
+
+  void
+  free (void*);
+
+  struct alloc_guard
+  {
+    alloc_guard (void*);
+    ~alloc_guard ();
+
+    void*
+    get () const;
+
+    void
+    release ();
+
+  private:
+    ...
+  };
+}
+
+ +

If C++ exceptions are disabled, these functions are equivalent + to xsde_alloc() and xsde_free(). + If exceptions are enabled, xml_schema::alloc() + throws std::bad_alloc on memory allocation failure.

+ +

The following code fragment shows how to create and destroy a + dynamically-allocated object with custom allocators when C++ + exceptions are disabled:

+ + 
+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);
+}
+
+ +

The equivalent code fragment for configurations with C++ exceptions + enabled is shown below:

+ + 
+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);
+}
+
+ +

5.9 A Minimal Example

The following example is a re-implementation of the person records example presented in 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 @@ 6.564-bit Integer Type 6.6Serializer Reuse 6.7Support for Polymorphism - 6.8A Minimal Example + 6.8Custom Allocators + 6.9A Minimal Example @@ -3664,7 +3665,116 @@ main () on root elements requires a number of special actions as shown in the polyroot example.

-

6.8 A Minimal Example

+

6.8 Custom Allocators

+ +

By default the XSD/e runtime and generated code use + the standard operators new and delete + 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 + --custom-allocator 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 malloc(), realloc(), and + free() functions.

+ + 
+extern "C" void*
+xsde_alloc (size_t);
+
+extern "C" void*
+xsde_realloc (void*, size_t);
+
+extern "C" void
+xsde_free (void*);
+
+ +

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 + xml_schema namespace defines the following two + helper functions and, if C++ exceptions are enabled, automatic + pointer class:

+ + 
+namespace xml_schema
+{
+  void*
+  alloc (size_t);
+
+  void
+  free (void*);
+
+  struct alloc_guard
+  {
+    alloc_guard (void*);
+    ~alloc_guard ();
+
+    void*
+    get () const;
+
+    void
+    release ();
+
+  private:
+    ...
+  };
+}
+
+ +

If C++ exceptions are disabled, these functions are equivalent + to xsde_alloc() and xsde_free(). + If exceptions are enabled, xml_schema::alloc() + throws std::bad_alloc on memory allocation failure.

+ +

The following code fragment shows how to create and destroy a + dynamically-allocated object with custom allocators when C++ + exceptions are disabled:

+ + 
+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);
+}
+
+ +

The equivalent code fragment for configurations with C++ exceptions + enabled is shown below:

+ + 
+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);
+}
+
+ +

6.9 A Minimal Example

The following example is a re-implementation of the person records example presented in 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 long and unsigned long. +

--custom-allocator
+
Generate code that performs memory management using custom allocator + functions provided by your application instead of the standard + operator new/delete.
+
--generate-inline
Generate simple functions inline. This option triggers creation of the inline file.
-- cgit v1.1