doc/stdlibug/26-9.html - stdcxx - Git at Google

 <!--
     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.

     Copyright 1999-2007 Rogue Wave Software, Inc.
 -->

 <HTML>
 <HEAD>
 <TITLE>Improving the Inserter Function</TITLE>
 <LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
 <BODY BGCOLOR=#FFFFFF>
 <A HREF="26-8.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="VIII.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library User's Guide</B></DIV>
 <H2>26.9 Improving the Inserter Function</H2>
 <A NAME="idx603"><!></A>
 <P>Let's turn here to improving our inserter function. Consider that the country code table might be huge, and access to a country code might turn out to be a time-consuming operation. We can optimize the inserter function's performance by caching the country code table, so that we can access it directly and thus reduce performance overhead. </P>
 <A NAME="idx604"><!></A>
 <A NAME="2691"><H3>26.9.1 Primitive Caching</H3></A>
 <A NAME="idx605"><!></A>
 <P>The code below does some primitive caching. It takes the phone facet object from the stream's locale object and copies the country code table into a static variable.</P>

 <UL><PRE>
 std::ostream&amp; operator&lt;&lt;(std::ostream&amp; os, const PhoneNumber&amp; pn)
 {
   std::locale loc = os.getloc();
   const phone_put&amp; ppFacet = std::use_facet&lt;phone_put&gt; (loc);

   // primitive caching
   static CodeMap cachedCodes = *(ppFacet.getCodes());

   // some sophisticated output using the cached codes
   ...
   return (os);
 }
 </PRE></UL>
 <P>Now consider that the locale object imbued on a stream might change, but the cached static country code table does not. The cache is filled once, and all changes to the stream's locale object have no effect on this inserter function's cache. That's probably not what we want. What we do need is some kind of notification each time a new locale object is imbued, so that we can update the cache.</P>
 <A NAME="idx606"><!></A>
 <A NAME="2692"><H3>26.9.2 Registration of a Callback Function</H3></A>
 <A NAME="idx607"><!></A>
 <P>In the following example, notification is provided by a callback function. The iostreams allow registration of callback functions. Class <B><I><A HREF="../stdlibref/ios-base.html">std::ios_base</A></I></B> declares:</P>

 <UL><PRE>
 enum event { erase_event, imbue_event, copyfmt_event };  //1
 typedef void (*event_callback) (event, ios_base&amp;, int index);
 void register_callback(event_callback fn, int index);    //2
 </PRE></UL>
 <TABLE CELLPADDING="3">

 <TR VALIGN="top"><TD><SAMP>//1</SAMP></TD><TD>Registered callback functions are called for three events:
 <UL>
 <LI><P CLASS="LIST">Destruction of a stream </P></LI>
 <LI><P CLASS="LIST">Imbuing a new locale</P></LI>
 <LI><P CLASS="LIST">Copying the stream state.</P></LI>
 </UL>
 <A NAME="idx608"><!></A>
 <TR VALIGN="top"><TD><SAMP>//2</SAMP></TD><TD>The <SAMP>register_callback()</SAMP> function registers a callback function and an index to the stream's <SAMP>parray</SAMP>. During calls to <SAMP>imbue()</SAMP>, <SAMP>copyfmt()</SAMP>, or <SAMP>~ios_base()</SAMP>, the function <SAMP>fn</SAMP><SAMP> </SAMP>is called with argument <SAMP>index</SAMP>. Functions registered are called when an event occurs, in opposite order of registration.
 <A NAME="idx609"><!></A>
 The <SAMP>parray</SAMP> is an array member defined in class <B><I><A HREF="../stdlibref/ios-base.html">std::ios_base</A></I></B>. One can obtain an index to this array via <SAMP>xalloc()</SAMP>, and access the array via <SAMP>pword(index)</SAMP> or <SAMP>iword(index)</SAMP>, as shown in <A HREF="26-9.html#Figure&nbsp;16">Figure&nbsp;16</A>:
 <A NAME="idx610"><!></A>
 <H4><A NAME="Figure&nbsp;16">Figure&nbsp;16: The array parray</A></H4>

 <P><IMG SRC="images/locfig17.gif" WIDTH=638 HEIGHT=336></P>
 </TABLE>
 <A NAME="idx611"><!></A>
 <P>In order to install a callback function that updates our cache, we implement a class that retrieves an index to <SAMP>parray</SAMP> and creates the cache, then registers the callback function in its constructor. The procedure is shown in the following code:</P>

 <UL><PRE>
 class CallbackRegistrar {
   public:
     CallbackRegistrar(std::ostream&amp; os,
                       std::ios::event_callback fct,
                       CodeMap* cachedCodes)
     {
       int index = os.xalloc();                             //1
       os.pword(index) = cachedCodes;                       //2
       os.register_callback(fct,index);                     //3
     }
 };
 </PRE></UL>
 <TABLE CELLPADDING="3">

 <TR VALIGN="top"><TD><SAMP>//1</SAMP></TD><TD>An index to the array is obtained via <SAMP>xalloc()</SAMP>.
 <TR VALIGN="top"><TD><SAMP>//2</SAMP></TD><TD>The pointer to the code table is stored in the array via<SAMP> pword()</SAMP>.
 <TR VALIGN="top"><TD><SAMP>//3</SAMP></TD><TD>The callback function and the index are registered.
 </TABLE>
 <A NAME="idx612"><!></A>
 <P>The actual callback function will later have access to the cache via the index to <SAMP>parray</SAMP>. At this point, we still need a callback function that updates the cache each time the stream's locale is replaced. Such a callback function could look like this:</P>

 <UL><PRE>
 void cacheCodesCallback(std::ios_base::event callbackEvent,
                         std::ios_base&amp; stream, int cacheIndex)
 {
   if (callbackEvent == std::ios::imbue_event) {             //1
     const phone_put&amp; ppFacet =
       std::use_facet&lt;phone_put&gt; (stream.getloc);            //2
     phone_put::CodeMap* cachedCodes =
       (phone_put::CodeMap*) stream.pword(cacheIndex);       //3

     *cachedCodes = *ppFacet.getCodes();
   }
 }
 </PRE></UL>
 <TABLE CELLPADDING="3">

 <TR VALIGN="top"><TD><SAMP>//1</SAMP></TD><TD>Check whether the event was a change of the imbued locale,
 <TR VALIGN="top"><TD><SAMP>//2</SAMP></TD><TD>retrieve the phone number facet from the stream's locale, and
 <TR VALIGN="top"><TD><SAMP>//3</SAMP></TD><TD>store the country code table in the cache. The cache is accessible via the stream's <SAMP>parray</SAMP>.
 </TABLE>
 <A NAME="2693"><H3>26.9.3 Improving the Inserter</H3></A>
 <A NAME="idx613"><!></A>
 <P>We now have everything we need to improve our inserter. It registers a callback function that updates the cache whenever necessary. Registration is done only once, by declaring a static variable of class <SAMP>CallbackRegistrar</SAMP>.</P>

 <UL><PRE>
 std::ostream&amp; operator&lt;&lt;(std::ostream&amp; os, const phoneNumber&amp; pn)
 {
  static phone_put::CodeMap codes =
     *(std::use_facet&lt;phone_put&gt;(os.getloc()).getCodes());     //1

  static CallbackRegistrar
      registrar(os,cacheCountryCodes,&amp;codes);                  //2

   // some sophisticated output using the cached codes
   ...
 }
 </PRE></UL>
 <TABLE CELLPADDING="3">

 <TR VALIGN="top"><TD><SAMP>//1</SAMP></TD><TD>The current country code table is cached.
 <TR VALIGN="top"><TD><SAMP>//2</SAMP></TD><TD>The callback function <SAMP>cacheCodesCallback()</SAMP> is registered.
 </TABLE>


 <BR>
 <HR>
 <A HREF="26-8.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="VIII.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>

 <!-- Google Analytics tracking code -->
 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
 </script>
 <script type="text/javascript">
     _uacct = "UA-1775151-1";
     urchinTracker();
 </script>
 <!-- end of Google Analytics tracking code -->

 </BODY>
 </HTML>
	<!--
	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.

	Copyright 1999-2007 Rogue Wave Software, Inc.
	-->

	<HTML>
	<HEAD>
	<TITLE>Improving the Inserter Function</TITLE>
	<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
	<BODY BGCOLOR=#FFFFFF>
	<A HREF="26-8.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="VIII.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library User's Guide</B></DIV>
	<H2>26.9 Improving the Inserter Function</H2>
	<A NAME="idx603"><!></A>
	<P>Let's turn here to improving our inserter function. Consider that the country code table might be huge, and access to a country code might turn out to be a time-consuming operation. We can optimize the inserter function's performance by caching the country code table, so that we can access it directly and thus reduce performance overhead. </P>
	<A NAME="idx604"><!></A>
	<A NAME="2691"><H3>26.9.1 Primitive Caching</H3></A>
	<A NAME="idx605"><!></A>
	<P>The code below does some primitive caching. It takes the phone facet object from the stream's locale object and copies the country code table into a static variable.</P>

	<UL><PRE>
	std::ostream& operator<<(std::ostream& os, const PhoneNumber& pn)
	{
	std::locale loc = os.getloc();
	const phone_put& ppFacet = std::use_facet<phone_put> (loc);

	// primitive caching
	static CodeMap cachedCodes = *(ppFacet.getCodes());

	// some sophisticated output using the cached codes
	...
	return (os);
	}
	</PRE></UL>
	<P>Now consider that the locale object imbued on a stream might change, but the cached static country code table does not. The cache is filled once, and all changes to the stream's locale object have no effect on this inserter function's cache. That's probably not what we want. What we do need is some kind of notification each time a new locale object is imbued, so that we can update the cache.</P>
	<A NAME="idx606"><!></A>
	<A NAME="2692"><H3>26.9.2 Registration of a Callback Function</H3></A>
	<A NAME="idx607"><!></A>
	<P>In the following example, notification is provided by a callback function. The iostreams allow registration of callback functions. Class <B><I><A HREF="../stdlibref/ios-base.html">std::ios_base</A></I></B> declares:</P>

	<UL><PRE>
	enum event { erase_event, imbue_event, copyfmt_event }; //1
	typedef void (*event_callback) (event, ios_base&, int index);
	void register_callback(event_callback fn, int index); //2
	</PRE></UL>
	<TABLE CELLPADDING="3">

	<TR VALIGN="top"><TD><SAMP>//1</SAMP></TD><TD>Registered callback functions are called for three events:
	<UL>
	<LI><P CLASS="LIST">Destruction of a stream </P></LI>
	<LI><P CLASS="LIST">Imbuing a new locale</P></LI>
	<LI><P CLASS="LIST">Copying the stream state.</P></LI>
	</UL>
	<A NAME="idx608"><!></A>
	<TR VALIGN="top"><TD><SAMP>//2</SAMP></TD><TD>The <SAMP>register_callback()</SAMP> function registers a callback function and an index to the stream's <SAMP>parray</SAMP>. During calls to <SAMP>imbue()</SAMP>, <SAMP>copyfmt()</SAMP>, or <SAMP>~ios_base()</SAMP>, the function <SAMP>fn</SAMP><SAMP> </SAMP>is called with argument <SAMP>index</SAMP>. Functions registered are called when an event occurs, in opposite order of registration.
	<A NAME="idx609"><!></A>
	The <SAMP>parray</SAMP> is an array member defined in class <B><I><A HREF="../stdlibref/ios-base.html">std::ios_base</A></I></B>. One can obtain an index to this array via <SAMP>xalloc()</SAMP>, and access the array via <SAMP>pword(index)</SAMP> or <SAMP>iword(index)</SAMP>, as shown in <A HREF="26-9.html#Figure 16">Figure 16</A>:
	<A NAME="idx610"><!></A>
	<H4><A NAME="Figure 16">Figure 16: The array parray</A></H4>

	<P><IMG SRC="images/locfig17.gif" WIDTH=638 HEIGHT=336></P>
	</TABLE>
	<A NAME="idx611"><!></A>
	<P>In order to install a callback function that updates our cache, we implement a class that retrieves an index to <SAMP>parray</SAMP> and creates the cache, then registers the callback function in its constructor. The procedure is shown in the following code:</P>

	<UL><PRE>
	class CallbackRegistrar {
	public:
	CallbackRegistrar(std::ostream& os,
	std::ios::event_callback fct,
	CodeMap* cachedCodes)
	{
	int index = os.xalloc(); //1
	os.pword(index) = cachedCodes; //2
	os.register_callback(fct,index); //3
	}
	};
	</PRE></UL>
	<TABLE CELLPADDING="3">

	<TR VALIGN="top"><TD><SAMP>//1</SAMP></TD><TD>An index to the array is obtained via <SAMP>xalloc()</SAMP>.
	<TR VALIGN="top"><TD><SAMP>//2</SAMP></TD><TD>The pointer to the code table is stored in the array via<SAMP> pword()</SAMP>.
	<TR VALIGN="top"><TD><SAMP>//3</SAMP></TD><TD>The callback function and the index are registered.
	</TABLE>
	<A NAME="idx612"><!></A>
	<P>The actual callback function will later have access to the cache via the index to <SAMP>parray</SAMP>. At this point, we still need a callback function that updates the cache each time the stream's locale is replaced. Such a callback function could look like this:</P>

	<UL><PRE>
	void cacheCodesCallback(std::ios_base::event callbackEvent,
	std::ios_base& stream, int cacheIndex)
	{
	if (callbackEvent == std::ios::imbue_event) { //1
	const phone_put& ppFacet =
	std::use_facet<phone_put> (stream.getloc); //2
	phone_put::CodeMap* cachedCodes =
	(phone_put::CodeMap*) stream.pword(cacheIndex); //3

	cachedCodes = ppFacet.getCodes();
	}
	}
	</PRE></UL>
	<TABLE CELLPADDING="3">

	<TR VALIGN="top"><TD><SAMP>//1</SAMP></TD><TD>Check whether the event was a change of the imbued locale,
	<TR VALIGN="top"><TD><SAMP>//2</SAMP></TD><TD>retrieve the phone number facet from the stream's locale, and
	<TR VALIGN="top"><TD><SAMP>//3</SAMP></TD><TD>store the country code table in the cache. The cache is accessible via the stream's <SAMP>parray</SAMP>.
	</TABLE>
	<A NAME="2693"><H3>26.9.3 Improving the Inserter</H3></A>
	<A NAME="idx613"><!></A>
	<P>We now have everything we need to improve our inserter. It registers a callback function that updates the cache whenever necessary. Registration is done only once, by declaring a static variable of class <SAMP>CallbackRegistrar</SAMP>.</P>

	<UL><PRE>
	std::ostream& operator<<(std::ostream& os, const phoneNumber& pn)
	{
	static phone_put::CodeMap codes =
	*(std::use_facet<phone_put>(os.getloc()).getCodes()); //1

	static CallbackRegistrar
	registrar(os,cacheCountryCodes,&codes); //2

	// some sophisticated output using the cached codes
	...
	}
	</PRE></UL>
	<TABLE CELLPADDING="3">

	<TR VALIGN="top"><TD><SAMP>//1</SAMP></TD><TD>The current country code table is cached.
	<TR VALIGN="top"><TD><SAMP>//2</SAMP></TD><TD>The callback function <SAMP>cacheCodesCallback()</SAMP> is registered.
	</TABLE>


	<BR>
	<HR>
	<A HREF="26-8.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="VIII.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>

	<!-- Google Analytics tracking code -->
	<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
	</script>
	<script type="text/javascript">
	_uacct = "UA-1775151-1";
	urchinTracker();
	</script>
	<!-- end of Google Analytics tracking code -->

	</BODY>
	</HTML>