axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ros...@apache.org
Subject cvs commit: ws-axis/c/docs/arch mem-management.html
Date Fri, 15 Oct 2004 07:42:17 GMT
roshan      2004/10/15 00:42:17

  Modified:    c/docs/arch mem-management.html
  Log:
  Added the mem-management.html to the C\Docs. Changed by Rangika
  
  Revision  Changes    Path
  1.2       +11 -11    ws-axis/c/docs/arch/mem-management.html
  
  Index: mem-management.html
  ===================================================================
  RCS file: /home/cvs/ws-axis/c/docs/arch/mem-management.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- mem-management.html	8 Sep 2004 10:28:42 -0000	1.1
  +++ mem-management.html	15 Oct 2004 07:42:17 -0000	1.2
  @@ -23,8 +23,8 @@
   <br><a href="#Open Issues">Open Issues</a>
   
   <h2><a NAME="Introduction"></a>Introduction</h2>
  -<p> This guide records the memory management semantics and some of the rationale
of the desing decisions on which memory management semantics are based on. Being a C/C++ application,
it is a must that all users as well as developers have a clear understanding on how to deal
with memory allocation and deallocation. 
  -<p> The allocation and deallocation mechanisms are centred around the serializer
and deserializer operations in Axis C++. At the moment, because Axis C++ support both C and
C++ clients and services, the deserializer uses <i>malloc()</i> for memory allocation.
Hence C++ users may have to live with <i>free()</i> (instead of <i>delete</i>)
for deallocation. Of course one could still use delte from C++ programs, however this may
not gaurentee the cleanest memory deallocation.
  +<p> This guide records the memory management semantics and some of the rationales
of the design decisions on which memory management semantics are based on. Being a C/C++ application,
it is a must that all users as well as developers have a clear understanding on how to deal
with memory allocation and deallocation. 
  +<p> The allocation and deallocation mechanisms are centered around the serializer
and deserializer operations in Axis C++. At the moment, because Axis C++ support both C and
C++ clients and services, the deserializer uses <i>malloc()</i> for memory allocation.
Hence C++ users may have to live with <i>free()</i> (instead of <i>delete</i>)
for deallocation. Of course one could still use delete from C++ programs, however this may
not guarantee the cleanest memory deallocation.
   
   <h2><a NAME="Semantics"></a>Allocation/De-allocation Semantics</h2>
   <h3>Parameters</h3>
  @@ -37,7 +37,7 @@
   One can select his/her own allocation mechanism. (<i>malloc()</i> in case of
C programs and/or <i>new</i> in case of C++ programs)
   
   <h3>Other Objects</h3>
  -For XML elements and attribute objects that are created by IHandlerSoapSerializer, HeaderBlock
and Attribute the rules for deleting the objects when the request or response is processed
are as follows.
  +For XML elements and attribute objects that are created by IHandlerSoapSerializer, HeaderBlock
and Attribute, the rules for deleting the objects when the request or response is processed
are as follows.
   <ol>
   <li> Any outbound objects created, either by a client application or by a handler,
must be managed by the creator him(her)self. The Axis C++ engine does not delete any objects
(HeaderBlocks, Attributes, BasicNodes etc.).</li> 
   <li> Any inbound objects that are created by the Axis C++ Engine as a result of deserialization
should be deallocated by a target handler or the client application. Axis C++ Engine deallocates
only the headerblocks that will remain in the deserializer (headerblocks with no target handler).</li>
  @@ -45,7 +45,7 @@
   
   <h3>Return Values</h3>
   <p> The values returned by the Axis C++ engine must be memory cleaned by the user
written code.
  -The C++ code generated by the WSDL2Ws tool does contain destructors. However, at the moment,
it is not gaurenteed that the destructor of a generated class would clean all of the pointer
members (Some memmbers are cleaned while others are not). Hence the users must have a look
at the generated code to understand the semantics of memory cleaning. In case of C code, of
cource the user must take care of memory cleaning.
  +The C++ code generated by the WSDL2Ws tool does contain destructors. However, at the moment,
it is not gauranteed that the destructor of a generated class would clean all  the pointer
members (Some members are cleaned while others are not). Hence the users must have a look
at the generated code to understand the semantics of memory cleaning. In case of C code, of
course the user must take care of memory cleaning.
   <p> Please note that in case of arrays, both for C and C++, the Axis C++ engine returns
a struct. Hence it is a must that the memory is cleaned properly. 
   <br> C++ Example:<br>
   <pre>
  @@ -80,32 +80,32 @@
   
   <h2><a NAME="IHeaderBlock"></a>Dealing with SOAP Headers</h2>
   <h3>From Stubs</h3>
  -<p> IHeaderBlock is a virtual class that defines the interface to deal with SOAP
headers. You can create an IHeaderBlock at the client side using the API provided with Stub
classs. <br>
  +<p> IHeaderBlock is a virtual class that defines the interface to deal with SOAP
