sources/xalan/programming.xml

<?xml version="1.0" standalone="no"?> 
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<!--
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the  "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->
<s1 title="Programming Tips">
   <ul>
      <li><link anchor="intro">Introduction</link></li>
      <li><link anchor="memory">Pluggable Memory Management</link></li>
      <li><link anchor="more">More topics</link></li>
   </ul>

<anchor name="intro"/>   
<s2 title="Introduction">
<p>This section was created to guide users on how to use some of the new features going into the Xalan 
source code base.  Some of the features discussed in this section was based on feedback and questions
posted on the xalan-c-users newsgroup postings.  This section will cover the benefits of certain features
and provide users with programming hints on how to utilize the features in their applications.</p>
</s2>

<anchor name="memory"/>
<s2 title="Pluggable Memory Management">
<p>Pluggable memory management was added as a new feature in &xslt4c-current;.  This feature introduces an
object called MemoryManager which allows applications with stricter memory management requirements to 
utilize a more efficient allocation method.  This MemoryManager object can be applied to 
each processor instance, thus recovery procedures from memory leaks or processor crashes will be applied to 
the associated instance only.</p>
<p>The memory management model is similar to the memory management feature provided by &xml4c;.  For more 
information on the &xml4c; memory management feature, please see <resource-ref idref="xercesmm"/>.</p>
<s3 title="How To Use This Feature">
<p>To apply memory management to your application, the MemoryManager object needs to be specified in two
stages:</p>
<ul>
<li>At initialization phase.  The purpose of specifying a MemoryManager object during initialization is to 
create a separate memory manager for the overall application.  Example of how this can be done is shown in 
the example below<br/><br/>
<source>
// Initialization step
static void XalanTransformer::initialize(MemoryManager* initMemoryManager=0);
</source>
</li>
<li>Creation of a transformer instance.  This creates a unique memory manager for the instance of the 
processor.  This step is optional.  If no memory manager is provided, the global heap is used as the memory
source.  Example of this is shown below:<br/><br/>
<source>
// Create instance of XalanTransformer
MemoryManager      memMgrA;                // memory manager object
XalanTransformer   transformerA(&amp;memMgrA); 

MemoryManager      memMgrB;
XalanTransformer   transformerB(&amp;memMgrB);
XalanTransformer   transformerC(&amp;memMgrB);  // Uses same memory manager object as transformerB
XalanTransformer   transformerD;           // Uses default static memory manager
</source>
</li>
</ul>
<p>The above method demonstrates how users can apply the basic pluggable memory management feature.  Users
also have the option of implementing their own memory manager.  This can be done by simply writing methods 
for:</p>
<source>
// Method for allocating memory
void* allocate(size_t size);
</source>
<p>and</p>
<source>
// Method for deallocating memory
void deallocate(void *p);
</source>
<p>For an example of how to use this feature, please see the <link idref="samples" anchor="simpletransform">
SimpleTransform</link> sample that has been provided in the binary distributions.</p>
</s3>
</s2>

<anchor name="more"/>
<s2 title="More Topics">
<p>Please feel free to give us feedback on what topics you would like to see</p>
</s2>
</s1>