----------------------------------------------------------------------
 Template::Stash::XS					  August 2001
----------------------------------------------------------------------

Introduction:

 * This is an XS implementation of the Template::Stash module, based
   in part upon work that Andy Wardley did late last year.  It is
   an alternative version of the core Template::Stash methods ''get'' 
   and ''set'' (the ones that should benefit most from a speedy C 
   implementation), along with some virtual methods (like first, last,
   reverse, etc.)

   Doug Steinwand took the original code and made it into the fast and
   fully functional version you see here.  Our appreciation is due to
   Ticketmaster, Inc. (http://www.ticketmaster.com/) who funded Doug's
   work on this to the benefit of us all.

   You can run the additional test script ''tt-bench.pl'' to see the 
   improvement in speed. You may need to install the BSD::Resource
   module -- see http://search.cpan.org/search?dist=BSD-Resource
	
       perl tt-bench.pl


Additional Notes:

 * Depending upon the size and content of a template, this version
   has about twice the speed of the original Template::Stash.


 * When a virtual method (like pop, push, nsort, sort etc.) has not 
   been implemented in XS, it uses these hashrefs in Template::Stash 
   package -- $HASH_OPS, $LIST_OPS, and $SCALAR_OPS -- to call perl 
   subroutines that can do the work. 


 * Using the ''reference'' feature of Template Toolkit -- like
   [% a = \foo %] -- leaks a large amount of memory. Enable the 
   template code at the end of ''tt-bench.pl'' for a demonstration.
   (Note: This is a problem in the pure-perl version, too.  Also, 
   you'll need a platform that fully supports getrusage() -- FreeBSD 
   and IRIX are two that should work. Otherwise, use a utility like 
   ''top''. )


 * Although it passes all the tests that I've thrown at it, there may
   still be some problems and/or bugs.  My primary goal was to mirror
   the behavior of the pure-perl version using XS.  

   (NOTE: The XS Stash has subsequently been tested by numerous people
   on the Template Toolkit mailing list and everyone has reported 100%
   success and notable speedups - abw)


 * Profiling code can be enabled with ''#define TT_PERF_ENABLE'' in
   the Stash.xs source, but doing so hurts performance a bit.  The 
   results can be displayed by adding the line: 

	  print Template::Stash::XS::performance(1);

   to your code. Use 0 instead of 1 for a more compact display.


 * There's no need to try crazy compiler optimizations on this code,
   because a majority of time is spent inside Perl's functions.