headers. You can create an IHeaderBlock at the client side using the API provided with Stub
classes. <br>
   <pre>
   IHeaderBlock* Stub::createSOAPHeaderBlock(AxisChar * pachLocalName, AxisChar * pachUri);
   </pre>
  -Here the Stub class will maintain a list of all created Header Blocks, and in the destructor
of the Stub class, it will clean up memory by deleting all those Header Blocks that were created
by the user. 
  +Here the Stub class will maintain a list of all the created Header Blocks, and in the destructor
of the Stub class, it will clean up memory by deleting all those Header Blocks that were created
by the user. 
   
   <p> <b>Note 1</b>: It is advisable that if a user wants to delete a Hheader
Block, (s)he uses the API provided by the Stub class to do so.<br>
   <pre>
   void deleteCurrentSOAPHeaderBlock();
   </pre>
  -Stub class is also equipped with iterator methods to traverse the current list of Header
Blocks created.
  +Stub class is also equipped with iterator methods to traverse through the current list
of Header Blocks created.
   <br>
   
  -<p> <b>Note 2</b>: IHeaderBlock destructor will take care of the Header
Block member variables and clean them; BasicNodes (i.e its children) and the Attributes. <br>
  +<p> <b>Note 2</b>: IHeaderBlock destructor will take care of the Header
Block member variables and cleans them; BasicNodes (i.e its children) and the Attributes.
<br>
   
   <h3>From Handlers</h3>
  -<p> If the Header Blocks are created from within a Handler then it is the responsiblity
of the Handler writer to clean those. For that the user can write the cleanup code either
in the fini() method or in the destructor of the Handler, depending on the following situations
  +<p> If the Header Blocks are created within a Handler then it is the responsibility
of the Handler writer to clean those. For that the user can write the cleanup code either
in the fini() method or in the destructor of the Handler, depending on the following situations
   <nl>
  -<li> If it is a sessoin handler which needs to maintain its state, then the cleanup
has to be done in the destructor.</li>
  +<li> If it is a session handler which needs to maintain its state, then the cleanup
has to be done in the destructor.</li>
   <li> If it is a request type handler the clean up can be done in the fini() mehtod
of the Handler. Here the writer has to explicitly write the clean up code.</li>
   </nl>
   
   <p> If a target handler access a Header Block created by the deserializer then it
is the responsibility of the Handler to delete it.
   
   <h2><a NAME="Open Issues"></a>Open Issues</h2>
  -<p> As C++ is and object oriented language, one would ideally like to leverage constructors
and destructors for memory management. However, the Axis C++ engine uses structs in some cases
(e.g. Arrays) and use <i>malloc()</i> to allocate memory. Hence the C++ programmer
woul be forced to use <i>free()</i> at times. When using <i>malloc()</i>
and <i>free()</i> constructors and destructors are not called. However, as the
Axis C++ engine currently supports both C and C++, it is not simple to replace all <i>malloc()</i>
with <i>new</i> or <i>free()</i> with <i>delete</i>. At
the same time, there are some places where <i>new</i> and <i>delete</i>
are being used. They too cannot be replaced with <i>malloc()</i> and <i>free()</i>
overnight. This memory management complexity is the price paid for dual support of C and C++.
Efforts are under way to clean up the memroy management mix-ups and still support both C and
C++. Currently the proposed solution is to make the Axis C++ engine pure C++ and use a wrapper
mechanism to support C. 
  +<p> As C++ is an object oriented language, one would ideally like to leverage constructors
and destructors for memory management. However, the Axis C++ engine uses structs in some cases
(e.g. Arrays) and uses <i>malloc()</i> to allocate memory. Hence the C++ programmer
would be forced to use <i>free()</i> at times. When using <i>malloc()</i>
and <i>free()</i> constructors and destructors are not called. However, as the
Axis C++ engine currently supports both C and C++, it is not simple to replace all <i>malloc()</i>
with <i>new</i> or <i>free()</i> with <i>delete</i>. At
the same time, there are some places where <i>new</i> and <i>delete</i>
are being used. They too cannot be replaced with <i>malloc()</i> and <i>free()</i>
overnight. This memory management complexity is the price paid for dual support of C and C++.
Efforts are under way to clean up the memory management mix-ups and still support both C and
C++. Currently the proposed solution is to make the Axis C++ engine pure C++ and use a wrapper
mechanism to support C. 
   
   <p> When an array is de-serialized it uses C style memory re-allocation mechanism
in the present code. C++ does not support <i>realloc()</i> and if we use <i>new</i>
instead we have to allocate fresh memory blocks each time we need to increase the array size.
This can be more expensive than using <i>realloc()</i>. Again the price paid for
efficiency is that one has to use <i>free()</i> and not <i>delete []</i>
 from C++ code. 
   
  
  
  

Mime
View raw message