yelp:cache implementation

[Shaun McCance <shaunm gnome org>]

>From the mighty Brent:

-------- Forwarded Message --------
> From: Brent Smith <gnome nextreality net>
> To: GNOME Documentation <gnome-doc-list gnome org>, Shaun McCance
> <shaunm gnome org>, Don Scorgie <DonScorgie Blueyonder co uk>
> Subject: yelp:cache implementation
> Date: Thu, 29 Jun 2006 20:36:28 -0600
> 
> This is the first rough pass at an implementation of a yelp:cache 
> extension element.
> 
> Shaun and I discussed this on IRC and basically the premise is that if a 
> template depends solely on a xsl:param element that is passed to it, 
> then we can cache the results of that template and if it is called again 
> with the same parameter, then we look up the result in a hash table 
> instead of performing all the XSLT again.
> 
> A prime example of this is the db.number template.
> 
> <xsl:template name="db.number">
>    <xsl:param name="node" select="."/>
>      <xsl:apply-templates mode="db.number.mode" select="$node"/>
> </xsl:template>
> 
> This template is responsible for calculating the numbers for a 
> particular docbook section, and takes up quite a bit of processing time 
> for docbook files with many sections and deep nesting.  Since the same
> node is passed to the function often, a considerable amount of time is
> wasted recalculating something we've already done before.
> 
> In comes the <yelp:cache> extension element.  Yelp's db2html.xsl 
> template now has the following (overriding the original version of this 
> template in db-label.xsl)
> 
> <xsl:template name="db.number">
>    <xsl:param name="node" select="."/>
>    <yelp:cache key="db.number" node="$node">
>      <xsl:apply-templates mode="db.number.mode" select="$node"/>
>    </yelp:cache>
> </xsl:template>
> 
> You can see that two attributes are required for the <yelp:cache> 
> element.  The key is unique value per template and is used in generating 
> the key for the hash table lookup.  The other required attribute is 
> node, which right now must be a nodeset with a single node.  The 
> xmlNodePtr to this single node makes up the other part of the hash key.
> 
> On the first call to the db.number template with a particular node, the 
> extension element function will not find a value in the hash table. 
> Therefore, it will apply the child elements of the yelp:cache element, 
> and put the result in the hash table.  On the second call with the same 
> node, the extension element function finds the value in the hash table, 
> and instantiates it in the result tree.
> 
> So enough blabbing, here are the results before and after for the 
> Gnumeric manual, which takes the longest time to process (by far).
> 
> BEFORE:
> 
> smitten home:/extra/cvs/gnome2/yelp-head2$ YELP_DEBUG="enable-profiling" 
> /opt/gnome2/bin/yelp
> PROFILE [20:31:59]: entering xslt_pager_process
> PROFILE [20:32:52]: leaving xslt_pager_process
> 
> 
> AFTER:
> 
> smitten home:/extra/cvs/gnome2/yelp-head2$ YELP_DEBUG="enable-profiling" 
> /opt/gnome2/bin/yelp
> PROFILE [20:30:10]: entering xslt_pager_process
> PROFILE [20:30:35]: leaving xslt_pager_process
> 
> Pretty dramatic!!
> 
> Shaun had some concerns about localization, but I don't think this 
> should affect it since the extension element function caches the actual 
> result of the db.number.mode template.  That is unless the result of 
> db.number.mode is dependent on the depth of numbering as well as the 
> $node parameter...
> 
> Let me know your thoughts!
>