[ObjectHandler-cvs] ObjectHandler/Docs/pages excelbinding.docs, 1.1, 1.2

[Eric E. <eri...@us...>]

Update of /cvsroot/objecthandler/ObjectHandler/Docs/pages
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv32103

Modified Files:
	excelbinding.docs 
Log Message:
update docs

Index: excelbinding.docs
===================================================================
RCS file: /cvsroot/objecthandler/ObjectHandler/Docs/pages/excelbinding.docs,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** excelbinding.docs	19 May 2006 15:12:41 -0000	1.1
--- excelbinding.docs	5 Oct 2006 10:42:11 -0000	1.2
***************
*** 43,97 ****
  </ul>
  
- Both builds also support garbage collection, i.e. deletion of objects
- that have been orphaned in the repository by events such as the closing 
- of a workbook.
- 
  \section xl_gc Garbage Collection
  
! In Excel, a cell formula invokes the constructor of an object, causing that
! object to be added to the repository.  The object is assigned a handle which
! is returned to the calling cell, allowing the object to be accessed, e.g. the
! handle of one object could be passed as an input to the constructor of another.
! 
! An object persists in the repository even after the formula which instantiated 
! the object is deleted - this happens, for example, when a workbook is closed.  
! The object is not lost, its handle can still be retrieved and used to access 
! the object.  However the object is likely redundant and a mechanism for cleaning 
! it up is desirable.
! 
! ObjectHandler implements the following functions in support of garbage
! collection functionality: \ref ohSetGcEnabled, \ref ohGetGcEnabled ,\ref
! ohCallGC.
! 
! By default the feature is enabled, it can be disabled by calling ohSetGcEnabled(FALSE).  Whether or not garbage collection is enabled comprises a tradeoff in performance:
! 
! <table>
! <tr><td><b>Event</b></td><td><b>GC Enabled</b></td><td><b>GC Disabled</b></td></tr>
! <tr>
! <td><b>Object Construction / Destruction</b></td>
! <td>When objects are constructed/destroyed, a link to the calling cell is
! updated.  The exact magnitude of the performance hit depends on many variables,
! such as the number of objects in the repository, but in most cases the overhead
! is negligible.</td>
! <td>no performance overhead</td></tr>
! <tr><td><b>Deletion of Orphaned Objects</b></td>
! <td>Orphaned objects are deleted by calling ohCallGC() and the operation is
! very fast.</td>
! <td>In order to cull orphaned objects when GC is disabled, it's necessary to
! delete all objects then recreate the active ones:<br>
  
! - invoke function \ref ohDeleteAllObjects to empty the repository<br>
! - invoke Ctrl-Alt-F9 (recalculate all workbooks) to re-instantiate any active
! objects<br>
  
! Depending on the quantity and nature of the objects to be reconstructed, the
! magnitude of the performance hit may be high.</td></tr>
! </table>
  
! For most practical applications it should be preferable to leave garbage
! collection enabled.
  
! ObjectHandler's garbage collection functionality is an implementation
! of a technique presented in 
  <a href=" http://eu.wiley.com/WileyCDA/WileyTitle/productCd-0470024690.html">
  Excel Add-in Development in C/C++: Applications in Finance</a> by Steve Dalton.
--- 43,69 ----
  </ul>
  
  \section xl_gc Garbage Collection
  
! The Excel implementation of ObjectHandler supports function
! \ref ohCollectGarbage which can be called to cull objects that have been
! orphaned in the repository by events such as the closing of a workbook.
  
! A cell formula invokes the constructor of an object, causing that object to be
! added to the repository.  The object is assigned an ID which is returned to the
! calling cell, allowing the object to be accessed, e.g. the ID of one object
! could be passed as an input to the constructor of another.
  
! An object persists in the repository even after the formula which instantiated
! the object is deleted - this happens, for example, when a workbook is closed.
! The object is not lost, its ID can still be retrieved and used to access the
! object.
  
! However the object is likely redundant and a mechanism for cleaning it up is
! desirable.  Function ohCollectGarbage iterates through all the objects in the
! repository and culls those objects which have been orphaned by the deletion of
! the calling cell.
  
! ObjectHandler's garbage collection functionality is an implementation of a
! technique presented in 
  <a href=" http://eu.wiley.com/WileyCDA/WileyTitle/productCd-0470024690.html">
  Excel Add-in Development in C/C++: Applications in Finance</a> by Steve Dalton.