1 files changed, 69 insertions, 0 deletions
diff --git a/documentation/content/xdocs/BewareStdStringLiterals.html b/documentation/content/xdocs/BewareStdStringLiterals.html
new file mode 100755
index 0000000000..b8388982c0
--- /dev/null
+++ b/documentation/content/xdocs/BewareStdStringLiterals.html
@@ -0,0 +1,69 @@
+<html>
+    <head>
+        <title>Apache Qpid : BewareStdStringLiterals</title>
+	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
+        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
+    </head>
+
+    <body>
+	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
+		    <tr>
+			    <td valign="top" class="pagebody">
+				    <div class="pageheader">
+					    <span class="pagetitle">
+                            Apache Qpid : BewareStdStringLiterals
+                                                    </span>
+				    </div>
+				    <div class="pagesubheading">
+					    This page last changed on Oct 19, 2006 by <font color="#0050B2">mmccorma</font>.
+				    </div>
+
+				    <p>The short story: in C++ code using <tt>std::string</tt> never use string literals except to initialize static-scoped <tt>std::string</tt> constants.<br/>
+(And by the way: <a href="http://cwiki.apache.org/confluence/display/qpid/NeverUseStaticLocalVariables" title="Visit page outside Confluence">NeverUseStaticLocalVariables</a></p>
+
+<p>The long story: <tt>std::string</tt> is all about avoiding copies. Reference counting and copy-on-write serve to maximise the sharing of a single heap-allocated char array while maintaining memory safety. When used consistently in a program it works rather nicely.</p>
+
+<p>However, when mixed with classic C-style string literals <tt>std::string</tt> can actually <em>cause</em> needless heap-allocated copies. Consider these innocent looking constructs:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">void f(<span class="code-keyword">const</span> std::string&amp; s);
+void g(<span class="code-keyword">const</span> std::string&amp; s = <span class="code-quote">"hello"</span>);
+std::string h() { <span class="code-keyword">return</span> <span class="code-quote">"foo"</span>; }
+
+void copy_surprise {
+  std::string x = <span class="code-quote">"x"</span>; <span class="code-comment">// 1
+</span>  f(<span class="code-quote">"y"</span>); <span class="code-comment">// 2
+</span>  g(); <span class="code-comment">// 3
+</span>  x = h(); <span class="code-comment">//4
+</span>  <span class="code-keyword">while</span> (x != <span class="code-quote">"end"</span>) { ... } <span class="code-comment">// 4
+</span>}</pre>
+</div></div>
+
+<p>Lines 1-4 all cause creation and destruction of an implicit temporary <tt>std::string</tt> to hold the literal value. Line 5 does this for every execution of the while loop. That's a new/memcpy/delete each time. The heap is a heavily used resource, in tight inner loops in multi-threaded code this can be a <em>severe</em> contention bottleneck that cripples scalability.</p>
+
+<p>Use static class <tt>std::string</tt> constants or file-private constants instead. You can make global declarations file-private by using a nameless namespace (this is preferred over the use of the <tt>static</tt>  keyword.)</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">namespace { 
+   <span class="code-keyword">const</span> std::string end(<span class="code-quote">"end"</span>);
+}
+void f() { std::string x; <span class="code-keyword">while</span> (x != end) {...} }</pre>
+</div></div>
+
+<p>And once again <a href="http://cwiki.apache.org/confluence/display/qpid/NeverUseStaticLocalVariables" title="Visit page outside Confluence">NeverUseStaticLocalVariables</a></p>
+
+
+				    
+                    			    </td>
+		    </tr>
+	    </table>
+	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
+			<tr>
+				<td height="12" background="border/border_bottom.gif"><img src="border/spacer.gif" width="1" height="1" border="0"/></td>
+			</tr>
+		    <tr>
+			    <td align="center"><font color="grey">Document generated by Confluence on Apr 22, 2008 02:47</font></td>
+		    </tr>
+	    </table>
+    </body>
+</html>
+\ No newline at end of file