+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a>
+</div>
+
+<div class="doc_text">
+
+<p>The use of <tt>#include <iostream></tt> in library files is
+hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
+support clients using LLVM libraries as part of larger systems. In particular,
+we statically link LLVM into some dynamic libraries. Even if LLVM isn't used,
+the static c'tors are run whenever an application start up that uses the dynamic
+library. There are two problems with this:</p>
+
+<ol>
+ <li>The time to run the static c'tors impacts startup time of
+ applications—a critical time for GUI apps.</li>
+ <li>The static c'tors cause the app to pull many extra pages of memory off the
+ disk: both the code for the static c'tors in each <tt>.o</tt> file and the
+ small amount of data that gets touched. In addition, touched/dirty pages
+ put more pressure on the VM system on low-memory machines.</li>
+</ol>
+
+<div align="center">
+<table>
+ <tbody>
+ <tr>
+ <th>Old Way</th>
+ <th>New Way</th>
+ </tr>
+ <tr>
+ <td align="left"><pre>#include <iostream></pre></td>
+ <td align="left"><pre>#include "llvm/Support/Streams.h"</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>DEBUG(std::cerr << ...);
+DEBUG(dump(std::cerr));</pre></td>
+ <td align="left"><pre>DOUT << ...;
+DEBUG(dump(DOUT));</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cerr << "Hello world\n";</pre></td>
+ <td align="left"><pre>llvm::cerr << "Hello world\n";</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cout << "Hello world\n";</pre></td>
+ <td align="left"><pre>llvm::cout << "Hello world\n";</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cin >> Var;</pre></td>
+ <td align="left"><pre>llvm::cin >> Var;</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::ostream</pre></td>
+ <td align="left"><pre>llvm::OStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::istream</pre></td>
+ <td align="left"><pre>llvm::IStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::stringstream</pre></td>
+ <td align="left"><pre>llvm::StringStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>void print(std::ostream &Out);
+// ...
+print(std::cerr);</pre></td>
+ <td align="left"><pre>void print(llvm::OStream Out);<sup>1</sup>
+// ...
+print(llvm::cerr);</pre>
+
+</td> </tbody> </table>
+</div>
+
+<div class="doc_text">
+<p><sup>1</sup><tt>llvm::OStream</tt> is a light-weight class so it should never
+be passed by reference. This is important because in some configurations,
+<tt>DOUT</tt> is an rvalue.</p>
+</div>
+
+</div>
+
+