diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index a1b4af02c34..a59a0b6334a 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,15 @@ +2011-09-27 Benjamin Kosnik + + * doc/html/*: Regenerate. + + * doc/Makefile.am: Un-nest the ext output directory. + * doc/Makefile.in: Regenerate. + * spine.xml: Remove authors, add abstract for short + contents. Rename to index.html for html output. + * manual/spine.xml: Authors here, manual starts with index.html. + * api.xml: Update. + * faq.xml: Same. + 2011-09-27 Marcus Shawcroft * libsupc++/tinfo.cc (type_info::operator==): Test __name instead @@ -16,7 +28,7 @@ * testsuite/23_containers/deque/modifiers/erase/50529.cc: Likewise. * testsuite/23_containers/deque/modifiers/erase/3.cc: Adjust. -2011-09-25 Benjamin Kosnik Jonathan Wakely PR libstdc++/48698 diff --git a/libstdc++-v3/doc/Makefile.am b/libstdc++-v3/doc/Makefile.am index 1e386826ee1..81c05b9ea27 100644 --- a/libstdc++-v3/doc/Makefile.am +++ b/libstdc++-v3/doc/Makefile.am @@ -477,8 +477,9 @@ ${docbook_outdir}/fo: ${docbook_outdir}/html: mkdir -p ${docbook_outdir}/html + mkdir -p ${docbook_outdir}/html/ext mkdir -p ${docbook_outdir}/html/images - mkdir -p ${docbook_outdir}/html/manual/ext + mkdir -p ${docbook_outdir}/html/manual ${docbook_outdir}/pdf: mkdir -p ${docbook_outdir}/pdf @@ -521,7 +522,7 @@ stamp-html-docbook-images: stamp-html-docbook $(xml_images) $(STAMP) stamp-html-docbook-images stamp-html-docbook-lwg: stamp-html-docbook $(xml_extra) - $(INSTALL_DATA) $(xml_extra) ${docbook_outdir}/html/manual/ext + $(INSTALL_DATA) $(xml_extra) ${docbook_outdir}/html/ext $(STAMP) stamp-html-docbook-lwg stamp-html-docbook-data: stamp-html-docbook-images stamp-html-docbook-lwg diff --git a/libstdc++-v3/doc/Makefile.in b/libstdc++-v3/doc/Makefile.in index ec3e1d282bd..43045671ccd 100644 --- a/libstdc++-v3/doc/Makefile.in +++ b/libstdc++-v3/doc/Makefile.in @@ -877,8 +877,9 @@ ${docbook_outdir}/fo: ${docbook_outdir}/html: mkdir -p ${docbook_outdir}/html + mkdir -p ${docbook_outdir}/html/ext mkdir -p ${docbook_outdir}/html/images - mkdir -p ${docbook_outdir}/html/manual/ext + mkdir -p ${docbook_outdir}/html/manual ${docbook_outdir}/pdf: mkdir -p ${docbook_outdir}/pdf @@ -907,7 +908,7 @@ stamp-html-docbook-images: stamp-html-docbook $(xml_images) $(STAMP) stamp-html-docbook-images stamp-html-docbook-lwg: stamp-html-docbook $(xml_extra) - $(INSTALL_DATA) $(xml_extra) ${docbook_outdir}/html/manual/ext + $(INSTALL_DATA) $(xml_extra) ${docbook_outdir}/html/ext $(STAMP) stamp-html-docbook-lwg stamp-html-docbook-data: stamp-html-docbook-images stamp-html-docbook-lwg diff --git a/libstdc++-v3/doc/html/api.html b/libstdc++-v3/doc/html/api.html index c70a8dfe731..feb596b299a 100644 --- a/libstdc++-v3/doc/html/api.html +++ b/libstdc++-v3/doc/html/api.html @@ -1,14 +1,14 @@ -The GNU C++ Library API Reference
The GNU C++ Library API Reference
Prev  Next

Copyright © +The GNU C++ Library API Reference

The GNU C++ Library API Reference
Prev  Next

The GNU C++ library sources have been specially formatted so that @@ -38,6 +38,9 @@

  • for the 4.5 release +

  • + for the 4.6 release +

  • "the latest collection" @@ -53,4 +56,4 @@

    In addition, a rendered set of man pages are available in the same location specified above. Start with C++Intro(3). -

    • Prev Up Next
     Home 
    +

    Prev Up Next
     Home 
    diff --git a/libstdc++-v3/doc/html/bk02.html b/libstdc++-v3/doc/html/bk02.html index 9c2d768c74b..f95372ebd79 100644 --- a/libstdc++-v3/doc/html/bk02.html +++ b/libstdc++-v3/doc/html/bk02.html @@ -1,3 +1,3 @@ -<meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><link rel="home" href="spine.html" title="The GNU C++ Library"/><link rel="up" href="spine.html" title="The GNU C++ Library"/><link rel="prev" href="manual/backwards.html" title="Backwards Compatibility"/><link rel="next" href="api.html" title="The GNU C++ Library API Reference"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"/></tr><tr><td align="left"><a accesskey="p" href="manual/backwards.html">Prev</a> </td><th width="60%" align="center"> </th><td align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr/></div><div class="book"><div class="titlepage"><hr/></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="article"><a href="api.html">The GNU C++ Library API Reference</a></span></dt></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="manual/backwards.html">Prev</a> </td><td align="center"> </td><td align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td align="left" valign="top">Backwards Compatibility </td><td align="center"><a accesskey="h" href="spine.html">Home</a></td><td align="right" valign="top"> The GNU C++ Library API Reference</td></tr></table></div></body></html> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title/><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , runtime , library "/><link rel="home" href="index.html" title="The GNU C++ Library"/><link rel="up" href="index.html" title="The GNU C++ Library"/><link rel="prev" href="manual/backwards.html" title="Backwards Compatibility"/><link rel="next" href="api.html" title="The GNU C++ Library API Reference"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"/></tr><tr><td align="left"><a accesskey="p" href="manual/backwards.html">Prev</a> </td><th width="60%" align="center"> </th><td align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr/></div><div class="book"><div class="titlepage"><hr/></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="article"><a href="api.html">The GNU C++ Library API Reference</a></span></dt></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="manual/backwards.html">Prev</a> </td><td align="center"> </td><td align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td align="left" valign="top">Backwards Compatibility </td><td align="center"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top"> The GNU C++ Library API Reference</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/bk03.html b/libstdc++-v3/doc/html/bk03.html index 6d1d2e9aacb..5a73901a9c9 100644 --- a/libstdc++-v3/doc/html/bk03.html +++ b/libstdc++-v3/doc/html/bk03.html @@ -1,3 +1,3 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"><head><title/><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><link rel="home" href="spine.html" title="The GNU C++ Library"/><link rel="up" href="spine.html" title="The GNU C++ Library"/><link rel="prev" href="api.html" title="The GNU C++ Library API Reference"/><link rel="next" href="faq.html" title="Frequently Asked Questions"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"/></tr><tr><td align="left"><a accesskey="p" href="api.html">Prev</a> </td><th width="60%" align="center"> </th><td align="right"> <a accesskey="n" href="faq.html">Next</a></td></tr></table><hr/></div><div class="book"><div class="titlepage"><hr/></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="article"><a href="faq.html">Frequently Asked Questions</a></span></dt></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="api.html">Prev</a> </td><td align="center"> </td><td align="right"> <a accesskey="n" href="faq.html">Next</a></td></tr><tr><td align="left" valign="top">The GNU C++ Library API Reference </td><td align="center"><a accesskey="h" href="spine.html">Home</a></td><td align="right" valign="top"> Frequently Asked Questions</td></tr></table></div></body></html> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title/><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , runtime , library "/><link rel="home" href="index.html" title="The GNU C++ Library"/><link rel="up" href="index.html" title="The GNU C++ Library"/><link rel="prev" href="api.html" title="The GNU C++ Library API Reference"/><link rel="next" href="faq.html" title="Frequently Asked Questions"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"/></tr><tr><td align="left"><a accesskey="p" href="api.html">Prev</a> </td><th width="60%" align="center"> </th><td align="right"> <a accesskey="n" href="faq.html">Next</a></td></tr></table><hr/></div><div class="book"><div class="titlepage"><hr/></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="article"><a href="faq.html">Frequently Asked Questions</a></span></dt></dl></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="api.html">Prev</a> </td><td align="center"> </td><td align="right"> <a accesskey="n" href="faq.html">Next</a></td></tr><tr><td align="left" valign="top">The GNU C++ Library API Reference </td><td align="center"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top"> Frequently Asked Questions</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/faq.html b/libstdc++-v3/doc/html/faq.html index 7667530732a..b4e05ed943f 100644 --- a/libstdc++-v3/doc/html/faq.html +++ b/libstdc++-v3/doc/html/faq.html @@ -1,10 +1,10 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Frequently Asked Questions
    Frequently Asked Questions
    Prev  
    Prev Up 
     Home 
    +

    Prev Up 
     Home 
    diff --git a/libstdc++-v3/doc/html/images/confdeps.png b/libstdc++-v3/doc/html/images/confdeps.png new file mode 100644 index 00000000000..55c07ba015e Binary files /dev/null and b/libstdc++-v3/doc/html/images/confdeps.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_balls_and_bins.png b/libstdc++-v3/doc/html/images/pbds_balls_and_bins.png new file mode 100644 index 00000000000..529c3ae41bc Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_balls_and_bins.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_binary_priority_queue_int_push.png b/libstdc++-v3/doc/html/images/pbds_binary_priority_queue_int_push.png new file mode 100644 index 00000000000..601d60fda8c Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_binary_priority_queue_int_push.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_binary_priority_queue_int_push_pop.png b/libstdc++-v3/doc/html/images/pbds_binary_priority_queue_int_push_pop.png new file mode 100644 index 00000000000..93637b06c85 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_binary_priority_queue_int_push_pop.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_cc_hash_int_find.png b/libstdc++-v3/doc/html/images/pbds_cc_hash_int_find.png new file mode 100644 index 00000000000..ee3518799d1 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_cc_hash_int_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_cc_hash_int_subscript_find.png b/libstdc++-v3/doc/html/images/pbds_cc_hash_int_subscript_find.png new file mode 100644 index 00000000000..6c66291f51d Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_cc_hash_int_subscript_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_cc_hash_int_subscript_insert.png b/libstdc++-v3/doc/html/images/pbds_cc_hash_int_subscript_insert.png new file mode 100644 index 00000000000..ba8478084bb Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_cc_hash_int_subscript_insert.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_ccgp_hash_int_subscript_insert.png b/libstdc++-v3/doc/html/images/pbds_ccgp_hash_int_subscript_insert.png new file mode 100644 index 00000000000..d36c47eb418 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_ccgp_hash_int_subscript_insert.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_container_tag_hierarchy.png b/libstdc++-v3/doc/html/images/pbds_container_tag_hierarchy.png new file mode 100644 index 00000000000..f827f6e0b03 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_container_tag_hierarchy.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_different_underlying_dss_1.png b/libstdc++-v3/doc/html/images/pbds_different_underlying_dss_1.png new file mode 100644 index 00000000000..adee1263600 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_different_underlying_dss_1.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_different_underlying_dss_2.png b/libstdc++-v3/doc/html/images/pbds_different_underlying_dss_2.png new file mode 100644 index 00000000000..9d84791fc0d Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_different_underlying_dss_2.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_embedded_lists_1.png b/libstdc++-v3/doc/html/images/pbds_embedded_lists_1.png new file mode 100644 index 00000000000..9470a65b568 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_embedded_lists_1.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_embedded_lists_2.png b/libstdc++-v3/doc/html/images/pbds_embedded_lists_2.png new file mode 100644 index 00000000000..d2ac91c1ab0 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_embedded_lists_2.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_embedded_lists_3.png b/libstdc++-v3/doc/html/images/pbds_embedded_lists_3.png new file mode 100644 index 00000000000..08ecb0ffe16 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_embedded_lists_3.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_exception_hierarchy.png b/libstdc++-v3/doc/html/images/pbds_exception_hierarchy.png new file mode 100644 index 00000000000..a7c33838253 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_exception_hierarchy.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_gp_hash_int_find.png b/libstdc++-v3/doc/html/images/pbds_gp_hash_int_find.png new file mode 100644 index 00000000000..66aa0481cdc Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_gp_hash_int_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_gp_hash_int_subscript_find.png b/libstdc++-v3/doc/html/images/pbds_gp_hash_int_subscript_find.png new file mode 100644 index 00000000000..d84733fe086 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_gp_hash_int_subscript_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_gp_hash_int_subscript_insert.png b/libstdc++-v3/doc/html/images/pbds_gp_hash_int_subscript_insert.png new file mode 100644 index 00000000000..27940fcd8be Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_gp_hash_int_subscript_insert.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_hash_int_erase_mem.png b/libstdc++-v3/doc/html/images/pbds_hash_int_erase_mem.png new file mode 100644 index 00000000000..d26ed8fd543 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_hash_int_erase_mem.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_hash_policy_cd.png b/libstdc++-v3/doc/html/images/pbds_hash_policy_cd.png new file mode 100644 index 00000000000..f3122a112fc Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_hash_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_hash_range_hashing_seq_diagram.png b/libstdc++-v3/doc/html/images/pbds_hash_range_hashing_seq_diagram.png new file mode 100644 index 00000000000..5c37407dda6 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_hash_range_hashing_seq_diagram.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_hash_range_hashing_seq_diagram2.png b/libstdc++-v3/doc/html/images/pbds_hash_range_hashing_seq_diagram2.png new file mode 100644 index 00000000000..87763caacc7 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_hash_range_hashing_seq_diagram2.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_hash_ranged_hash_range_hashing_fns.png b/libstdc++-v3/doc/html/images/pbds_hash_ranged_hash_range_hashing_fns.png new file mode 100644 index 00000000000..5e0d7f4037b Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_hash_ranged_hash_range_hashing_fns.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_hash_text_find.png b/libstdc++-v3/doc/html/images/pbds_hash_text_find.png new file mode 100644 index 00000000000..04c7eebb6e6 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_hash_text_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_hash_zlob_int_find.png b/libstdc++-v3/doc/html/images/pbds_hash_zlob_int_find.png new file mode 100644 index 00000000000..d4dac479c1c Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_hash_zlob_int_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram1.png b/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram1.png new file mode 100644 index 00000000000..f64764ec931 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram1.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram2.png b/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram2.png new file mode 100644 index 00000000000..e4645973eeb Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram2.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram3.png b/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram3.png new file mode 100644 index 00000000000..5535c5fe603 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_insert_resize_sequence_diagram3.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_invalidation_guarantee_erase.png b/libstdc++-v3/doc/html/images/pbds_invalidation_guarantee_erase.png new file mode 100644 index 00000000000..940a27f7142 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_invalidation_guarantee_erase.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_invalidation_tag_hierarchy.png b/libstdc++-v3/doc/html/images/pbds_invalidation_tag_hierarchy.png new file mode 100644 index 00000000000..570a70da969 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_invalidation_tag_hierarchy.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_list_update.png b/libstdc++-v3/doc/html/images/pbds_list_update.png new file mode 100644 index 00000000000..7c96dcaf665 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_list_update.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_find_large_s2p_hash.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_find_large_s2p_hash.png new file mode 100644 index 00000000000..cb9000fa41c Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_find_large_s2p_hash.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_find_large_s2p_tree.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_find_large_s2p_tree.png new file mode 100644 index 00000000000..12d062dbc05 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_find_large_s2p_tree.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_find_small_s2p_hash.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_find_small_s2p_hash.png new file mode 100644 index 00000000000..7c387198e2f Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_find_small_s2p_hash.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_find_small_s2p_tree.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_find_small_s2p_tree.png new file mode 100644 index 00000000000..2066376ee58 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_find_small_s2p_tree.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_large_s2p_hash.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_large_s2p_hash.png new file mode 100644 index 00000000000..09afca29a68 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_large_s2p_hash.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_large_s2p_tree.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_large_s2p_tree.png new file mode 100644 index 00000000000..a063d4b0934 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_large_s2p_tree.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_large_s2p_hash.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_large_s2p_hash.png new file mode 100644 index 00000000000..01b0884c163 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_large_s2p_hash.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_large_s2p_tree.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_large_s2p_tree.png new file mode 100644 index 00000000000..f88c9b9aa40 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_large_s2p_tree.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_small_s2p_hash.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_small_s2p_hash.png new file mode 100644 index 00000000000..a5c8cf60293 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_small_s2p_hash.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_small_s2p_tree.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_small_s2p_tree.png new file mode 100644 index 00000000000..88b59ae4c0e Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_mem_small_s2p_tree.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_small_s2p_hash.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_small_s2p_hash.png new file mode 100644 index 00000000000..9cf2a8e8d1a Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_small_s2p_hash.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_small_s2p_tree.png b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_small_s2p_tree.png new file mode 100644 index 00000000000..b851d21499d Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_multimap_text_insert_small_s2p_tree.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_node_invariants.png b/libstdc++-v3/doc/html/images/pbds_node_invariants.png new file mode 100644 index 00000000000..b375f5168d7 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_node_invariants.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_modify_down_thin.png b/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_modify_down_thin.png new file mode 100644 index 00000000000..3f56eebb083 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_modify_down_thin.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_modify_up_thin.png b/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_modify_up_thin.png new file mode 100644 index 00000000000..c647e4f5510 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_modify_up_thin.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_push.png b/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_push.png new file mode 100644 index 00000000000..9f7498a5f3e Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_push.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_push_pop.png b/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_push_pop.png new file mode 100644 index 00000000000..b56a35e17b5 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_pairing_priority_queue_text_push_pop.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_pat_trie.png b/libstdc++-v3/doc/html/images/pbds_pat_trie.png new file mode 100644 index 00000000000..e7129a1a67b Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_pat_trie.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_point_iterator_hierarchy.png b/libstdc++-v3/doc/html/images/pbds_point_iterator_hierarchy.png new file mode 100644 index 00000000000..25a69fc6e8b Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_point_iterator_hierarchy.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_point_iterators_range_ops_1.png b/libstdc++-v3/doc/html/images/pbds_point_iterators_range_ops_1.png new file mode 100644 index 00000000000..c5bc8e5d6c0 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_point_iterators_range_ops_1.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_point_iterators_range_ops_2.png b/libstdc++-v3/doc/html/images/pbds_point_iterators_range_ops_2.png new file mode 100644 index 00000000000..c3f94ee93bc Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_point_iterators_range_ops_2.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_different_underlying_dss.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_different_underlying_dss.png new file mode 100644 index 00000000000..9d84791fc0d Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_different_underlying_dss.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_int_push.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_int_push.png new file mode 100644 index 00000000000..fdc53c76258 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_int_push.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_int_push_pop.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_int_push_pop.png new file mode 100644 index 00000000000..56c841d5ece Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_int_push_pop.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_tag_hierarchy.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_tag_hierarchy.png new file mode 100644 index 00000000000..3a849d2d741 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_tag_hierarchy.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_text_join.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_join.png new file mode 100644 index 00000000000..5c3073d8f46 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_join.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_text_modify_down.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_modify_down.png new file mode 100644 index 00000000000..931812d13b0 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_modify_down.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_text_modify_up.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_modify_up.png new file mode 100644 index 00000000000..e8e76549e0d Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_modify_up.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_text_pop_mem.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_pop_mem.png new file mode 100644 index 00000000000..741aa8b94ef Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_pop_mem.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_text_push.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_push.png new file mode 100644 index 00000000000..0107d473ea7 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_push.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_priority_queue_text_push_pop.png b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_push_pop.png new file mode 100644 index 00000000000..5da52c3def3 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_priority_queue_text_push_pop.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_rationale_null_node_updator.png b/libstdc++-v3/doc/html/images/pbds_rationale_null_node_updator.png new file mode 100644 index 00000000000..43874891517 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_rationale_null_node_updator.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_resize_policy_cd.png b/libstdc++-v3/doc/html/images/pbds_resize_policy_cd.png new file mode 100644 index 00000000000..338e33c15cc Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_resize_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_restoring_node_invariants.png b/libstdc++-v3/doc/html/images/pbds_restoring_node_invariants.png new file mode 100644 index 00000000000..33ba84bfe33 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_restoring_node_invariants.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_simple_list.png b/libstdc++-v3/doc/html/images/pbds_simple_list.png new file mode 100644 index 00000000000..9a05d3f5e4f Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_simple_list.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_int_find.png b/libstdc++-v3/doc/html/images/pbds_tree_int_find.png new file mode 100644 index 00000000000..31bd80c5d87 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_int_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_node_invalidations.png b/libstdc++-v3/doc/html/images/pbds_tree_node_invalidations.png new file mode 100644 index 00000000000..bbd91842ba8 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_node_invalidations.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_node_invariants.png b/libstdc++-v3/doc/html/images/pbds_tree_node_invariants.png new file mode 100644 index 00000000000..b375f5168d7 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_node_invariants.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_node_updator_policy_cd.png b/libstdc++-v3/doc/html/images/pbds_tree_node_updator_policy_cd.png new file mode 100644 index 00000000000..5cae5781a18 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_node_updator_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_order_statistics.png b/libstdc++-v3/doc/html/images/pbds_tree_order_statistics.png new file mode 100644 index 00000000000..76177087f3c Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_order_statistics.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_split_join.png b/libstdc++-v3/doc/html/images/pbds_tree_split_join.png new file mode 100644 index 00000000000..dcbc2dbe0c3 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_split_join.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_text_find.png b/libstdc++-v3/doc/html/images/pbds_tree_text_find.png new file mode 100644 index 00000000000..ce4e606f756 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_text_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_text_insert_node.png b/libstdc++-v3/doc/html/images/pbds_tree_text_insert_node.png new file mode 100644 index 00000000000..4ec35d4b709 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_text_insert_node.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_text_insert_trie.png b/libstdc++-v3/doc/html/images/pbds_tree_text_insert_trie.png new file mode 100644 index 00000000000..3420298ce48 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_text_insert_trie.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_text_insert_vector.png b/libstdc++-v3/doc/html/images/pbds_tree_text_insert_vector.png new file mode 100644 index 00000000000..cdb367ef605 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_text_insert_vector.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_tree_text_lor_find.png b/libstdc++-v3/doc/html/images/pbds_tree_text_lor_find.png new file mode 100644 index 00000000000..acc4a6f274c Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_tree_text_lor_find.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_trie_node_updator_policy_cd.png b/libstdc++-v3/doc/html/images/pbds_trie_node_updator_policy_cd.png new file mode 100644 index 00000000000..4376929ec28 Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_trie_node_updator_policy_cd.png differ diff --git a/libstdc++-v3/doc/html/images/pbds_update_seq_diagram.png b/libstdc++-v3/doc/html/images/pbds_update_seq_diagram.png new file mode 100644 index 00000000000..880a50edf8e Binary files /dev/null and b/libstdc++-v3/doc/html/images/pbds_update_seq_diagram.png differ diff --git a/libstdc++-v3/doc/html/index.html b/libstdc++-v3/doc/html/index.html index b3b2ee69d6c..33e5ea69f33 100644 --- a/libstdc++-v3/doc/html/index.html +++ b/libstdc++-v3/doc/html/index.html @@ -1,43 +1,168 @@ - - - -The GNU C++ Library Documentation - - - - - - - -
    -

    The GNU C++ Library Documentation

    - -

    Copyright 2008, 2009 FSF

    - -

    - Permission is granted to copy, distribute and/or modify this - document under the terms of the GNU Free Documentation - License, Version 1.2 or any later version published by the - Free Software Foundation; with no Invariant Sections, with no - Front-Cover Texts, and with no Back-Cover Texts. -

    -

    - This is the top level of the libstdc++ documentation tree. - The documentation is contained in three logically separate - documents, as listed in the following Table of Contents. -

    -
    - - - - - + + +The GNU C++ Library
    The GNU C++ Library
       Next

    Short Contents

    + Copyright 2008, 2009, 2011 + FSF + +

    + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation + License, Version 1.2 or any later version published by the + Free Software Foundation; with no Invariant Sections, with no + Front-Cover Texts, and with no Back-Cover Texts. +

    + This is the top level of the libstdc++ documentation set. The + documentation is divided into the following three sections. +

    +

    +

    Table of Contents

    The GNU C++ Library Manual
    I. + Introduction - +
    1. Status
    Implementation Status
    C++ 1998/2003
    Implementation Status
    Implementation Specific Behavior
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs
    2. Setup
    Prerequisites
    Configure
    Make
    3. Using
    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Structure
    Defaults
    Future
    Alternatives
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    With C
    With POSIX thread cancellation
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Data Race Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis
    II. + Standard Contents +
    4. + Support + +
    Types
    Fundamental Types
    Numeric Properties
    NULL
    Dynamic Memory
    Termination
    Termination Handlers
    Verbose Terminate Handler
    5. + Diagnostics + +
    Exceptions
    API Reference
    Adding Data to exception
    Concept Checking
    6. + Utilities + +
    Functors
    Pairs
    Memory
    Allocators
    Requirements
    Design Issues
    Implementation
    Interface Design
    Selecting Default Allocation Policy
    Disabling Memory Caching
    Using a Specific Allocator
    Custom Allocators
    Extension Allocators
    auto_ptr
    Limitations
    Use in Containers
    shared_ptr
    Requirements
    Design Issues
    Implementation
    Class Hierarchy
    Thread Safety
    Selecting Lock Policy
    Dual C++0x and TR1 Implementation
    Related functions and classes
    Use
    Examples
    Unresolved Issues
    Acknowledgments
    Traits
    7. + Strings + +
    String Classes
    Simple Transformations
    Case Sensitivity
    Arbitrary Character Types
    Tokenizing
    Shrink to Fit
    CString (MFC)
    8. + Localization + +
    Locales
    locale
    Requirements
    Design
    Implementation
    Interacting with "C" locales
    Future
    Facets
    ctype
    Implementation
    Specializations
    Future
    codecvt
    Requirements
    Design
    wchar_t Size
    Support for Unicode
    Other Issues
    Implementation
    Use
    Future
    messages
    Requirements
    Design
    Implementation
    Models
    The GNU Model
    Use
    Future
    9. + Containers + +
    Sequences
    list
    list::size() is O(n)
    vector
    Space Overhead Management
    Associative
    Insertion Hints
    bitset
    Size Variable
    Type String
    Interacting with C
    Containers vs. Arrays
    10. + Iterators + +
    Predefined
    Iterators vs. Pointers
    One Past the End
    11. + Algorithms + +
    Mutating
    swap
    Specializations
    12. + Numerics + +
    Complex
    complex Processing
    Generalized Operations
    Interacting with C
    Numerics vs. Arrays
    C99
    13. + Input and Output + +
    Iostream Objects
    Stream Buffers
    Derived streambuf Classes
    Buffering
    Memory Based Streams
    Compatibility With strstream
    File Based Streams
    Copying a File
    Binary Input and Output
    Interacting with C
    Using FILE* and file descriptors
    Performance
    14. + Atomics + +
    API Reference
    15. + Concurrency + +
    API Reference
    III. + Extensions + +
    16. Compile Time Checks
    17. Debug Mode
    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    The Wrapper Model
    Safe Iterators
    Safe Sequences (Containers)
    Precondition Checking
    Release- and debug-mode coexistence
    Compile-time coexistence of release- and debug-mode components
    Link- and run-time coexistence of release- and + debug-mode components
    Alternatives for Coexistence
    Other Implementations
    18. Parallel Mode
    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Setting up the OpenMP Environment
    Compile Time Switches
    Run Time Settings and Defaults
    Implementation Namespaces
    Testing
    Bibliography
    19. Profile Mode
    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Hashtable Too Small
    Hashtable Too Large
    Inefficient Hash
    Vector Too Small
    Vector Too Large
    Vector to Hashtable
    Hashtable to Vector
    Vector to List
    List to Vector
    List to Forward List (Slist)
    Ordered to Unordered Associative Container
    Algorithms
    Sort Algorithm Performance
    Data Locality
    Need Software Prefetch
    Linked Structure Locality
    Multithreaded Data Access
    Data Dependence Violations at Container Level
    False Sharing
    Statistics
    Bibliography
    20. The mt_allocator
    Intro
    Design Issues
    Overview
    Implementation
    Tunable Parameters
    Initialization
    Deallocation Notes
    Single Thread Example
    Multiple Thread Example
    21. The bitmap_allocator
    Design
    Implementation
    Free List Store
    Super Block
    Super Block Data Layout
    Maximum Wasted Percentage
    allocate
    deallocate
    Questions
    1
    2
    3
    Locality
    Overhead and Grow Policy
    22. Policy-Based Data Structures
    Intro
    Performance Issues
    Associative
    Priority Que
    Goals
    Associative
    Policy Choices
    Underlying Data Structures
    Iterators
    Functional
    Priority Queues
    Policy Choices
    Underlying Data Structures
    Binary Heaps
    Using
    Prerequisites
    Organization
    Tutorial
    Basic Use
    + Configuring via Template Parameters +
    + Querying Container Attributes +
    + Point and Range Iteration +
    Examples
    Intermediate Use
    Querying with container_traits
    By Container Method
    Hash-Based
    Branch-Based
    Priority Queues
    Design
    Concepts
    Null Policy Classes
    Map and Set Semantics
    + Distinguishing Between Maps and Sets +
    Alternatives to std::multiset and std::multimap
    Iterator Semantics
    Point and Range Iterators
    Distinguishing Point and Range Iterators
    Invalidation Guarantees
    Genericity
    Tag
    Traits
    By Container
    hash
    Interface
    Details
    tree
    Interface
    Details
    Trie
    Interface
    Details
    List
    Interface
    Details
    Priority Queue
    Interface
    Details
    Testing
    Regression
    Performance
    Hash-Based
    + Text find +
    + Integer find +
    + Integer Subscript find +
    + Integer Subscript insert +
    + Integer find with Skewed-Distribution +
    + Erase Memory Use +
    Branch-Based
    + Text insert +
    + Text find +
    + Text find with Locality-of-Reference +
    + split and join +
    + Order-Statistics +
    Multimap
    + Text find with Small Secondary-to-Primary Key Ratios +
    + Text find with Large Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios Memory Use +
    + Text insert with Small + Secondary-to-Primary Key Ratios Memory Use +
    Priority Queue
    + Text push +
    + Text push and pop +
    + Integer push +
    + Integer push +
    + Text pop Memory Use +
    + Text join +
    + Text modify Up +
    + Text modify Down +
    Observations
    Associative
    Priority_Queue
    Acknowledgments
    + Bibliography +
    23. HP/SGI Extensions
    Backwards Compatibility
    Deprecated
    24. Utilities
    25. Algorithms
    26. Numerics
    27. Iterators
    28. Input and Output
    Derived filebufs
    29. Demangling
    30. Concurrency
    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use
    IV. + Appendices +
    A. + Contributing + +
    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Design Notes
    B. + Porting and Maintenance + +
    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Prerequisites
    Generating the Doxygen Files
    Markup
    Docbook
    Prerequisites
    Generating the DocBook Files
    Editing and Validation
    File Organization and Basics
    Markup By Example
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Directory Layout
    Naming Conventions
    Running the Testsuite
    Basic
    Variations
    Permutations
    Writing a new test case
    Test Harness and Utilities
    Dejagnu Harness Details
    Utilities
    Special Topics
    + Qualifying Exception Safety Guarantees + +
    Overview
    + Existing tests +
    +C++0x Requirements Test Sequence Descriptions +
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Goals
    History
    Prerequisites
    Configuring
    Checking Active
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Single ABI Testing
    Multiple ABI Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    No ios_base
    No cout in ostream.h, no cin in istream.h
    Second
    Namespace std:: not supported
    Illegal iterator usage
    isspace from cctype is a macro +
    No vector::at, deque::at, string::at
    No std::char_traits<char>::eof
    No string::clear
    + Removal of ostream::form and istream::scan + extensions +
    No basic_stringbuf, basic_stringstream
    Little or no wide character support
    No templatized iostreams
    Thread safety issues
    Third
    Pre-ISO headers moved to backwards or removed
    Extension headers hash_map, hash_set moved to ext or backwards
    No ios::nocreate/ios::noreplace. +
    +No stream::attach(int fd) +
    +Support for C++98 dialect. +
    +Support for C++TR1 dialect. +
    +Support for C++0x dialect. +
    + Container::iterator_type is not necessarily Container::value_type* +
    C. + Free Software Needs Free Documentation + +
    D. + GNU General Public License version 3 +
    E. GNU Free Documentation License
    The GNU C++ Library API Reference
    Frequently Asked Questions
       Next
       The GNU C++ Library Manual
    diff --git a/libstdc++-v3/doc/html/manual/abi.html b/libstdc++-v3/doc/html/manual/abi.html index 436be2d5e85..dd3e011b0b0 100644 --- a/libstdc++-v3/doc/html/manual/abi.html +++ b/libstdc++-v3/doc/html/manual/abi.html @@ -1,6 +1,6 @@ -ABI Policy and Guidelines
    ABI Policy and Guidelines
    Prev Appendix B.  +ABI Policy and Guidelines
    ABI Policy and Guidelines
    Prev Appendix B.  Porting and Maintenance  Next

    @@ -482,41 +482,51 @@ gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so. 24660: versioning weak symbols in libstdc++

    19664: libstdc++ headers should have pop/push of the visibility around the declarations -

    - . - ABIcheck, a vague idea of checking ABI compatibility - .

    - . - C++ ABI Reference - .

    - . +

    [biblio.abicheck] + + ABIcheck + + .

    [biblio.cxxabi] + + C++ ABI Summary + + .

    + Intel Compilers for Linux Compatibility with the GNU Compilers - .

    - . + + .

    + Linker and Libraries Guide (document 819-0690) - .

    - . + + .

    + Sun Studio 11: C++ Migration Guide (document 819-3689) - .

    - . + + .

    + How to Write Shared Libraries - . Ulrich Drepper.

    - . + + . Ulrich Drepper.

    + C++ ABI for the ARM Architecture - .

    - . + + .

    + Dynamic Shared Objects: Survey and Issues - . + + . ISO C++ J16/06-0046 - . Benjamin Kosnik.

    - . + . Benjamin Kosnik.

    + Versioning With Namespaces + . ISO C++ J16/06-0083 - . Benjamin Kosnik.

    - . + . Benjamin Kosnik.

    + Binary Compatibility of Shared Libraries Implemented in C++ on GNU/Linux Systems - . + + . SYRCoSE 2009 - . Pavel Shved. Denis Silakov.

    Prev Up Next
    Test Home API Evolution and Deprecation History
    + . Pavel Shved. Denis Silakov.

    Prev Up Next
    Test Home API Evolution and Deprecation History
    diff --git a/libstdc++-v3/doc/html/manual/algorithms.html b/libstdc++-v3/doc/html/manual/algorithms.html index 8cf55cf8651..dfbb967653d 100644 --- a/libstdc++-v3/doc/html/manual/algorithms.html +++ b/libstdc++-v3/doc/html/manual/algorithms.html @@ -1,14 +1,14 @@ -Chapter 11.  Algorithms
    Chapter 11.  +Chapter 11.  Algorithms
    Chapter 11.  Algorithms
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Mutating
    swap

    + +

    Table of Contents

    Mutating
    swap
    Specializations

    The neatest accomplishment of the algorithms sect1 is that all the work is done via iterators, not containers directly. This means two important things: @@ -55,7 +55,7 @@

    Prev Up Next
    Chapter 10.  Iterators - Home Chapter 12.  + Home Chapter 12.  Numerics
    diff --git a/libstdc++-v3/doc/html/manual/api.html b/libstdc++-v3/doc/html/manual/api.html index cd9541d01ba..59ca7bca99f 100644 --- a/libstdc++-v3/doc/html/manual/api.html +++ b/libstdc++-v3/doc/html/manual/api.html @@ -1,6 +1,6 @@ -API Evolution and Deprecation History
    API Evolution and Deprecation History
    Prev Appendix B.  +API Evolution and Deprecation History
    API Evolution and Deprecation History
    Prev Appendix B.  Porting and Maintenance  Next

    @@ -75,11 +75,11 @@ _Alloc_traits have been removed. __alloc to select an underlying allocator that satisfied memory allocation requests. The selection of this underlying allocator was not user-configurable. -

    Table B.6. Extension Allocators

    Allocator (3.4)Header (3.4)Allocator (3.[0-3])Header (3.[0-3])
    __gnu_cxx::new_allocator<T>ext/new_allocator.hstd::__new_allocmemory
    __gnu_cxx::malloc_allocator<T>ext/malloc_allocator.hstd::__malloc_alloc_template<int>memory
    __gnu_cxx::debug_allocator<T>ext/debug_allocator.hstd::debug_alloc<T>memory
    __gnu_cxx::__pool_alloc<T>ext/pool_allocator.hstd::__default_alloc_template<bool,int>memory
    __gnu_cxx::__mt_alloc<T>ext/mt_allocator.h
    __gnu_cxx::bitmap_allocator<T>ext/bitmap_allocator.h

    Releases after gcc-3.4 have continued to add to the collection +

    Table B.6. Extension Allocators

    Allocator (3.4)Header (3.4)Allocator (3.[0-3])Header (3.[0-3])
    __gnu_cxx::new_allocator<T>ext/new_allocator.hstd::__new_allocmemory
    __gnu_cxx::malloc_allocator<T>ext/malloc_allocator.hstd::__malloc_alloc_template<int>memory
    __gnu_cxx::debug_allocator<T>ext/debug_allocator.hstd::debug_alloc<T>memory
    __gnu_cxx::__pool_alloc<T>ext/pool_allocator.hstd::__default_alloc_template<bool,int>memory
    __gnu_cxx::__mt_alloc<T>ext/mt_allocator.h
    __gnu_cxx::bitmap_allocator<T>ext/bitmap_allocator.h

    Releases after gcc-3.4 have continued to add to the collection of available allocators. All of these new allocators are standard-style. The following table includes details, along with the first released version of GCC that included the extension allocator. -

    Table B.7. Extension Allocators Continued

    AllocatorIncludeVersion
    __gnu_cxx::array_allocator<T>ext/array_allocator.h4.0.0
    __gnu_cxx::throw_allocator<T>ext/throw_allocator.h4.2.0

    +

    Table B.7. Extension Allocators Continued

    AllocatorIncludeVersion
    __gnu_cxx::array_allocator<T>ext/array_allocator.h4.0.0
    __gnu_cxx::throw_allocator<T>ext/throw_allocator.h4.2.0

    Debug mode first appears.

    Precompiled header support PCH support. @@ -237,4 +237,4 @@ The default behavior for comparing typeinfo names changed, so in typeinfo, __GXX_MERGED_TYPEINFO_NAMES now defaults to zero.

    Extensions modified: ext/throw_allocator.h. -

    Prev Up Next
    ABI Policy and Guidelines Home Backwards Compatibility
    +

    Prev Up Next
    ABI Policy and Guidelines Home Backwards Compatibility
    diff --git a/libstdc++-v3/doc/html/manual/appendix_contributing.html b/libstdc++-v3/doc/html/manual/appendix_contributing.html index bbf124164d2..0aefd110331 100644 --- a/libstdc++-v3/doc/html/manual/appendix_contributing.html +++ b/libstdc++-v3/doc/html/manual/appendix_contributing.html @@ -1,13 +1,13 @@ -Appendix A.  Contributing
    Appendix A.  +Appendix A.  Contributing
    Appendix A.  Contributing
    Prev Part IV.  Appendices  Next

    Table of Contents

    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Design Notes

    The GNU C++ Library follows an open development model. Active contributors are assigned maintainer-ship responsibility, and given @@ -114,4 +114,4 @@ libstdc++ mailing list.

    Prev Up Next
    Part IV.  Appendices - Home Directory Layout and Source Conventions
    +     		Home Directory Layout and Source Conventions
    diff --git a/libstdc++-v3/doc/html/manual/appendix_free.html b/libstdc++-v3/doc/html/manual/appendix_free.html index 8449abb6184..7174e48ae93 100644 --- a/libstdc++-v3/doc/html/manual/appendix_free.html +++ b/libstdc++-v3/doc/html/manual/appendix_free.html @@ -1,13 +1,13 @@ -Appendix C.  Free Software Needs Free Documentation
    Appendix C.  +Appendix C.  Free Software Needs Free Documentation
    Appendix C.  Free Software Needs Free Documentation
    Prev Part IV.  Appendices  Next

    The biggest deficiency in free operating systems is not in the software--it is the lack of good free manuals that we can include in @@ -121,6 +121,6 @@ prefer copylefted manuals to non-copylefted ones. that lists free books available from other publishers].

    Copyright © 2004, 2005, 2006, 2007 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

    Verbatim copying and distribution of this entire article are permitted worldwide, without royalty, in any medium, provided this -notice is preserved.

    Report any problems or suggestions to .

    Prev Up Next
    Backwards Compatibility Home Appendix D.  +notice is preserved.

    Report any problems or suggestions to .

    Prev Up Next
    Backwards Compatibility Home Appendix D.  GNU General Public License version 3
    diff --git a/libstdc++-v3/doc/html/manual/appendix_gfdl.html b/libstdc++-v3/doc/html/manual/appendix_gfdl.html index 9a46f18d112..dc1088a241f 100644 --- a/libstdc++-v3/doc/html/manual/appendix_gfdl.html +++ b/libstdc++-v3/doc/html/manual/appendix_gfdl.html @@ -1,6 +1,6 @@ -Appendix E. GNU Free Documentation License
    Appendix E. GNU Free Documentation License
    Prev Part IV.  +Appendix E. GNU Free Documentation License
    Appendix E. GNU Free Documentation License
    Prev Part IV.  Appendices  Next

    Version 1.3, 3 November 2008

    Copyright © 2000, 2001, 2002, 2007, 2008 @@ -446,4 +446,4 @@ being LIST, and with the Back-Cover Texts being LIST.

    use in free software.

    Prev Up Next
    Appendix D.  GNU General Public License version 3 -  Home 
    +      		Home 
    diff --git a/libstdc++-v3/doc/html/manual/appendix_gpl.html b/libstdc++-v3/doc/html/manual/appendix_gpl.html index 376ac4ebd30..348d6fad2ca 100644 --- a/libstdc++-v3/doc/html/manual/appendix_gpl.html +++ b/libstdc++-v3/doc/html/manual/appendix_gpl.html @@ -1,6 +1,6 @@ -Appendix D.  GNU General Public License version 3
    Appendix D.  +Appendix D.  GNU General Public License version 3
    Appendix D.  GNU General Public License version 3
    Prev Part IV.  Appendices @@ -78,7 +78,7 @@

    The precise terms and conditions for copying, distribution and modification follow. -

    +

    TERMS AND CONDITIONS

    0. Definitions. @@ -619,7 +619,7 @@ waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. -

    +

    END OF TERMS AND CONDITIONS

    How to Apply These Terms to Your New Programs @@ -680,4 +680,4 @@ under certain conditions; type ‘show c’ for det

    Prev Up Next
    Appendix C.  Free Software Needs Free Documentation - Home Appendix E. GNU Free Documentation License
    + 

    		Home Appendix E. GNU Free Documentation License
    diff --git a/libstdc++-v3/doc/html/manual/appendix_porting.html b/libstdc++-v3/doc/html/manual/appendix_porting.html index 9fc23776388..b2b0d387314 100644 --- a/libstdc++-v3/doc/html/manual/appendix_porting.html +++ b/libstdc++-v3/doc/html/manual/appendix_porting.html @@ -1,14 +1,36 @@ -Appendix B.  Porting and Maintenance
    Appendix B.  +Appendix B.  Porting and Maintenance
    Appendix B.  Porting and Maintenance
    Prev Part IV.  Appendices  Next

    Table of Contents

    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Docbook
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Running the Testsuite
    Writing a new test case
    Test Harness and Utilities
    Special Topics
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    Second
    Third

    + +

    Table of Contents

    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Prerequisites
    Generating the Doxygen Files
    Markup
    Docbook
    Prerequisites
    Generating the DocBook Files
    Editing and Validation
    File Organization and Basics
    Markup By Example
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Directory Layout
    Naming Conventions
    Running the Testsuite
    Basic
    Variations
    Permutations
    Writing a new test case
    Test Harness and Utilities
    Dejagnu Harness Details
    Utilities
    Special Topics
    + Qualifying Exception Safety Guarantees + +
    Overview
    + Existing tests +
    +C++0x Requirements Test Sequence Descriptions +
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Goals
    History
    Prerequisites
    Configuring
    Checking Active
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Single ABI Testing
    Multiple ABI Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    No ios_base
    No cout in ostream.h, no cin in istream.h
    Second
    Namespace std:: not supported
    Illegal iterator usage
    isspace from cctype is a macro +
    No vector::at, deque::at, string::at
    No std::char_traits<char>::eof
    No string::clear
    + Removal of ostream::form and istream::scan + extensions +
    No basic_stringbuf, basic_stringstream
    Little or no wide character support
    No templatized iostreams
    Thread safety issues
    Third
    Pre-ISO headers moved to backwards or removed
    Extension headers hash_map, hash_set moved to ext or backwards
    No ios::nocreate/ios::noreplace. +
    +No stream::attach(int fd) +
    +Support for C++98 dialect. +
    +Support for C++TR1 dialect. +
    +Support for C++0x dialect. +
    + Container::iterator_type is not necessarily Container::value_type* +

    As noted previously, certain other tools are necessary for hacking on files that control configure (configure.ac, @@ -19,7 +41,7 @@ in GCC try to stay in sync with each other in terms of versions of the auto-tools used, so please try to play nicely with the neighbors. -

    Figure B.1. Configure and Build File Dependencies

    Dependency Graph for Configure and Build Files

    +

    Figure B.1. Configure and Build File Dependencies

    Dependency Graph for Configure and Build Files

    Regenerate all generated files by using the command sequence "autoreconf" at the top level of the libstdc++ source directory. The following will also work, but is much more complex: @@ -227,4 +249,4 @@ argument checking at all is done in this signature. See GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error message. -

    Prev Up Next
    Design Notes Home Writing and Generating Documentation
    +

    Prev Up Next
    Design Notes Home Writing and Generating Documentation
    diff --git a/libstdc++-v3/doc/html/manual/associative.html b/libstdc++-v3/doc/html/manual/associative.html index 351ec9402ee..587b75643b9 100644 --- a/libstdc++-v3/doc/html/manual/associative.html +++ b/libstdc++-v3/doc/html/manual/associative.html @@ -1,6 +1,6 @@ -Associative
    Associative
    Prev Chapter 9.  +Associative
    Associative
    Prev Chapter 9.  Containers  Next

    @@ -168,7 +168,7 @@ author would love to hear from you...

    Also note that the implementation of bitset used in libstdc++ has - some extensions. + some extensions.

    Bitmasks do not take char* nor const char* arguments in their @@ -189,4 +189,4 @@

    Prev Up Next
    Chapter 9.  Containers - Home Interacting with C
    +     		Home Interacting with C
    diff --git a/libstdc++-v3/doc/html/manual/atomics.html b/libstdc++-v3/doc/html/manual/atomics.html index 1a24059a904..d22415ab3cd 100644 --- a/libstdc++-v3/doc/html/manual/atomics.html +++ b/libstdc++-v3/doc/html/manual/atomics.html @@ -1,13 +1,13 @@ -Chapter 14.  Atomics
    Chapter 14.  +Chapter 14.  Atomics
    Chapter 14.  Atomics
    Prev Part II.  Standard Contents  Next

    Table of Contents

    API Reference

    Facilities for atomic operations.

    @@ -25,7 +25,7 @@ atomic<int>.

    Full API details. -

    Prev Up Next
    Interacting with C Home Chapter 15.  +

    Prev Up Next
    Interacting with C Home Chapter 15.  Concurrency
    diff --git a/libstdc++-v3/doc/html/manual/backwards.html b/libstdc++-v3/doc/html/manual/backwards.html index 2497438a1e9..fa7d92cd311 100644 --- a/libstdc++-v3/doc/html/manual/backwards.html +++ b/libstdc++-v3/doc/html/manual/backwards.html @@ -1,6 +1,6 @@ -Backwards Compatibility
    Backwards Compatibility
    Prev Appendix B.  +Backwards Compatibility
    Backwards Compatibility
    Prev Appendix B.  Porting and Maintenance  Next

    The first generation GNU C++ library was called libg++. It was a @@ -17,8 +17,8 @@ ISO Standard (e.g., statistical analysis). While there are a lot of really useful things that are used by a lot of people, the Standards Committee couldn't include everything, and so a lot of those “obvious” classes didn't get included. -

    Known Issues include many of the limitations of its immediate ancestor.

    Portability notes and known implementation limitations are as follows.

    At least some older implementations don't have std::ios_base, so you should use std::ios::badbit, std::ios::failbit and std::ios::eofbit and std::ios::goodbit. -

    +

    Known Issues include many of the limitations of its immediate ancestor.

    Portability notes and known implementation limitations are as follows.

    At least some older implementations don't have std::ios_base, so you should use std::ios::badbit, std::ios::failbit and std::ios::eofbit and std::ios::goodbit. +

    In earlier versions of the standard, fstream.h, ostream.h @@ -44,7 +44,7 @@ considered replaced and rewritten. archived. The code is considered replaced and rewritten.

    Portability notes and known implementation limitations are as follows. -

    +

    Some care is required to support C++ compiler and or library implementation that do not have the standard library in namespace std. @@ -108,7 +108,7 @@ AC_DEFUN([AC_CXX_NAMESPACE_STD], [ AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ]) fi ]) -

    +

    The following illustrate implementation-allowed illegal iterator use, and then correct use.

    Glibc 2.0.x and 2.1.x define ctype.h functionality as macros (isspace, isalpha etc.). @@ -154,7 +154,7 @@ std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; (ctype.h) and the definitions in namespace std:: (<cctype>). -

    +

    One solution is to add an autoconf-test for this: 

     AC_MSG_CHECKING(for container::at)
@@ -180,7 +180,7 @@ AC_DEFINE(HAVE_CONTAINER_AT)],

    If you are using other (non-GNU) compilers it might be a good idea to check for string::at separately. -

    +

    Use some kind of autoconf test, plus this: 

     #ifdef HAVE_CHAR_TRAITS
@@ -188,7 +188,7 @@ AC_DEFINE(HAVE_CONTAINER_AT)],
 #else
 #define CPP_EOF EOF
 #endif
-

    +

    There are two functions for deleting the contents of a string: clear and erase (the latter returns the string). @@ -206,12 +206,12 @@ erase(size_type __pos = 0, size_type __n = npos) Unfortunately, clear is not implemented in this version, so you should use erase (which is probably faster than operator=(charT*)). -

    These are no longer supported. Please use stringstreams instead. -

    +

    Although the ISO standard i/ostringstream-classes are provided, (sstream), for compatibility with older implementations the pre-ISO @@ -299,14 +299,14 @@ any = temp; Another example of using stringstreams is in this howto.

    There is additional information in the libstdc++-v2 info files, in particular “info iostream”. -

    +

    Classes wstring and char_traits<wchar_t> are not supported. -

    +

    Classes wfilebuf and wstringstream are not supported. -

    +

    Earlier GCC releases had a somewhat different approach to threading configuration and proper compilation. Before GCC 3.0, configuration of the threading model was dictated by compiler @@ -364,7 +364,7 @@ libstdc++-v3. of the SGI STL (version 3.3), with extensive changes.

    A more formal description of the V3 goals can be found in the official design document. -

    Portability notes and known implementation limitations are as follows.

    The pre-ISO C++ headers +

    Portability notes and known implementation limitations are as follows.

    The pre-ISO C++ headers (iostream.h, defalloc.h etc.) are available, unlike previous libstdc++ versions, but inclusion generates a warning that you are using deprecated headers. @@ -436,7 +436,7 @@ like vector.h can be replaced with using namespace std; can be put at the global scope. This should be enough to get this code compiling, assuming the other usage is correct. -

    At this time most of the features of the SGI STL extension have been +

    At this time most of the features of the SGI STL extension have been replaced by standardized libraries. In particular, the unordered_map and unordered_set containers of TR1 are suitable replacement for the non-standard hash_map and hash_set @@ -508,7 +508,7 @@ AC_DEFUN([AC_HEADER_EXT_HASH_SET], [ AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ]) fi ]) -

    The existence of ios::nocreate being used for input-streams has been confirmed, most probably because the author thought it would be more correct to specify nocreate explicitly. So @@ -519,7 +519,7 @@ open the file for reading, check if it has been opened, and then decide whether you want to create/replace or not. To my knowledge, even older implementations support app, ate and trunc (except for app ?). -

    Phil Edwards writes: It was considered and rejected for the ISO @@ -542,7 +542,7 @@ No stream::attach(int fd) For another example of this, refer to fdstream example by Nicolai Josuttis. -

    Check for complete library coverage of the C++1998/2003 standard. 

    @@ -610,7 +610,7 @@ AC_DEFUN([AC_HEADER_STDCXX_98], [
     AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ])
   fi
 ])
-

    Check for library coverage of the TR1 standard. 

    @@ -687,7 +687,7 @@ AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [
     AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ])
   fi
 ])
-

    Check for baseline language coverage in the compiler for the C++0xstandard. 

    @@ -899,22 +899,25 @@ AC_DEFUN([AC_HEADER_UNORDERED_SET], [
     AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ])
   fi
 ])
-

    - . +

    + Migrating to GCC 4.1 - . Dan Kegel.

    - . + + . Dan Kegel.

    + Building the Whole Debian Archive with GCC 4.1: A Summary - . Martin Michlmayr.

    - . + + . Martin Michlmayr.

    + Migration guide for GCC-3.2 - .

    Prev Up Next
    API Evolution and Deprecation History Home Appendix C.  + + .

    Prev Up Next
    API Evolution and Deprecation History Home Appendix C.  Free Software Needs Free Documentation
    diff --git a/libstdc++-v3/doc/html/manual/bitmap_allocator.html b/libstdc++-v3/doc/html/manual/bitmap_allocator.html index 9f750e9c0dc..d73a5d1d7fa 100644 --- a/libstdc++-v3/doc/html/manual/bitmap_allocator.html +++ b/libstdc++-v3/doc/html/manual/bitmap_allocator.html @@ -1,7 +1,10 @@ -bitmap_allocator
    bitmap_allocator
    Prev Chapter 20. Allocators Next

    -

    +Chapter 21. The bitmap_allocator

    Chapter 21. The bitmap_allocator
    Prev Part III.  + Extensions + + Next

    Table of Contents

    Design
    Implementation
    Free List Store
    Super Block
    Super Block Data Layout
    Maximum Wasted Percentage
    allocate
    deallocate
    Questions
    1
    2
    3
    Locality
    Overhead and Grow Policy

    +

    As this name suggests, this allocator uses a bit-map to keep track of the used and unused memory locations for its book-keeping purposes. @@ -27,314 +30,4 @@ Mutex Protection around every allocation/deallocation. The state of the macro is picked up automatically from the gthr abstraction layer. -

    - The Free List Store (referred to as FLS for the remaining part of this - document) is the Global memory pool that is shared by all instances of - the bitmapped allocator instantiated for any type. This maintains a - sorted order of all free memory blocks given back to it by the - bitmapped allocator, and is also responsible for giving memory to the - bitmapped allocator when it asks for more. -

    - Internally, there is a Free List threshold which indicates the - Maximum number of free lists that the FLS can hold internally - (cache). Currently, this value is set at 64. So, if there are - more than 64 free lists coming in, then some of them will be given - back to the OS using operator delete so that at any given time the - Free List's size does not exceed 64 entries. This is done because - a Binary Search is used to locate an entry in a free list when a - request for memory comes along. Thus, the run-time complexity of - the search would go up given an increasing size, for 64 entries - however, lg(64) == 6 comparisons are enough to locate the correct - free list if it exists. -

    - Suppose the free list size has reached its threshold, then the - largest block from among those in the list and the new block will - be selected and given back to the OS. This is done because it - reduces external fragmentation, and allows the OS to use the - larger blocks later in an orderly fashion, possibly merging them - later. Also, on some systems, large blocks are obtained via calls - to mmap, so giving them back to free system resources becomes most - important. -

    - The function _S_should_i_give decides the policy that determines - whether the current block of memory should be given to the - allocator for the request that it has made. That's because we may - not always have exact fits for the memory size that the allocator - requests. We do this mainly to prevent external fragmentation at - the cost of a little internal fragmentation. Now, the value of - this internal fragmentation has to be decided by this function. I - can see 3 possibilities right now. Please add more as and when you - find better strategies. -

    1. Equal size check. Return true only when the 2 blocks are of equal -size.

    2. Difference Threshold: Return true only when the _block_size is -greater than or equal to the _required_size, and if the _BS is > _RS -by a difference of less than some THRESHOLD value, then return true, -else return false.

    3. Percentage Threshold. Return true only when the _block_size is -greater than or equal to the _required_size, and if the _BS is > _RS -by a percentage of less than some THRESHOLD value, then return true, -else return false.

    - Currently, (3) is being used with a value of 36% Maximum wastage per - Super Block. -

    - A super block is the block of memory acquired from the FLS from - which the bitmap allocator carves out memory for single objects - and satisfies the user's requests. These super blocks come in - sizes that are powers of 2 and multiples of 32 - (_Bits_Per_Block). Yes both at the same time! That's because the - next super block acquired will be 2 times the previous one, and - also all super blocks have to be multiples of the _Bits_Per_Block - value. -

    - How does it interact with the free list store? -

    - The super block is contained in the FLS, and the FLS is responsible for - getting / returning Super Bocks to and from the OS using operator new - as defined by the C++ standard. -

    - Each Super Block will be of some size that is a multiple of the - number of Bits Per Block. Typically, this value is chosen as - Bits_Per_Byte x sizeof(size_t). On an x86 system, this gives the - figure 8 x 4 = 32. Thus, each Super Block will be of size 32 - x Some_Value. This Some_Value is sizeof(value_type). For now, let - it be called 'K'. Thus, finally, Super Block size is 32 x K bytes. -

    - This value of 32 has been chosen because each size_t has 32-bits - and Maximum use of these can be made with such a figure. -

    - Consider a block of size 64 ints. In memory, it would look like this: - (assume a 32-bit system where, size_t is a 32-bit entity). -

    Table 20.1. Bitmap Allocator Memory Map

    268042949672954294967295Data -> Space for 64 ints

    - The first Column(268) represents the size of the Block in bytes as - seen by the Bitmap Allocator. Internally, a global free list is - used to keep track of the free blocks used and given back by the - bitmap allocator. It is this Free List Store that is responsible - for writing and managing this information. Actually the number of - bytes allocated in this case would be: 4 + 4 + (4x2) + (64x4) = - 272 bytes, but the first 4 bytes are an addition by the Free List - Store, so the Bitmap Allocator sees only 268 bytes. These first 4 - bytes about which the bitmapped allocator is not aware hold the - value 268. -

    - What do the remaining values represent?

    - The 2nd 4 in the expression is the sizeof(size_t) because the - Bitmapped Allocator maintains a used count for each Super Block, - which is initially set to 0 (as indicated in the diagram). This is - incremented every time a block is removed from this super block - (allocated), and decremented whenever it is given back. So, when - the used count falls to 0, the whole super block will be given - back to the Free List Store. -

    - The value 4294967295 represents the integer corresponding to the bit - representation of all bits set: 11111111111111111111111111111111. -

    - The 3rd 4x2 is size of the bitmap itself, which is the size of 32-bits - x 2, - which is 8-bytes, or 2 x sizeof(size_t). -

    - This has nothing to do with the algorithm per-se, - only with some vales that must be chosen correctly to ensure that the - allocator performs well in a real word scenario, and maintains a good - balance between the memory consumption and the allocation/deallocation - speed. -

    - The formula for calculating the maximum wastage as a percentage: -

    -(32 x k + 1) / (2 x (32 x k + 1 + 32 x c)) x 100. -

    - where k is the constant overhead per node (e.g., for list, it is - 8 bytes, and for map it is 12 bytes) and c is the size of the - base type on which the map/list is instantiated. Thus, suppose the - type1 is int and type2 is double, they are related by the relation - sizeof(double) == 2*sizeof(int). Thus, all types must have this - double size relation for this formula to work properly. -

    - Plugging-in: For List: k = 8 and c = 4 (int and double), we get: - 33.376% -

    -For map/multimap: k = 12, and c = 4 (int and double), we get: 37.524% -

    - Thus, knowing these values, and based on the sizeof(value_type), we may - create a function that returns the Max_Wastage_Percentage for us to use. -

    - The allocate function is specialized for single object allocation - ONLY. Thus, ONLY if n == 1, will the bitmap_allocator's - specialized algorithm be used. Otherwise, the request is satisfied - directly by calling operator new. -

    - Suppose n == 1, then the allocator does the following: -

    1. - Checks to see whether a free block exists somewhere in a region - of memory close to the last satisfied request. If so, then that - block is marked as allocated in the bit map and given to the - user. If not, then (2) is executed. -

    2. - Is there a free block anywhere after the current block right - up to the end of the memory that we have? If so, that block is - found, and the same procedure is applied as above, and - returned to the user. If not, then (3) is executed. -

    3. - Is there any block in whatever region of memory that we own - free? This is done by checking -

      - Note: Here we are never touching any of the memory that the - user will be given, and we are confining all memory accesses - to a small region of memory! This helps reduce cache - misses. If this succeeds then we apply the same procedure on - that bit-map as (1), and return that block of memory to the - user. However, if this process fails, then we resort to (4). -

    4. - This process involves Refilling the internal exponentially - growing memory pool. The said effect is achieved by calling - _S_refill_pool which does the following: -

    -Thus, you can clearly see that the allocate function is nothing but a -combination of the next-fit and first-fit algorithm optimized ONLY for -single object allocations. -

    - The deallocate function again is specialized for single objects ONLY. - For all n belonging to > 1, the operator delete is called without - further ado, and the deallocate function returns. -

    - However for n == 1, a series of steps are performed: -

    1. - We first need to locate that super-block which holds the memory - location given to us by the user. For that purpose, we maintain - a static variable _S_last_dealloc_index, which holds the index - into the vector of block pairs which indicates the index of the - last super-block from which memory was freed. We use this - strategy in the hope that the user will deallocate memory in a - region close to what he/she deallocated the last time around. If - the check for belongs_to succeeds, then we determine the bit-map - for the given pointer, and locate the index into that bit-map, - and mark that bit as free by setting it. -

    2. - If the _S_last_dealloc_index does not point to the memory block - that we're looking for, then we do a linear search on the block - stored in the vector of Block Pairs. This vector in code is - called _S_mem_blocks. When the corresponding super-block is - found, we apply the same procedure as we did for (1) to mark the - block as free in the bit-map. -

    - Now, whenever a block is freed, the use count of that particular - super block goes down by 1. When this use count hits 0, we remove - that super block from the list of all valid super blocks stored in - the vector. While doing this, we also make sure that the basic - invariant is maintained by making sure that _S_last_request and - _S_last_dealloc_index point to valid locations within the vector. -

    -Q1) The "Data Layout" section is -cryptic. I have no idea of what you are trying to say. Layout of what? -The free-list? Each bitmap? The Super Block? -

    - The layout of a Super Block of a given -size. In the example, a super block of size 32 x 1 is taken. The -general formula for calculating the size of a super block is -32 x sizeof(value_type) x 2^n, where n ranges from 0 to 32 for 32-bit -systems. -

    - And since I just mentioned the -term `each bitmap', what in the world is meant by it? What does each -bitmap manage? How does it relate to the super block? Is the Super -Block a bitmap as well? -

    - Each bitmap is part of a Super Block which is made up of 3 parts - as I have mentioned earlier. Re-iterating, 1. The use count, - 2. The bit-map for that Super Block. 3. The actual memory that - will be eventually given to the user. Each bitmap is a multiple - of 32 in size. If there are 32 x (2^3) blocks of single objects - to be given, there will be '32 x (2^3)' bits present. Each 32 - bits managing the allocated / free status for 32 blocks. Since - each size_t contains 32-bits, one size_t can manage up to 32 - blocks' status. Each bit-map is made up of a number of size_t, - whose exact number for a super-block of a given size I have just - mentioned. -

    - How do the allocate and deallocate functions work in regard to - bitmaps? -

    - The allocate and deallocate functions manipulate the bitmaps and - have nothing to do with the memory that is given to the user. As - I have earlier mentioned, a 1 in the bitmap's bit field - indicates free, while a 0 indicates allocated. This lets us - check 32 bits at a time to check whether there is at lease one - free block in those 32 blocks by testing for equality with - (0). Now, the allocate function will given a memory block find - the corresponding bit in the bitmap, and will reset it (i.e., - make it re-set (0)). And when the deallocate function is called, - it will again set that bit after locating it to indicate that - that particular block corresponding to this bit in the bit-map - is not being used by anyone, and may be used to satisfy future - requests. -

    - e.g.: Consider a bit-map of 64-bits as represented below: - 1111111111111111111111111111111111111111111111111111111111111111 -

    - Now, when the first request for allocation of a single object - comes along, the first block in address order is returned. And - since the bit-maps in the reverse order to that of the address - order, the last bit (LSB if the bit-map is considered as a - binary word of 64-bits) is re-set to 0. -

    - The bit-map now looks like this: - 1111111111111111111111111111111111111111111111111111111111111110 -

    - Another issue would be whether to keep the all bitmaps in a - separate area in memory, or to keep them near the actual blocks - that will be given out or allocated for the client. After some - testing, I've decided to keep these bitmaps close to the actual - blocks. This will help in 2 ways. -

    1. Constant time access for the bitmap themselves, since no kind of -look up will be needed to find the correct bitmap list or its -equivalent.

    2. And also this would preserve the cache as far as possible.

    - So in effect, this kind of an allocator might prove beneficial from a - purely cache point of view. But this allocator has been made to try and - roll out the defects of the node_allocator, wherein the nodes get - skewed about in memory, if they are not returned in the exact reverse - order or in the same order in which they were allocated. Also, the - new_allocator's book keeping overhead is too much for small objects and - single object allocations, though it preserves the locality of blocks - very well when they are returned back to the allocator. -

    - Expected overhead per block would be 1 bit in memory. Also, once - the address of the free list has been found, the cost for - allocation/deallocation would be negligible, and is supposed to be - constant time. For these very reasons, it is very important to - minimize the linear time costs, which include finding a free list - with a free block while allocating, and finding the corresponding - free list for a block while deallocating. Therefore, I have - decided that the growth of the internal pool for this allocator - will be exponential as compared to linear for - node_allocator. There, linear time works well, because we are - mainly concerned with speed of allocation/deallocation and memory - consumption, whereas here, the allocation/deallocation part does - have some linear/logarithmic complexity components in it. Thus, to - try and minimize them would be a good thing to do at the cost of a - little bit of memory. -

    - Another thing to be noted is the pool size will double every time - the internal pool gets exhausted, and all the free blocks have - been given away. The initial size of the pool would be - sizeof(size_t) x 8 which is the number of bits in an integer, - which can fit exactly in a CPU register. Hence, the term given is - exponential growth of the internal pool. -

    Prev Up Next
    Chapter 20. Allocators Home Chapter 21. Containers
    +

    Prev Up Next
    Multiple Thread Example Home Implementation
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt02.html b/libstdc++-v3/doc/html/manual/bk01pt02.html index 3a0751ab9e7..5c344b16857 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt02.html @@ -1,6 +1,6 @@ -Part II.  Standard Contents
    Part II.  +Part II.  Standard Contents
    Part II.  Standard Contents
    Prev The GNU C++ Library Manual Next

    Part II.  Standard Contents @@ -13,22 +13,22 @@
    Exceptions
    API Reference
    Adding Data to exception
    Concept Checking
    6. Utilities -
    Functors
    Pairs
    Memory
    Allocators
    auto_ptr
    shared_ptr
    Traits
    7. +
    Functors
    Pairs
    Memory
    Allocators
    Requirements
    Design Issues
    Implementation
    Interface Design
    Selecting Default Allocation Policy
    Disabling Memory Caching
    Using a Specific Allocator
    Custom Allocators
    Extension Allocators
    auto_ptr
    Limitations
    Use in Containers
    shared_ptr
    Requirements
    Design Issues
    Implementation
    Class Hierarchy
    Thread Safety
    Selecting Lock Policy
    Dual C++0x and TR1 Implementation
    Related functions and classes
    Use
    Examples
    Unresolved Issues
    Acknowledgments
    Traits
    7. Strings
    String Classes
    Simple Transformations
    Case Sensitivity
    Arbitrary Character Types
    Tokenizing
    Shrink to Fit
    CString (MFC)
    8. Localization -
    Locales
    locale
    Facets
    ctype
    codecvt
    messages
    9. +
    Locales
    locale
    Requirements
    Design
    Implementation
    Interacting with "C" locales
    Future
    Facets
    ctype
    Implementation
    Specializations
    Future
    codecvt
    Requirements
    Design
    wchar_t Size
    Support for Unicode
    Other Issues
    Implementation
    Use
    Future
    messages
    Requirements
    Design
    Implementation
    Models
    The GNU Model
    Use
    Future
    9. Containers -
    Sequences
    list
    vector
    Associative
    Insertion Hints
    bitset
    Interacting with C
    Containers vs. Arrays
    10. +
    Sequences
    list
    list::size() is O(n)
    vector
    Space Overhead Management
    Associative
    Insertion Hints
    bitset
    Size Variable
    Type String
    Interacting with C
    Containers vs. Arrays
    10. Iterators
    Predefined
    Iterators vs. Pointers
    One Past the End
    11. Algorithms -
    Mutating
    swap
    12. +
    Mutating
    swap
    Specializations
    12. Numerics
    Complex
    complex Processing
    Generalized Operations
    Interacting with C
    Numerics vs. Arrays
    C99
    13. @@ -40,7 +40,7 @@
    API Reference
    15. Concurrency -
    API Reference

    Prev Up Next
    Debugging Support Home Chapter 4.  +
    API Reference
    Prev Up Next
    Debugging Support Home Chapter 4.  Support
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html b/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html index 6a67bef7c5c..74c468d8800 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html @@ -1,6 +1,6 @@ -Concept Checking
    Concept Checking
    Prev Chapter 5.  +Concept Checking
    Concept Checking
    Prev Chapter 5.  Diagnostics  Next

    @@ -44,7 +44,7 @@

    Prev Up Next
    Chapter 5.  Diagnostics - Home Chapter 6.  + Home Chapter 6.  Utilities
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html index 8fa7981deff..1616ce59358 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html @@ -1,6 +1,6 @@ -Semantics
    Semantics
    Prev Chapter 17. Debug Mode Next

    +Semantics

    Semantics
    Prev Chapter 17. Debug Mode Next

    A program that uses the C++ standard library correctly will maintain the same semantics under debug mode as it had with the normal (release) library. All functional and exception-handling @@ -52,4 +52,4 @@ with the debug-mode checks included, but this is unsupported and not guaranteed to work. For full debug-mode support you can use the __gnu_debug::basic_string debugging container directly, which always works correctly. -

    Prev Up Next
    Chapter 17. Debug Mode Home Using
    +

    Prev Up Next
    Chapter 17. Debug Mode Home Using
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html index bff64a3747b..4ad5743ca05 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html @@ -1,6 +1,6 @@ -Using
    Using
    Prev Chapter 17. Debug Mode Next

    +Using

    Using
    Prev Chapter 17. Debug Mode Next

    To use the libstdc++ debug mode, compile your application with the compiler flag -D_GLIBCXX_DEBUG. Note that this flag changes the sizes and behavior of standard class templates such @@ -19,6 +19,6 @@ mode or with debug mode. The following table provides the names and headers of the debugging containers: -

    Table 17.1. Debugging Containers

    ContainerHeaderDebug containerDebug header
    std::bitsetbitset__gnu_debug::bitset<debug/bitset>
    std::dequedeque__gnu_debug::deque<debug/deque>
    std::listlist__gnu_debug::list<debug/list>
    std::mapmap__gnu_debug::map<debug/map>
    std::multimapmap__gnu_debug::multimap<debug/map>
    std::multisetset__gnu_debug::multiset<debug/set>
    std::setset__gnu_debug::set<debug/set>
    std::stringstring__gnu_debug::string<debug/string>
    std::wstringstring__gnu_debug::wstring<debug/string>
    std::basic_stringstring__gnu_debug::basic_string<debug/string>
    std::vectorvector__gnu_debug::vector<debug/vector>

    In addition, when compiling in C++0x mode, these additional +

    Table 17.1. Debugging Containers

    ContainerHeaderDebug containerDebug header
    std::bitsetbitset__gnu_debug::bitset<debug/bitset>
    std::dequedeque__gnu_debug::deque<debug/deque>
    std::listlist__gnu_debug::list<debug/list>
    std::mapmap__gnu_debug::map<debug/map>
    std::multimapmap__gnu_debug::multimap<debug/map>
    std::multisetset__gnu_debug::multiset<debug/set>
    std::setset__gnu_debug::set<debug/set>
    std::stringstring__gnu_debug::string<debug/string>
    std::wstringstring__gnu_debug::wstring<debug/string>
    std::basic_stringstring__gnu_debug::basic_string<debug/string>
    std::vectorvector__gnu_debug::vector<debug/vector>

    In addition, when compiling in C++0x mode, these additional containers have additional debug capability. -

    Table 17.2. Debugging Containers C++0x

    ContainerHeaderDebug containerDebug header
    std::unordered_mapunordered_map__gnu_debug::unordered_map<debug/unordered_map>
    std::unordered_multimapunordered_map__gnu_debug::unordered_multimap<debug/unordered_map>
    std::unordered_setunordered_set__gnu_debug::unordered_set<debug/unordered_set>
    std::unordered_multisetunordered_set__gnu_debug::unordered_multiset<debug/unordered_set>

    Prev Up Next
    Semantics Home Design
    +

    Table 17.2. Debugging Containers C++0x

    ContainerHeaderDebug containerDebug header
    std::unordered_mapunordered_map__gnu_debug::unordered_map<debug/unordered_map>
    std::unordered_multimapunordered_map__gnu_debug::unordered_multimap<debug/unordered_map>
    std::unordered_setunordered_set__gnu_debug::unordered_set<debug/unordered_set>
    std::unordered_multisetunordered_set__gnu_debug::unordered_multiset<debug/unordered_set>

    Prev Up Next
    Semantics Home Design
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html index 3e35af0fac8..a0a85b76dc1 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html @@ -1,6 +1,6 @@ -Design
    Design
    Prev Chapter 17. Debug Mode Next

    +Design

    Design
    Prev Chapter 17. Debug Mode Next

    The libstdc++ debug mode replaces unsafe (but efficient) standard containers and iterators with semantically equivalent safe standard @@ -409,4 +409,4 @@ test02() a full debug-mode implementation (including debugging for CodeWarrior extensions) and is easy to use, although it meets only the "Full recompilation" (1) recompilation - guarantee.

    Prev Up Next
    Using Home Chapter 18. Parallel Mode
    + guarantee.

    Prev Up Next
    Using Home Chapter 18. Parallel Mode
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html index 7a7419ac51d..2017808229f 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html @@ -1,6 +1,6 @@ -Semantics
    Semantics
    Prev Chapter 18. Parallel Mode Next

    The parallel mode STL algorithms are currently not exception-safe, +Semantics

    Semantics
    Prev Chapter 18. Parallel Mode Next

    The parallel mode STL algorithms are currently not exception-safe, i.e. user-defined functors must not throw exceptions. Also, the order of execution is not guaranteed for some functions, of course. Therefore, user-defined functors should not have any concurrent side effects. @@ -8,4 +8,4 @@ Therefore, user-defined functors should not have any concurrent side effects. OpenMP parallel regions in concurrent threads, it is not possible to call parallel STL algorithm in concurrent threads, either. -It might work with other compilers, though.

    Prev Up Next
    Chapter 18. Parallel Mode Home Using
    +It might work with other compilers, though.

    Prev Up Next
    Chapter 18. Parallel Mode Home Using
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html index 564989e02b6..71b3de20a73 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html @@ -1,6 +1,6 @@ -Using
    Using
    Prev Chapter 18. Parallel Mode Next

    +Using

    Using
    Prev Chapter 18. Parallel Mode Next

    Any use of parallel functionality requires additional compiler and runtime support, in particular support for OpenMP. Adding this support is not difficult: just compile your application with the compiler @@ -63,4 +63,4 @@ Then compile this code with the prerequisite compiler flags flags for atomic operations.)

    The following table provides the names and headers of all the parallel algorithms that can be used in a similar manner: -

    Table 18.1. Parallel Algorithms

    AlgorithmHeaderParallel algorithmParallel header
    std::accumulatenumeric__gnu_parallel::accumulateparallel/numeric
    std::adjacent_differencenumeric__gnu_parallel::adjacent_differenceparallel/numeric
    std::inner_productnumeric__gnu_parallel::inner_productparallel/numeric
    std::partial_sumnumeric__gnu_parallel::partial_sumparallel/numeric
    std::adjacent_findalgorithm__gnu_parallel::adjacent_findparallel/algorithm
    std::countalgorithm__gnu_parallel::countparallel/algorithm
    std::count_ifalgorithm__gnu_parallel::count_ifparallel/algorithm
    std::equalalgorithm__gnu_parallel::equalparallel/algorithm
    std::findalgorithm__gnu_parallel::findparallel/algorithm
    std::find_ifalgorithm__gnu_parallel::find_ifparallel/algorithm
    std::find_first_ofalgorithm__gnu_parallel::find_first_ofparallel/algorithm
    std::for_eachalgorithm__gnu_parallel::for_eachparallel/algorithm
    std::generatealgorithm__gnu_parallel::generateparallel/algorithm
    std::generate_nalgorithm__gnu_parallel::generate_nparallel/algorithm
    std::lexicographical_comparealgorithm__gnu_parallel::lexicographical_compareparallel/algorithm
    std::mismatchalgorithm__gnu_parallel::mismatchparallel/algorithm
    std::searchalgorithm__gnu_parallel::searchparallel/algorithm
    std::search_nalgorithm__gnu_parallel::search_nparallel/algorithm
    std::transformalgorithm__gnu_parallel::transformparallel/algorithm
    std::replacealgorithm__gnu_parallel::replaceparallel/algorithm
    std::replace_ifalgorithm__gnu_parallel::replace_ifparallel/algorithm
    std::max_elementalgorithm__gnu_parallel::max_elementparallel/algorithm
    std::mergealgorithm__gnu_parallel::mergeparallel/algorithm
    std::min_elementalgorithm__gnu_parallel::min_elementparallel/algorithm
    std::nth_elementalgorithm__gnu_parallel::nth_elementparallel/algorithm
    std::partial_sortalgorithm__gnu_parallel::partial_sortparallel/algorithm
    std::partitionalgorithm__gnu_parallel::partitionparallel/algorithm
    std::random_shufflealgorithm__gnu_parallel::random_shuffleparallel/algorithm
    std::set_unionalgorithm__gnu_parallel::set_unionparallel/algorithm
    std::set_intersectionalgorithm__gnu_parallel::set_intersectionparallel/algorithm
    std::set_symmetric_differencealgorithm__gnu_parallel::set_symmetric_differenceparallel/algorithm
    std::set_differencealgorithm__gnu_parallel::set_differenceparallel/algorithm
    std::sortalgorithm__gnu_parallel::sortparallel/algorithm
    std::stable_sortalgorithm__gnu_parallel::stable_sortparallel/algorithm
    std::unique_copyalgorithm__gnu_parallel::unique_copyparallel/algorithm

    Prev Up Next
    Semantics Home Design
    +

    Table 18.1. Parallel Algorithms

    AlgorithmHeaderParallel algorithmParallel header
    std::accumulatenumeric__gnu_parallel::accumulateparallel/numeric
    std::adjacent_differencenumeric__gnu_parallel::adjacent_differenceparallel/numeric
    std::inner_productnumeric__gnu_parallel::inner_productparallel/numeric
    std::partial_sumnumeric__gnu_parallel::partial_sumparallel/numeric
    std::adjacent_findalgorithm__gnu_parallel::adjacent_findparallel/algorithm
    std::countalgorithm__gnu_parallel::countparallel/algorithm
    std::count_ifalgorithm__gnu_parallel::count_ifparallel/algorithm
    std::equalalgorithm__gnu_parallel::equalparallel/algorithm
    std::findalgorithm__gnu_parallel::findparallel/algorithm
    std::find_ifalgorithm__gnu_parallel::find_ifparallel/algorithm
    std::find_first_ofalgorithm__gnu_parallel::find_first_ofparallel/algorithm
    std::for_eachalgorithm__gnu_parallel::for_eachparallel/algorithm
    std::generatealgorithm__gnu_parallel::generateparallel/algorithm
    std::generate_nalgorithm__gnu_parallel::generate_nparallel/algorithm
    std::lexicographical_comparealgorithm__gnu_parallel::lexicographical_compareparallel/algorithm
    std::mismatchalgorithm__gnu_parallel::mismatchparallel/algorithm
    std::searchalgorithm__gnu_parallel::searchparallel/algorithm
    std::search_nalgorithm__gnu_parallel::search_nparallel/algorithm
    std::transformalgorithm__gnu_parallel::transformparallel/algorithm
    std::replacealgorithm__gnu_parallel::replaceparallel/algorithm
    std::replace_ifalgorithm__gnu_parallel::replace_ifparallel/algorithm
    std::max_elementalgorithm__gnu_parallel::max_elementparallel/algorithm
    std::mergealgorithm__gnu_parallel::mergeparallel/algorithm
    std::min_elementalgorithm__gnu_parallel::min_elementparallel/algorithm
    std::nth_elementalgorithm__gnu_parallel::nth_elementparallel/algorithm
    std::partial_sortalgorithm__gnu_parallel::partial_sortparallel/algorithm
    std::partitionalgorithm__gnu_parallel::partitionparallel/algorithm
    std::random_shufflealgorithm__gnu_parallel::random_shuffleparallel/algorithm
    std::set_unionalgorithm__gnu_parallel::set_unionparallel/algorithm
    std::set_intersectionalgorithm__gnu_parallel::set_intersectionparallel/algorithm
    std::set_symmetric_differencealgorithm__gnu_parallel::set_symmetric_differenceparallel/algorithm
    std::set_differencealgorithm__gnu_parallel::set_differenceparallel/algorithm
    std::sortalgorithm__gnu_parallel::sortparallel/algorithm
    std::stable_sortalgorithm__gnu_parallel::stable_sortparallel/algorithm
    std::unique_copyalgorithm__gnu_parallel::unique_copyparallel/algorithm

    Prev Up Next
    Semantics Home Design
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html index 91c951d3855..2eef0ee575f 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html @@ -1,6 +1,6 @@ -Design
    Design
    Prev Chapter 18. Parallel Mode Next

    +Design

    Design
    Prev Chapter 18. Parallel Mode Next

    All parallel algorithms are intended to have signatures that are equivalent to the ISO C++ algorithms replaced. For instance, the @@ -210,4 +210,4 @@ __gnu_parallel.

    More information, and an organized index of types and functions related to the parallel mode on a per-namespace basis, can be found in the generated source documentation. -

    Prev Up Next
    Using Home Testing
    +

    Prev Up Next
    Using Home Testing
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html index f00a4a2815a..9d27f10f151 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html @@ -1,6 +1,6 @@ -Testing
    Testing
    Prev Chapter 18. Parallel Mode Next

    +Testing

    Testing
    Prev Chapter 18. Parallel Mode Next

    Both the normal conformance and regression tests and the supplemental performance tests work.

    @@ -23,4 +23,4 @@ additional software dependencies than the usual bare-boned text file, and can be generated by using the make doc-performance rule in the testsuite's Makefile. -

    Prev Up Next
    Design Home Chapter 19. Profile Mode
    +

    Prev Up Next
    Design Home Chapter 19. Profile Mode
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html index 2f640624c8b..e8cf6a4b05d 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html @@ -1,7 +1,7 @@ -Design
    Design
    Prev Chapter 19. Profile Mode Next

    -

    Table 19.1. Profile Code Location

    Code LocationUse
    libstdc++-v3/include/std/*Preprocessor code to redirect to profile extension headers.
    libstdc++-v3/include/profile/*Profile extension public headers (map, vector, ...).
    libstdc++-v3/include/profile/impl/*Profile extension internals. Implementation files are +Design
    Design
    Prev Chapter 19. Profile Mode Next

    +

    Table 19.1. Profile Code Location

    Code LocationUse
    libstdc++-v3/include/std/*Preprocessor code to redirect to profile extension headers.
    libstdc++-v3/include/profile/*Profile extension public headers (map, vector, ...).
    libstdc++-v3/include/profile/impl/*Profile extension internals. Implementation files are only included from impl/profiler.h, which is the only file included from the public headers.

    @@ -119,4 +119,4 @@ it helps the user focus on the key problems and ignore the uninteresting ones. We created a profile directory in the test suite. Each diagnostic must come with at least two tests, one for false positives and one for false negatives. -

    Prev Up Next
    Chapter 19. Profile Mode Home Extensions for Custom Containers
    +

    Prev Up Next
    Chapter 19. Profile Mode Home Extensions for Custom Containers
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html index 37d1ed8e4bb..c3cb96f729d 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html @@ -1,10 +1,10 @@ -Extensions for Custom Containers
    Extensions for Custom Containers
    Prev Chapter 19. Profile Mode Next

    +Extensions for Custom Containers

    Extensions for Custom Containers
    Prev Chapter 19. Profile Mode Next

    Many large projects use their own data structures instead of the ones in the standard library. If these data structures are similar in functionality to the standard library, they can be instrumented with the same hooks that are used to instrument the standard library. The instrumentation API is exposed in file profiler.h (look for "Instrumentation hooks"). -

    Prev Up Next
    Design Home Empirical Cost Model
    +

    Prev Up Next
    Design Home Empirical Cost Model
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html index 8fc162b7c73..8915bc051ac 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html @@ -1,6 +1,6 @@ -Empirical Cost Model
    Empirical Cost Model
    Prev Chapter 19. Profile Mode Next

    +Empirical Cost Model

    Empirical Cost Model
    Prev Chapter 19. Profile Mode Next

    Currently, the cost model uses formulas with predefined relative weights for alternative containers or container implementations. For instance, iterating through a vector is X times faster than iterating through a list. @@ -15,4 +15,4 @@ filled in either by hand or by an automated training mechanism. The analysis module will then use this database instead of the built in. generic parameters. -

    Prev Up Next
    Extensions for Custom Containers Home Implementation Issues
    +

    Prev Up Next
    Extensions for Custom Containers Home Implementation Issues
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html index 2d072f0b41a..7b74bb86e38 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html @@ -1,6 +1,6 @@ -Implementation Issues
    Implementation Issues
    Prev Chapter 19. Profile Mode Next

    +Implementation Issues

    Implementation Issues
    Prev Chapter 19. Profile Mode Next

    Accurate stack traces are needed during profiling since we group events by call context and dynamic instance. Without accurate traces, diagnostics may be hard to interpret. For instance, when giving advice to the user @@ -48,4 +48,4 @@ However, we cannot do the same at destruction time. The trace is written by a function registered by atexit, thus invoked by exit. -

    Prev Up Next
    Empirical Cost Model Home Developer Information
    +

    Prev Up Next
    Empirical Cost Model Home Developer Information
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html index ddcc7f5708d..d1e790fa476 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html @@ -1,6 +1,6 @@ -Developer Information
    Developer Information
    Prev Chapter 19. Profile Mode Next

    The profile mode headers are included with +Developer Information

    Developer Information
    Prev Chapter 19. Profile Mode Next

    The profile mode headers are included with -D_GLIBCXX_PROFILE through preprocessor directives in include/std/*.

    Instrumented implementations are provided in @@ -65,4 +65,4 @@ include/profile/impl/profiler_trace.h. Use __trace_vector_to_list as an example.

    Add documentation in file doc/xml/manual/profile_mode.xml. -

    Prev Up Next
    Implementation Issues Home Diagnostics
    +

    Prev Up Next
    Implementation Issues Home Diagnostics
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html index 33377853d40..6548b8b8c41 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html @@ -1,6 +1,6 @@ -Diagnostics
    Diagnostics
    Prev Chapter 19. Profile Mode Next

    +Diagnostics

    Diagnostics
    Prev Chapter 19. Profile Mode Next

    The table below presents all the diagnostics we intend to implement. Each diagnostic has a corresponding compile time switch -D_GLIBCXX_PROFILE_<diagnostic>. @@ -18,7 +18,7 @@ A high accuracy means that the diagnostic is unlikely to be wrong. These grades are not perfect. They are just meant to guide users with specific needs or time budgets. -

    Table 19.2. Profile Diagnostics

    GroupFlagBenefitCostFreq.Implemented 
    +

    Table 19.2. Profile Diagnostics

    GroupFlagBenefitCostFreq.Implemented 
    CONTAINERS HASHTABLE_TOO_SMALL101 10yes
      HASHTABLE_TOO_LARGE51 10yes
      @@ -555,4 +555,4 @@ sharing in multithreaded access at foo.cc:4. Detected N shared cache lines. This diagnostic will not issue any advice, but it will print statistics for each container construction site. The statistics will contain the cost of each operation actually performed on the container. -

    Prev Up Next
    Developer Information Home Chapter 20. Allocators
    +

    Prev Up Next
    Developer Information Home Chapter 20. The mt_allocator
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch20s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch20s02.html new file mode 100644 index 00000000000..7ec3af13b52 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch20s02.html @@ -0,0 +1,39 @@ + + +Design Issues
    Design Issues
    Prev Chapter 20. The mt_allocator Next

    There are three general components to the allocator: a datum +describing the characteristics of the memory pool, a policy class +containing this pool that links instantiation types to common or +individual pools, and a class inheriting from the policy class that is +the actual allocator. +

    The datum describing pools characteristics is +

    +  template<bool _Thread>
+    class __pool
+

    This class is parametrized on thread support, and is explicitly +specialized for both multiple threads (with bool==true) +and single threads (via bool==false.) It is possible to +use a custom pool datum instead of the default class that is provided. +

    There are two distinct policy classes, each of which can be used +with either type of underlying pool datum. +

    +  template<bool _Thread>
+    struct __common_pool_policy
+
+  template<typename _Tp, bool _Thread>
+    struct __per_type_pool_policy
+

    The first policy, __common_pool_policy, implements a +common pool. This means that allocators that are instantiated with +different types, say char and long will both +use the same pool. This is the default policy. +

    The second policy, __per_type_pool_policy, implements +a separate pool for each instantiating type. Thus, char +and long will use separate pools. This allows per-type +tuning, for instance. +

    Putting this all together, the actual allocator class is +

    +  template<typename _Tp, typename _Poolp = __default_policy>
+    class __mt_alloc : public __mt_alloc_base<_Tp>,  _Poolp
+

    This class has the interface required for standard library allocator +classes, namely member functions allocate and +deallocate, plus others. +

    Prev Up Next
    Chapter 20. The mt_allocator Home Implementation
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch20s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch20s03.html new file mode 100644 index 00000000000..1bff6823ef9 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch20s03.html @@ -0,0 +1,161 @@ + + +Implementation
    Implementation
    Prev Chapter 20. The mt_allocator Next

    Certain allocation parameters can be modified, or tuned. There +exists a nested struct __pool_base::_Tune that contains all +these parameters, which include settings for +

    Adjusting parameters for a given instance of an allocator can only +happen before any allocations take place, when the allocator itself is +initialized. For instance: +

    +#include <ext/mt_allocator.h>
+
+struct pod
+{
+  int i;
+  int j;
+};
+
+int main()
+{
+  typedef pod value_type;
+  typedef __gnu_cxx::__mt_alloc<value_type> allocator_type;
+  typedef __gnu_cxx::__pool_base::_Tune tune_type;
+
+  tune_type t_default;
+  tune_type t_opt(16, 5120, 32, 5120, 20, 10, false);
+  tune_type t_single(16, 5120, 32, 5120, 1, 10, false);
+
+  tune_type t;
+  t = allocator_type::_M_get_options();
+  allocator_type::_M_set_options(t_opt);
+  t = allocator_type::_M_get_options();
+
+  allocator_type a;
+  allocator_type::pointer p1 = a.allocate(128);
+  allocator_type::pointer p2 = a.allocate(5128);
+
+  a.deallocate(p1, 128);
+  a.deallocate(p2, 5128);
+
+  return 0;
+}
+

    +The static variables (pointers to freelists, tuning parameters etc) +are initialized as above, or are set to the global defaults. +

    +The very first allocate() call will always call the +_S_initialize_once() function. In order to make sure that this +function is called exactly once we make use of a __gthread_once call +in MT applications and check a static bool (_S_init) in ST +applications. +

    +The _S_initialize() function: +- If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool + _S_force_new to true and then returns. This will cause subsequent calls to + allocate() to return memory directly from a new() call, and deallocate will + only do a delete() call. +

    +- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT + applications will: + - Calculate the number of bins needed. A bin is a specific power of two size + of bytes. I.e., by default the allocator will deal with requests of up to + 128 bytes (or whatever the value of _S_max_bytes is when _S_init() is + called). This means that there will be bins of the following sizes + (in bytes): 1, 2, 4, 8, 16, 32, 64, 128. + + - Create the _S_binmap array. All requests are rounded up to the next + "large enough" bin. I.e., a request for 29 bytes will cause a block from + the "32 byte bin" to be returned to the application. The purpose of + _S_binmap is to speed up the process of finding out which bin to use. + I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes). +

    + - Create the _S_bin array. This array consists of bin_records. There will be + as many bin_records in this array as the number of bins that we calculated + earlier. I.e., if _S_max_bytes = 128 there will be 8 entries. + Each bin_record is then initialized: + - bin_record->first = An array of pointers to block_records. There will be + as many block_records pointers as there are maximum number of threads + (in a ST application there is only 1 thread, in a MT application there + are _S_max_threads). + This holds the pointer to the first free block for each thread in this + bin. I.e., if we would like to know where the first free block of size 32 + for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ] + + The above created block_record pointers members are now initialized to + their initial values. I.e. _S_bin[ n ].first[ n ] = NULL; +

    +- Additionally a MT application will: + - Create a list of free thread id's. The pointer to the first entry + is stored in _S_thread_freelist_first. The reason for this approach is + that the __gthread_self() call will not return a value that corresponds to + the maximum number of threads allowed but rather a process id number or + something else. So what we do is that we create a list of thread_records. + This list is _S_max_threads long and each entry holds a size_t thread_id + which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads. + Each time a thread calls allocate() or deallocate() we call + _S_get_thread_id() which looks at the value of _S_thread_key which is a + thread local storage pointer. If this is NULL we know that this is a newly + created thread and we pop the first entry from this list and saves the + pointer to this record in the _S_thread_key variable. The next time + we will get the pointer to the thread_record back and we use the + thread_record->thread_id as identification. I.e., the first thread that + calls allocate will get the first record in this list and thus be thread + number 1 and will then find the pointer to its first free 32 byte block + in _S_bin[ 5 ].first[ 1 ] + When we create the _S_thread_key we also define a destructor + (_S_thread_key_destr) which means that when the thread dies, this + thread_record is returned to the front of this list and the thread id + can then be reused if a new thread is created. + This list is protected by a mutex (_S_thread_freelist_mutex) which is only + locked when records are removed or added to the list. +

    + - Initialize the free and used counters of each bin_record: + - bin_record->free = An array of size_t. This keeps track of the number + of blocks on a specific thread's freelist in each bin. I.e., if a thread + has 12 32-byte blocks on it's freelists and allocates one of these, this + counter would be decreased to 11. + + - bin_record->used = An array of size_t. This keeps track of the number + of blocks currently in use of this size by this thread. I.e., if a thread + has made 678 requests (and no deallocations...) of 32-byte blocks this + counter will read 678. + + The above created arrays are now initialized with their initial values. + I.e. _S_bin[ n ].free[ n ] = 0; +

    + - Initialize the mutex of each bin_record: The bin_record->mutex + is used to protect the global freelist. This concept of a global + freelist is explained in more detail in the section "A multi + threaded example", but basically this mutex is locked whenever a + block of memory is retrieved or returned to the global freelist + for this specific bin. This only occurs when a number of blocks + are grabbed from the global list to a thread specific list or when + a thread decides to return some blocks to the global freelist. +

    Notes about deallocation. This allocator does not explicitly +release memory. Because of this, memory debugging programs like +valgrind or purify may notice leaks: sorry about this +inconvenience. Operating systems will reclaim allocated memory at +program termination anyway. If sidestepping this kind of noise is +desired, there are three options: use an allocator, like +new_allocator that releases memory while debugging, use +GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a +custom pool datum that releases resources on destruction. +

    + On systems with the function __cxa_atexit, the +allocator can be forced to free all memory allocated before program +termination with the member function +__pool_type::_M_destroy. However, because this member +function relies on the precise and exactly-conforming ordering of +static destructors, including those of a static local +__pool object, it should not be used, ever, on systems +that don't have the necessary underlying support. In addition, in +practice, forcing deallocation can be tricky, as it requires the +__pool object to be fully-constructed before the object +that uses it is fully constructed. For most (but not all) STL +containers, this works, as an instance of the allocator is constructed +as part of a container's constructor. However, this assumption is +implementation-specific, and subject to change. For an example of a +pool that frees memory, see the following + + example. +

    Prev Up Next
    Design Issues Home Single Thread Example
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch20s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch20s04.html new file mode 100644 index 00000000000..faa6b4417d2 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch20s04.html @@ -0,0 +1,79 @@ + + +Single Thread Example
    Single Thread Example
    Prev Chapter 20. The mt_allocator Next

    +Let's start by describing how the data on a freelist is laid out in memory. +This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes): +

    ++----------------+
+| next* ---------|--+  (_S_bin[ 3 ].first[ 3 ] points here)
+|                |  |
+|                |  |
+|                |  |
++----------------+  |
+| thread_id = 3  |  |
+|                |  |
+|                |  |
+|                |  |
++----------------+  |
+| DATA           |  |  (A pointer to here is what is returned to the
+|                |  |   the application when needed)
+|                |  |
+|                |  |
+|                |  |
+|                |  |
+|                |  |
+|                |  |
++----------------+  |
++----------------+  |
+| next*          |<-+  (If next == NULL it's the last one on the list)
+|                |
+|                |
+|                |
++----------------+
+| thread_id = 3  |
+|                |
+|                |
+|                |
++----------------+
+| DATA           |
+|                |
+|                |
+|                |
+|                |
+|                |
+|                |
+|                |
++----------------+
+

    +With this in mind we simplify things a bit for a while and say that there is +only one thread (a ST application). In this case all operations are made to +what is referred to as the global pool - thread id 0 (No thread may be +assigned this id since they span from 1 to _S_max_threads in a MT application). +

    +When the application requests memory (calling allocate()) we first look at the +requested size and if this is > _S_max_bytes we call new() directly and return. +

    +If the requested size is within limits we start by finding out from which +bin we should serve this request by looking in _S_binmap. +

    +A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of +this size on the freelist (0). If this is not NULL - fine, just remove the +block that _S_bin[ bin ].first[ 0 ] points to from the list, +update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data. +

    +If the freelist is empty (the pointer is NULL) we must get memory from the +system and build us a freelist within this memory. All requests for new memory +is made in chunks of _S_chunk_size. Knowing the size of a block_record and +the bytes that this bin stores we then calculate how many blocks we can create +within this chunk, build the list, remove the first block, update the pointer +(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data. +

    +Deallocation is equally simple; the pointer is casted back to a block_record +pointer, lookup which bin to use based on the size, add the block to the front +of the global freelist and update the pointer as needed +(_S_bin[ bin ].first[ 0 ]). +

    +The decision to add deallocated blocks to the front of the freelist was made +after a set of performance measurements that showed that this is roughly 10% +faster than maintaining a set of "last pointers" as well. +

    Prev Up Next
    Implementation Home Multiple Thread Example
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch20s05.html b/libstdc++-v3/doc/html/manual/bk01pt03ch20s05.html new file mode 100644 index 00000000000..62870c439a3 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch20s05.html @@ -0,0 +1,107 @@ + + +Multiple Thread Example
    Multiple Thread Example
    Prev Chapter 20. The mt_allocator Next

    +In the ST example we never used the thread_id variable present in each block. +Let's start by explaining the purpose of this in a MT application. +

    +The concept of "ownership" was introduced since many MT applications +allocate and deallocate memory to shared containers from different +threads (such as a cache shared amongst all threads). This introduces +a problem if the allocator only returns memory to the current threads +freelist (I.e., there might be one thread doing all the allocation and +thus obtaining ever more memory from the system and another thread +that is getting a longer and longer freelist - this will in the end +consume all available memory). +

    +Each time a block is moved from the global list (where ownership is +irrelevant), to a threads freelist (or when a new freelist is built +from a chunk directly onto a threads freelist or when a deallocation +occurs on a block which was not allocated by the same thread id as the +one doing the deallocation) the thread id is set to the current one. +

    +What's the use? Well, when a deallocation occurs we can now look at +the thread id and find out if it was allocated by another thread id +and decrease the used counter of that thread instead, thus keeping the +free and used counters correct. And keeping the free and used counters +corrects is very important since the relationship between these two +variables decides if memory should be returned to the global pool or +not when a deallocation occurs. +

    +When the application requests memory (calling allocate()) we first +look at the requested size and if this is >_S_max_bytes we call new() +directly and return. +

    +If the requested size is within limits we start by finding out from which +bin we should serve this request by looking in _S_binmap. +

    +A call to _S_get_thread_id() returns the thread id for the calling thread +(and if no value has been set in _S_thread_key, a new id is assigned and +returned). +

    +A quick look at _S_bin[ bin ].first[ thread_id ] tells us if there are +any blocks of this size on the current threads freelist. If this is +not NULL - fine, just remove the block that _S_bin[ bin ].first[ +thread_id ] points to from the list, update _S_bin[ bin ].first[ +thread_id ], update the free and used counters and return a pointer to +that blocks data. +

    +If the freelist is empty (the pointer is NULL) we start by looking at +the global freelist (0). If there are blocks available on the global +freelist we lock this bins mutex and move up to block_count (the +number of blocks of this bins size that will fit into a _S_chunk_size) +or until end of list - whatever comes first - to the current threads +freelist and at the same time change the thread_id ownership and +update the counters and pointers. When the bins mutex has been +unlocked, we remove the block that _S_bin[ bin ].first[ thread_id ] +points to from the list, update _S_bin[ bin ].first[ thread_id ], +update the free and used counters, and return a pointer to that blocks +data. +

    +The reason that the number of blocks moved to the current threads +freelist is limited to block_count is to minimize the chance that a +subsequent deallocate() call will return the excess blocks to the +global freelist (based on the _S_freelist_headroom calculation, see +below). +

    +However if there isn't any memory on the global pool we need to get +memory from the system - this is done in exactly the same way as in a +single threaded application with one major difference; the list built +in the newly allocated memory (of _S_chunk_size size) is added to the +current threads freelist instead of to the global. +

    +The basic process of a deallocation call is simple: always add the +block to the front of the current threads freelist and update the +counters and pointers (as described earlier with the specific check of +ownership that causes the used counter of the thread that originally +allocated the block to be decreased instead of the current threads +counter). +

    +And here comes the free and used counters to service. Each time a +deallocation() call is made, the length of the current threads +freelist is compared to the amount memory in use by this thread. +

    +Let's go back to the example of an application that has one thread +that does all the allocations and one that deallocates. Both these +threads use say 516 32-byte blocks that was allocated during thread +creation for example. Their used counters will both say 516 at this +point. The allocation thread now grabs 1000 32-byte blocks and puts +them in a shared container. The used counter for this thread is now +1516. +

    +The deallocation thread now deallocates 500 of these blocks. For each +deallocation made the used counter of the allocating thread is +decreased and the freelist of the deallocation thread gets longer and +longer. But the calculation made in deallocate() will limit the length +of the freelist in the deallocation thread to _S_freelist_headroom % +of it's used counter. In this case, when the freelist (given that the +_S_freelist_headroom is at it's default value of 10%) exceeds 52 +(516/10) blocks will be returned to the global pool where the +allocating thread may pick them up and reuse them. +

    +In order to reduce lock contention (since this requires this bins +mutex to be locked) this operation is also made in chunks of blocks +(just like when chunks of blocks are moved from the global freelist to +a threads freelist mentioned above). The "formula" used can probably +be improved to further reduce the risk of blocks being "bounced back +and forth" between freelists. +

    Prev Up Next
    Single Thread Example Home Chapter 21. The bitmap_allocator
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html index eba8cfb31db..5b62d1fbc72 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html @@ -1,43 +1,313 @@ -HP/SGI
    HP/SGI
    Prev Chapter 21. Containers Next

    -

    A few extensions and nods to backwards-compatibility have been made with - containers. Those dealing with older SGI-style allocators are dealt with - elsewhere. The remaining ones all deal with bits: -

    The old pre-standard bit_vector class is present for - backwards compatibility. It is simply a typedef for the - vector<bool> specialization. -

    The bitset class has a number of extensions, described in the - rest of this item. First, we'll mention that this implementation of - bitset<N> is specialized for cases where N number of - bits will fit into a single word of storage. If your choice of N is - within that range (<=32 on i686-pc-linux-gnu, for example), then all - of the operations will be faster. -

    There are - versions of single-bit test, set, reset, and flip member functions which - do no range-checking. If we call them member functions of an instantiation - of "bitset<N>," then their names and signatures are: -

    -   bitset<N>&   _Unchecked_set   (size_t pos);
-   bitset<N>&   _Unchecked_set   (size_t pos, int val);
-   bitset<N>&   _Unchecked_reset (size_t pos);
-   bitset<N>&   _Unchecked_flip  (size_t pos);
-   bool         _Unchecked_test  (size_t pos);
-

    Note that these may in fact be removed in the future, although we have - no present plans to do so (and there doesn't seem to be any immediate - reason to). -

    The semantics of member function operator[] are not specified - in the C++ standard. A long-standing defect report calls for sensible - obvious semantics, which are already implemented here: op[] - on a const bitset returns a bool, and for a non-const bitset returns a - reference (a nested type). However, this implementation does - no range-checking on the index argument, which is in keeping with other - containers' op[] requirements. The defect report's proposed - resolution calls for range-checking to be done. We'll just wait and see... -

    Finally, two additional searching functions have been added. They return - the index of the first "on" bit, and the index of the first - "on" bit that is after prev, respectively: -

    -   size_t _Find_first() const;
-   size_t _Find_next (size_t prev) const;

    The same caveat given for the _Unchecked_* functions applies here also. -

    Prev Up Next
    Chapter 21. Containers Home Deprecated HP/SGI
    +Implementation
    Implementation
    Prev Chapter 21. The bitmap_allocator Next

    + The Free List Store (referred to as FLS for the remaining part of this + document) is the Global memory pool that is shared by all instances of + the bitmapped allocator instantiated for any type. This maintains a + sorted order of all free memory blocks given back to it by the + bitmapped allocator, and is also responsible for giving memory to the + bitmapped allocator when it asks for more. +

    + Internally, there is a Free List threshold which indicates the + Maximum number of free lists that the FLS can hold internally + (cache). Currently, this value is set at 64. So, if there are + more than 64 free lists coming in, then some of them will be given + back to the OS using operator delete so that at any given time the + Free List's size does not exceed 64 entries. This is done because + a Binary Search is used to locate an entry in a free list when a + request for memory comes along. Thus, the run-time complexity of + the search would go up given an increasing size, for 64 entries + however, lg(64) == 6 comparisons are enough to locate the correct + free list if it exists. +

    + Suppose the free list size has reached its threshold, then the + largest block from among those in the list and the new block will + be selected and given back to the OS. This is done because it + reduces external fragmentation, and allows the OS to use the + larger blocks later in an orderly fashion, possibly merging them + later. Also, on some systems, large blocks are obtained via calls + to mmap, so giving them back to free system resources becomes most + important. +

    + The function _S_should_i_give decides the policy that determines + whether the current block of memory should be given to the + allocator for the request that it has made. That's because we may + not always have exact fits for the memory size that the allocator + requests. We do this mainly to prevent external fragmentation at + the cost of a little internal fragmentation. Now, the value of + this internal fragmentation has to be decided by this function. I + can see 3 possibilities right now. Please add more as and when you + find better strategies. +

    1. Equal size check. Return true only when the 2 blocks are of equal +size.

    2. Difference Threshold: Return true only when the _block_size is +greater than or equal to the _required_size, and if the _BS is > _RS +by a difference of less than some THRESHOLD value, then return true, +else return false.

    3. Percentage Threshold. Return true only when the _block_size is +greater than or equal to the _required_size, and if the _BS is > _RS +by a percentage of less than some THRESHOLD value, then return true, +else return false.

    + Currently, (3) is being used with a value of 36% Maximum wastage per + Super Block. +

    + A super block is the block of memory acquired from the FLS from + which the bitmap allocator carves out memory for single objects + and satisfies the user's requests. These super blocks come in + sizes that are powers of 2 and multiples of 32 + (_Bits_Per_Block). Yes both at the same time! That's because the + next super block acquired will be 2 times the previous one, and + also all super blocks have to be multiples of the _Bits_Per_Block + value. +

    + How does it interact with the free list store? +

    + The super block is contained in the FLS, and the FLS is responsible for + getting / returning Super Bocks to and from the OS using operator new + as defined by the C++ standard. +

    + Each Super Block will be of some size that is a multiple of the + number of Bits Per Block. Typically, this value is chosen as + Bits_Per_Byte x sizeof(size_t). On an x86 system, this gives the + figure 8 x 4 = 32. Thus, each Super Block will be of size 32 + x Some_Value. This Some_Value is sizeof(value_type). For now, let + it be called 'K'. Thus, finally, Super Block size is 32 x K bytes. +

    + This value of 32 has been chosen because each size_t has 32-bits + and Maximum use of these can be made with such a figure. +

    + Consider a block of size 64 ints. In memory, it would look like this: + (assume a 32-bit system where, size_t is a 32-bit entity). +

    Table 21.1. Bitmap Allocator Memory Map

    268042949672954294967295Data -> Space for 64 ints

    + The first Column(268) represents the size of the Block in bytes as + seen by the Bitmap Allocator. Internally, a global free list is + used to keep track of the free blocks used and given back by the + bitmap allocator. It is this Free List Store that is responsible + for writing and managing this information. Actually the number of + bytes allocated in this case would be: 4 + 4 + (4x2) + (64x4) = + 272 bytes, but the first 4 bytes are an addition by the Free List + Store, so the Bitmap Allocator sees only 268 bytes. These first 4 + bytes about which the bitmapped allocator is not aware hold the + value 268. +

    + What do the remaining values represent?

    + The 2nd 4 in the expression is the sizeof(size_t) because the + Bitmapped Allocator maintains a used count for each Super Block, + which is initially set to 0 (as indicated in the diagram). This is + incremented every time a block is removed from this super block + (allocated), and decremented whenever it is given back. So, when + the used count falls to 0, the whole super block will be given + back to the Free List Store. +

    + The value 4294967295 represents the integer corresponding to the bit + representation of all bits set: 11111111111111111111111111111111. +

    + The 3rd 4x2 is size of the bitmap itself, which is the size of 32-bits + x 2, + which is 8-bytes, or 2 x sizeof(size_t). +

    + This has nothing to do with the algorithm per-se, + only with some vales that must be chosen correctly to ensure that the + allocator performs well in a real word scenario, and maintains a good + balance between the memory consumption and the allocation/deallocation + speed. +

    + The formula for calculating the maximum wastage as a percentage: +

    +(32 x k + 1) / (2 x (32 x k + 1 + 32 x c)) x 100. +

    + where k is the constant overhead per node (e.g., for list, it is + 8 bytes, and for map it is 12 bytes) and c is the size of the + base type on which the map/list is instantiated. Thus, suppose the + type1 is int and type2 is double, they are related by the relation + sizeof(double) == 2*sizeof(int). Thus, all types must have this + double size relation for this formula to work properly. +

    + Plugging-in: For List: k = 8 and c = 4 (int and double), we get: + 33.376% +

    +For map/multimap: k = 12, and c = 4 (int and double), we get: 37.524% +

    + Thus, knowing these values, and based on the sizeof(value_type), we may + create a function that returns the Max_Wastage_Percentage for us to use. +

    + The allocate function is specialized for single object allocation + ONLY. Thus, ONLY if n == 1, will the bitmap_allocator's + specialized algorithm be used. Otherwise, the request is satisfied + directly by calling operator new. +

    + Suppose n == 1, then the allocator does the following: +

    1. + Checks to see whether a free block exists somewhere in a region + of memory close to the last satisfied request. If so, then that + block is marked as allocated in the bit map and given to the + user. If not, then (2) is executed. +

    2. + Is there a free block anywhere after the current block right + up to the end of the memory that we have? If so, that block is + found, and the same procedure is applied as above, and + returned to the user. If not, then (3) is executed. +

    3. + Is there any block in whatever region of memory that we own + free? This is done by checking +

      + Note: Here we are never touching any of the memory that the + user will be given, and we are confining all memory accesses + to a small region of memory! This helps reduce cache + misses. If this succeeds then we apply the same procedure on + that bit-map as (1), and return that block of memory to the + user. However, if this process fails, then we resort to (4). +

    4. + This process involves Refilling the internal exponentially + growing memory pool. The said effect is achieved by calling + _S_refill_pool which does the following: +

    +Thus, you can clearly see that the allocate function is nothing but a +combination of the next-fit and first-fit algorithm optimized ONLY for +single object allocations. +

    + The deallocate function again is specialized for single objects ONLY. + For all n belonging to > 1, the operator delete is called without + further ado, and the deallocate function returns. +

    + However for n == 1, a series of steps are performed: +

    1. + We first need to locate that super-block which holds the memory + location given to us by the user. For that purpose, we maintain + a static variable _S_last_dealloc_index, which holds the index + into the vector of block pairs which indicates the index of the + last super-block from which memory was freed. We use this + strategy in the hope that the user will deallocate memory in a + region close to what he/she deallocated the last time around. If + the check for belongs_to succeeds, then we determine the bit-map + for the given pointer, and locate the index into that bit-map, + and mark that bit as free by setting it. +

    2. + If the _S_last_dealloc_index does not point to the memory block + that we're looking for, then we do a linear search on the block + stored in the vector of Block Pairs. This vector in code is + called _S_mem_blocks. When the corresponding super-block is + found, we apply the same procedure as we did for (1) to mark the + block as free in the bit-map. +

    + Now, whenever a block is freed, the use count of that particular + super block goes down by 1. When this use count hits 0, we remove + that super block from the list of all valid super blocks stored in + the vector. While doing this, we also make sure that the basic + invariant is maintained by making sure that _S_last_request and + _S_last_dealloc_index point to valid locations within the vector. +

    +Q1) The "Data Layout" section is +cryptic. I have no idea of what you are trying to say. Layout of what? +The free-list? Each bitmap? The Super Block? +

    + The layout of a Super Block of a given +size. In the example, a super block of size 32 x 1 is taken. The +general formula for calculating the size of a super block is +32 x sizeof(value_type) x 2^n, where n ranges from 0 to 32 for 32-bit +systems. +

    + And since I just mentioned the +term `each bitmap', what in the world is meant by it? What does each +bitmap manage? How does it relate to the super block? Is the Super +Block a bitmap as well? +

    + Each bitmap is part of a Super Block which is made up of 3 parts + as I have mentioned earlier. Re-iterating, 1. The use count, + 2. The bit-map for that Super Block. 3. The actual memory that + will be eventually given to the user. Each bitmap is a multiple + of 32 in size. If there are 32 x (2^3) blocks of single objects + to be given, there will be '32 x (2^3)' bits present. Each 32 + bits managing the allocated / free status for 32 blocks. Since + each size_t contains 32-bits, one size_t can manage up to 32 + blocks' status. Each bit-map is made up of a number of size_t, + whose exact number for a super-block of a given size I have just + mentioned. +

    + How do the allocate and deallocate functions work in regard to + bitmaps? +

    + The allocate and deallocate functions manipulate the bitmaps and + have nothing to do with the memory that is given to the user. As + I have earlier mentioned, a 1 in the bitmap's bit field + indicates free, while a 0 indicates allocated. This lets us + check 32 bits at a time to check whether there is at lease one + free block in those 32 blocks by testing for equality with + (0). Now, the allocate function will given a memory block find + the corresponding bit in the bitmap, and will reset it (i.e., + make it re-set (0)). And when the deallocate function is called, + it will again set that bit after locating it to indicate that + that particular block corresponding to this bit in the bit-map + is not being used by anyone, and may be used to satisfy future + requests. +

    + e.g.: Consider a bit-map of 64-bits as represented below: + 1111111111111111111111111111111111111111111111111111111111111111 +

    + Now, when the first request for allocation of a single object + comes along, the first block in address order is returned. And + since the bit-maps in the reverse order to that of the address + order, the last bit (LSB if the bit-map is considered as a + binary word of 64-bits) is re-set to 0. +

    + The bit-map now looks like this: + 1111111111111111111111111111111111111111111111111111111111111110 +

    + Another issue would be whether to keep the all bitmaps in a + separate area in memory, or to keep them near the actual blocks + that will be given out or allocated for the client. After some + testing, I've decided to keep these bitmaps close to the actual + blocks. This will help in 2 ways. +

    1. Constant time access for the bitmap themselves, since no kind of +look up will be needed to find the correct bitmap list or its +equivalent.

    2. And also this would preserve the cache as far as possible.

    + So in effect, this kind of an allocator might prove beneficial from a + purely cache point of view. But this allocator has been made to try and + roll out the defects of the node_allocator, wherein the nodes get + skewed about in memory, if they are not returned in the exact reverse + order or in the same order in which they were allocated. Also, the + new_allocator's book keeping overhead is too much for small objects and + single object allocations, though it preserves the locality of blocks + very well when they are returned back to the allocator. +

    + Expected overhead per block would be 1 bit in memory. Also, once + the address of the free list has been found, the cost for + allocation/deallocation would be negligible, and is supposed to be + constant time. For these very reasons, it is very important to + minimize the linear time costs, which include finding a free list + with a free block while allocating, and finding the corresponding + free list for a block while deallocating. Therefore, I have + decided that the growth of the internal pool for this allocator + will be exponential as compared to linear for + node_allocator. There, linear time works well, because we are + mainly concerned with speed of allocation/deallocation and memory + consumption, whereas here, the allocation/deallocation part does + have some linear/logarithmic complexity components in it. Thus, to + try and minimize them would be a good thing to do at the cost of a + little bit of memory. +

    + Another thing to be noted is the pool size will double every time + the internal pool gets exhausted, and all the free blocks have + been given away. The initial size of the pool would be + sizeof(size_t) x 8 which is the number of bits in an integer, + which can fit exactly in a CPU register. Hence, the term given is + exponential growth of the internal pool. +

    Prev Up Next
    Chapter 21. The bitmap_allocator Home Chapter 22. Policy-Based Data Structures
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch23s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch23s02.html new file mode 100644 index 00000000000..29d9f5d1db6 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch23s02.html @@ -0,0 +1,50 @@ + + +Deprecated
    Deprecated
    Prev Chapter 23. HP/SGI Extensions Next

    + The SGI hashing classes hash_set and + hash_set have been deprecated by the + unordered_set, unordered_multiset, unordered_map, + unordered_multimap containers in TR1 and the upcoming C++0x, and + may be removed in future releases. +

    The SGI headers

    +     <hash_map>
+     <hash_set>
+     <rope>
+     <slist>
+     <rb_tree>
+

    are all here; + <hash_map> and <hash_set> + are deprecated but available as backwards-compatible extensions, + as discussed further below. <rope> is the + SGI specialization for large strings ("rope," + "large strings," get it? Love that geeky humor.) + <slist> is a singly-linked list, for when the + doubly-linked list<> is too much space + overhead, and <rb_tree> exposes the red-black + tree classes used in the implementation of the standard maps and + sets. +

    Each of the associative containers map, multimap, set, and multiset + have a counterpart which uses a + hashing + function to do the arranging, instead of a strict weak ordering + function. The classes take as one of their template parameters a + function object that will return the hash value; by default, an + instantiation of + hash. + You should specialize this functor for your class, or define your own, + before trying to use one of the hashing classes. +

    The hashing classes support all the usual associative container + functions, as well as some extra constructors specifying the number + of buckets, etc. +

    Why would you want to use a hashing class instead of the + “normal”implementations? Matt Austern writes: +

    + [W]ith a well chosen hash function, hash tables + generally provide much better average-case performance than + binary search trees, and much worse worst-case performance. So + if your implementation has hash_map, if you don't mind using + nonstandard components, and if you aren't scared about the + possibility of pathological cases, you'll probably get better + performance from hash_map. + +

    Prev Up Next
    Chapter 23. HP/SGI Extensions Home Chapter 24. Utilities
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch30s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch30s02.html new file mode 100644 index 00000000000..7d38a24dc7a --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch30s02.html @@ -0,0 +1,41 @@ + + +Implementation
    Implementation
    Prev Chapter 30. Concurrency Next

    The functions for atomic operations described above are either +implemented via compiler intrinsics (if the underlying host is +capable) or by library fallbacks.

    Compiler intrinsics (builtins) are always preferred. However, as +the compiler builtins for atomics are not universally implemented, +using them directly is problematic, and can result in undefined +function calls. (An example of an undefined symbol from the use +of __sync_fetch_and_add on an unsupported host is a +missing reference to __sync_fetch_and_add_4.) +

    In addition, on some hosts the compiler intrinsics are enabled +conditionally, via the -march command line flag. This makes +usage vary depending on the target hardware and the flags used during +compile. +

    +If builtins are possible for bool-sized integral types, +_GLIBCXX_ATOMIC_BUILTINS_1 will be defined. +If builtins are possible for int-sized integral types, +_GLIBCXX_ATOMIC_BUILTINS_4 will be defined. +

    For the following hosts, intrinsics are enabled by default. +

    For others, some form of -march may work. On +non-ancient x86 hardware, -march=native usually does the +trick.

    For hosts without compiler intrinsics, but with capable +hardware, hand-crafted assembly is selected. This is the case for the following hosts: +

    And for the rest, a simulated atomic lock via pthreads. +

    Detailed information about compiler intrinsics for atomic operations can be found in the GCC documentation. +

    More details on the library fallbacks from the porting section. +

    A thin layer above IEEE 1003.1 (i.e. pthreads) is used to abstract +the thread interface for GCC. This layer is called "gthread," and is +comprised of one header file that wraps the host's default thread layer with +a POSIX-like interface. +

    The file <gthr-default.h> points to the deduced wrapper for +the current host. In libstdc++ implementation files, +<bits/gthr.h> is used to select the proper gthreads file. +

    Within libstdc++ sources, all calls to underlying thread functionality +use this layer. More detail as to the specific interface can be found in the source documentation. +

    By design, the gthread layer is interoperable with the types, +functions, and usage found in the usual <pthread.h> file, +including pthread_t, pthread_once_t, pthread_create, +etc. +

    Prev Up Next
    Chapter 30. Concurrency Home Use
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch30s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch30s03.html new file mode 100644 index 00000000000..81df30435e5 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch30s03.html @@ -0,0 +1,36 @@ + + +Use
    Use
    Prev Chapter 30. Concurrency Next

    Typical usage of the last two constructs is demonstrated as follows: +

    +#include <ext/concurrence.h>
+
+namespace
+{
+  __gnu_cxx::__mutex safe_base_mutex;
+} // anonymous namespace
+
+namespace other
+{
+  void
+  foo()
+  {
+    __gnu_cxx::__scoped_lock sentry(safe_base_mutex);
+    for (int i = 0; i < max;  ++i)
+      {
+	_Safe_iterator_base* __old = __iter;
+	__iter = __iter-<_M_next;
+	__old-<_M_detach_single();
+      }
+}
+

    In this sample code, an anonymous namespace is used to keep +the __mutex private to the compilation unit, +and __scoped_lock is used to guard access to the critical +section within the for loop, locking the mutex on creation and freeing +the mutex as control moves out of this block. +

    Several exception classes are used to keep track of +concurrence-related errors. These classes +are: __concurrence_lock_error, __concurrence_unlock_error, __concurrence_wait_error, +and __concurrence_broadcast_error. +

    Prev Up Next
    Implementation Home Part IV.  + Appendices +
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03pr01.html b/libstdc++-v3/doc/html/manual/bk01pt03pr01.html index 7ca94896fff..7e3eb4ac9dc 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03pr01.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03pr01.html @@ -1,12 +1,13 @@ -<meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><link rel="home" href="../spine.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III.  Extensions"/><link rel="prev" href="extensions.html" title="Part III.  Extensions"/><link rel="next" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"/></tr><tr><td align="left"><a accesskey="p" href="extensions.html">Prev</a> </td><th width="60%" align="center">Part III.  +<html xmlns="http://www.w3.org/1999/xhtml"><head><title/><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" ISO C++ , library "/><meta name="keywords" content=" ISO C++ , runtime , library "/><link rel="home" href="../index.html" title="The GNU C++ Library"/><link rel="up" href="extensions.html" title="Part III.  Extensions"/><link rel="prev" href="extensions.html" title="Part III.  Extensions"/><link rel="next" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"/></tr><tr><td align="left"><a accesskey="p" href="extensions.html">Prev</a> </td><th width="60%" align="center">Part III.  Extensions -</th><td align="right"> <a accesskey="n" href="ext_compile_checks.html">Next</a></td></tr></table><hr/></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a id="id472170"/></h1></div></div></div><p> - Here we will make an attempt at describing the non-Standard extensions to - the library. Some of these are from SGI's STL, some of these are GNU's, - and some just seemed to appear on the doorstep. +</th><td align="right"> <a accesskey="n" href="ext_compile_checks.html">Next</a></td></tr></table><hr/></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a id="id654345"/></h1></div></div></div><p> + Here we will make an attempt at describing the non-Standard + extensions to the library. Some of these are from older versions of + standard library components, namely SGI's STL, and some of these are + GNU's. </p><p><span class="emphasis"><em>Before</em></span> you leap in and use any of these extensions, be aware of two things: </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p> @@ -23,4 +24,4 @@ extensions, be aware of two things: </p></li></ol></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="extensions.html">Prev</a> </td><td align="center"><a accesskey="u" href="extensions.html">Up</a></td><td align="right"> <a accesskey="n" href="ext_compile_checks.html">Next</a></td></tr><tr><td align="left" valign="top">Part III.  Extensions - </td><td align="center"><a accesskey="h" href="../spine.html">Home</a></td><td align="right" valign="top"> Chapter 16. Compile Time Checks</td></tr></table></div></body></html> + </td><td align="center"><a accesskey="h" href="../index.html">Home</a></td><td align="right" valign="top"> Chapter 16. Compile Time Checks</td></tr></table></div></body></html> diff --git a/libstdc++-v3/doc/html/manual/bk01pt04.html b/libstdc++-v3/doc/html/manual/bk01pt04.html index acdf72acafd..a12cff854f4 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt04.html +++ b/libstdc++-v3/doc/html/manual/bk01pt04.html @@ -1,8 +1,8 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Part IV.  Appendices
    Part IV.  +Part IV.  Appendices
    Part IV.  Appendices -
    Prev The GNU C++ Library Manual Next
    Prev The GNU C++ Library Manual Next

    Table of Contents

    A. Contributing @@ -10,12 +10,34 @@
    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Design Notes
    B. Porting and Maintenance -
    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Docbook
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Running the Testsuite
    Writing a new test case
    Test Harness and Utilities
    Special Topics
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    Second
    Third
    C. +
    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Prerequisites
    Generating the Doxygen Files
    Markup
    Docbook
    Prerequisites
    Generating the DocBook Files
    Editing and Validation
    File Organization and Basics
    Markup By Example
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Directory Layout
    Naming Conventions
    Running the Testsuite
    Basic
    Variations
    Permutations
    Writing a new test case
    Test Harness and Utilities
    Dejagnu Harness Details
    Utilities
    Special Topics
    + Qualifying Exception Safety Guarantees + +
    Overview
    + Existing tests +
    +C++0x Requirements Test Sequence Descriptions +
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Goals
    History
    Prerequisites
    Configuring
    Checking Active
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Single ABI Testing
    Multiple ABI Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    No ios_base
    No cout in ostream.h, no cin in istream.h
    Second
    Namespace std:: not supported
    Illegal iterator usage
    isspace from cctype is a macro +
    No vector::at, deque::at, string::at
    No std::char_traits<char>::eof
    No string::clear
    + Removal of ostream::form and istream::scan + extensions +
    No basic_stringbuf, basic_stringstream
    Little or no wide character support
    No templatized iostreams
    Thread safety issues
    Third
    Pre-ISO headers moved to backwards or removed
    Extension headers hash_map, hash_set moved to ext or backwards
    No ios::nocreate/ios::noreplace. +
    +No stream::attach(int fd) +
    +Support for C++98 dialect. +
    +Support for C++TR1 dialect. +
    +Support for C++0x dialect. +
    + Container::iterator_type is not necessarily Container::value_type* +
    C. Free Software Needs Free Documentation
    D. GNU General Public License version 3 -
    E. GNU Free Documentation License
    Prev Up Next
    Use Home Appendix A.  +
    E. GNU Free Documentation License
    Prev Up Next
    Use Home Appendix A.  Contributing
    diff --git a/libstdc++-v3/doc/html/manual/bugs.html b/libstdc++-v3/doc/html/manual/bugs.html index eb6efdcaf5f..a3dcaaf94cf 100644 --- a/libstdc++-v3/doc/html/manual/bugs.html +++ b/libstdc++-v3/doc/html/manual/bugs.html @@ -1,6 +1,6 @@ -Bugs
    Bugs
    Prev Chapter 1. Status Next

    +Bugs

    Bugs
    Prev Chapter 1. Status Next

    Information on known bugs, details on efforts to fix them, and fixed bugs are all available as part of the GCC bug tracking system, with the category set to libstdc++. @@ -349,4 +349,4 @@ More algorithms that throw away information

    The traditional HP / SGI return type and value is blessed by the resolution of the DR. -

    Prev Up Next
    License Home Chapter 2. Setup
    +

    Prev Up Next
    License Home Chapter 2. Setup
    diff --git a/libstdc++-v3/doc/html/manual/concurrency.html b/libstdc++-v3/doc/html/manual/concurrency.html index 5031a3299e5..7294c3ccd8d 100644 --- a/libstdc++-v3/doc/html/manual/concurrency.html +++ b/libstdc++-v3/doc/html/manual/concurrency.html @@ -1,13 +1,13 @@ -Chapter 15.  Concurrency
    Chapter 15.  +Chapter 15.  Concurrency
    Chapter 15.  Concurrency
    Prev Part II.  Standard Contents  Next

    Table of Contents

    API Reference

    Facilities for concurrent operation, and control thereof.

    @@ -36,7 +36,7 @@

    Prev Up Next
    Chapter 14.  Atomics - Home Part III.  + Home Part III.  Extensions
    diff --git a/libstdc++-v3/doc/html/manual/configure.html b/libstdc++-v3/doc/html/manual/configure.html index 70409d0c42f..92809aa09e9 100644 --- a/libstdc++-v3/doc/html/manual/configure.html +++ b/libstdc++-v3/doc/html/manual/configure.html @@ -1,6 +1,6 @@ -Configure
    Configure
    Prev Chapter 2. Setup Next

    +Configure

    Configure
    Prev Chapter 2. Setup Next

    When configuring libstdc++, you'll have to configure the entire gccsrcdir directory. Consider using the toplevel gcc configuration option @@ -208,4 +208,4 @@ freestanding environment, in which only a minimal set of headers are provided. This option builds such an environment. -

    Prev Up Next
    Chapter 2. Setup Home Make
    +

    Prev Up Next
    Chapter 2. Setup Home Make
    diff --git a/libstdc++-v3/doc/html/manual/containers.html b/libstdc++-v3/doc/html/manual/containers.html index 14b37374140..b95e4805a52 100644 --- a/libstdc++-v3/doc/html/manual/containers.html +++ b/libstdc++-v3/doc/html/manual/containers.html @@ -1,14 +1,14 @@ -Chapter 9.  Containers
    Chapter 9.  +Chapter 9.  Containers
    Chapter 9.  Containers
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Sequences
    list
    vector
    Associative
    Insertion Hints
    bitset
    Interacting with C
    Containers vs. Arrays

    + +

    Table of Contents

    Sequences
    list
    list::size() is O(n)
    vector
    Space Overhead Management
    Associative
    Insertion Hints
    bitset
    Size Variable
    Type String
    Interacting with C
    Containers vs. Arrays

    Yes it is, and that's okay. This is a decision that we preserved when we imported SGI's STL implementation. The following is quoted from their FAQ: @@ -52,4 +52,4 @@

    The first two alpha releases were announced here and here. -

    Prev Up Next
    Facets Home Associative
    +

    Prev Up Next
    Facets Home Associative
    diff --git a/libstdc++-v3/doc/html/manual/containers_and_c.html b/libstdc++-v3/doc/html/manual/containers_and_c.html index 3e612aa5a50..33ae476501f 100644 --- a/libstdc++-v3/doc/html/manual/containers_and_c.html +++ b/libstdc++-v3/doc/html/manual/containers_and_c.html @@ -1,6 +1,6 @@ -Interacting with C
    Interacting with C
    Prev Chapter 9.  +Interacting with C
    Interacting with C
    Prev Chapter 9.  Containers  Next

    @@ -84,7 +84,7 @@ template<typename T, unsigned int sz> inline unsigned int lengthof (T (&)[sz]) { return sz; }

    looks just weird! Hint: unused parameters can be left nameless. -

    Prev Up Next
    Associative Home Chapter 10.  +

    Prev Up Next
    Associative Home Chapter 10.  Iterators
    diff --git a/libstdc++-v3/doc/html/manual/debug.html b/libstdc++-v3/doc/html/manual/debug.html index 55b5abf7674..70edbf2a59e 100644 --- a/libstdc++-v3/doc/html/manual/debug.html +++ b/libstdc++-v3/doc/html/manual/debug.html @@ -1,6 +1,6 @@ -Debugging Support
    Debugging Support
    Prev Chapter 3. Using Next

    +Debugging Support

    Debugging Support
    Prev Chapter 3. Using Next

    There are numerous things that can be done to improve the ease with which C++ binaries are debugged when using the GNU tool chain. Here are some of them. @@ -67,7 +67,7 @@ thing of great importance to keep in mind when debugging C++ code that uses new and delete: there are different kinds of allocation schemes that can be used by - std::allocator . For implementation details, see the mt allocator documentation and + std::allocator . For implementation details, see the mt allocator documentation and look specifically for GLIBCXX_FORCE_NEW.

    In a nutshell, the default allocator used by @@ -226,6 +226,6 @@

    The Profile-based Performance Analysis Extension has performance checks for many algorithms. -

    Prev Up Next
    Exceptions Home Part II.  +

    Prev Up Next
    Exceptions Home Part II.  Standard Contents
    diff --git a/libstdc++-v3/doc/html/manual/debug_mode.html b/libstdc++-v3/doc/html/manual/debug_mode.html index f35960b53b7..99a90e5f300 100644 --- a/libstdc++-v3/doc/html/manual/debug_mode.html +++ b/libstdc++-v3/doc/html/manual/debug_mode.html @@ -1,9 +1,10 @@ -Chapter 17. Debug Mode
    Chapter 17. Debug Mode
    Prev Part III.  +Chapter 17. Debug Mode
    Chapter 17. Debug Mode
    Prev Part III.  Extensions - Next

    Table of Contents

    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    Other Implementations

    +

    		 Next

    Table of Contents

    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    The Wrapper Model
    Safe Iterators
    Safe Sequences (Containers)
    Precondition Checking
    Release- and debug-mode coexistence
    Compile-time coexistence of release- and debug-mode components
    Link- and run-time coexistence of release- and + debug-mode components
    Alternatives for Coexistence
    Other Implementations

    By default, libstdc++ is built with efficiency in mind, and therefore performs little or no error checking that is not required by the C++ standard. This means that programs that @@ -34,4 +35,4 @@ the same predicate that was passed to set_intersection; the libstdc++ debug mode will detect an error if the sequence is not sorted or was sorted by a - different predicate.

    Prev Up Next
    Chapter 16. Compile Time Checks Home Semantics
    + different predicate.

    Prev Up Next
    Chapter 16. Compile Time Checks Home Semantics
    diff --git a/libstdc++-v3/doc/html/manual/diagnostics.html b/libstdc++-v3/doc/html/manual/diagnostics.html index d4fbf34d856..399d7719d07 100644 --- a/libstdc++-v3/doc/html/manual/diagnostics.html +++ b/libstdc++-v3/doc/html/manual/diagnostics.html @@ -1,13 +1,13 @@ -Chapter 5.  Diagnostics
    Chapter 5.  +Chapter 5.  Diagnostics
    Chapter 5.  Diagnostics
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Exceptions
    API Reference
    Adding Data to exception
    Concept Checking

    All exception objects are defined in one of the standard header files: exception, @@ -40,4 +40,4 @@ int e; DBID id; // some user-defined type }; -

    Prev Up Next
    Termination Home Concept Checking
    +
    Prev Up Next
    Termination Home Concept Checking
    diff --git a/libstdc++-v3/doc/html/manual/documentation_hacking.html b/libstdc++-v3/doc/html/manual/documentation_hacking.html index 3ad897f1509..293d2a922d7 100644 --- a/libstdc++-v3/doc/html/manual/documentation_hacking.html +++ b/libstdc++-v3/doc/html/manual/documentation_hacking.html @@ -1,6 +1,6 @@ -Writing and Generating Documentation
    Writing and Generating Documentation
    Prev Appendix B.  +Writing and Generating Documentation
    Writing and Generating Documentation
    Prev Appendix B.  Porting and Maintenance  Next

    @@ -117,7 +117,7 @@ supported, and are always aliased to dummy rules. These unsupported formats are: info, ps, and dvi. -

    Table B.1. Doxygen Prerequisites

    ToolVersionRequired By
    coreutils8.5all
    bash4.1all
    doxygen1.7.0all
    graphviz2.26graphical hierarchies
    pdflatex2007-59pdf output

    +

    Table B.1. Doxygen Prerequisites

    ToolVersionRequired By
    coreutils8.5all
    bash4.1all
    doxygen1.7.0all
    graphviz2.26graphical hierarchies
    pdflatex2007-59pdf output

    Prerequisite tools are Bash 2.0 or later, Doxygen, and the GNU @@ -263,7 +263,7 @@ writing Doxygen comments. Single and double quotes, and separators in filenames are two common trouble spots. When in doubt, consult the following table. -

    Table B.2. HTML to Doxygen Markup Comparison

    HTMLDoxygen
    \\\
    "\"
    '\'
    <i>@a word
    <b>@b word
    <code>@c word
    <em>@a word
    <em><em>two words or more</em>

    Table B.3. Docbook Prerequisites

    ToolVersionRequired By
    docbook5-style-xsl1.76.1all
    xsltproc1.1.26all
    xmllint2.7.7validation
    dblatex0.3pdf output
    pdflatex2007-59pdf output
    docbook2X0.8.8info output

    +

    Table B.2. HTML to Doxygen Markup Comparison

    HTMLDoxygen
    \\\
    "\"
    '\'
    <i>@a word
    <b>@b word
    <code>@c word
    <em>@a word
    <em><em>two words or more</em>

    Table B.3. Docbook Prerequisites

    ToolVersionRequired By
    docbook5-style-xsl1.76.1all
    xsltproc1.1.26all
    xmllint2.7.7validation
    dblatex0.3pdf output
    pdflatex2007-59pdf output
    docbook2X0.8.8info output

    Editing the DocBook sources requires an XML editor. Many exist: some notable options include emacs, Kate, @@ -419,11 +419,11 @@ make XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwal online. An incomplete reference for HTML to Docbook conversion is detailed in the table below. -

    Table B.4. HTML to Docbook XML Markup Comparison

    HTMLDocbook
    <p><para>
    <pre><computeroutput>, <programlisting>, +

    Table B.4. HTML to Docbook XML Markup Comparison

    HTMLDocbook
    <p><para>
    <pre><computeroutput>, <programlisting>, <literallayout>
    <ul><itemizedlist>
    <ol><orderedlist>
    <il><listitem>
    <dl><variablelist>
    <dt><term>
    <dd><listitem>
    <a href=""><ulink url="">
    <code><literal>, <programlisting>
    <strong><emphasis>
    <em><emphasis>
    "<quote>

    And examples of detailed markup for which there are no real HTML equivalents are listed in the table below. -

    Table B.5. Docbook XML Element Use

    ElementUse
    <structname><structname>char_traits</structname>
    <classname><classname>string</classname>
    <function> +

    Table B.5. Docbook XML Element Use

    ElementUse
    <structname><structname>char_traits</structname>
    <classname><classname>string</classname>
    <function>

    <function>clear()</function>

    <function>fs.clear()</function>

    <type><type>long long</type>
    <varname><varname>fs</varname>
    <literal> @@ -439,4 +439,4 @@ make XSL_STYLE_DIR="/usr/share/xml/docbook/stylesheet/nwal

    Prev Up Next
    Appendix B.  Porting and Maintenance - Home Porting to New Hardware or Operating Systems
    +     		Home Porting to New Hardware or Operating Systems
    diff --git a/libstdc++-v3/doc/html/manual/dynamic_memory.html b/libstdc++-v3/doc/html/manual/dynamic_memory.html index 481347bef07..4303d3fe685 100644 --- a/libstdc++-v3/doc/html/manual/dynamic_memory.html +++ b/libstdc++-v3/doc/html/manual/dynamic_memory.html @@ -1,6 +1,6 @@ -Dynamic Memory
    Dynamic Memory
    Prev Chapter 4.  +Dynamic Memory
    Dynamic Memory
    Prev Chapter 4.  Support  Next

    @@ -69,4 +69,4 @@

    Prev Up Next
    Chapter 4.  Support - Home Termination
    +     		Home Termination
    diff --git a/libstdc++-v3/doc/html/manual/ext_algorithms.html b/libstdc++-v3/doc/html/manual/ext_algorithms.html index 354dd9bbc7c..744829a65f1 100644 --- a/libstdc++-v3/doc/html/manual/ext_algorithms.html +++ b/libstdc++-v3/doc/html/manual/ext_algorithms.html @@ -1,9 +1,9 @@ -Chapter 23. Algorithms
    Chapter 23. Algorithms
    Prev Part III.  +Chapter 25. Algorithms
    Chapter 25. Algorithms
    Prev Part III.  Extensions - Next

    25.1.6 (count, count_if) is extended with two more versions of count +

    		 Next

    25.1.6 (count, count_if) is extended with two more versions of count and count_if. The standard versions return their results. The additional signatures return void, but take a final parameter by reference to which they assign their results, e.g., @@ -20,4 +20,4 @@ 

        lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
 				 _InputIter2 first2, _InputIter2 last2)

    which does... what? -

    Prev Up Next
    Chapter 22. Utilities Home Chapter 24. Numerics
    +

    Prev Up Next
    Chapter 24. Utilities Home Chapter 26. Numerics
    diff --git a/libstdc++-v3/doc/html/manual/ext_allocators.html b/libstdc++-v3/doc/html/manual/ext_allocators.html deleted file mode 100644 index bd283b75c40..00000000000 --- a/libstdc++-v3/doc/html/manual/ext_allocators.html +++ /dev/null @@ -1,397 +0,0 @@ - - -Chapter 20. Allocators
    Chapter 20. Allocators
    Prev Part III.  - Extensions - - Next

    Table of Contents

    mt_allocator
    Intro
    Design Issues
    Implementation
    Single Thread Example
    Multiple Thread Example
    bitmap_allocator
    Design
    Implementation

    -

    - The mt allocator [hereinafter referred to simply as "the allocator"] - is a fixed size (power of two) allocator that was initially - developed specifically to suit the needs of multi threaded - applications [hereinafter referred to as an MT application]. Over - time the allocator has evolved and been improved in many ways, in - particular it now also does a good job in single threaded - applications [hereinafter referred to as a ST application]. (Note: - In this document, when referring to single threaded applications - this also includes applications that are compiled with gcc without - thread support enabled. This is accomplished using ifdef's on - __GTHREADS). This allocator is tunable, very flexible, and capable - of high-performance. -

    - The aim of this document is to describe - from an application point of - view - the "inner workings" of the allocator. -

    There are three general components to the allocator: a datum -describing the characteristics of the memory pool, a policy class -containing this pool that links instantiation types to common or -individual pools, and a class inheriting from the policy class that is -the actual allocator. -

    The datum describing pools characteristics is -

    -  template<bool _Thread>
-    class __pool
-

    This class is parametrized on thread support, and is explicitly -specialized for both multiple threads (with bool==true) -and single threads (via bool==false.) It is possible to -use a custom pool datum instead of the default class that is provided. -

    There are two distinct policy classes, each of which can be used -with either type of underlying pool datum. -

    -  template<bool _Thread>
-    struct __common_pool_policy
-
-  template<typename _Tp, bool _Thread>
-    struct __per_type_pool_policy
-

    The first policy, __common_pool_policy, implements a -common pool. This means that allocators that are instantiated with -different types, say char and long will both -use the same pool. This is the default policy. -

    The second policy, __per_type_pool_policy, implements -a separate pool for each instantiating type. Thus, char -and long will use separate pools. This allows per-type -tuning, for instance. -

    Putting this all together, the actual allocator class is -

    -  template<typename _Tp, typename _Poolp = __default_policy>
-    class __mt_alloc : public __mt_alloc_base<_Tp>,  _Poolp
-

    This class has the interface required for standard library allocator -classes, namely member functions allocate and -deallocate, plus others. -

    Certain allocation parameters can be modified, or tuned. There -exists a nested struct __pool_base::_Tune that contains all -these parameters, which include settings for -

    Adjusting parameters for a given instance of an allocator can only -happen before any allocations take place, when the allocator itself is -initialized. For instance: -

    -#include <ext/mt_allocator.h>
-
-struct pod
-{
-  int i;
-  int j;
-};
-
-int main()
-{
-  typedef pod value_type;
-  typedef __gnu_cxx::__mt_alloc<value_type> allocator_type;
-  typedef __gnu_cxx::__pool_base::_Tune tune_type;
-
-  tune_type t_default;
-  tune_type t_opt(16, 5120, 32, 5120, 20, 10, false);
-  tune_type t_single(16, 5120, 32, 5120, 1, 10, false);
-
-  tune_type t;
-  t = allocator_type::_M_get_options();
-  allocator_type::_M_set_options(t_opt);
-  t = allocator_type::_M_get_options();
-
-  allocator_type a;
-  allocator_type::pointer p1 = a.allocate(128);
-  allocator_type::pointer p2 = a.allocate(5128);
-
-  a.deallocate(p1, 128);
-  a.deallocate(p2, 5128);
-
-  return 0;
-}
-

    -The static variables (pointers to freelists, tuning parameters etc) -are initialized as above, or are set to the global defaults. -

    -The very first allocate() call will always call the -_S_initialize_once() function. In order to make sure that this -function is called exactly once we make use of a __gthread_once call -in MT applications and check a static bool (_S_init) in ST -applications. -

    -The _S_initialize() function: -- If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool - _S_force_new to true and then returns. This will cause subsequent calls to - allocate() to return memory directly from a new() call, and deallocate will - only do a delete() call. -

    -- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT - applications will: - - Calculate the number of bins needed. A bin is a specific power of two size - of bytes. I.e., by default the allocator will deal with requests of up to - 128 bytes (or whatever the value of _S_max_bytes is when _S_init() is - called). This means that there will be bins of the following sizes - (in bytes): 1, 2, 4, 8, 16, 32, 64, 128. - - - Create the _S_binmap array. All requests are rounded up to the next - "large enough" bin. I.e., a request for 29 bytes will cause a block from - the "32 byte bin" to be returned to the application. The purpose of - _S_binmap is to speed up the process of finding out which bin to use. - I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes). -

    - - Create the _S_bin array. This array consists of bin_records. There will be - as many bin_records in this array as the number of bins that we calculated - earlier. I.e., if _S_max_bytes = 128 there will be 8 entries. - Each bin_record is then initialized: - - bin_record->first = An array of pointers to block_records. There will be - as many block_records pointers as there are maximum number of threads - (in a ST application there is only 1 thread, in a MT application there - are _S_max_threads). - This holds the pointer to the first free block for each thread in this - bin. I.e., if we would like to know where the first free block of size 32 - for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ] - - The above created block_record pointers members are now initialized to - their initial values. I.e. _S_bin[ n ].first[ n ] = NULL; -

    -- Additionally a MT application will: - - Create a list of free thread id's. The pointer to the first entry - is stored in _S_thread_freelist_first. The reason for this approach is - that the __gthread_self() call will not return a value that corresponds to - the maximum number of threads allowed but rather a process id number or - something else. So what we do is that we create a list of thread_records. - This list is _S_max_threads long and each entry holds a size_t thread_id - which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads. - Each time a thread calls allocate() or deallocate() we call - _S_get_thread_id() which looks at the value of _S_thread_key which is a - thread local storage pointer. If this is NULL we know that this is a newly - created thread and we pop the first entry from this list and saves the - pointer to this record in the _S_thread_key variable. The next time - we will get the pointer to the thread_record back and we use the - thread_record->thread_id as identification. I.e., the first thread that - calls allocate will get the first record in this list and thus be thread - number 1 and will then find the pointer to its first free 32 byte block - in _S_bin[ 5 ].first[ 1 ] - When we create the _S_thread_key we also define a destructor - (_S_thread_key_destr) which means that when the thread dies, this - thread_record is returned to the front of this list and the thread id - can then be reused if a new thread is created. - This list is protected by a mutex (_S_thread_freelist_mutex) which is only - locked when records are removed or added to the list. -

    - - Initialize the free and used counters of each bin_record: - - bin_record->free = An array of size_t. This keeps track of the number - of blocks on a specific thread's freelist in each bin. I.e., if a thread - has 12 32-byte blocks on it's freelists and allocates one of these, this - counter would be decreased to 11. - - - bin_record->used = An array of size_t. This keeps track of the number - of blocks currently in use of this size by this thread. I.e., if a thread - has made 678 requests (and no deallocations...) of 32-byte blocks this - counter will read 678. - - The above created arrays are now initialized with their initial values. - I.e. _S_bin[ n ].free[ n ] = 0; -

    - - Initialize the mutex of each bin_record: The bin_record->mutex - is used to protect the global freelist. This concept of a global - freelist is explained in more detail in the section "A multi - threaded example", but basically this mutex is locked whenever a - block of memory is retrieved or returned to the global freelist - for this specific bin. This only occurs when a number of blocks - are grabbed from the global list to a thread specific list or when - a thread decides to return some blocks to the global freelist. -

    Notes about deallocation. This allocator does not explicitly -release memory. Because of this, memory debugging programs like -valgrind or purify may notice leaks: sorry about this -inconvenience. Operating systems will reclaim allocated memory at -program termination anyway. If sidestepping this kind of noise is -desired, there are three options: use an allocator, like -new_allocator that releases memory while debugging, use -GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a -custom pool datum that releases resources on destruction. -

    - On systems with the function __cxa_atexit, the -allocator can be forced to free all memory allocated before program -termination with the member function -__pool_type::_M_destroy. However, because this member -function relies on the precise and exactly-conforming ordering of -static destructors, including those of a static local -__pool object, it should not be used, ever, on systems -that don't have the necessary underlying support. In addition, in -practice, forcing deallocation can be tricky, as it requires the -__pool object to be fully-constructed before the object -that uses it is fully constructed. For most (but not all) STL -containers, this works, as an instance of the allocator is constructed -as part of a container's constructor. However, this assumption is -implementation-specific, and subject to change. For an example of a -pool that frees memory, see the following - - example. -

    -Let's start by describing how the data on a freelist is laid out in memory. -This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes): -

    -+----------------+
-| next* ---------|--+  (_S_bin[ 3 ].first[ 3 ] points here)
-|                |  |
-|                |  |
-|                |  |
-+----------------+  |
-| thread_id = 3  |  |
-|                |  |
-|                |  |
-|                |  |
-+----------------+  |
-| DATA           |  |  (A pointer to here is what is returned to the
-|                |  |   the application when needed)
-|                |  |
-|                |  |
-|                |  |
-|                |  |
-|                |  |
-|                |  |
-+----------------+  |
-+----------------+  |
-| next*          |<-+  (If next == NULL it's the last one on the list)
-|                |
-|                |
-|                |
-+----------------+
-| thread_id = 3  |
-|                |
-|                |
-|                |
-+----------------+
-| DATA           |
-|                |
-|                |
-|                |
-|                |
-|                |
-|                |
-|                |
-+----------------+
-

    -With this in mind we simplify things a bit for a while and say that there is -only one thread (a ST application). In this case all operations are made to -what is referred to as the global pool - thread id 0 (No thread may be -assigned this id since they span from 1 to _S_max_threads in a MT application). -

    -When the application requests memory (calling allocate()) we first look at the -requested size and if this is > _S_max_bytes we call new() directly and return. -

    -If the requested size is within limits we start by finding out from which -bin we should serve this request by looking in _S_binmap. -

    -A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of -this size on the freelist (0). If this is not NULL - fine, just remove the -block that _S_bin[ bin ].first[ 0 ] points to from the list, -update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data. -

    -If the freelist is empty (the pointer is NULL) we must get memory from the -system and build us a freelist within this memory. All requests for new memory -is made in chunks of _S_chunk_size. Knowing the size of a block_record and -the bytes that this bin stores we then calculate how many blocks we can create -within this chunk, build the list, remove the first block, update the pointer -(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data. -

    -Deallocation is equally simple; the pointer is casted back to a block_record -pointer, lookup which bin to use based on the size, add the block to the front -of the global freelist and update the pointer as needed -(_S_bin[ bin ].first[ 0 ]). -

    -The decision to add deallocated blocks to the front of the freelist was made -after a set of performance measurements that showed that this is roughly 10% -faster than maintaining a set of "last pointers" as well. -

    -In the ST example we never used the thread_id variable present in each block. -Let's start by explaining the purpose of this in a MT application. -

    -The concept of "ownership" was introduced since many MT applications -allocate and deallocate memory to shared containers from different -threads (such as a cache shared amongst all threads). This introduces -a problem if the allocator only returns memory to the current threads -freelist (I.e., there might be one thread doing all the allocation and -thus obtaining ever more memory from the system and another thread -that is getting a longer and longer freelist - this will in the end -consume all available memory). -

    -Each time a block is moved from the global list (where ownership is -irrelevant), to a threads freelist (or when a new freelist is built -from a chunk directly onto a threads freelist or when a deallocation -occurs on a block which was not allocated by the same thread id as the -one doing the deallocation) the thread id is set to the current one. -

    -What's the use? Well, when a deallocation occurs we can now look at -the thread id and find out if it was allocated by another thread id -and decrease the used counter of that thread instead, thus keeping the -free and used counters correct. And keeping the free and used counters -corrects is very important since the relationship between these two -variables decides if memory should be returned to the global pool or -not when a deallocation occurs. -

    -When the application requests memory (calling allocate()) we first -look at the requested size and if this is >_S_max_bytes we call new() -directly and return. -

    -If the requested size is within limits we start by finding out from which -bin we should serve this request by looking in _S_binmap. -

    -A call to _S_get_thread_id() returns the thread id for the calling thread -(and if no value has been set in _S_thread_key, a new id is assigned and -returned). -

    -A quick look at _S_bin[ bin ].first[ thread_id ] tells us if there are -any blocks of this size on the current threads freelist. If this is -not NULL - fine, just remove the block that _S_bin[ bin ].first[ -thread_id ] points to from the list, update _S_bin[ bin ].first[ -thread_id ], update the free and used counters and return a pointer to -that blocks data. -

    -If the freelist is empty (the pointer is NULL) we start by looking at -the global freelist (0). If there are blocks available on the global -freelist we lock this bins mutex and move up to block_count (the -number of blocks of this bins size that will fit into a _S_chunk_size) -or until end of list - whatever comes first - to the current threads -freelist and at the same time change the thread_id ownership and -update the counters and pointers. When the bins mutex has been -unlocked, we remove the block that _S_bin[ bin ].first[ thread_id ] -points to from the list, update _S_bin[ bin ].first[ thread_id ], -update the free and used counters, and return a pointer to that blocks -data. -

    -The reason that the number of blocks moved to the current threads -freelist is limited to block_count is to minimize the chance that a -subsequent deallocate() call will return the excess blocks to the -global freelist (based on the _S_freelist_headroom calculation, see -below). -

    -However if there isn't any memory on the global pool we need to get -memory from the system - this is done in exactly the same way as in a -single threaded application with one major difference; the list built -in the newly allocated memory (of _S_chunk_size size) is added to the -current threads freelist instead of to the global. -

    -The basic process of a deallocation call is simple: always add the -block to the front of the current threads freelist and update the -counters and pointers (as described earlier with the specific check of -ownership that causes the used counter of the thread that originally -allocated the block to be decreased instead of the current threads -counter). -

    -And here comes the free and used counters to service. Each time a -deallocation() call is made, the length of the current threads -freelist is compared to the amount memory in use by this thread. -

    -Let's go back to the example of an application that has one thread -that does all the allocations and one that deallocates. Both these -threads use say 516 32-byte blocks that was allocated during thread -creation for example. Their used counters will both say 516 at this -point. The allocation thread now grabs 1000 32-byte blocks and puts -them in a shared container. The used counter for this thread is now -1516. -

    -The deallocation thread now deallocates 500 of these blocks. For each -deallocation made the used counter of the allocating thread is -decreased and the freelist of the deallocation thread gets longer and -longer. But the calculation made in deallocate() will limit the length -of the freelist in the deallocation thread to _S_freelist_headroom % -of it's used counter. In this case, when the freelist (given that the -_S_freelist_headroom is at it's default value of 10%) exceeds 52 -(516/10) blocks will be returned to the global pool where the -allocating thread may pick them up and reuse them. -

    -In order to reduce lock contention (since this requires this bins -mutex to be locked) this operation is also made in chunks of blocks -(just like when chunks of blocks are moved from the global freelist to -a threads freelist mentioned above). The "formula" used can probably -be improved to further reduce the risk of blocks being "bounced back -and forth" between freelists. -

    Prev Up Next
    Diagnostics Home bitmap_allocator
    diff --git a/libstdc++-v3/doc/html/manual/ext_compile_checks.html b/libstdc++-v3/doc/html/manual/ext_compile_checks.html index c648797c181..63ffe75723f 100644 --- a/libstdc++-v3/doc/html/manual/ext_compile_checks.html +++ b/libstdc++-v3/doc/html/manual/ext_compile_checks.html @@ -1,6 +1,6 @@ -Chapter 16. Compile Time Checks
    Chapter 16. Compile Time Checks
    Prev Part III.  +Chapter 16. Compile Time Checks
    Chapter 16. Compile Time Checks
    Prev Part III.  Extensions  Next

    @@ -37,4 +37,4 @@ support for template parameter constraints based on concepts in the core language. This will obviate the need for the library-simulated concept checking described above. -

    Prev Up Next
     Home Chapter 17. Debug Mode
    +

    Prev Up Next
     Home Chapter 17. Debug Mode
    diff --git a/libstdc++-v3/doc/html/manual/ext_concurrency.html b/libstdc++-v3/doc/html/manual/ext_concurrency.html index 99718e04f5e..d321c5aa93a 100644 --- a/libstdc++-v3/doc/html/manual/ext_concurrency.html +++ b/libstdc++-v3/doc/html/manual/ext_concurrency.html @@ -1,9 +1,9 @@ -Chapter 28. Concurrency
    Chapter 28. Concurrency
    Prev Part III.  +Chapter 30. Concurrency
    Chapter 30. Concurrency
    Prev Part III.  Extensions - Next

    Table of Contents

    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use

    The file <ext/concurrence.h> contains all the higher-level +

    		 Next

    Table of Contents

    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use

    The file <ext/concurrence.h> contains all the higher-level constructs for playing with threads. In contrast to the atomics layer, the concurrence layer consists largely of types. All types are defined within namespace __gnu_cxx.

    @@ -88,4 +88,4 @@ _GLIBCXX_WRITE_MEM_BARRIER

    Which expand to the appropriate write and read barrier required by the host hardware and operating system. -

    Prev Up Next
    Chapter 27. Demangling Home Implementation
    +

    Prev Up Next
    Chapter 29. Demangling Home Implementation
    diff --git a/libstdc++-v3/doc/html/manual/ext_containers.html b/libstdc++-v3/doc/html/manual/ext_containers.html index d07860bbd68..d422675138b 100644 --- a/libstdc++-v3/doc/html/manual/ext_containers.html +++ b/libstdc++-v3/doc/html/manual/ext_containers.html @@ -1,9 +1,46 @@ -Chapter 21. Containers
    Chapter 21. Containers
    Prev Part III.  +Chapter 23. HP/SGI Extensions
    Chapter 23. HP/SGI Extensions
    Prev Part III.  Extensions - Next

    Table of Contents

    Policy Based Data Structures
    HP/SGI
    Deprecated HP/SGI

    -

    - More details here. -

    Prev Up Next
    bitmap_allocator Home HP/SGI
    +    		 Next

    Table of Contents

    Backwards Compatibility
    Deprecated

    A few extensions and nods to backwards-compatibility have + been made with containers. Those dealing with older SGI-style + allocators are dealt with elsewhere. The remaining ones all deal + with bits: +

    The old pre-standard bit_vector class is + present for backwards compatibility. It is simply a typedef for + the vector<bool> specialization. +

    The bitset class has a number of extensions, described in the + rest of this item. First, we'll mention that this implementation of + bitset<N> is specialized for cases where N number of + bits will fit into a single word of storage. If your choice of N is + within that range (<=32 on i686-pc-linux-gnu, for example), then all + of the operations will be faster. +

    There are + versions of single-bit test, set, reset, and flip member functions which + do no range-checking. If we call them member functions of an instantiation + of "bitset<N>," then their names and signatures are: +

    +   bitset<N>&   _Unchecked_set   (size_t pos);
+   bitset<N>&   _Unchecked_set   (size_t pos, int val);
+   bitset<N>&   _Unchecked_reset (size_t pos);
+   bitset<N>&   _Unchecked_flip  (size_t pos);
+   bool         _Unchecked_test  (size_t pos);
+

    Note that these may in fact be removed in the future, although we have + no present plans to do so (and there doesn't seem to be any immediate + reason to). +

    The semantics of member function operator[] are not specified + in the C++ standard. A long-standing defect report calls for sensible + obvious semantics, which are already implemented here: op[] + on a const bitset returns a bool, and for a non-const bitset returns a + reference (a nested type). However, this implementation does + no range-checking on the index argument, which is in keeping with other + containers' op[] requirements. The defect report's proposed + resolution calls for range-checking to be done. We'll just wait and see... +

    Finally, two additional searching functions have been added. They return + the index of the first "on" bit, and the index of the first + "on" bit that is after prev, respectively: +

    +   size_t _Find_first() const;
+   size_t _Find_next (size_t prev) const;

    The same caveat given for the _Unchecked_* functions applies here also. +

    Prev Up Next
    Acknowledgments Home Deprecated
    diff --git a/libstdc++-v3/doc/html/manual/ext_demangling.html b/libstdc++-v3/doc/html/manual/ext_demangling.html index 0120bc2b050..455a705f9c2 100644 --- a/libstdc++-v3/doc/html/manual/ext_demangling.html +++ b/libstdc++-v3/doc/html/manual/ext_demangling.html @@ -1,9 +1,9 @@ -Chapter 27. Demangling
    Chapter 27. Demangling
    Prev Part III.  +Chapter 29. Demangling
    Chapter 29. Demangling
    Prev Part III.  Extensions - Next

    +

    		 Next

    Transforming C++ ABI identifiers (like RTTI symbols) into the original C++ source identifiers is called “demangling.” @@ -71,4 +71,4 @@ int main() be writing C++ in order to demangle C++. (That also means we have to use crummy memory management facilities, so don't forget to free() the returned char array.) -

    Prev Up Next
    Chapter 26. Input and Output Home Chapter 28. Concurrency
    +

    Prev Up Next
    Chapter 28. Input and Output Home Chapter 30. Concurrency
    diff --git a/libstdc++-v3/doc/html/manual/ext_io.html b/libstdc++-v3/doc/html/manual/ext_io.html index aba0fe1d634..84879447684 100644 --- a/libstdc++-v3/doc/html/manual/ext_io.html +++ b/libstdc++-v3/doc/html/manual/ext_io.html @@ -1,9 +1,9 @@ -Chapter 26. Input and Output
    Chapter 26. Input and Output
    Prev Part III.  +Chapter 28. Input and Output
    Chapter 28. Input and Output
    Prev Part III.  Extensions - Next

    Table of Contents

    Derived filebufs

    +

    		 Next

    Table of Contents

    Derived filebufs

    Extensions allowing filebufs to be constructed from "C" types like FILE*s and file descriptors.

    The v2 library included non-standard extensions to construct @@ -47,4 +47,4 @@ call) then you might be interested in Henry Suter's RWLock class.

    -

    Prev Up Next
    Chapter 25. Iterators Home Chapter 27. Demangling
    +

    Prev Up Next
    Chapter 27. Iterators Home Chapter 29. Demangling
    diff --git a/libstdc++-v3/doc/html/manual/ext_iterators.html b/libstdc++-v3/doc/html/manual/ext_iterators.html index 8c00985c4dc..5085c6bcc8a 100644 --- a/libstdc++-v3/doc/html/manual/ext_iterators.html +++ b/libstdc++-v3/doc/html/manual/ext_iterators.html @@ -1,9 +1,9 @@ -Chapter 25. Iterators
    Chapter 25. Iterators
    Prev Part III.  +Chapter 27. Iterators
    Chapter 27. Iterators
    Prev Part III.  Extensions - Next

    24.3.2 describes struct iterator, which didn't exist in the +

    		 Next

    24.3.2 describes struct iterator, which didn't exist in the original HP STL implementation (the language wasn't rich enough at the time). For backwards compatibility, base classes are provided which declare the same nested typedefs: @@ -11,4 +11,4 @@ two iterators and returns a result. It is extended by another signature which takes two iterators and a reference to a result. The result is modified, and the function returns nothing. -

    Prev Up Next
    Chapter 24. Numerics Home Chapter 26. Input and Output
    +

    Prev Up Next
    Chapter 26. Numerics Home Chapter 28. Input and Output
    diff --git a/libstdc++-v3/doc/html/manual/ext_numerics.html b/libstdc++-v3/doc/html/manual/ext_numerics.html index 71d417c3af2..1fbb34aaebe 100644 --- a/libstdc++-v3/doc/html/manual/ext_numerics.html +++ b/libstdc++-v3/doc/html/manual/ext_numerics.html @@ -1,9 +1,9 @@ -Chapter 24. Numerics
    Chapter 24. Numerics
    Prev Part III.  +Chapter 26. Numerics
    Chapter 26. Numerics
    Prev Part III.  Extensions - Next

    26.4, the generalized numeric operations such as accumulate, are extended +

    		 Next

    26.4, the generalized numeric operations such as accumulate, are extended with the following functions: 

        power (x, n);
@@ -17,4 +17,4 @@
    That is, it assigns value to *first, value + 1 to *(first + 1) and so
    on."  Quoted from SGI documentation.
 
    -   void iota(_ForwardIter first, _ForwardIter last, _Tp value);
    Prev Up Next
    Chapter 23. Algorithms Home Chapter 25. Iterators
    + void iota(_ForwardIter first, _ForwardIter last, _Tp value);
    Prev Up Next
    Chapter 25. Algorithms Home Chapter 27. Iterators
    diff --git a/libstdc++-v3/doc/html/manual/ext_utilities.html b/libstdc++-v3/doc/html/manual/ext_utilities.html index d15057c2778..aba78264765 100644 --- a/libstdc++-v3/doc/html/manual/ext_utilities.html +++ b/libstdc++-v3/doc/html/manual/ext_utilities.html @@ -1,9 +1,9 @@ -Chapter 22. Utilities
    Chapter 22. Utilities
    Prev Part III.  +Chapter 24. Utilities
    Chapter 24. Utilities
    Prev Part III.  Extensions - Next

    +

    		 Next

    The <functional> header contains many additional functors and helper functions, extending section 20.3. They are implemented in the file stl_function.h: @@ -38,4 +38,4 @@ get_temporary_buffer(5, (int*)0);

    The specialized algorithms of section 20.4.4 are extended with uninitialized_copy_n. * -

    Prev Up Next
    Deprecated HP/SGI Home Chapter 23. Algorithms
    +

    Prev Up Next
    Deprecated Home Chapter 25. Algorithms
    diff --git a/libstdc++-v3/doc/html/manual/extensions.html b/libstdc++-v3/doc/html/manual/extensions.html index 1b59f2f862c..4e6a01495c3 100644 --- a/libstdc++-v3/doc/html/manual/extensions.html +++ b/libstdc++-v3/doc/html/manual/extensions.html @@ -1,9 +1,74 @@ -Part III.  Extensions
    Part III.  +Part III.  Extensions
    Part III.  Extensions
    Prev The GNU C++ Library Manual Next

    Table of Contents

    16. Compile Time Checks
    17. Debug Mode
    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    Other Implementations
    18. Parallel Mode
    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Implementation Namespaces
    Testing
    Bibliography
    19. Profile Mode
    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Algorithms
    Data Locality
    Multithreaded Data Access
    Statistics
    Bibliography
    20. Allocators
    mt_allocator
    Intro
    Design Issues
    Implementation
    Single Thread Example
    Multiple Thread Example
    bitmap_allocator
    Design
    Implementation
    21. Containers
    Policy Based Data Structures
    HP/SGI
    Deprecated HP/SGI
    22. Utilities
    23. Algorithms
    24. Numerics
    25. Iterators
    26. Input and Output
    Derived filebufs
    27. Demangling
    28. Concurrency
    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use
    Prev Up Next
    Interacting with C Home 
    + +

    Table of Contents

    16. Compile Time Checks
    17. Debug Mode
    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    The Wrapper Model
    Safe Iterators
    Safe Sequences (Containers)
    Precondition Checking
    Release- and debug-mode coexistence
    Compile-time coexistence of release- and debug-mode components
    Link- and run-time coexistence of release- and + debug-mode components
    Alternatives for Coexistence
    Other Implementations
    18. Parallel Mode
    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Setting up the OpenMP Environment
    Compile Time Switches
    Run Time Settings and Defaults
    Implementation Namespaces
    Testing
    Bibliography
    19. Profile Mode
    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Hashtable Too Small
    Hashtable Too Large
    Inefficient Hash
    Vector Too Small
    Vector Too Large
    Vector to Hashtable
    Hashtable to Vector
    Vector to List
    List to Vector
    List to Forward List (Slist)
    Ordered to Unordered Associative Container
    Algorithms
    Sort Algorithm Performance
    Data Locality
    Need Software Prefetch
    Linked Structure Locality
    Multithreaded Data Access
    Data Dependence Violations at Container Level
    False Sharing
    Statistics
    Bibliography
    20. The mt_allocator
    Intro
    Design Issues
    Overview
    Implementation
    Tunable Parameters
    Initialization
    Deallocation Notes
    Single Thread Example
    Multiple Thread Example
    21. The bitmap_allocator
    Design
    Implementation
    Free List Store
    Super Block
    Super Block Data Layout
    Maximum Wasted Percentage
    allocate
    deallocate
    Questions
    1
    2
    3
    Locality
    Overhead and Grow Policy
    22. Policy-Based Data Structures
    Intro
    Performance Issues
    Associative
    Priority Que
    Goals
    Associative
    Policy Choices
    Underlying Data Structures
    Iterators
    Functional
    Priority Queues
    Policy Choices
    Underlying Data Structures
    Binary Heaps
    Using
    Prerequisites
    Organization
    Tutorial
    Basic Use
    + Configuring via Template Parameters +
    + Querying Container Attributes +
    + Point and Range Iteration +
    Examples
    Intermediate Use
    Querying with container_traits
    By Container Method
    Hash-Based
    Branch-Based
    Priority Queues
    Design
    Concepts
    Null Policy Classes
    Map and Set Semantics
    + Distinguishing Between Maps and Sets +
    Alternatives to std::multiset and std::multimap
    Iterator Semantics
    Point and Range Iterators
    Distinguishing Point and Range Iterators
    Invalidation Guarantees
    Genericity
    Tag
    Traits
    By Container
    hash
    Interface
    Details
    tree
    Interface
    Details
    Trie
    Interface
    Details
    List
    Interface
    Details
    Priority Queue
    Interface
    Details
    Testing
    Regression
    Performance
    Hash-Based
    + Text find +
    + Integer find +
    + Integer Subscript find +
    + Integer Subscript insert +
    + Integer find with Skewed-Distribution +
    + Erase Memory Use +
    Branch-Based
    + Text insert +
    + Text find +
    + Text find with Locality-of-Reference +
    + split and join +
    + Order-Statistics +
    Multimap
    + Text find with Small Secondary-to-Primary Key Ratios +
    + Text find with Large Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios Memory Use +
    + Text insert with Small + Secondary-to-Primary Key Ratios Memory Use +
    Priority Queue
    + Text push +
    + Text push and pop +
    + Integer push +
    + Integer push +
    + Text pop Memory Use +
    + Text join +
    + Text modify Up +
    + Text modify Down +
    Observations
    Associative
    Priority_Queue
    Acknowledgments
    + Bibliography +
    23. HP/SGI Extensions
    Backwards Compatibility
    Deprecated
    24. Utilities
    25. Algorithms
    26. Numerics
    27. Iterators
    28. Input and Output
    Derived filebufs
    29. Demangling
    30. Concurrency
    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use
    Prev Up Next
    Interacting with C Home 
    diff --git a/libstdc++-v3/doc/html/manual/facets.html b/libstdc++-v3/doc/html/manual/facets.html index 25f0e142573..33350cd5914 100644 --- a/libstdc++-v3/doc/html/manual/facets.html +++ b/libstdc++-v3/doc/html/manual/facets.html @@ -1,9 +1,9 @@ -Facets
    Facets
    Prev Chapter 8.  +Facets
    Facets
    Prev Chapter 8.  Localization - Next

    +

    		 Next

    For the required specialization codecvt<wchar_t, char, mbstate_t> , conversions are made between the internal character set (always UCS4 on GNU/Linux) and whatever the currently selected locale for the @@ -50,23 +50,24 @@ characters.

  • Rename abstract base class. See if just smash-overriding is a better approach. Clarify, add sanity to naming. -

    • +

    The GNU C Library - . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling and 7 Locales and Internationalization.

    + . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling and 7 Locales and Internationalization.

    Correspondence - . Ulrich Drepper. Copyright © 2002 .

    + . Ulrich Drepper. Copyright © 2002 .

    ISO/IEC 14882:1998 Programming languages - C++ - . Copyright © 1998 ISO.

    + . Copyright © 1998 ISO.

    ISO/IEC 9899:1999 Programming languages - C - . Copyright © 1999 ISO.

    - . + . Copyright © 1999 ISO.

    + The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004) + . Copyright © 1999 - The Open Group/The Institute of Electrical and Electronics Engineers, Inc..

    + The Open Group/The Institute of Electrical and Electronics Engineers, Inc..

    The C++ Programming Language, Special Edition . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. Addison Wesley - .

    + .

    Standard C++ IOStreams and Locales . Advanced Programmer's Guide and Reference @@ -409,42 +410,46 @@ codecvt usage.

  • wchar_t/char internal buffers and conversions between internal/external buffers? -

    • +

    The GNU C Library . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling and 7 Locales and Internationalization - .

    + .

    Correspondence - . Ulrich Drepper. Copyright © 2002 .

    + . Ulrich Drepper. Copyright © 2002 .

    ISO/IEC 14882:1998 Programming languages - C++ - . Copyright © 1998 ISO.

    + . Copyright © 1998 ISO.

    ISO/IEC 9899:1999 Programming languages - C - . Copyright © 1999 ISO.

    - . + . Copyright © 1999 ISO.

    + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) - . Copyright © 2008 + + . Copyright © 2008 The Open Group/The Institute of Electrical and Electronics Engineers, Inc. - .

    + .

    The C++ Programming Language, Special Edition . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. Addison Wesley - .

    + .

    Standard C++ IOStreams and Locales . Advanced Programmer's Guide and Reference . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. Addison Wesley Longman - .

    - . + .

    + A brief description of Normative Addendum 1 - . Clive Feather. Extended Character Sets.

    - . + + . Clive Feather. Extended Character Sets.

    + The Unicode HOWTO - . Bruno Haible.

    - . + + . Bruno Haible.

    + UTF-8 and Unicode FAQ for Unix/Linux - . Markus Khun.

    + + . Markus Khun.

    The std::messages facet implements message retrieval functionality equivalent to Java's java.text.MessageFormat .using either GNU gettext or IEEE 1003.1-200 functions. @@ -685,44 +690,47 @@ void test01() model. As of this writing, it is unknown how to query to see if a specified message catalog exists using the gettext package. -

    +

    The GNU C Library . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling, and 7 Locales and Internationalization - .

    + .

    Correspondence - . Ulrich Drepper. Copyright © 2002 .

    + . Ulrich Drepper. Copyright © 2002 .

    ISO/IEC 14882:1998 Programming languages - C++ - . Copyright © 1998 ISO.

    + . Copyright © 1998 ISO.

    ISO/IEC 9899:1999 Programming languages - C - . Copyright © 1999 ISO.

    - . + . Copyright © 1999 ISO.

    + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) - . Copyright © 2008 + + . Copyright © 2008 The Open Group/The Institute of Electrical and Electronics Engineers, Inc. - .

    + .

    The C++ Programming Language, Special Edition . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. Addison Wesley - .

    + .

    Standard C++ IOStreams and Locales . Advanced Programmer's Guide and Reference . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. Addison Wesley Longman - .

    - . + .

    + API Specifications, Java Platform + . java.util.Properties, java.text.MessageFormat, java.util.Locale, java.util.ResourceBundle - .

    - . + .

    + GNU gettext tools, version 0.10.38, Native Language Support Library and Tools. - .

    Prev Up Next
    Chapter 8.  + + .

    Prev Up Next
    Chapter 8.  Localization - Home Chapter 9.  + Home Chapter 9.  Containers
    diff --git a/libstdc++-v3/doc/html/manual/fstreams.html b/libstdc++-v3/doc/html/manual/fstreams.html index 6c03a2bb62a..44f57272804 100644 --- a/libstdc++-v3/doc/html/manual/fstreams.html +++ b/libstdc++-v3/doc/html/manual/fstreams.html @@ -1,6 +1,6 @@ -File Based Streams
    File Based Streams
    Prev Chapter 13.  +File Based Streams
    File Based Streams
    Prev Chapter 13.  Input and Output  Next

    @@ -147,4 +147,4 @@ between arbitrary programs, or across a network, or from one invocation of a program to another invocation of the same program on a different platform, etc. -

    Prev Up Next
    Memory Based Streams Home Interacting with C
    +

    Prev Up Next
    Memory Based Streams Home Interacting with C
    diff --git a/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html b/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html index 043cbeb36dd..a203d3e3bfa 100644 --- a/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html +++ b/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html @@ -1,6 +1,6 @@ -Generalized Operations
    Generalized Operations
    Prev Chapter 12.  +Generalized Operations
    Generalized Operations
    Prev Chapter 12.  Numerics  Next

    @@ -29,4 +29,4 @@

    Prev Up Next
    Chapter 12.  Numerics - Home Interacting with C
    +     		Home Interacting with C
    diff --git a/libstdc++-v3/doc/html/manual/index.html b/libstdc++-v3/doc/html/manual/index.html new file mode 100644 index 00000000000..d2108b00eca --- /dev/null +++ b/libstdc++-v3/doc/html/manual/index.html @@ -0,0 +1,166 @@ + + +The GNU C++ Library Manual
    The GNU C++ Library Manual
    Prev   Next

    Table of Contents

    I. + Introduction + +
    1. Status
    Implementation Status
    C++ 1998/2003
    Implementation Status
    Implementation Specific Behavior
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs
    2. Setup
    Prerequisites
    Configure
    Make
    3. Using
    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Structure
    Defaults
    Future
    Alternatives
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    With C
    With POSIX thread cancellation
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Data Race Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis
    II. + Standard Contents +
    4. + Support + +
    Types
    Fundamental Types
    Numeric Properties
    NULL
    Dynamic Memory
    Termination
    Termination Handlers
    Verbose Terminate Handler
    5. + Diagnostics + +
    Exceptions
    API Reference
    Adding Data to exception
    Concept Checking
    6. + Utilities + +
    Functors
    Pairs
    Memory
    Allocators
    Requirements
    Design Issues
    Implementation
    Interface Design
    Selecting Default Allocation Policy
    Disabling Memory Caching
    Using a Specific Allocator
    Custom Allocators
    Extension Allocators
    auto_ptr
    Limitations
    Use in Containers
    shared_ptr
    Requirements
    Design Issues
    Implementation
    Class Hierarchy
    Thread Safety
    Selecting Lock Policy
    Dual C++0x and TR1 Implementation
    Related functions and classes
    Use
    Examples
    Unresolved Issues
    Acknowledgments
    Traits
    7. + Strings + +
    String Classes
    Simple Transformations
    Case Sensitivity
    Arbitrary Character Types
    Tokenizing
    Shrink to Fit
    CString (MFC)
    8. + Localization + +
    Locales
    locale
    Requirements
    Design
    Implementation
    Interacting with "C" locales
    Future
    Facets
    ctype
    Implementation
    Specializations
    Future
    codecvt
    Requirements
    Design
    wchar_t Size
    Support for Unicode
    Other Issues
    Implementation
    Use
    Future
    messages
    Requirements
    Design
    Implementation
    Models
    The GNU Model
    Use
    Future
    9. + Containers + +
    Sequences
    list
    list::size() is O(n)
    vector
    Space Overhead Management
    Associative
    Insertion Hints
    bitset
    Size Variable
    Type String
    Interacting with C
    Containers vs. Arrays
    10. + Iterators + +
    Predefined
    Iterators vs. Pointers
    One Past the End
    11. + Algorithms + +
    Mutating
    swap
    Specializations
    12. + Numerics + +
    Complex
    complex Processing
    Generalized Operations
    Interacting with C
    Numerics vs. Arrays
    C99
    13. + Input and Output + +
    Iostream Objects
    Stream Buffers
    Derived streambuf Classes
    Buffering
    Memory Based Streams
    Compatibility With strstream
    File Based Streams
    Copying a File
    Binary Input and Output
    Interacting with C
    Using FILE* and file descriptors
    Performance
    14. + Atomics + +
    API Reference
    15. + Concurrency + +
    API Reference
    III. + Extensions + +
    16. Compile Time Checks
    17. Debug Mode
    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    The Wrapper Model
    Safe Iterators
    Safe Sequences (Containers)
    Precondition Checking
    Release- and debug-mode coexistence
    Compile-time coexistence of release- and debug-mode components
    Link- and run-time coexistence of release- and + debug-mode components
    Alternatives for Coexistence
    Other Implementations
    18. Parallel Mode
    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Setting up the OpenMP Environment
    Compile Time Switches
    Run Time Settings and Defaults
    Implementation Namespaces
    Testing
    Bibliography
    19. Profile Mode
    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Hashtable Too Small
    Hashtable Too Large
    Inefficient Hash
    Vector Too Small
    Vector Too Large
    Vector to Hashtable
    Hashtable to Vector
    Vector to List
    List to Vector
    List to Forward List (Slist)
    Ordered to Unordered Associative Container
    Algorithms
    Sort Algorithm Performance
    Data Locality
    Need Software Prefetch
    Linked Structure Locality
    Multithreaded Data Access
    Data Dependence Violations at Container Level
    False Sharing
    Statistics
    Bibliography
    20. The mt_allocator
    Intro
    Design Issues
    Overview
    Implementation
    Tunable Parameters
    Initialization
    Deallocation Notes
    Single Thread Example
    Multiple Thread Example
    21. The bitmap_allocator
    Design
    Implementation
    Free List Store
    Super Block
    Super Block Data Layout
    Maximum Wasted Percentage
    allocate
    deallocate
    Questions
    1
    2
    3
    Locality
    Overhead and Grow Policy
    22. Policy-Based Data Structures
    Intro
    Performance Issues
    Associative
    Priority Que
    Goals
    Associative
    Policy Choices
    Underlying Data Structures
    Iterators
    Functional
    Priority Queues
    Policy Choices
    Underlying Data Structures
    Binary Heaps
    Using
    Prerequisites
    Organization
    Tutorial
    Basic Use
    + Configuring via Template Parameters +
    + Querying Container Attributes +
    + Point and Range Iteration +
    Examples
    Intermediate Use
    Querying with container_traits
    By Container Method
    Hash-Based
    Branch-Based
    Priority Queues
    Design
    Concepts
    Null Policy Classes
    Map and Set Semantics
    + Distinguishing Between Maps and Sets +
    Alternatives to std::multiset and std::multimap
    Iterator Semantics
    Point and Range Iterators
    Distinguishing Point and Range Iterators
    Invalidation Guarantees
    Genericity
    Tag
    Traits
    By Container
    hash
    Interface
    Details
    tree
    Interface
    Details
    Trie
    Interface
    Details
    List
    Interface
    Details
    Priority Queue
    Interface
    Details
    Testing
    Regression
    Performance
    Hash-Based
    + Text find +
    + Integer find +
    + Integer Subscript find +
    + Integer Subscript insert +
    + Integer find with Skewed-Distribution +
    + Erase Memory Use +
    Branch-Based
    + Text insert +
    + Text find +
    + Text find with Locality-of-Reference +
    + split and join +
    + Order-Statistics +
    Multimap
    + Text find with Small Secondary-to-Primary Key Ratios +
    + Text find with Large Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios Memory Use +
    + Text insert with Small + Secondary-to-Primary Key Ratios Memory Use +
    Priority Queue
    + Text push +
    + Text push and pop +
    + Integer push +
    + Integer push +
    + Text pop Memory Use +
    + Text join +
    + Text modify Up +
    + Text modify Down +
    Observations
    Associative
    Priority_Queue
    Acknowledgments
    + Bibliography +
    23. HP/SGI Extensions
    Backwards Compatibility
    Deprecated
    24. Utilities
    25. Algorithms
    26. Numerics
    27. Iterators
    28. Input and Output
    Derived filebufs
    29. Demangling
    30. Concurrency
    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use
    IV. + Appendices +
    A. + Contributing + +
    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Design Notes
    B. + Porting and Maintenance + +
    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Prerequisites
    Generating the Doxygen Files
    Markup
    Docbook
    Prerequisites
    Generating the DocBook Files
    Editing and Validation
    File Organization and Basics
    Markup By Example
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Directory Layout
    Naming Conventions
    Running the Testsuite
    Basic
    Variations
    Permutations
    Writing a new test case
    Test Harness and Utilities
    Dejagnu Harness Details
    Utilities
    Special Topics
    + Qualifying Exception Safety Guarantees + +
    Overview
    + Existing tests +
    +C++0x Requirements Test Sequence Descriptions +
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Goals
    History
    Prerequisites
    Configuring
    Checking Active
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Single ABI Testing
    Multiple ABI Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    No ios_base
    No cout in ostream.h, no cin in istream.h
    Second
    Namespace std:: not supported
    Illegal iterator usage
    isspace from cctype is a macro +
    No vector::at, deque::at, string::at
    No std::char_traits<char>::eof
    No string::clear
    + Removal of ostream::form and istream::scan + extensions +
    No basic_stringbuf, basic_stringstream
    Little or no wide character support
    No templatized iostreams
    Thread safety issues
    Third
    Pre-ISO headers moved to backwards or removed
    Extension headers hash_map, hash_set moved to ext or backwards
    No ios::nocreate/ios::noreplace. +
    +No stream::attach(int fd) +
    +Support for C++98 dialect. +
    +Support for C++TR1 dialect. +
    +Support for C++0x dialect. +
    + Container::iterator_type is not necessarily Container::value_type* +
    C. + Free Software Needs Free Documentation + +
    D. + GNU General Public License version 3 +
    E. GNU Free Documentation License

    List of Figures

    22.1. Node Invariants
    22.2. Underlying Associative Data Structures
    22.3. Range Iteration in Different Data Structures
    22.4. Point Iteration in Hash Data Structures
    22.5. Effect of erase in different underlying data structures
    22.6. Underlying Priority Queue Data Structures
    22.7. Exception Hierarchy
    22.8. Non-unique Mapping Standard Containers
    22.9. + Effect of embedded lists in + std::multimap +
    22.10. Non-unique Mapping Containers
    22.11. Point Iterator Hierarchy
    22.12. Invalidation Guarantee Tags Hierarchy
    22.13. Container Tag Hierarchy
    22.14. Hash functions, ranged-hash functions, and + range-hashing functions
    22.15. Insert hash sequence diagram
    22.16. Insert hash sequence diagram with a null policy
    22.17. Hash policy class diagram
    22.18. Balls and bins
    22.19. Insert resize sequence diagram
    22.20. Standard resize policy trigger sequence + diagram
    22.21. Standard resize policy size sequence + diagram
    22.22. Tree node invariants
    22.23. Tree node invalidation
    22.24. A tree and its update policy
    22.25. Restoring node invariants
    22.26. Insert update sequence
    22.27. Useless update path
    22.28. A PATRICIA trie
    22.29. A trie and its update policy
    22.30. A simple list
    22.31. The counter algorithm
    22.32. Underlying Priority-Queue Data-Structures.
    22.33. Priority-Queue Data-Structure Tags.
    B.1. Configure and Build File Dependencies

    List of Tables

    1.1. C++ 1998/2003 Implementation Status
    1.2. C++ 200x Implementation Status
    1.3. C++ TR1 Implementation Status
    1.4. C++ TR 24733 Implementation Status
    3.1. C++ Command Options
    3.2. C++ 1998 Library Headers
    3.3. C++ 1998 Library Headers for C Library Facilities
    3.4. C++ 200x Library Headers
    3.5. C++ 200x Library Headers for C Library Facilities
    3.6. C++ TR 1 Library Headers
    3.7. C++ TR 1 Library Headers for C Library Facilities
    3.8. C++ TR 24733 Decimal Floating-Point Header
    3.9. C++ ABI Headers
    3.10. Extension Headers
    3.11. Extension Debug Headers
    3.12. Extension Profile Headers
    3.13. Extension Parallel Headers
    17.1. Debugging Containers
    17.2. Debugging Containers C++0x
    18.1. Parallel Algorithms
    19.1. Profile Code Location
    19.2. Profile Diagnostics
    21.1. Bitmap Allocator Memory Map
    B.1. Doxygen Prerequisites
    B.2. HTML to Doxygen Markup Comparison
    B.3. Docbook Prerequisites
    B.4. HTML to Docbook XML Markup Comparison
    B.5. Docbook XML Element Use
    B.6. Extension Allocators
    B.7. Extension Allocators Continued

    List of Equations

    22.1. Ranged Hash Function
    22.2. Range-Hashing, Division Method
    22.3. Division via Prime Modulo
    22.4. Division via Bit Mask
    22.5. + A Standard String Hash Function +
    22.6. + Only k String DNA Hash +
    22.7. + Probability of Probe Sequence of Length k +
    22.8. + Probability Probe Sequence in Some Bin +
    Prev   Next
    The GNU C++ Library Home Part I.  + Introduction + +
    diff --git a/libstdc++-v3/doc/html/manual/internals.html b/libstdc++-v3/doc/html/manual/internals.html index a80fea357b7..48b190b5146 100644 --- a/libstdc++-v3/doc/html/manual/internals.html +++ b/libstdc++-v3/doc/html/manual/internals.html @@ -1,6 +1,6 @@ -Porting to New Hardware or Operating Systems
    Porting to New Hardware or Operating Systems
    Prev Appendix B.  +Porting to New Hardware or Operating Systems
    Porting to New Hardware or Operating Systems
    Prev Appendix B.  Porting and Maintenance  Next

    @@ -365,4 +365,4 @@ do this is to build the library using gcc -shared. ltcf-c.sh in the top-level directory. Find the switch statement that sets archive_cmds. Here, adjust the setting for your operating system. -

    Prev Up Next
    Writing and Generating Documentation Home Test
    +

    Prev Up Next
    Writing and Generating Documentation Home Test
    diff --git a/libstdc++-v3/doc/html/manual/intro.html b/libstdc++-v3/doc/html/manual/intro.html index a7c6bd2149a..f0bc8ce6ea2 100644 --- a/libstdc++-v3/doc/html/manual/intro.html +++ b/libstdc++-v3/doc/html/manual/intro.html @@ -1,9 +1,9 @@ -Part I.  Introduction
    Part I.  +Part I.  Introduction
    Part I.  Introduction -
    Prev The GNU C++ Library Manual Next
    Prev The GNU C++ Library Manual Next

    Table of Contents

    1. Status
    Implementation Status
    C++ 1998/2003
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs
    2. Setup
    Prerequisites
    Configure
    Make
    3. Using
    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Data Race Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis
    Prev Up Next
    The GNU C++ Library Manual Home Chapter 1. Status
    + +

    Table of Contents

    1. Status
    Implementation Status
    C++ 1998/2003
    Implementation Status
    Implementation Specific Behavior
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs
    2. Setup
    Prerequisites
    Configure
    Make
    3. Using
    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Structure
    Defaults
    Future
    Alternatives
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    With C
    With POSIX thread cancellation
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Data Race Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis
    Prev Up Next
    The GNU C++ Library Manual Home Chapter 1. Status
    diff --git a/libstdc++-v3/doc/html/manual/io.html b/libstdc++-v3/doc/html/manual/io.html index 5591e165d6c..d2544ae1295 100644 --- a/libstdc++-v3/doc/html/manual/io.html +++ b/libstdc++-v3/doc/html/manual/io.html @@ -1,13 +1,13 @@ -Chapter 13.  Input and Output
    Chapter 13.  +Chapter 13.  Input and Output
    Chapter 13.  Input and Output
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Iostream Objects
    Stream Buffers
    Derived streambuf Classes
    Buffering
    Memory Based Streams
    Compatibility With strstream
    File Based Streams
    Copying a File
    Binary Input and Output
    Interacting with C
    Using FILE* and file descriptors
    Performance

    To minimize the time you have to wait on the compiler, it's good to only include the headers you really need. Many people simply include <iostream> when they don't need to -- and that can penalize @@ -118,4 +118,4 @@ the standard objects in that source file; you'll pay less startup time. Only include the header files you need to in general; your compile times will go down when there's less parsing work to do. -

    Prev Up Next
    Interacting with C Home Stream Buffers
    +

    Prev Up Next
    Interacting with C Home Stream Buffers
    diff --git a/libstdc++-v3/doc/html/manual/io_and_c.html b/libstdc++-v3/doc/html/manual/io_and_c.html index 6b4066154f7..425d165148b 100644 --- a/libstdc++-v3/doc/html/manual/io_and_c.html +++ b/libstdc++-v3/doc/html/manual/io_and_c.html @@ -1,10 +1,10 @@ -Interacting with C
    Interacting with C
    Prev Chapter 13.  +Interacting with C
    Interacting with C
    Prev Chapter 13.  Input and Output  Next

    - See the extensions for using + See the extensions for using FILE and file descriptors with ofstream and ifstream. @@ -51,7 +51,7 @@ clog, and their wide-character counterchapters). File stream objects that you declare yourself have no such requirement and are fully buffered. -

    Prev Up Next
    File Based Streams Home Chapter 14.  +

    Prev Up Next
    File Based Streams Home Chapter 14.  Atomics
    diff --git a/libstdc++-v3/doc/html/manual/iterators.html b/libstdc++-v3/doc/html/manual/iterators.html index 2ca7cb47360..d47ca9bf0e3 100644 --- a/libstdc++-v3/doc/html/manual/iterators.html +++ b/libstdc++-v3/doc/html/manual/iterators.html @@ -1,13 +1,13 @@ -Chapter 10.  Iterators
    Chapter 10.  +Chapter 10.  Iterators
    Chapter 10.  Iterators
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Predefined
    Iterators vs. Pointers
    One Past the End

    The following FAQ entry points out that @@ -124,7 +124,7 @@ classes. sequences very simple to recognize: if the two endpoints compare equal, then the {array, sequence, container, whatever} is empty.

    Just don't dereference end(). -

    Prev Up Next
    Interacting with C Home Chapter 11.  +

    Prev Up Next
    Interacting with C Home Chapter 11.  Algorithms
    diff --git a/libstdc++-v3/doc/html/manual/license.html b/libstdc++-v3/doc/html/manual/license.html index da021a9fe79..52a63ff3079 100644 --- a/libstdc++-v3/doc/html/manual/license.html +++ b/libstdc++-v3/doc/html/manual/license.html @@ -1,6 +1,6 @@ -License
    License
    Prev Chapter 1. Status Next

    +License

    License
    Prev Chapter 1. Status Next

    There are two licenses affecting GNU libstdc++: one for the code, and one for the documentation.

    @@ -102,4 +102,4 @@ requirements of the license of GCC.

    If you plan on making copies of the documentation, please let us know. We can probably offer suggestions. -

    Prev Up Next
    Chapter 1. Status Home Bugs
    +

    Prev Up Next
    Chapter 1. Status Home Bugs
    diff --git a/libstdc++-v3/doc/html/manual/localization.html b/libstdc++-v3/doc/html/manual/localization.html index e440c5a10cd..a9171a98797 100644 --- a/libstdc++-v3/doc/html/manual/localization.html +++ b/libstdc++-v3/doc/html/manual/localization.html @@ -1,14 +1,14 @@ -Chapter 8.  Localization
    Chapter 8.  +Chapter 8.  Localization
    Chapter 8.  Localization
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Locales
    locale
    Facets
    ctype
    codecvt
    messages

    + +

    Table of Contents

    Locales
    locale
    Requirements
    Design
    Implementation
    Interacting with "C" locales
    Future
    Facets
    ctype
    Implementation
    Specializations
    Future
    codecvt
    Requirements
    Design
    wchar_t Size
    Support for Unicode
    Other Issues
    Implementation
    Use
    Future
    messages
    Requirements
    Design
    Implementation
    Models
    The GNU Model
    Use
    Future

    Describes the basic locale object, including nested classes id, facet, and the reference-counted implementation object, class _Impl. @@ -403,28 +403,29 @@ global locale" (emphasis Paolo), that is: What should non-required facet instantiations do? If the generic implementation is provided, then how to end-users provide specializations? -

    +

    The GNU C Library . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling and 7 Locales and Internationalization - .

    + .

    Correspondence - . Ulrich Drepper. Copyright © 2002 .

    + . Ulrich Drepper. Copyright © 2002 .

    ISO/IEC 14882:1998 Programming languages - C++ - . Copyright © 1998 ISO.

    + . Copyright © 1998 ISO.

    ISO/IEC 9899:1999 Programming languages - C - . Copyright © 1999 ISO.

    - . + . Copyright © 1999 ISO.

    + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) - . Copyright © 2008 + + . Copyright © 2008 The Open Group/The Institute of Electrical and Electronics Engineers, Inc. - .

    + .

    The C++ Programming Language, Special Edition . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. Addison Wesley - .

    + .

    Standard C++ IOStreams and Locales . Advanced Programmer's Guide and Reference @@ -433,4 +434,4 @@ global locale" (emphasis Paolo), that is: .

    Prev Up Next
    Chapter 7.  Strings - Home Facets
    +     		Home Facets
    diff --git a/libstdc++-v3/doc/html/manual/make.html b/libstdc++-v3/doc/html/manual/make.html index 62b1499240f..f032333c69b 100644 --- a/libstdc++-v3/doc/html/manual/make.html +++ b/libstdc++-v3/doc/html/manual/make.html @@ -1,9 +1,9 @@ -Make
    Make
    Prev Chapter 2. Setup Next

    If you have never done this before, you should read the basic +Make

    Make
    Prev Chapter 2. Setup Next

    If you have never done this before, you should read the basic GCC Installation Instructions first. Read all of them. Twice.

    Then type: make, and congratulations, you've started to build. -

    Prev Up Next
    Configure Home Chapter 3. Using
    +

    Prev Up Next
    Configure Home Chapter 3. Using
    diff --git a/libstdc++-v3/doc/html/manual/memory.html b/libstdc++-v3/doc/html/manual/memory.html index 69de53d3b95..8a1129bc6af 100644 --- a/libstdc++-v3/doc/html/manual/memory.html +++ b/libstdc++-v3/doc/html/manual/memory.html @@ -1,6 +1,6 @@ -Memory
    Memory
    Prev Chapter 6.  +Memory
    Memory
    Prev Chapter 6.  Utilities  Next

    @@ -93,7 +93,7 @@ or loading and unloading shared objects in memory. As such, using caching allocators on systems that do not support abi::__cxa_atexit is not recommended. -

    +

    The only allocator interface that is supported is the standard C++ interface. As such, all STL containers have been adjusted, and all external allocators have @@ -106,7 +106,7 @@

    The base class that allocator is derived from may not be user-configurable. -

    +

    It's difficult to pick an allocation strategy that will provide maximum utility, without excessively penalizing some behavior. In fact, it's difficult just deciding which typical actions to measure @@ -143,7 +143,7 @@ The current default choice for allocator is __gnu_cxx::new_allocator. -

    +

    In use, allocator may allocate and deallocate using implementation-specified strategies and heuristics. Because of this, every call to an allocator object's @@ -301,36 +301,40 @@

    A high-performance fixed-size allocator with exponentially-increasing allocations. It has its own - documentation, found here. + documentation, found here.

  • bitmap_allocator

    A high-performance allocator that uses a bit-map to keep track of the used and unused memory locations. It has its own - documentation, found here. -

    • + documentation, found here. +

    ISO/IEC 14882:1998 Programming languages - C++ . isoc++_1998 - 20.4 Memory.

    - . + 20.4 Memory.

    + The Standard Librarian: What Are Allocators Good For? - . Matt Austern. + + . Matt Austern. C/C++ Users Journal - .

    - . + .

    + The Hoard Memory Allocator - . Emery Berger.

    - . + + . Emery Berger.

    + Reconsidering Custom Memory Allocation - . Emery Berger. Ben Zorn. Kathryn McKinley. Copyright © 2002 OOPSLA.

    - . + + . Emery Berger. Ben Zorn. Kathryn McKinley. Copyright © 2002 OOPSLA.

    + Allocator Types - . Klaus Kreft. Angelika Langer. + + . Klaus Kreft. Angelika Langer. C/C++ Users Journal - .

    The C++ Programming Language. Bjarne Stroustrup. Copyright © 2000 . 19.4 Allocators. + .

    The C++ Programming Language. Bjarne Stroustrup. Copyright © 2000 . 19.4 Allocators. Addison Wesley - .

    Yalloc: A Recycling C++ Allocator. Felix Yen.

    Explaining all of the fun and delicious things that can + .

    Yalloc: A Recycling C++ Allocator. Felix Yen.

    Explaining all of the fun and delicious things that can happen with misuse of the auto_ptr class template (called AP here) would take some time. Suffice it to say that the use of AP @@ -446,7 +450,7 @@ drops to zero. Derived classes override those functions to destroy resources in a context where the correct dynamic type is known. This is an application of the technique known as type erasure. -

    +

    A shared_ptr<T> contains a pointer of type T* and an object of type __shared_count. The shared_count contains a @@ -488,7 +492,7 @@ be forwarded to Tp's constructor. Unlike the other _Sp_counted_* classes, this one is parameterized on the type of object, not the type of pointer; this is purely a convenience that simplifies the implementation slightly. -

    +

    C++0x-only features are: rvalue-ref/move support, allocator support, aliasing constructor, make_shared & allocate_shared. Additionally, the constructors taking auto_ptr parameters are @@ -538,7 +542,7 @@ compiler, standard library, platform etc. For the version of shared_ptr in libstdc++ the compiler and library are fixed, which makes things much simpler: we have an atomic CAS or we don't, see Lock Policy below for details. -

    +

    There is a single _Sp_counted_base class, which is a template parameterized on the enum @@ -579,7 +583,7 @@ used when libstdc++ is built without --enable-threadsext/atomicity.h, which detect if the program is multi-threaded. If only one thread of execution exists in the program then less expensive non-atomic operations are used. -

    +

    The interface of tr1::shared_ptr was extended for C++0x with support for rvalue-references and the other features from N2351. The _Sp_counted_base base class is implemented in @@ -596,7 +600,7 @@ change unless bug fixes require it. If the code that is common to both C++0x and TR1 modes needs to diverge further then it might be necessary to duplicate _Sp_counted_base and only make changes to the C++0x version. -

    dynamic_pointer_cast, static_pointer_cast, +

    dynamic_pointer_cast, static_pointer_cast, const_pointer_cast

    As noted in N2351, these functions can be implemented non-intrusively using the alias constructor. However the aliasing constructor is only available @@ -629,13 +633,13 @@ is called. Users should not try to use this. As well as the extra constructors, this implementation also needs some members of _Sp_counted_deleter to be protected where they could otherwise be private. -

    +

    Examples of use can be found in the testsuite, under testsuite/tr1/2_general_utilities/shared_ptr, testsuite/20_util/shared_ptr and testsuite/20_util/weak_ptr. -

    +

    The shared_ptr atomic access clause in the C++0x working draft is not implemented in GCC.

    @@ -676,24 +680,28 @@ be private. code to work with, Peter Dimov in particular for his help and invaluable advice on thread safety. Phillip Jordan and Paolo Carlini for the lock policy implementation. -

    - . +

    + Improving shared_ptr for C++0x, Revision 2 - . + + . N2351 - .

    - . + .

    + C++ Standard Library Active Issues List - . + + . N2456 - .

    - . + .

    + Working Draft, Standard for Programming Language C++ - . + + . N2461 - .

    shared_ptr - . + .

    + Boost C++ Libraries documentation, shared_ptr - . + + . N2461 - .

    Prev Up Next
    Pairs Home Traits
    + .

    Prev Up Next
    Pairs Home Traits
    diff --git a/libstdc++-v3/doc/html/manual/mt_allocator.html b/libstdc++-v3/doc/html/manual/mt_allocator.html new file mode 100644 index 00000000000..8b3ad4df090 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/mt_allocator.html @@ -0,0 +1,23 @@ + + +Chapter 20. The mt_allocator
    Chapter 20. The mt_allocator
    Prev Part III.  + Extensions + + Next

    Table of Contents

    Intro
    Design Issues
    Overview
    Implementation
    Tunable Parameters
    Initialization
    Deallocation Notes
    Single Thread Example
    Multiple Thread Example

    +

    + The mt allocator [hereinafter referred to simply as "the allocator"] + is a fixed size (power of two) allocator that was initially + developed specifically to suit the needs of multi threaded + applications [hereinafter referred to as an MT application]. Over + time the allocator has evolved and been improved in many ways, in + particular it now also does a good job in single threaded + applications [hereinafter referred to as a ST application]. (Note: + In this document, when referring to single threaded applications + this also includes applications that are compiled with gcc without + thread support enabled. This is accomplished using ifdef's on + __GTHREADS). This allocator is tunable, very flexible, and capable + of high-performance. +

    + The aim of this document is to describe - from an application point of + view - the "inner workings" of the allocator. +

    Prev Up Next
    Diagnostics Home Design Issues
    diff --git a/libstdc++-v3/doc/html/manual/numerics.html b/libstdc++-v3/doc/html/manual/numerics.html index d5ccecef9c3..4fe23e34bb0 100644 --- a/libstdc++-v3/doc/html/manual/numerics.html +++ b/libstdc++-v3/doc/html/manual/numerics.html @@ -1,13 +1,13 @@ -Chapter 12.  Numerics
    Chapter 12.  +Chapter 12.  Numerics
    Chapter 12.  Numerics
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Complex
    complex Processing
    Generalized Operations
    Interacting with C
    Numerics vs. Arrays
    C99

    Using complex<> becomes even more comple- er, sorry, @@ -27,4 +27,4 @@

    Prev Up Next
    Chapter 11.  Algorithms - Home Generalized Operations
    +     		Home Generalized Operations
    diff --git a/libstdc++-v3/doc/html/manual/numerics_and_c.html b/libstdc++-v3/doc/html/manual/numerics_and_c.html index 3a2fb499e50..b6ee4904595 100644 --- a/libstdc++-v3/doc/html/manual/numerics_and_c.html +++ b/libstdc++-v3/doc/html/manual/numerics_and_c.html @@ -1,6 +1,6 @@ -Interacting with C
    Interacting with C
    Prev Chapter 12.  +Interacting with C
    Interacting with C
    Prev Chapter 12.  Numerics  Next

    One of the major reasons why FORTRAN can chew through numbers so well @@ -31,7 +31,7 @@ are supported, as is the lldiv_t typedef. Also supported are the wide character functions using 'long long', like wcstoll. -

    Prev Up Next
    Generalized Operations Home Chapter 13.  +

    Prev Up Next
    Generalized Operations Home Chapter 13.  Input and Output
    diff --git a/libstdc++-v3/doc/html/manual/pairs.html b/libstdc++-v3/doc/html/manual/pairs.html index 8c4dbb7633b..472337b36bf 100644 --- a/libstdc++-v3/doc/html/manual/pairs.html +++ b/libstdc++-v3/doc/html/manual/pairs.html @@ -1,6 +1,6 @@ -Pairs
    Pairs
    Prev Chapter 6.  +Pairs
    Pairs
    Prev Chapter 6.  Utilities  Next

    The pair<T1,T2> is a simple and handy way to @@ -42,4 +42,4 @@

    Prev Up Next
    Chapter 6.  Utilities - Home Memory
    +     		Home Memory
    diff --git a/libstdc++-v3/doc/html/manual/parallel_mode.html b/libstdc++-v3/doc/html/manual/parallel_mode.html index 435f37443c5..b85e408591e 100644 --- a/libstdc++-v3/doc/html/manual/parallel_mode.html +++ b/libstdc++-v3/doc/html/manual/parallel_mode.html @@ -1,9 +1,9 @@ -Chapter 18. Parallel Mode
    Chapter 18. Parallel Mode
    Prev Part III.  +Chapter 18. Parallel Mode
    Chapter 18. Parallel Mode
    Prev Part III.  Extensions - Next

    Table of Contents

    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Implementation Namespaces
    Testing
    Bibliography

    The libstdc++ parallel mode is an experimental parallel +

    		 Next

    Table of Contents

    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Setting up the OpenMP Environment
    Compile Time Switches
    Run Time Settings and Defaults
    Implementation Namespaces
    Testing
    Bibliography

    The libstdc++ parallel mode is an experimental parallel implementation of many algorithms the C++ Standard Library.

    Several of the standard algorithms, for instance @@ -13,12 +13,12 @@ explicit source declaration or by compiling existing sources with a specific compiler flag.

    The following library components in the include numeric are included in the parallel mode:

    The following library components in the include -algorithm are included in the parallel mode:

    +algorithm are included in the parallel mode:

    • std::adjacent_find

    • std::count

    • std::count_if

    • std::equal

    • std::find

    • std::find_if

    • std::find_first_of

    • std::for_each

    • std::generate

    • std::generate_n

    • std::lexicographical_compare

    • std::mismatch

    • std::search

    • std::search_n

    • std::transform

    • std::replace

    • std::replace_if

    • std::max_element

    • std::merge

    • std::min_element

    • std::nth_element

    • std::partial_sort

    • std::partition

    • std::random_shuffle

    • std::set_union

    • std::set_intersection

    • std::set_symmetric_difference

    • std::set_difference

    • std::sort

    • std::stable_sort

    • std::unique_copy

    Parallelization of Bulk Operations for STL Dictionaries . Johannes Singler. Leonor Frias. Copyright © 2007 . Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS) - .

    + .

    The Multi-Core Standard Template Library . Johannes Singler. Peter Sanders. Felix Putze. Copyright © 2007 . Euro-Par 2007: Parallel Processing. (LNCS 4641) - .

    Prev Up Next
    Design Home Semantics
    + .

    Prev Up Next
    Design Home Semantics
    diff --git a/libstdc++-v3/doc/html/manual/policy_based_data_structures_test.html b/libstdc++-v3/doc/html/manual/policy_based_data_structures_test.html new file mode 100644 index 00000000000..ee89d191709 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/policy_based_data_structures_test.html @@ -0,0 +1,3813 @@ + + +Testing
    Testing
    Prev Chapter 22. Policy-Based Data Structures Next

    The library contains a single comprehensive regression test. + For a given container type in this library, the test creates + an object of the container type and an object of the + corresponding standard type (e.g., std::set). It + then performs a random sequence of methods with random + arguments (e.g., inserts, erases, and so forth) on both + objects. At each operation, the test checks the return value of + the method, and optionally both compares this library's + object with the standard's object as well as performing other + consistency checks on this library's object (e.g., + order preservation, when applicable, or node invariants, when + applicable).

    Additionally, the test integrally checks exception safety + and resource leaks. This is done as follows. A special + allocator type, written for the purpose of the test, both + randomly throws an exceptions when allocations are performed, + and tracks allocations and de-allocations. The exceptions thrown + at allocations simulate memory-allocation failures; the + tracking mechanism checks for memory-related bugs (e.g., + resource leaks and multiple de-allocations). Both + this library's containers and the containers' value-types are + configured to use this allocator.

    For granularity, the test is split into the + several sources, each checking only some containers.

    For more details, consult the files in + testsuite/ext/pb_ds/regression.

    + This test inserts a number of values with keys from an + arbitrary text ([biblio.wickland96thirty]) into a container, + then performs a series of finds using + find . It measures the average + time for find as a function of + the number of values inserted.

    + It uses the test file: + + performance/ext/pb_ds/text_find_timing_test.cc + +

    + And uses the data file: + + filethirty_years_among_the_dead_preproc.txt + +

    The test checks the effect of different range-hashing + functions, trigger policies, and cache-hashing policies. +

    The graphic below show the results for the native + and collision-chaining hash types the the function + applied being a text find timing test using + find. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + cc_hash_mod_prime_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mask_exp_1div2_sth_map +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +
    + cc_hash_mask_exp_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mask_exp_1div2_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    In this setting, the range-hashing scheme affects performance + more than other policies. As the results show, containers using + mod-based range-hashing (including the native hash-based container, + which is currently hard-wired to this scheme) have lower performance + than those using mask-based range-hashing. A modulo-based + range-hashing scheme's main benefit is that it takes into account + all hash-value bits. Standard string hash-functions are designed to + create hash values that are nearly-uniform as is ([biblio.knuth98sorting]).

    Trigger policies, i.e. the load-checks constants, affect + performance to a lesser extent.

    Perhaps surprisingly, storing the hash value alongside each + entry affects performance only marginally, at least in this + library's implementation. (Unfortunately, it was not possible to run + the tests with std::tr1::unordered_map 's + cache_hash_code = true , as it appeared to + malfuntion.)

    This test inserts a number of values with uniform + integer keys into a container, then performs a series of finds + using find. It measures the average time + for find as a function of the number of values + inserted.

    + It uses the test file: + + performance/ext/pb_ds/random_int_find_timing.cc + +

    The test checks the effect of different underlying + hash-tables, + range-hashing functions, and trigger policies.

    + There are two sets of results for this type, one for + collision-chaining hashes, and one for general-probe hashes. +

    The first graphic below shows the results for the native and + collision-chaining hash types. The function applied being a random + integer timing test using find. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + cc_hash_mod_prime_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mod_prime_1div2_nsth_map +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +
    + cc_hash_mask_exp_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mask_exp_1div2_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    +

    +

    And the second graphic shows the results for the native and + general-probe hash types. The function applied being a random + integer timing test using find. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + gp_hash_mod_quadp_prime_1div2_nsth_map +
    + gp_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Probe_Fn + + quadratic_probe_fn +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +
    + gp_hash_mask_linp_exp_1div2_nsth_map +
    + + gp_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Probe_Fn + + linear_probe_fn +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    In this setting, the choice of underlying hash-table affects + performance most, then the range-hashing scheme and, only finally, + other policies.

    When comparing probing and chaining containers, it is + apparent that the probing containers are less efficient than the + collision-chaining containers ( + std::tr1::unordered_map uses + collision-chaining) in this case.

    Hash-Based Integer Subscript Insert Timing Test shows + a different case, where the situation is reversed; +

    Within each type of hash-table, the range-hashing scheme + affects performance more than other policies; Hash-Based Text + find Find Timing Test also shows this. In the + above graphics should be noted that + std::tr1::unordered_map are hard-wired + currently to mod-based schemes. +

    This test inserts a number of values with uniform + integer keys into a container, then performs a series of finds + using operator[]. It measures the average time + for operator[] as a function of the number of + values inserted.

    + It uses the test file: + + performance/ext/pb_ds/random_int_subscript_find_timing.cc + +

    The test checks the effect of different underlying + hash-tables, range-hashing functions, and trigger policies.

    + There are two sets of results for this type, one for + collision-chaining hashes, and one for general-probe hashes. +

    The first graphic below shows the results for the native + and collision-chaining hash types, using as the function + applied an integer subscript timing test with + find. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + cc_hash_mod_prime_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mod_prime_1div2_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +
    + cc_hash_mask_exp_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mask_exp_1div2_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    +

    +

    And the second graphic shows the results for the native and + general-probe hash types. The function applied being a random + integer timing test using find. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + gp_hash_mod_quadp_prime_1div2_nsth_map +
    + gp_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Probe_Fn + + quadratic_probe_fn +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +
    + gp_hash_mask_linp_exp_1div2_nsth_map +
    + + gp_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Probe_Fn + + linear_probe_fn +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    This test shows similar results to Hash-Based + Integer find Find Timing test.

    This test inserts a number of values with uniform i.i.d. + integer keys into a container, using + operator[]. It measures the average time for + operator[] as a function of the number of + values inserted.

    + It uses the test file: + + performance/ext/pb_ds/random_int_subscript_insert_timing.cc + +

    The test checks the effect of different underlying + hash-tables.

    + There are two sets of results for this type, one for + collision-chaining hashes, and one for general-probe hashes. +

    The first graphic below shows the results for the native + and collision-chaining hash types, using as the function + applied an integer subscript timing test with + insert. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + cc_hash_mod_prime_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mod_prime_1div2_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +
    + cc_hash_mask_exp_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mask_exp_1div2_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    +

    +

    And the second graphic shows the results for the native and + general-probe hash types. The function applied being a random + integer timing test using find. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + gp_hash_mod_quadp_prime_1div2_nsth_map +
    + gp_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Probe_Fn + + quadratic_probe_fn +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +
    + gp_hash_mask_linp_exp_1div2_nsth_map +
    + + gp_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Probe_Fn + + linear_probe_fn +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    In this setting, as in Hash-Based Text + find Find Timing test and Hash-Based + Integer find Find Timing test , the choice + of underlying hash-table underlying hash-table affects performance + most, then the range-hashing scheme, and + finally any other policies.

    There are some differences, however:

    1. In this setting, probing tables function sometimes more + efficiently than collision-chaining tables. + This is explained shortly.

    2. The performance graphs have a "saw-tooth" shape. The + average insert time rises and falls. As values are inserted + into the container, the load factor grows larger. Eventually, + a resize occurs. The reallocations and rehashing are + relatively expensive. After this, the load factor is smaller + than before.

    Collision-chaining containers use indirection for greater + flexibility; probing containers store values contiguously, in + an array (see Figure Motivation::Different + underlying data structures A and B, respectively). It + follows that for simple data types, probing containers access + their allocator less frequently than collision-chaining + containers, (although they still have less efficient probing + sequences). This explains why some probing containers fare + better than collision-chaining containers in this case.

    + Within each type of hash-table, the range-hashing scheme affects + performance more than other policies. This is similar to the + situation in Hash-Based Text + find Find Timing Test and Hash-Based + Integer find Find Timing Test. + Unsurprisingly, however, containers with lower αmax perform worse in this case, + since more re-hashes are performed.

    This test inserts a number of values with a markedly + non-uniform integer keys into a container, then performs + a series of finds using find. It measures the average + time for find as a function of the number of values in + the containers. The keys are generated as follows. First, a + uniform integer is created. Then it is then shifted left 8 bits.

    + It uses the test file: + + performance/ext/pb_ds/hash_zlob_random_int_find_timing.cc + +

    The test checks the effect of different range-hashing + functions and trigger policies.

    The graphic below show the results for the native, collision-chaining, and general-probing hash types. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + cc_hash_mod_prime_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mask_exp_1div1_nsth_map +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + gp_hash_mod_quadp_prime_1div2_nsth_map +
    + gp_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Probe_Fn + + quadratic_probe_fn +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    In this setting, the distribution of keys is so skewed that + the underlying hash-table type affects performance marginally. + (This is in contrast with Hash-Based Text + find Find Timing Test, Hash-Based + Integer find Find Timing Test, Hash-Based + Integer Subscript Find Timing Test and Hash-Based + Integer Subscript Insert Timing Test.)

    The range-hashing scheme affects performance dramatically. A + mask-based range-hashing scheme effectively maps all values + into the same bucket. Access degenerates into a search within + an unordered linked-list. In the graphic above, it should be noted that + std::tr1::unordered_map is hard-wired currently to mod-based and mask-based schemes, + respectively.

    When observing the settings of this test, it is apparent + that the keys' distribution is far from natural. One might ask + if the test is not contrived to show that, in some cases, + mod-based range hashing does better than mask-based range + hashing. This is, in fact just the case. A + more natural case in which mod-based range hashing is better was not encountered. + Thus the inescapable conclusion: real-life key distributions are handled better + with an appropriate hash function and a mask-based + range-hashing function. (pb_ds/example/hash_shift_mask.cc + shows an example of handling this a-priori known skewed + distribution with a mask-based range-hashing function). If hash + performance is bad, a χ2 test can be used + to check how to transform it into a more uniform + distribution.

    For this reason, this library's default range-hashing + function is mask-based.

    This test inserts a number of uniform integer keys + into a container, then erases all keys except one. It measures + the final size of the container.

    + It uses the test file: + + performance/ext/pb_ds/hash_random_int_erase_mem_usage.cc + +

    The test checks how containers adjust internally as their + logical size decreases.

    The graphic below show the results for the native, collision-chaining, and general-probing hash types. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetails
    + n_hash_map_ncah +
    + std::tr1::unordered_map + + cache_hash_code + + false +  
    + cc_hash_mod_prime_1div1_nsth_map +
    + cc_hash_table + + Comb_Hash_Fn + + direct_mod_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_prime_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/1 +
    + cc_hash_mask_exp_1div2_nsth_map +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +
    + gp_hash_mask_linp_exp_1div2_nsth_set +
    + gp_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Probe_Fn + + linear_probe_fn +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    The standard's hash-based containers act very differently than trees in + this respect. When erasing numerous keys from an standard + associative-container, the resulting memory user varies greatly + depending on whether the container is tree-based or hash-based. + This is a fundamental consequence of the standard's interface for + associative containers, and it is not due to a specific + implementation.

    This test inserts a number of values with keys from an arbitrary + text ([ wickland96thirty ]) into a container + using insert . It measures the average time + for insert as a function of the number of + values inserted.

    The test checks the effect of different underlying + data structures.

    + It uses the test file: + + performance/ext/pb_ds/tree_text_insert_timing.cc + +

    The three graphics below show the results for the native + tree and this library's node-based trees, the native tree and + this library's vector-based trees, and the native tree + and this library's PATRICIA-trie, respectively. +

    The graphic immediately below shows the results for the + native tree type and several node-based tree types. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_map +
    + std::map +  
    + splay_tree_map +
    + tree + + Tag + + splay_tree_tag +
    + Node_update + + null_node_update +
    + rb_tree_map +
    + tree + + Tag + + rb_tree_tag +
    + Node_update + + null_node_update +

    The graphic below shows the results for the + native tree type and a vector-based tree type. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_map +
    + std::map +  
    + ov_tree_map +
    + tree + + Tag + + ov_tree_tag +
    + Node_update + + null_node_update +

    The graphic below shows the results for the + native tree type and a PATRICIA trie type. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_map +
    + std::map +  
    + pat_trie_map +
    + tree + + Tag + + pat_trie_tag +
    + Node_update + + null_node_update +

    Observing the first graphic implies that for this setting, a splay tree + (tree with Tag + = splay_tree_tag) does not do + well. See also the Branch-Based + Text find Find Timing Test. The two + red-black trees perform better.

    Observing the second graphic, an ordered-vector tree + (tree with Tag + = ov_tree_tag) performs + abysmally. Inserting into this type of tree has linear complexity + [ austern00noset].

    Observing the third and last graphic, A PATRICIA trie + (trie with Tag + = pat_trie_tag) has abysmal + performance, as well. This is not that surprising, since a + large-fan-out PATRICIA trie works like a hash table with + collisions resolved by a sub-trie. Each time a collision is + encountered, a new "hash-table" is built A large fan-out PATRICIA + trie, however, doe does well in look-ups (see Branch-Based + Text find Find Timing Test). It may be + beneficial in semi-static settings.

    This test inserts a number of values with keys from an + arbitrary text ([wickland96thirty]) into + a container, then performs a series of finds using + find. It measures the average time + for find as a function of the number of + values inserted.

    + It uses the test file: + + performance/ext/pb_ds/text_find_timing.cc + +

    The test checks the effect of different underlying + data structures.

    The graphic immediately below shows the results for the + native tree type and several other tree types. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_map +
    + std::map +  
    + splay_tree_map +
    + tree + + Tag + + splay_tree_tag +
    + Node_Update + + null_node_update +
    + rb_tree_map +
    + tree + + Tag + + rb_tree_tag +
    + Node_Update + + null_node_update +
    + ov_tree_map +
    + tree + + Tag + + ov_tree_tag +
    + Node_Update + + null_node_update +
    + pat_trie_map +
    + tree + + Tag + + pat_trie_tag +
    + Node_Update + + null_node_update +

    For this setting, a splay tree (tree + with Tag + = splay_tree_tag) does not do + well. This is possibly due to two reasons:

    1. A splay tree is not guaranteed to be balanced [motwani95random]. If a + splay tree contains n nodes, its average root-leaf + path can be m >> log(n).

    2. Assume a specific root-leaf search path has length + m, and the search-target node has distance m' + from the root. A red-black tree will require m + 1 + comparisons to find the required node; a splay tree will + require 2 m' comparisons. A splay tree, consequently, + can perform many more comparisons than a red-black tree.

    An ordered-vector tree (tree + with Tag = ov_tree_tag), a red-black + tree (tree + with Tag = rb_tree_tag), and the + native red-black tree all share approximately the same + performance.

    An ordered-vector tree is slightly slower than red-black + trees, since it requires, in order to find a key, more math + operations than they do. Conversely, an ordered-vector tree + requires far lower space than the others. ([austern00noset], however, + seems to have an implementation that is also faster than a + red-black tree).

    A PATRICIA trie (trie + with Tag = pat_trie_tag) has good + look-up performance, due to its large fan-out in this case. In + this setting, a PATRICIA trie has look-up performance comparable + to a hash table (see Hash-Based Text + find Timing Test), but it is order + preserving. This is not that surprising, since a large-fan-out + PATRICIA trie works like a hash table with collisions resolved + by a sub-trie. A large-fan-out PATRICIA trie does not do well on + modifications (see Tree-Based and Trie-Based + Text Insert Timing Test). Therefore, it is possibly beneficial in + semi-static settings.

    This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container, then performs a series of finds using + find. It is different than Tree-Based and + Trie-Based Text find Find Timing Test in the + sequence of finds it performs: this test performs multiple + finds on the same key before moving on to the next + key. It measures the average time for find as a + function of the number of values inserted.

    + It uses the test file: + + performance/ext/pb_ds/tree_text_lor_find_timing.cc + +

    The test checks the effect of different underlying + data structures in a locality-of-reference setting.

    The graphic immediately below shows the results for the + native tree type and several other tree types. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_map +
    + std::map +  
    + splay_tree_map +
    + tree + + Tag + + splay_tree_tag +
    + Node_Update + + null_node_update +
    + rb_tree_map +
    + tree + + Tag + + rb_tree_tag +
    + Node_Update + + null_node_update +
    + ov_tree_map +
    + tree + + Tag + + ov_tree_tag +
    + Node_Update + + null_node_update +
    + pat_trie_map +
    + tree + + Tag + + pat_trie_tag +
    + Node_Update + + null_node_update +

    For this setting, an ordered-vector tree + (tree with Tag + = ov_tree_tag), a red-black tree + (tree with Tag + = rb_tree_tag), and the native red-black + tree all share approximately the same performance.

    A splay tree (tree + with Tag = splay_tree_tag) does + much better, since each (successful) find "bubbles" the + corresponding node to the root of the tree.

    This test a container, inserts into a number of values, splits + the container at the median, and joins the two containers. (If the + containers are one of this library's trees, + it splits and joins with the split and + join method; otherwise, it uses the erase and + insert methods.) It measures the time for splitting + and joining the containers as a function of the number of + values inserted.

    + It uses the test file: + + performance/ext/pb_ds/tree_split_join_timing.cc + +

    The test checks the performance difference of join + as opposed to a sequence of insert operations; by + implication, this test checks the most efficient way to erase a + sub-sequence from a tree-like-based container, since this can + always be performed by a small sequence of splits and joins. +

    The graphic immediately below shows the results for the + native tree type and several other tree types. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_set +
    + std::set +  
    + splay_tree_set +
    + tree + + Tag + + splay_tree_tag +
    + Node_Update + + null_node_update +
    + rb_tree_set +
    + tree + + Tag + + rb_tree_tag +
    + Node_Update + + null_node_update +
    + ov_tree_set +
    + tree + + Tag + + ov_tree_tag +
    + Node_Update + + null_node_update +
    + pat_trie_map +
    + tree + + Tag + + pat_trie_tag +
    + Node_Update + + null_node_update +

    In this test, the native red-black trees must be split and + joined externally, through a sequence of erase and + insert operations. This is clearly + super-linear, and it is not that surprising that the cost is + high.

    This library's tree-based containers use in this test the + split and join methods, + which have lower complexity: the join method + of a splay tree (tree + with Tag + = splay_tree_tag) is quadratic in the + length of the longest root-leaf path, and linear in the total + number of elements; the join method of a + red-black tree (tree + with Tag + = rb_tree_tag) or an ordered-vector tree + (tree with Tag + = ov_tree_tag) is linear in the number of + elements.

    Asides from orders of growth, this library's trees access their + allocator very little in these operations, and some of them do not + access it at all. This leads to lower constants in their + complexity, and, for some containers, to exception-free splits and + joins (which can be determined + via container_traits).

    It is important to note that split and + join are not esoteric methods - they are the most + efficient means of erasing a contiguous range of values from a + tree based container.

    This test creates a container, inserts random integers into the + the container, and then checks the order-statistics of the + container's values. (If the container is one of this + library's trees, it does this with + the order_of_key method of + tree_order_statistics_node_update + ; otherwise, it uses the find method and + std::distance.) It measures the average + time for such queries as a function of the number of values + inserted.

    + It uses the test file: + + performance/ext/pb_ds/tree_order_statistics_timing.cc + +

    The test checks the performance difference of policies based + on node-invariant as opposed to a external functions.

    The graphic immediately below shows the results for the + native tree type and several other tree types. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_set +
    + std::set +  
    + splay_tree_ost_set +
    + tree + + Tag + + splay_tree_tag +
    + Node_Update + + tree_order_statistics_node_update +
    + rb_tree_ost_set +
    + tree + + Tag + + rb_tree_tag +
    + Node_Update + + tree_order_statistics_node_update +

    In this test, the native red-black tree can support + order-statistics queries only externally, by performing a + find (alternatively, lower_bound or + upper_bound ) and then using std::distance . + This is clearly linear, and it is not that surprising that the + cost is high.

    This library's tree-based containers use in this test the + order_of_key method of tree_order_statistics_node_update. + This method has only linear complexity in the length of the + root-node path. Unfortunately, the average path of a splay tree + (tree + with Tag = splay_tree_tag ) can + be higher than logarithmic; the longest path of a red-black + tree (tree + with Tag = rb_tree_tag ) is + logarithmic in the number of elements. Consequently, the splay + tree has worse performance than the red-black tree.

    This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform i.i.d.integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key (see Motivation::Associative + Containers::Alternative to Multiple Equivalent Keys). There + are 400 distinct primary keys, and the ratio of secondary keys + to primary keys ranges from 1 to 5.

    The test measures the average find-time as a function of the + number of values inserted. For this library's containers, it + finds the secondary key from a container obtained from finding + a primary key. For the native multimaps, it searches a range + obtained using std::equal_range on a primary key.

    + It uses the test file: + + performance/ext/pb_ds/multimap_text_find_timing_small.cc + +

    The test checks the find-time scalability of different + "multimap" designs.

    The graphic below show the results for "multimaps" which + use a tree-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_mmap +
    + std::multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    The graphic below show the results for "multimaps" which + use a hash-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_hash_mmap +
    + std::tr1::unordered_multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    See Observations::Mapping-Semantics + Considerations.

    This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key. There + are 400 distinct primary keys, and the ratio of secondary keys + to primary keys ranges from 1 to 5.

    The test measures the average find-time as a function of the + number of values inserted. For this library's containers, it + finds the secondary key from a container obtained from finding + a primary key. For the native multimaps, it searches a range + obtained using std::equal_range on a primary key.

    + It uses the test file: + + performance/ext/pb_ds/multimap_text_find_timing_large.cc + +

    The test checks the find-time scalability of different + "multimap" designs.

    The graphic below show the results for "multimaps" which + use a tree-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_mmap +
    + std::multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    The graphic below show the results for "multimaps" which + use a hash-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_hash_mmap +
    + std::tr1::unordered_multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    See Observations::Mapping-Semantics + Considerations.

    This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key. There + are 400 distinct primary keys, and the ratio of secondary keys + to primary keys ranges from 1 to 5.

    The test measures the average insert-time as a function of + the number of values inserted. For this library's containers, + it inserts a primary key into the primary associative + container, then a secondary key into the secondary associative + container. For the native multimaps, it obtains a range using + std::equal_range, and inserts a value only if it was + not contained already.

    + It uses the test file: + + performance/ext/pb_ds/multimap_text_insert_timing_small.cc + +

    The test checks the insert-time scalability of different + "multimap" designs.

    The graphic below show the results for "multimaps" which + use a tree-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_mmap +
    + std::multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    The graphic below show the results for "multimaps" which + use a hash-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_hash_mmap +
    + std::tr1::unordered_multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    See Observations::Mapping-Semantics + Considerations.

    This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key. There + are 400 distinct primary keys, and the ratio of secondary keys + to primary keys ranges from 1 to 5.

    The test measures the average insert-time as a function of + the number of values inserted. For this library's containers, + it inserts a primary key into the primary associative + container, then a secondary key into the secondary associative + container. For the native multimaps, it obtains a range using + std::equal_range, and inserts a value only if it was + not contained already.

    + It uses the test file: + + performance/ext/pb_ds/multimap_text_insert_timing_large.cc + +

    The test checks the insert-time scalability of different + "multimap" designs.

    The graphic below show the results for "multimaps" which + use a tree-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_mmap +
    + std::multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    The graphic below show the results for "multimaps" which + use a hash-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_hash_mmap +
    + std::tr1::unordered_multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    See Observations::Mapping-Semantics + Considerations.

    This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key. There + are 100 distinct primary keys, and the ratio of secondary keys + to primary keys ranges to about 20.

    The test measures the memory use as a function of the number + of values inserted.

    + It uses the test file: + + performance/ext/pb_ds/multimap_text_insert_mem_usage_small.cc + +

    The test checks the memory scalability of different + "multimap" designs.

    The graphic below show the results for "multimaps" which + use a tree-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_mmap +
    + std::multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    The graphic below show the results for "multimaps" which + use a hash-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_hash_mmap +
    + std::tr1::unordered_multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    See Observations::Mapping-Semantics + Considerations.

    This test inserts a number of pairs into a container. The + first item of each pair is a string from an arbitrary text + [wickland96thirty], and + the second is a uniform integer. The container is a + "multimap" - it considers the first member of each pair as a + primary key, and the second member of each pair as a secondary + key. There + are 100 distinct primary keys, and the ratio of secondary keys + to primary keys ranges to about 20.

    The test measures the memory use as a function of the number + of values inserted.

    + It uses the test file: + + performance/ext/pb_ds/multimap_text_insert_mem_usage_large.cc + +

    The test checks the memory scalability of different + "multimap" designs.

    The graphic below show the results for "multimaps" which + use a tree-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_mmap +
    + std::multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + tree + + Tag + + rb_tree_tag +  
    + Node_Update + + null_node_update +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    The graphic below show the results for "multimaps" which + use a hash-based container for primary keys. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetailsParameterDetailsParameterDetails
    + n_hash_mmap +
    + std::tr1::unordered_multimap +  
    + rb_tree_mmap_lu_mtf_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + list_update + + Update_Policy + + lu_move_to_front_policy +  
    + rb_tree_mmap_cc_hash_mask_exp_1div2_nsth_set +
    + + cc_hash_table + + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +  
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +  
    + Mapped + + cc_hash_table + + Comb_Hash_Fn + + direct_mask_range_hashing +  
    + Resize_Policy + + hash_standard_resize_policy + + Size_Policy + + hash_exponential_size_policy +
    + Trigger_Policy + + hash_load_check_resize_trigger with + αmin = 1/8 and αmax = 1/2 +

    See Observations::Mapping-Semantics + Considerations.

    This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container using push. It measures the average time + for push as a function of the number of values + pushed.

    + It uses the test file: + + performance/ext/pb_ds/priority_queue_text_push_timing.cc + +

    The test checks the effect of different underlying data + structures. +

    The two graphics below show the results for the native + priority_queues and this library's priority_queues. +

    The graphic immediately below shows the results for the + native priority_queue type instantiated with different underlying + container types versus several different versions of library's + priority_queues. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +
    + binomial_heap +
    + priority_queue + + Tag + + binomial_heap_tag +
    + rc_binomial_heap +
    + priority_queue + + Tag + + rc_binomial_heap_tag +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    The graphic below shows the results for the binary-heap + based native priority queues and this library's pairing-heap + priority_queue data structures. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    Pairing heaps (priority_queue with + Tag = pairing_heap_tag) + are the most suited for sequences of push and + pop operations of non-primitive types (e.g. + std::strings). (See Priority Queue + Text push and pop Timing Test.) They are + less constrained than binomial heaps, e.g., and since + they are node-based, they outperform binary heaps. (See + Priority + Queue Random Integer push Timing Test for the case + of primitive types.)

    The standard's priority queues do not seem to perform well in + this case: the std::vector implementation needs to + perform a logarithmic sequence of string operations for each + operation, and the deque implementation is possibly hampered by + its need to manipulate a relatively-complex type (deques + support a O(1) push_front, even though it is + not used by std::priority_queue.)

    This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container using push , then removes them using + pop . It measures the average time for push + as a function of the number of values.

    + It uses the test file: + + performance/ext/pb_ds/priority_queue_text_push_pop_timing.cc + +

    The test checks the effect of different underlying data + structures. +

    The two graphics below show the results for the native + priority_queues and this library's priority_queues. +

    The graphic immediately below shows the results for the + native priority_queue type instantiated with different underlying + container types versus several different versions of library's + priority_queues. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +
    + binomial_heap +
    + priority_queue + + Tag + + binomial_heap_tag +
    + rc_binomial_heap +
    + priority_queue + + Tag + + rc_binomial_heap_tag +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    The graphic below shows the results for the native priority + queues and this library's pairing-heap priority_queue data + structures. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue adapting std::vector + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    These results are very similar to Priority Queue Text + push Timing Test. As stated there, pairing heaps + (priority_queue with + Tag + = pairing_heap_tag) are most suited + for push and pop + sequences of non-primitive types such as strings. Observing these + two tests, one can note that a pairing heap outperforms the others + in terms of push operations, but equals + binary heaps (priority_queue with + Tag + = binary_heap_tag) if the number + of push and pop + operations is equal. As the number of pop + operations is at most equal to the number + of push operations, pairing heaps are better + in this case. See Priority Queue Random + Integer push and pop + Timing Test for a case which is different.

    This test inserts a number of values with integer keys + into a container using push. It + measures the average time for push as a + function of the number of values.

    + It uses the test file: + + performance/ext/pb_ds/priority_queue_random_int_push_timing.cc + +

    The test checks the effect of different underlying data + structures. +

    The two graphics below show the results for the native + priority_queues and this library's priority_queues. +

    The graphic immediately below shows the results for the + native priority_queue type instantiated with different underlying + container types versus several different versions of library's + priority_queues. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +
    + binomial_heap +
    + priority_queue + + Tag + + binomial_heap_tag +
    + rc_binomial_heap +
    + priority_queue + + Tag + + rc_binomial_heap_tag +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    The graphic below shows the results for the binary-heap + based native priority queues and this library's + priority_queue data structures. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue adapting std::vector + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +

    Binary heaps are the most suited for sequences of + push and pop operations of primitive types + (e.g. ints). They are less constrained + than any other type, and since it is very efficient to store + such types in arrays, they outperform even pairing heaps. (See + Priority + Queue Text push Timing Test for the case of + non-primitive types.)

    This test inserts a number of values with integer keys + into a container using push , then removes them + using pop . It measures the average time for + push and pop as a function + of the number of values.

    + It uses the test file: + + performance/ext/pb_ds/priority_queue_random_int_push_pop_timing.cc + +

    The test checks the effect of different underlying data + structures. +

    The graphic immediately below shows the results for the + native priority_queue type instantiated with different underlying + container types versus several different versions of library's + priority_queues. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +
    + binomial_heap +
    + priority_queue + + Tag + + binomial_heap_tag +
    + rc_binomial_heap +
    + priority_queue + + Tag + + rc_binomial_heap_tag +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    Binary heaps are the most suited for sequences of + push and pop operations of primitive types + (e.g. ints). This is explained in + Priority + Queue Random Int push Timing Test. (See Priority Queue + Text push Timing Test for the case of primitive + types.)

    At first glance it seems that the standard's vector-based + priority queue is approximately on par with this + library's corresponding priority queue. There are two + differences however:

    1. The standard's priority queue does not downsize the underlying + vector (or deque) as the priority queue becomes smaller + (see Priority Queue + Text pop Memory Use Test). It is therefore + gaining some speed at the expense of space.

    2. From Priority Queue Random + Integer push and pop + Timing Test, it seems that the standard's priority queue is + slower in terms of push operations. Since + the number of + pop operations is at most that of push + operations, the test here is the "best" for the standard's + priority queue.

    This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + a container, then pops them until only one is left in the + container. It measures the memory use as a function of the + number of values pushed to the container.

    + It uses the test file: + + performance/ext/pb_ds/priority_queue_text_pop_mem_usage.cc + +

    The test checks the effect of different underlying data + structures. +

    The graphic immediately below shows the results for the + native priority_queue type instantiated with different underlying + container types versus several different versions of library's + priority_queues. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +
    + binomial_heap +
    + priority_queue + + Tag + + binomial_heap_tag +
    + rc_binomial_heap +
    + priority_queue + + Tag + + rc_binomial_heap_tag +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    The priority queue implementations (excluding the standard's) use + memory proportionally to the number of values they hold: + node-based implementations (e.g., a pairing heap) do so + naturally; this library's binary heap de-allocates memory when + a certain lower threshold is exceeded.

    Note from Priority Queue Text push + and pop Timing Test and Priority Queue + Random Integer push + and pop Timing Test that this does not + impede performance compared to the standard's priority + queues.

    See Hash-Based Erase + Memory Use Test for a similar phenomenon regarding priority + queues.

    This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + two containers, then merges the containers. It uses + join for this library's priority queues; for + the standard's priority queues, it successively pops values from + one container and pushes them into the other. The test measures + the average time as a function of the number of values.

    + It uses the test file: + + performance/ext/pb_ds/priority_queue_text_join_timing.cc + +

    The test checks the effect of different underlying data + structures. +

    The graphic immediately below shows the results for the + native priority_queue type instantiated with different underlying + container types versus several different versions of library's + priority_queues. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +
    + binomial_heap +
    + priority_queue + + Tag + + binomial_heap_tag +
    + rc_binomial_heap +
    + priority_queue + + Tag + + rc_binomial_heap_tag +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    In this test the node-based heaps perform join in + either logarithmic or constant time. The binary heap requires + linear time, since the well-known heapify algorithm [clrs2001] is linear.

    It would be possible to apply the heapify algorithm to the + standard containers, if they would support iteration (which they + don't). Barring iterators, it is still somehow possible to perform + linear-time merge on a std::vector-based + standard priority queue, using top() + and size() (since they are enough to expose + the underlying array), but this is impossible for + a std::deque-based standard priority queue. + Without heapify, the cost is super-linear.

    This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + into a container then modifies each one "up" (i.e., it + makes it larger). It uses modify for this library's + priority queues; for the standard's priority queues, it pops values + from a container until it reaches the value that should be + modified, then pushes values back in. It measures the average + time for modify as a function of the number of + values.

    + It uses the test file: + + performance/ext/pb_ds/priority_queue_text_modify_up_timing.cc + +

    The test checks the effect of different underlying data + structures for graph algorithms settings. Note that making an + arbitrary value larger (in the sense of the priority queue's + comparison functor) corresponds to decrease-key in standard graph + algorithms [clrs2001]. +

    The two graphics below show the results for the native + priority_queues and this library's priority_queues. +

    The graphic immediately below shows the results for the + native priority_queue type instantiated with different underlying + container types versus several different versions of library's + priority_queues. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +
    + binomial_heap +
    + priority_queue + + Tag + + binomial_heap_tag +
    + rc_binomial_heap +
    + priority_queue + + Tag + + rc_binomial_heap_tag +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    The graphic below shows the results for the + native priority queues and this library's pairing and thin heap + priority_queue data structures. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    As noted above, increasing an arbitrary value (in the sense of + the priority queue's comparison functor) is very common in + graph-related algorithms. In this case, a thin heap + (priority_queue with + Tag = thin_heap_tag) + outperforms a pairing heap (priority_queue with + Tag = pairing_heap_tag). + Conversely, Priority Queue Text + push Timing Test, Priority Queue + Text push and pop Timing Test, Priority + Queue Random Integer push Timing Test, and + Priority + Queue Random Integer push and pop Timing + Test show that the situation is reversed for other + operations. It is not clear when to prefer one of these two + different types.

    In this test this library's binary heaps + effectively perform modify in linear time. As explained in + Priority Queue Design::Traits, given a valid point-type iterator, + a binary heap can perform + modify logarithmically. The problem is that binary + heaps invalidate their find iterators with each modifying + operation, and so the only way to obtain a valid point-type + iterator is to iterate using a range-type iterator until + finding the appropriate value, then use the range-type iterator + for the modify operation.

    The explanation for the standard's priority queues' performance + is similar to that in Priority Queue Text + join Timing Test.

    This test inserts a number of values with keys from an + arbitrary text ([ wickland96thirty ]) into + into a container then modifies each one "down" (i.e., it + makes it smaller). It uses modify for this library's + priority queues; for the standard's priority queues, it pops values + from a container until it reaches the value that should be + modified, then pushes values back in. It measures the average + time for modify as a function of the number of + values.

    + It uses the test file: + + performance/ext/pb_ds/priority_queue_text_modify_down_timing.cc + +

    The main purpose of this test is to contrast Priority Queue + Text modify Up Timing Test.

    The two graphics below show the results for the native + priority_queues and this library's priority_queues. +

    The graphic immediately below shows the results for the + native priority_queue type instantiated with different underlying + container types versus several different versions of library's + priority_queues. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + n_pq_vector +
    + std::priority_queue + + Sequence + + std::vector +
    + n_pq_deque +
    + std::priority_queue + + Sequence + + std::deque +
    + binary_heap +
    + priority_queue + + Tag + + binary_heap_tag +
    + binomial_heap +
    + priority_queue + + Tag + + binomial_heap_tag +
    + rc_binomial_heap +
    + priority_queue + + Tag + + rc_binomial_heap_tag +
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    The graphic below shows the results for the + native priority queues and this library's pairing and thin heap + priority_queue data structures. +

    + The abbreviated names in the legend of the graphic above are + instantiated with the types in the following table. +

    Name/Instantiating TypeParameterDetails
    + thin_heap +
    + priority_queue + + Tag + + thin_heap_tag +
    + pairing_heap +
    + priority_queue + + Tag + + pairing_heap_tag +

    Most points in these results are similar to Priority Queue + Text modify Up Timing Test.

    It is interesting to note, however, that as opposed to that + test, a thin heap (priority_queue with + Tag = thin_heap_tag) is + outperformed by a pairing heap (priority_queue with + Tag = pairing_heap_tag). + In this case, both heaps essentially perform an erase + operation followed by a push operation. As the other + tests show, a pairing heap is usually far more efficient than a + thin heap, so this is not surprising.

    Most algorithms that involve priority queues increase values + (in the sense of the priority queue's comparison functor), and + so Priority Queue + Text modify Up Timing Test - is more interesting + than this test.

    In general, hash-based containers have better timing performance + than containers based on different underlying-data structures. The + main reason to choose a tree-based or trie-based container is if a + byproduct of the tree-like structure is required: either + order-preservation, or the ability to utilize node invariants. If + memory-use is the major factor, an ordered-vector tree gives + optimal results (albeit with high modificiation costs), and a + list-based container gives reasonable results.

    Hash-based containers are typically either collision + chaining or probing. Collision-chaining + containers are more flexible internally, and so offer better + timing performance. Probing containers, if used for simple + value-types, manage memory more efficiently (they perform far + fewer allocation-related calls). In general, therefore, a + collision-chaining table should be used. A probing container, + conversely, might be used efficiently for operations such as + eliminating duplicates in a sequence, or counting the number of + occurrences within a sequence. Probing containers might be more + useful also in multithreaded applications where each thread + manipulates a hash-based container: in the standard, allocators have + class-wise semantics (see [meyers96more] - Item 10); a + probing container might incur less contention in this case.

    In hash-based containers, the range-hashing scheme seems to + affect performance more than other considerations. In most + settings, a mask-based scheme works well (or can be made to + work well). If the key-distribution can be estimated a-priori, + a simple hash function can produce nearly uniform hash-value + distribution. In many other cases (e.g., text hashing, + floating-point hashing), the hash function is powerful enough + to generate hash values with good uniformity properties + [knuth98sorting]; + a modulo-based scheme, taking into account all bits of the hash + value, appears to overlap the hash function in its effort.

    The range-hashing scheme determines many of the other + policies. A mask-based scheme works + well with an exponential-size policy; for + probing-based containers, it goes well with a linear-probe + function.

    An orthogonal consideration is the trigger policy. This + presents difficult tradeoffs. E.g., different load + factors in a load-check trigger policy yield a + space/amortized-cost tradeoff.

    In general, there are several families of tree-based + underlying data structures: balanced node-based trees + (e.g., red-black or AVL trees), high-probability + balanced node-based trees (e.g., random treaps or + skip-lists), competitive node-based trees (e.g., splay + trees), vector-based "trees", and tries. (Additionally, there + are disk-residing or network-residing trees, such as B-Trees + and their numerous variants. An interface for this would have + to deal with the execution model and ACID guarantees; this is + out of the scope of this library.) Following are some + observations on their application to different settings.

    Of the balanced node-based trees, this library includes a + red-black tree, as does standard (in + practice). This type of tree is the "workhorse" of tree-based + containers: it offers both reasonable modification and + reasonable lookup time. Unfortunately, this data structure + stores a huge amount of metadata. Each node must contain, + besides a value, three pointers and a boolean. This type might + be avoided if space is at a premium [austern00noset].

    High-probability balanced node-based trees suffer the + drawbacks of deterministic balanced trees. Although they are + fascinating data structures, preliminary tests with them showed + their performance was worse than red-black trees. The library + does not contain any such trees, therefore.

    Competitive node-based trees have two drawbacks. They are + usually somewhat unbalanced, and they perform a large number of + comparisons. Balanced trees perform one comparison per each + node they encounter on a search path; a splay tree performs two + comparisons. If the keys are complex objects, e.g., + std::string, this can increase the running time. + Conversely, such trees do well when there is much locality of + reference. It is difficult to determine in which case to prefer + such trees over balanced trees. This library includes a splay + tree.

    Ordered-vector trees use very little space + [austern00noset]. + They do not have any other advantages (at least in this + implementation).

    Large-fan-out PATRICIA tries have excellent lookup + performance, but they do so through maintaining, for each node, + a miniature "hash-table". Their space efficiency is low, and + their modification performance is bad. These tries might be + used for semi-static settings, where order preservation is + important. Alternatively, red-black trees cross-referenced with + hash tables can be used. [okasaki98mereable] + discusses small-fan-out PATRICIA tries for integers, but the + cited results seem to indicate that the amortized cost of + maintaining such trees is higher than that of balanced trees. + Moderate-fan-out trees might be useful for sequences where each + element has a limited number of choices, e.g., DNA + strings.

    Different mapping semantics were discussed in the introduction and design sections.Here + the focus will be on the case where a keys can be composed into + primary keys and secondary keys. (In the case where some keys + are completely identical, it is trivial that one should use an + associative container mapping values to size types.) In this + case there are (at least) five possibilities:

    1. Use an associative container that allows equivalent-key + values (such as std::multimap)

    2. Use a unique-key value associative container that maps + each primary key to some complex associative container of + secondary keys, say a tree-based or hash-based container. +

    3. Use a unique-key value associative container that maps + each primary key to some simple associative container of + secondary keys, say a list-based container.

    4. Use a unique-key value associative container that maps + each primary key to some non-associative container + (e.g., std::vector)

    5. Use a unique-key value associative container that takes + into account both primary and secondary keys.

    Stated simply: there is a simple answer for this. (Excluding + option 1, which should be avoided in all cases).

    If the expected ratio of secondary keys to primary keys is + small, then 3 and 4 seem reasonable. Both types of secondary + containers are relatively lightweight (in terms of memory use + and construction time), and so creating an entire container + object for each primary key is not too expensive. Option 4 + might be preferable to option 3 if changing the secondary key + of some primary key is frequent - one cannot modify an + associative container's key, and the only possibility, + therefore, is erasing the secondary key and inserting another + one instead; a non-associative container, conversely, can + support in-place modification. The actual cost of erasing a + secondary key and inserting another one depends also on the + allocator used for secondary associative-containers (The tests + above used the standard allocator, but in practice one might + choose to use, e.g., [boost_pool]). Option 2 is + definitely an overkill in this case. Option 1 loses out either + immediately (when there is one secondary key per primary key) + or almost immediately after that. Option 5 has the same + drawbacks as option 2, but it has the additional drawback that + finding all values whose primary key is equivalent to some key, + might be linear in the total number of values stored (for + example, if using a hash-based container).

    If the expected ratio of secondary keys to primary keys is + large, then the answer is more complicated. It depends on the + distribution of secondary keys to primary keys, the + distribution of accesses according to primary keys, and the + types of operations most frequent.

    To be more precise, assume there are m primary keys, + primary key i is mapped to ni + secondary keys, and each primary key is mapped, on average, to + n secondary keys (i.e., + E(ni) = n).

    Suppose one wants to find a specific pair of primary and + secondary keys. Using 1 with a tree based container + (std::multimap), the expected cost is + E(Θ(log(m) + ni)) = Θ(log(m) + + n); using 1 with a hash-based container + (std::tr1::unordered_multimap), the expected cost is + Θ(n). Using 2 with a primary hash-based container + and secondary hash-based containers, the expected cost is + O(1); using 2 with a primary tree-based container and + secondary tree-based containers, the expected cost is (using + the Jensen inequality [motwani95random]) + E(O(log(m) + log(ni)) = O(log(m)) + + E(O(log(ni)) = O(log(m)) + O(log(n)), + assuming that primary keys are accessed equiprobably. 3 and 4 + are similar to 1, but with lower constants. Using 5 with a + hash-based container, the expected cost is O(1); using 5 + with a tree based container, the cost is + E(Θ(log(mn))) = Θ(log(m) + + log(n)).

    Suppose one needs the values whose primary key matches some + given key. Using 1 with a hash-based container, the expected + cost is Θ(n), but the values will not be ordered + by secondary keys (which may or may not be required); using 1 + with a tree-based container, the expected cost is + Θ(log(m) + n), but with high constants; again the + values will not be ordered by secondary keys. 2, 3, and 4 are + similar to 1, but typically with lower constants (and, + additionally, if one uses a tree-based container for secondary + keys, they will be ordered). Using 5 with a hash-based + container, the cost is Θ(mn).

    Suppose one wants to assign to a primary key all secondary + keys assigned to a different primary key. Using 1 with a + hash-based container, the expected cost is Θ(n), + but with very high constants; using 1 with a tree-based + container, the cost is Θ(nlog(mn)). Using 2, 3, + and 4, the expected cost is Θ(n), but typically + with far lower costs than 1. 5 is similar to 1.

    The following table shows the complexities of the different + underlying data structures in terms of orders of growth. It is + interesting to note that this table implies something about the + constants of the operations as well (see Amortized push + and pop operations).

     pushpopmodifyerasejoin
    + std::priority_queue + + Θ(n) worst + Θ(log(n)) amortized + + Θ(log(n)) Worst + + Θ(n log(n)) Worst + [std note 1] + + Θ(n log(n)) + [std note 2] + + Θ(n log(n)) + [std note 1] +
    + priority_queue + <Tag = + pairing_heap_tag> + + O(1) + + Θ(n) worst + Θ(log(n)) amortized + + Θ(n) worst + Θ(log(n)) amortized + + Θ(n) worst + Θ(log(n)) amortized + + O(1) +
    + priority_queue + <Tag = + binary_heap_tag> + + Θ(n) worst + Θ(log(n)) amortized + + Θ(n) worst + Θ(log(n)) amortized + + Θ(n) + + Θ(n) + + Θ(n) +
    + priority_queue + <Tag = + binomial_heap_tag> + + Θ(log(n)) worst + O(1) amortized + + Θ(log(n)) + + Θ(log(n)) + + Θ(log(n)) + + Θ(log(n)) +
    + priority_queue + <Tag = + rc_binomial_heap_tag> + + O(1) + + Θ(log(n)) + + Θ(log(n)) + + Θ(log(n)) + + Θ(log(n)) +
    + priority_queue<Tag = + thin_heap_tag> + + O(1) + + Θ(n) worst + Θ(log(n)) amortized + + Θ(log(n)) worst + O(1) amortized, + or Θ(log(n)) amortized + [thin_heap_note] + + Θ(n) worst + Θ(log(n)) amortized + + Θ(n) +

    [std note 1] This + is not a property of the algorithm, but rather due to the fact + that the standard's priority queue implementation does not support + iterators (and consequently the ability to access a specific + value inside it). If the priority queue is adapting an + std::vector, then it is still possible to reduce this + to Θ(n) by adapting over the standard's adapter and + using the fact that top returns a reference to the + first value; if, however, it is adapting an + std::deque, then this is impossible.

    [std note 2] As + with [std note 1], this is not a + property of the algorithm, but rather the standard's implementation. + Again, if the priority queue is adapting an + std::vector then it is possible to reduce this to + Θ(n), but with a very high constant (one must call + std::make_heap which is an expensive linear + operation); if the priority queue is adapting an + std::deque, then this is impossible.

    [thin_heap_note] A thin heap has + Θ(log(n)) worst case modify time + always, but the amortized time depends on the nature of the + operation: I) if the operation increases the key (in the sense + of the priority queue's comparison functor), then the amortized + time is O(1), but if II) it decreases it, then the + amortized time is the same as the worst case time. Note that + for most algorithms, I) is important and II) is not.

    In many cases, a priority queue is needed primarily for + sequences of push and pop operations. All of + the underlying data structures have the same amortized + logarithmic complexity, but they differ in terms of + constants.

    The table above shows that the different data structures are + "constrained" in some respects. In general, if a data structure + has lower worst-case complexity than another, then it will + perform slower in the amortized sense. Thus, for example a + redundant-counter binomial heap (priority_queue with + Tag = rc_binomial_heap_tag) + has lower worst-case push performance than a binomial + heap (priority_queue + with Tag = binomial_heap_tag), + and so its amortized push performance is slower in + terms of constants.

    As the table shows, the "least constrained" underlying + data structures are binary heaps and pairing heaps. + Consequently, it is not surprising that they perform best in + terms of amortized constants.

    1. Pairing heaps seem to perform best for non-primitive + types (e.g., std::strings), as shown by + Priority + Queue Text push Timing Test and Priority + Queue Text push and pop Timing + Test

    2. binary heaps seem to perform best for primitive types + (e.g., ints), as shown by Priority + Queue Random Integer push Timing Test and + Priority + Queue Random Integer push and pop Timing + Test.

    In some graph algorithms, a decrease-key operation is + required [clrs2001]; + this operation is identical to modify if a value is + increased (in the sense of the priority queue's comparison + functor). The table above and Priority Queue + Text modify Up Timing Test show that a thin heap + (priority_queue with + Tag = thin_heap_tag) + outperforms a pairing heap (priority_queue with + Tag = Tag = pairing_heap_tag), + but the rest of the tests show otherwise.

    This makes it difficult to decide which implementation to use in + this case. Dijkstra's shortest-path algorithm, for example, requires + Θ(n) push and pop operations + (in the number of vertices), but O(n2) + modify operations, which can be in practice Θ(n) + as well. It is difficult to find an a-priori characterization of + graphs in which the actual number of modify + operations will dwarf the number of push and + pop operations.

    Prev Up Next
    Design Home Acknowledgments
    diff --git a/libstdc++-v3/doc/html/manual/policy_data_structures.html b/libstdc++-v3/doc/html/manual/policy_data_structures.html new file mode 100644 index 00000000000..c6c32943f72 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/policy_data_structures.html @@ -0,0 +1,1312 @@ + + +Chapter 22. Policy-Based Data Structures
    Chapter 22. Policy-Based Data Structures
    Prev Part III.  + Extensions + + Next

    Table of Contents

    Intro
    Performance Issues
    Associative
    Priority Que
    Goals
    Associative
    Policy Choices
    Underlying Data Structures
    Iterators
    Functional
    Priority Queues
    Policy Choices
    Underlying Data Structures
    Binary Heaps
    Using
    Prerequisites
    Organization
    Tutorial
    Basic Use
    + Configuring via Template Parameters +
    + Querying Container Attributes +
    + Point and Range Iteration +
    Examples
    Intermediate Use
    Querying with container_traits
    By Container Method
    Hash-Based
    Branch-Based
    Priority Queues
    Design
    Concepts
    Null Policy Classes
    Map and Set Semantics
    + Distinguishing Between Maps and Sets +
    Alternatives to std::multiset and std::multimap
    Iterator Semantics
    Point and Range Iterators
    Distinguishing Point and Range Iterators
    Invalidation Guarantees
    Genericity
    Tag
    Traits
    By Container
    hash
    Interface
    Details
    tree
    Interface
    Details
    Trie
    Interface
    Details
    List
    Interface
    Details
    Priority Queue
    Interface
    Details
    Testing
    Regression
    Performance
    Hash-Based
    + Text find +
    + Integer find +
    + Integer Subscript find +
    + Integer Subscript insert +
    + Integer find with Skewed-Distribution +
    + Erase Memory Use +
    Branch-Based
    + Text insert +
    + Text find +
    + Text find with Locality-of-Reference +
    + split and join +
    + Order-Statistics +
    Multimap
    + Text find with Small Secondary-to-Primary Key Ratios +
    + Text find with Large Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios +
    + Text insert with Small + Secondary-to-Primary Key Ratios Memory Use +
    + Text insert with Small + Secondary-to-Primary Key Ratios Memory Use +
    Priority Queue
    + Text push +
    + Text push and pop +
    + Integer push +
    + Integer push +
    + Text pop Memory Use +
    + Text join +
    + Text modify Up +
    + Text modify Down +
    Observations
    Associative
    Priority_Queue
    Acknowledgments
    + Bibliography +

    + This is a library of policy-based elementary data structures: + associative containers and priority queues. It is designed for + high-performance, flexibility, semantic safety, and conformance to + the corresponding containers in std and + std::tr1 (except for some points where it differs + by design). +

    +

    +

    + An attempt is made to categorize the wide variety of possible + container designs in terms of performance-impacting factors. These + performance factors are translated into design policies and + incorporated into container design. +

    + There is tension between unravelling factors into a coherent set of + policies. Every attempt is made to make a minimal set of + factors. However, in many cases multiple factors make for long + template names. Every attempt is made to alias and use typedefs in + the source files, but the generated names for external symbols can + be large for binary files or debuggers. +

    + In many cases, the longer names allow capabilities and behaviours + controlled by macros to also be unamibiguously emitted as distinct + generated names. +

    + Specific issues found while unraveling performance factors in the + design of associative containers and priority queues follow. +

    + Associative containers depend on their composite policies to a very + large extent. Implicitly hard-wiring policies can hamper their + performance and limit their functionality. An efficient hash-based + container, for example, requires policies for testing key + equivalence, hashing keys, translating hash values into positions + within the hash table, and determining when and how to resize the + table internally. A tree-based container can efficiently support + order statistics, i.e. the ability to query what is the order of + each key within the sequence of keys in the container, but only if + the container is supplied with a policy to internally update + meta-data. There are many other such examples. +

    + Ideally, all associative containers would share the same + interface. Unfortunately, underlying data structures and mapping + semantics differentiate between different containers. For example, + suppose one writes a generic function manipulating an associative + container. + 

    +	  template<typename Cntnr>
+	  void
+	  some_op_sequence(Cntnr& r_cnt)
+	  {
+	  ...
+	  }
+

    + Given this, then what can one assume about the instantiating + container? The answer varies according to its underlying data + structure. If the underlying data structure of + Cntnr is based on a tree or trie, then the order + of elements is well defined; otherwise, it is not, in general. If + the underlying data structure of Cntnr is based + on a collision-chaining hash table, then modifying + r_Cntnr will not invalidate its iterators' order; + if the underlying data structure is a probing hash table, then this + is not the case. If the underlying data structure is based on a tree + or trie, then a reference to the container can efficiently be split; + otherwise, it cannot, in general. If the underlying data structure + is a red-black tree, then splitting a reference to the container is + exception-free; if it is an ordered-vector tree, exceptions can be + thrown. +

    + Priority queues are useful when one needs to efficiently access a + minimum (or maximum) value as the set of values changes. +

    + Most useful data structures for priority queues have a relatively + simple structure, as they are geared toward relatively simple + requirements. Unfortunately, these structures do not support access + to an arbitrary value, which turns out to be necessary in many + algorithms. Say, decreasing an arbitrary value in a graph + algorithm. Therefore, some extra mechanism is necessary and must be + invented for accessing arbitrary values. There are at least two + alternatives: embedding an associative container in a priority + queue, or allowing cross-referencing through iterators. The first + solution adds significant overhead; the second solution requires a + precise definition of iterator invalidation. Which is the next + point... +

    + Priority queues, like hash-based containers, store values in an + order that is meaningless and undefined externally. For example, a + push operation can internally reorganize the + values. Because of this characteristic, describing a priority + queues' iterator is difficult: on one hand, the values to which + iterators point can remain valid, but on the other, the logical + order of iterators can change unpredictably. +

    + Roughly speaking, any element that is both inserted to a priority + queue (e.g. through push) and removed + from it (e.g., through pop), incurs a + logarithmic overhead (in the amortized sense). Different underlying + data structures place the actual cost differently: some are + optimized for amortized complexity, whereas others guarantee that + specific operations only have a constant cost. One underlying data + structure might be chosen if modifying a value is frequent + (Dijkstra's shortest-path algorithm), whereas a different one might + be chosen otherwise. Unfortunately, an array-based binary heap - an + underlying data structure that optimizes (in the amortized sense) + push and pop operations, differs from the + others in terms of its invalidation guarantees. Other design + decisions also impact the cost and placement of the overhead, at the + expense of more difference in the the kinds of operations that the + underlying data structure can support. These differences pose a + challenge when creating a uniform interface for priority queues. +

    + Many fine associative-container libraries were already written, + most notably, the C++ standard's associative containers. Why + then write another library? This section shows some possible + advantages of this library, when considering the challenges in + the introduction. Many of these points stem from the fact that + the ISO C++ process introduced associative-containers in a + two-step process (first standardizing tree-based containers, + only then adding hash-based containers, which are fundamentally + different), did not standardize priority queues as containers, + and (in our opinion) overloads the iterator concept. +

    +

    + Associative containers require a relatively large number of + policies to function efficiently in various settings. In some + cases this is needed for making their common operations more + efficient, and in other cases this allows them to support a + larger set of operations +

    1. + Hash-based containers, for example, support look-up and + insertion methods (find and + insert). In order to locate elements + quickly, they are supplied a hash functor, which instruct + how to transform a key object into some size type; a hash + functor might transform "hello" + into 1123002298. A hash table, though, + requires transforming each key object into some size-type + type in some specific domain; a hash table with a 128-long + table might transform "hello" into + position 63. The policy by which the + hash value is transformed into a position within the table + can dramatically affect performance. Hash-based containers + also do not resize naturally (as opposed to tree-based + containers, for example). The appropriate resize policy is + unfortunately intertwined with the policy that transforms + hash value into a position within the table. +

    2. + Tree-based containers, for example, also support look-up and + insertion methods, and are primarily useful when maintaining + order between elements is important. In some cases, though, + one can utilize their balancing algorithms for completely + different purposes. +

      + Figure A shows a tree whose each node contains two entries: + a floating-point key, and some size-type + metadata (in bold beneath it) that is + the number of nodes in the sub-tree. (The root has key 0.99, + and has 5 nodes (including itself) in its sub-tree.) A + container based on this data structure can obviously answer + efficiently whether 0.3 is in the container object, but it + can also answer what is the order of 0.3 among all those in + the container object: see [biblio.clrs2001]. + +

      + As another example, Figure B shows a tree whose each node + contains two entries: a half-open geometric line interval, + and a number metadata (in bold beneath + it) that is the largest endpoint of all intervals in its + sub-tree. (The root describes the interval [20, + 36), and the largest endpoint in its sub-tree is + 99.) A container based on this data structure can obviously + answer efficiently whether [3, 41) is + in the container object, but it can also answer efficiently + whether the container object has intervals that intersect + [3, 41). These types of queries are + very useful in geometric algorithms and lease-management + algorithms. +

      + It is important to note, however, that as the trees are + modified, their internal structure changes. To maintain + these invariants, one must supply some policy that is aware + of these changes. Without this, it would be better to use a + linked list (in itself very efficient for these purposes). +

    Figure 22.1. Node Invariants

    Node Invariants

    + The standard C++ library contains associative containers based on + red-black trees and collision-chaining hash tables. These are + very useful, but they are not ideal for all types of + settings. +

    + The figure below shows the different underlying data structures + currently supported in this library. +

    Figure 22.2. Underlying Associative Data Structures

    Underlying Associative Data Structures

    + A shows a collision-chaining hash-table, B shows a probing + hash-table, C shows a red-black tree, D shows a splay tree, E shows + a tree based on an ordered vector(implicit in the order of the + elements), F shows a PATRICIA trie, and G shows a list-based + container with update policies. +

    + Each of these data structures has some performance benefits, in + terms of speed, size or both. For now, note that vector-based trees + and probing hash tables manipulate memory more efficiently than + red-black trees and collision-chaining hash tables, and that + list-based associative containers are very useful for constructing + "multimaps". +

    + Now consider a function manipulating a generic associative + container, + 

    +	    template<class Cntnr>
+	    int
+	    some_op_sequence(Cntnr &r_cnt)
+	    {
+	    ...
+	    }
+

    + Ideally, the underlying data structure + of Cntnr would not affect what can be + done with r_cnt. Unfortunately, this is not + the case. +

    + For example, if Cntnr + is std::map, then the function can + use + 

    +	    std::for_each(r_cnt.find(foo), r_cnt.find(bar), foobar)
+

    + in order to apply foobar to all + elements between foo and + bar. If + Cntnr is a hash-based container, + then this call's results are undefined. +

    + Also, if Cntnr is tree-based, the type + and object of the comparison functor can be + accessed. If Cntnr is hash based, these + queries are nonsensical. +

    + There are various other differences based on the container's + underlying data structure. For one, they can be constructed by, + and queried for, different policies. Furthermore: +

    1. + Containers based on C, D, E and F store elements in a + meaningful order; the others store elements in a meaningless + (and probably time-varying) order. By implication, only + containers based on C, D, E and F can + support erase operations taking an + iterator and returning an iterator to the following element + without performance loss. +

    2. + Containers based on C, D, E, and F can be split and joined + efficiently, while the others cannot. Containers based on C + and D, furthermore, can guarantee that this is exception-free; + containers based on E cannot guarantee this. +

    3. + Containers based on all but E can guarantee that + erasing an element is exception free; containers based on E + cannot guarantee this. Containers based on all but B and E + can guarantee that modifying an object of their type does + not invalidate iterators or references to their elements, + while containers based on B and E cannot. Containers based + on C, D, and E can furthermore make a stronger guarantee, + namely that modifying an object of their type does not + affect the order of iterators. +

    + A unified tag and traits system (as used for the C++ standard + library iterators, for example) can ease generic manipulation of + associative containers based on different underlying data + structures. +

    + Iterators are centric to the design of the standard library + containers, because of the container/algorithm/iterator + decomposition that allows an algorithm to operate on a range + through iterators of some sequence. Iterators, then, are useful + because they allow going over a + specific sequence. The standard library + also uses iterators for accessing a + specific element: when an associative + container returns one through find. The + standard library consistently uses the same types of iterators + for both purposes: going over a range, and accessing a specific + found element. Before the introduction of hash-based containers + to the standard library, this made sense (with the exception of + priority queues, which are discussed later). +

    + Using the standard associative containers together with + non-order-preserving associative containers (and also because of + priority-queues container), there is a possible need for + different types of iterators for self-organizing containers: + the iterator concept seems overloaded to mean two different + things (in some cases). XXX + "ds_gen.html#find_range">Design::Associative + Containers::Data-Structure Genericity::Point-Type and Range-Type + Methods. +

    + Suppose cntnr is some associative + container, and say c is an object of + type cntnr. Then what will be the outcome + of + 

    +	      std::for_each(c.find(1), c.find(5), foo);
+

    + If cntnr is a tree-based container + object, then an in-order walk will + apply foo to the relevant elements, + as in the graphic below, label A. If c is + a hash-based container, then the order of elements between any + two elements is undefined (and probably time-varying); there is + no guarantee that the elements traversed will coincide with the + logical elements between 1 and 5, as in + label B. +

    Figure 22.3. Range Iteration in Different Data Structures

    Node Invariants

    + In our opinion, this problem is not caused just because + red-black trees are order preserving while + collision-chaining hash tables are (generally) not - it + is more fundamental. Most of the standard's containers + order sequences in a well-defined manner that is + determined by their interface: + calling insert on a tree-based + container modifies its sequence in a predictable way, as + does calling push_back on a list or + a vector. Conversely, collision-chaining hash tables, + probing hash tables, priority queues, and list-based + containers (which are very useful for "multimaps") are + self-organizing data structures; the effect of each + operation modifies their sequences in a manner that is + (practically) determined by their + implementation. +

    + Consequently, applying an algorithm to a sequence obtained from most + containers may or may not make sense, but applying it to a + sub-sequence of a self-organizing container does not. +

    + Suppose c is some collision-chaining + hash-based container object, and one calls + 

    c.find(3)

    + Then what composes the returned iterator? +

    + In the graphic below, label A shows the simplest (and + most efficient) implementation of a collision-chaining + hash table. The little box marked + point_iterator shows an object + that contains a pointer to the element's node. Note that + this "iterator" has no way to move to the next element ( + it cannot support + operator++). Conversely, the little + box marked iterator stores both a + pointer to the element, as well as some other + information (the bucket number of the element). the + second iterator, then, is "heavier" than the first one- + it requires more time and space. If we were to use a + different container to cross-reference into this + hash-table using these iterators - it would take much + more space. As noted above, nothing much can be done by + incrementing these iterators, so why is this extra + information needed? +

    + Alternatively, one might create a collision-chaining hash-table + where the lists might be linked, forming a monolithic total-element + list, as in the graphic below, label B. Here the iterators are as + light as can be, but the hash-table's operations are more + complicated. +

    Figure 22.4. Point Iteration in Hash Data Structures

    Point Iteration in Hash Data Structures

    + It should be noted that containers based on collision-chaining + hash-tables are not the only ones with this type of behavior; + many other self-organizing data structures display it as well. +

    Consider the following snippet:

    +	      it = c.find(3);
+	      c.erase(5);
+

    + Following the call to erase, what is the + validity of it: can it be de-referenced? + can it be incremented? +

    + The answer depends on the underlying data structure of the + container. The graphic below shows three cases: A1 and A2 show + a red-black tree; B1 and B2 show a probing hash-table; C1 and C2 + show a collision-chaining hash table. +

    Figure 22.5. Effect of erase in different underlying data structures

    Effect of erase in different underlying data structures

    1. + Erasing 5 from A1 yields A2. Clearly, an iterator to 3 can + be de-referenced and incremented. The sequence of iterators + changed, but in a way that is well-defined by the interface. +

    2. + Erasing 5 from B1 yields B2. Clearly, an iterator to 3 is + not valid at all - it cannot be de-referenced or + incremented; the order of iterators changed in a way that is + (practically) determined by the implementation and not by + the interface. +

    3. + Erasing 5 from C1 yields C2. Here the situation is more + complicated. On the one hand, there is no problem in + de-referencing it. On the other hand, + the order of iterators changed in a way that is + (practically) determined by the implementation and not by + the interface. +

    + So in the standard library containers, it is not always possible + to express whether it is valid or not. This + is true also for insert. Again, the + iterator concept seems overloaded. +

    +

    + The design of the functional overlay to the underlying data + structures differs slightly from some of the conventions used in + the C++ standard. A strict public interface of methods that + comprise only operations which depend on the class's internal + structure; other operations are best designed as external + functions. (See [biblio.meyers02both]).With this + rubric, the standard associative containers lack some useful + methods, and provide other methods which would be better + removed. +

    1. + Order-preserving standard associative containers provide the + method + 

      +		  iterator
+		  erase(iterator it)
+

      + which takes an iterator, erases the corresponding + element, and returns an iterator to the following + element. Also standardd hash-based associative + containers provide this method. This seemingly + increasesgenericity between associative containers, + since it is possible to use + 

      +		  typename C::iterator it = c.begin();
+		  typename C::iterator e_it = c.end();
+
+		  while(it != e_it)
+		  it = pred(*it)? c.erase(it) : ++it;
+

      + in order to erase from a container object + c all element which match a + predicate pred. However, in a + different sense this actually decreases genericity: an + integral implication of this method is that tree-based + associative containers' memory use is linear in the total + number of elements they store, while hash-based + containers' memory use is unbounded in the total number of + elements they store. Assume a hash-based container is + allowed to decrease its size when an element is + erased. Then the elements might be rehashed, which means + that there is no "next" element - it is simply + undefined. Consequently, it is possible to infer from the + fact that the standard library's hash-based containers + provide this method that they cannot downsize when + elements are erased. As a consequence, different code is + needed to manipulate different containers, assuming that + memory should be conserved. Therefor, this library's + non-order preserving associative containers omit this + method. +

    2. + All associative containers include a conditional-erase method + 

      +		  template<
+		  class Pred>
+		  size_type
+		  erase_if
+		  (Pred pred)
+

      + which erases all elements matching a predicate. This is probably the + only way to ensure linear-time multiple-item erase which can + actually downsize a container. +

    3. + The standard associative containers provide methods for + multiple-item erase of the form + 

      +		  size_type
+		  erase(It b, It e)
+

      + erasing a range of elements given by a pair of + iterators. For tree-based or trie-based containers, this can + implemented more efficiently as a (small) sequence of split + and join operations. For other, unordered, containers, this + method isn't much better than an external loop. Moreover, + if c is a hash-based container, + then + 

      +		  c.erase(c.find(2), c.find(5))
+

      + is almost certain to do something + different than erasing all elements whose keys are between 2 + and 5, and is likely to produce other undefined behavior. +

    + It is well-known that tree-based and trie-based container + objects can be efficiently split or joined (See + [biblio.clrs2001]). Externally splitting or + joining trees is super-linear, and, furthermore, can throw + exceptions. Split and join methods, consequently, seem good + choices for tree-based container methods, especially, since as + noted just before, they are efficient replacements for erasing + sub-sequences. +

    + The standard associative containers provide methods of the form + 

    +	      template<class It>
+	      size_type
+	      insert(It b, It e);
+

    + for inserting a range of elements given by a pair of + iterators. At best, this can be implemented as an external loop, + or, even more efficiently, as a join operation (for the case of + tree-based or trie-based containers). Moreover, these methods seem + similar to constructors taking a range given by a pair of + iterators; the constructors, however, are transactional, whereas + the insert methods are not; this is possibly confusing. +

    + Associative containers are parametrized by policies allowing to + test key equivalence: a hash-based container can do this through + its equivalence functor, and a tree-based container can do this + through its comparison functor. In addition, some standard + associative containers have global function operators, like + operator== and operator<=, + that allow comparing entire associative containers. +

    + In our opinion, these functions are better left out. To begin + with, they do not significantly improve over an external + loop. More importantly, however, they are possibly misleading - + operator==, for example, usually checks for + equivalence, or interchangeability, but the associative + container cannot check for values' equivalence, only keys' + equivalence; also, are two containers considered equivalent if + they store the same values in different order? this is an + arbitrary decision. +

    + Priority queues are containers that allow efficiently inserting + values and accessing the maximal value (in the sense of the + container's comparison functor). Their interface + supports push + and pop. The standard + container std::priorityqueue indeed support + these methods, but little else. For algorithmic and + software-engineering purposes, other methods are needed: +

    1. + Many graph algorithms (see + [biblio.clrs2001]) require increasing a + value in a priority queue (again, in the sense of the + container's comparison functor), or joining two + priority-queue objects. +

    2. The return type of priority_queue's + push method is a point-type iterator, which can + be used for modifying or erasing arbitrary values. For + example:

      +		priority_queue<int> p;
+		priority_queue<int>::point_iterator it = p.push(3);
+		p.modify(it, 4);
+

      These types of cross-referencing operations are necessary + for making priority queues useful for different applications, + especially graph applications.

    3. + It is sometimes necessary to erase an arbitrary value in a + priority queue. For example, consider + the select function for monitoring + file descriptors: + 

      +		int
+		select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds,
+		struct timeval *timeout);
+

      + then, as the select documentation states: +

      + “ + The nfds argument specifies the range of file + descriptors to be tested. The select() function tests file + descriptors in the range of 0 to nfds-1.” +

      + It stands to reason, therefore, that we might wish to + maintain a minimal value for nfds, and + priority queues immediately come to mind. Note, though, that + when a socket is closed, the minimal file description might + change; in the absence of an efficient means to erase an + arbitrary value from a priority queue, we might as well + avoid its use altogether. +

      + The standard containers typically support iterators. It is + somewhat unusual + for std::priority_queue to omit them + (See [biblio.meyers01stl]). One might + ask why do priority queues need to support iterators, since + they are self-organizing containers with a different purpose + than abstracting sequences. There are several reasons: +

      1. + Iterators (even in self-organizing containers) are + useful for many purposes: cross-referencing + containers, serialization, and debugging code that uses + these containers. +

      2. + The standard library's hash-based containers support + iterators, even though they too are self-organizing + containers with a different purpose than abstracting + sequences. +

      3. + In standard-library-like containers, it is natural to specify the + interface of operations for modifying a value or erasing + a value (discussed previously) in terms of a iterators. + It should be noted that the standard + containers also use iterators for accessing and + manipulating a specific value. In hash-based + containers, one checks the existence of a key by + comparing the iterator returned by find to the + iterator returned by end, and not by comparing a + pointer returned by find to NULL. +

    + There are three main implementations of priority queues: the + first employs a binary heap, typically one which uses a + sequence; the second uses a tree (or forest of trees), which is + typically less structured than an associative container's tree; + the third simply uses an associative container. These are + shown in the figure below with labels A1 and A2, B, and C. +

    Figure 22.6. Underlying Priority Queue Data Structures

    Underlying Priority Queue Data Structures

    + No single implementation can completely replace any of the + others. Some have better push + and pop amortized performance, some have + better bounded (worst case) response time than others, some + optimize a single method at the expense of others, etc. In + general the "best" implementation is dictated by the specific + problem. +

    + As with associative containers, the more implementations + co-exist, the more necessary a traits mechanism is for handling + generic containers safely and efficiently. This is especially + important for priority queues, since the invalidation guarantees + of one of the most useful data structures - binary heaps - is + markedly different than those of most of the others. +

    + Binary heaps are one of the most useful underlying + data structures for priority queues. They are very efficient in + terms of memory (since they don't require per-value structure + metadata), and have the best amortized push and + pop performance for primitive types like + int. +

    + The standard library's priority_queue + implements this data structure as an adapter over a sequence, + typically + std::vector + or std::deque, which correspond to labels + A1 and A2 respectively in the graphic above. +

    + This is indeed an elegant example of the adapter concept and + the algorithm/container/iterator decomposition. (See [biblio.nelson96stlpq]). There are + several reasons why a binary-heap priority queue + may be better implemented as a container instead of a + sequence adapter: +

    1. + std::priority_queue cannot erase values + from its adapted sequence (irrespective of the sequence + type). This means that the memory use of + an std::priority_queue object is always + proportional to the maximal number of values it ever contained, + and not to the number of values that it currently + contains. (See performance/priority_queue_text_pop_mem_usage.cc.) + This implementation of binary heaps acts very differently than + other underlying data structures (See also pairing heaps). +

    2. + Some combinations of adapted sequences and value types + are very inefficient or just don't make sense. If one uses + std::priority_queue<std::vector<std::string> + > >, for example, then not only will each + operation perform a logarithmic number of + std::string assignments, but, furthermore, any + operation (including pop) can render the container + useless due to exceptions. Conversely, if one uses + std::priority_queue<std::deque<int> > + >, then each operation uses incurs a logarithmic + number of indirect accesses (through pointers) unnecessarily. + It might be better to let the container make a conservative + deduction whether to use the structure in the graphic above, labels A1 or A2. +

    3. + There does not seem to be a systematic way to determine + what exactly can be done with the priority queue. +

      1. + If p is a priority queue adapting an + std::vector, then it is possible to iterate over + all values by using &p.top() and + &p.top() + p.size(), but this will not work + if p is adapting an std::deque; in any + case, one cannot use p.begin() and + p.end(). If a different sequence is adapted, it + is even more difficult to determine what can be + done. +

      2. + If p is a priority queue adapting an + std::deque, then the reference return by + 

        +		    p.top()
+

        + will remain valid until it is popped, + but if p adapts an std::vector, the + next push will invalidate it. If a different + sequence is adapted, it is even more difficult to + determine what can be done. +

    4. + Sequence-based binary heaps can still implement + linear-time erase and modify operations. + This means that if one needs to erase a small + (say logarithmic) number of values, then one might still + choose this underlying data structure. Using + std::priority_queue, however, this will generally + change the order of growth of the entire sequence of + operations. +

    [biblio.abrahams97exception] + + STL Exception Handling Contract + + . 1997. + Dave + + Abrahams + . + ISO SC22/WG21 + .

    [biblio.alexandrescu01modern] + Modern C++ Design: Generic Programming and Design Patterns Applied + . + 2001 + . + Andrei + + Alexandrescu + . + Addison-Wesley Publishing Company + .

    [biblio.andrew04mtf] + MTF, Bit, and COMB: A Guide to Deterministic and Randomized + Algorithms for the List Update Problem + . + K. + + Andrew + and + D. + + Gleich + .

    [biblio.austern00noset] + Why You Shouldn't Use set - and What You Should Use Instead + . + April, 2000 + . + Matthew + + Austern + . + C++ Report + .

    [biblio.austern01htprop] + + A Proposal to Add Hashtables to the Standard Library + + . + 2001 + . + Matthew + + Austern + . + ISO SC22/WG21 + .

    [biblio.austern98segmentedit] + Segmented iterators and hierarchical algorithms + . + April, 1998 + . + Matthew + + Austern + . + Generic Programming + .

    [biblio.dawestimer] + + Boost Timer Library + + . + Beeman + + Dawes + . + Boost + .

    [biblio.clearypool] + + Boost Pool Library + + . + Stephen + + Cleary + . + Boost + .

    [biblio.maddocktraits] + + Boost Type Traits Library + + . + Maddock + + John + and + Stephen + + Cleary + . + Boost + .

    [biblio.brodal96priority] + + Worst-case efficient priority queues + + . + Gerth + + Stolting Brodal + .

    [biblio.bulkamayheweff] + Efficient C++ Programming Techniques + . + 1997 + . + D. + + Bulka + and + D. + + Mayhew + . + Addison-Wesley Publishing Company + .

    [biblio.clrs2001] + Introduction to Algorithms, 2nd edition + . + 2001 + . + T. H. + + Cormen + , + C. E. + + Leiserson + , + R. L. + + Rivest + , and + C. + + Stein + . + MIT Press + .

    [biblio.dubhashi98neg] + Balls and bins: A study in negative dependence + . + 1998 + . + D. + + Dubashi + and + D. + + Ranjan + . + Random Structures and Algorithms 13 + .

    [biblio.fagin79extendible] + Extendible hashing - a fast access method for dynamic files + . + 1979 + . + R. + + Fagin + , + J. + + Nievergelt + , + N. + + Pippenger + , and + H. R. + + Strong + . + ACM Trans. Database Syst. 4 + .

    [biblio.filliatre2000ptset] + + Ptset: Sets of integers implemented as Patricia trees + + . + 2000 + . + Jean-Christophe + + Filliatre + .

    [biblio.fredman86pairing] + + The pairing heap: a new form of self-adjusting heap + + . + 1986 + . + M. L. + + Fredman + , + R. + + Sedgewick + , + D. D. + + Sleator + , and + R. E. + + Tarjan + .

    [biblio.gof] + Design Patterns - Elements of Reusable Object-Oriented Software + . + 1995 + . + E. + + Gamma + , + R. + + Helm + , + R. + + Johnson + , and + J. + + Vlissides + . + Addison-Wesley Publishing Company + .

    [biblio.garg86order] + Order-preserving key transformations + . + 1986 + . + A. K. + + Garg + and + C. C. + + Gotlieb + . + Trans. Database Syst. 11 + .

    [biblio.hyslop02making] + Making a real hash of things + . + May 2002 + . + J. + + Hyslop + and + Herb + + Sutter + . + C++ Report + .

    [biblio.jossutis01stl] + The C++ Standard Library - A Tutorial and Reference + . + 2001 + . + N. M. + + Jossutis + . + Addison-Wesley Publishing Company + .

    [biblio.kt99fat_heaps] + + New Heap Data Structures + + . + 1999 + . + Haim + + Kaplan + and + Robert E. + + Tarjan + .

    [biblio.kleft00sets] + Are Set Iterators Mutable or Immutable? + . + October 2000 + . + Angelika + + Langer + and + Klaus + + Kleft + . + C/C++ Users Jornal + .

    [biblio.knuth98sorting] + The Art of Computer Programming - Sorting and Searching + . + 1998 + . + D. E. + + Knuth + . + Addison-Wesley Publishing Company + .

    [biblio.liskov98data] + Data abstraction and hierarchy + . + May 1998 + . + B. + + Liskov + . + SIGPLAN Notices 23 + .

    [biblio.litwin80lh] + Linear hashing: A new tool for file and table addressing + . + June 1980 + . + W. + + Litwin + . + Proceedings of International Conference on Very Large Data Bases + .

    [biblio.maverik_lowerbounds] + + Deamortization - Part 2: Binomial Heaps + + . + 2005 + . + Maverik + + Woo + .

    [biblio.meyers96more] + More Effective C++: 35 New Ways to Improve Your Programs and Designs + . + 1996 + . + Scott + + Meyers + . + Addison-Wesley Publishing Company + .

    [biblio.meyers00nonmember] + How Non-Member Functions Improve Encapsulation + . + 2000 + . + Scott + + Meyers + . + C/C++ Users Journal + .

    [biblio.meyers01stl] + Effective STL: 50 Specific Ways to Improve Your Use of the Standard Template Library + . + 2001 + . + Scott + + Meyers + . + Addison-Wesley Publishing Company + .

    [biblio.meyers02both] + Class Template, Member Template - or Both? + . + 2003 + . + Scott + + Meyers + . + C/C++ Users Journal + .

    [biblio.motwani95random] + Randomized Algorithms + . + 2003 + . + R. + + Motwani + and + P. + + Raghavan + . + Cambridge University Press + .

    [biblio.mscom] + + COM: Component Model Object Technologies + + . + Microsoft + .

    [biblio.musser95rationale] + Rationale for Adding Hash Tables to the C++ Standard Template Library + . + 1995 + . + David R. + + Musser + .

    [biblio.musser96stltutorial] + STL Tutorial and Reference Guide + . + 1996 + . + David R. + + Musser + and + A. + + Saini + . + Addison-Wesley Publishing Company + .

    [biblio.nelson96stlpq] + Priority Queues and the STL + + . + January 1996 + . + Mark + + Nelson + . + Dr. Dobbs Journal + .

    [biblio.okasaki98mereable] + Fast mergeable integer maps + . + September 1998 + . + C. + + Okasaki + and + A. + + Gill + . + In Workshop on ML + .

    [biblio.sgi_stl] + + Standard Template Library Programmer's Guide + + . + Matt + + Austern + . + SGI + .

    [biblio.select_man] + + select + + .

    [biblio.sleator84amortized] + Amortized Efficiency of List Update Problems + . + 1984 + . + D. D. + + Sleator + and + R. E. + + Tarjan + . + ACM Symposium on Theory of Computing + .

    [biblio.sleator85self] + Self-Adjusting Binary Search Trees + . + 1985 + . + D. D. + + Sleator + and + R. E. + + Tarjan + . + ACM Symposium on Theory of Computing + .

    [biblio.stepanov94standard] + The Standard Template Library + . + 1984 + . + A. A. + + Stepanov + and + M. + + Lee + .

    [biblio.stroustrup97cpp] + The C++ Programming Langugage + . + 1997 + . + Bjarne + + Stroustrup + . + Addison-Wesley Publishing Company + .

    [biblio.vandevoorde2002cpptemplates] + C++ Templates: The Complete Guide + . + 2002 + . + D. + + Vandevoorde + and + N. M. + + Josuttis + . + Addison-Wesley Publishing Company + .

    [biblio.wickland96thirty] + + Thirty Years Among the Dead + + . + 1996 + . + C. A. + + Wickland + . + National Psychological Institute + .

    Prev Up Next
    Implementation Home Using
    diff --git a/libstdc++-v3/doc/html/manual/policy_data_structures_biblio.html b/libstdc++-v3/doc/html/manual/policy_data_structures_biblio.html new file mode 100644 index 00000000000..aaaef164fb1 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/policy_data_structures_biblio.html @@ -0,0 +1,29 @@ + + +Acknowledgments
    Acknowledgments
    Prev Chapter 22. Policy-Based Data Structures Next

    + Written by Ami Tavory and Vladimir Dreizin (IBM Haifa Research + Laboratories), and Benjamin Kosnik (Red Hat). +

    + This library was partially written at + IBM's Haifa Research Labs. + It is based heavily on policy-based design and uses many useful + techniques from Modern C++ Design: Generic Programming and Design + Patterns Applied by Andrei Alexandrescu. +

    + Two ideas are borrowed from the SGI-STL implementation: +

    1. + The prime-based resize policies use a list of primes taken from + the SGI-STL implementation. +

    2. + The red-black trees contain both a root node and a header node + (containing metadata), connected in a way that forward and + reverse iteration can be performed efficiently. +

    + Some test utilities borrow ideas from + boost::timer. +

    + We would like to thank Scott Meyers for useful comments (without + attributing to him any flaws in the design or implementation of the + library). +

    We would like to thank Matt Austern for the suggestion to + include tries.

    Prev Up Next
    Testing Home Chapter 23. HP/SGI Extensions
    diff --git a/libstdc++-v3/doc/html/manual/policy_data_structures_design.html b/libstdc++-v3/doc/html/manual/policy_data_structures_design.html new file mode 100644 index 00000000000..71e80a993eb --- /dev/null +++ b/libstdc++-v3/doc/html/manual/policy_data_structures_design.html @@ -0,0 +1,1430 @@ + + +Design
    Design
    Prev Chapter 22. Policy-Based Data Structures Next

    + Associative containers are typically parametrized by various + policies. For example, a hash-based associative container is + parametrized by a hash-functor, transforming each key into an + non-negative numerical type. Each such value is then further mapped + into a position within the table. The mapping of a key into a + position within the table is therefore a two-step process. +

    + In some cases, instantiations are redundant. For example, when the + keys are integers, it is possible to use a redundant hash policy, + which transforms each key into its value. +

    + In some other cases, these policies are irrelevant. For example, a + hash-based associative container might transform keys into positions + within a table by a different method than the two-step method + described above. In such a case, the hash functor is simply + irrelevant. +

    + When a policy is either redundant or irrelevant, it can be replaced + by null_type. +

    + For example, a set is an associative + container with one of its template parameters (the one for the + mapped type) replaced with null_type. Other + places simplifications are made possible with this technique + include node updates in tree and trie data structures, and hash + and probe functions for hash data structures. +

    + Anyone familiar with the standard knows that there are four kinds + of associative containers: maps, sets, multimaps, and + multisets. The map datatype associates each key to + some data. +

    + Sets are associative containers that simply store keys - + they do not map them to anything. In the standard, each map class + has a corresponding set class. E.g., + std::map<int, char> maps each + int to a char, but + std::set<int, char> simply stores + ints. In this library, however, there are no + distinct classes for maps and sets. Instead, an associative + container's Mapped template parameter is a policy: if + it is instantiated by null_type, then it + is a "set"; otherwise, it is a "map". E.g., + 

    +	  cc_hash_table<int, char>
+

    + is a "map" mapping each int value to a + char, but + 

    +	  cc_hash_table<int, null_type>
+

    + is a type that uniquely stores int values. +

    Once the Mapped template parameter is instantiated + by null_type, then + the "set" acts very similarly to the standard's sets - it does not + map each key to a distinct null_type object. Also, + , the container's value_type is essentially + its key_type - just as with the standard's sets + .

    + The standard's multimaps and multisets allow, respectively, + non-uniquely mapping keys and non-uniquely storing keys. As + discussed, the + reasons why this might be necessary are 1) that a key might be + decomposed into a primary key and a secondary key, 2) that a + key might appear more than once, or 3) any arbitrary + combination of 1)s and 2)s. Correspondingly, + one should use 1) "maps" mapping primary keys to secondary + keys, 2) "maps" mapping keys to size types, or 3) any arbitrary + combination of 1)s and 2)s. Thus, for example, an + std::multiset<int> might be used to store + multiple instances of integers, but using this library's + containers, one might use + 

    +	  tree<int, size_t>
+

    + i.e., a map of ints to + size_ts. +

    + These "multimaps" and "multisets" might be confusing to + anyone familiar with the standard's std::multimap and + std::multiset, because there is no clear + correspondence between the two. For example, in some cases + where one uses std::multiset in the standard, one might use + in this library a "multimap" of "multisets" - i.e., a + container that maps primary keys each to an associative + container that maps each secondary key to the number of times + it occurs. +

    + When one uses a "multimap," one should choose with care the + type of container used for secondary keys. +

    + Brace onself: this library does not contain containers like + std::multimap or + std::multiset. Instead, these data + structures can be synthesized via manipulation of the + Mapped template parameter. +

    + One maps the unique part of a key - the primary key, into an + associative-container of the (originally) non-unique parts of + the key - the secondary key. A primary associative-container + is an associative container of primary keys; a secondary + associative-container is an associative container of + secondary keys. +

    + Stepping back a bit, and starting in from the beginning. +

    + Maps (or sets) allow mapping (or storing) unique-key values. + The standard library also supplies associative containers which + map (or store) multiple values with equivalent keys: + std::multimap, std::multiset, + std::tr1::unordered_multimap, and + unordered_multiset. We first discuss how these might + be used, then why we think it is best to avoid them. +

    + Suppose one builds a simple bank-account application that + records for each client (identified by an std::string) + and account-id (marked by an unsigned long) - + the balance in the account (described by a + float). Suppose further that ordering this + information is not useful, so a hash-based container is + preferable to a tree based container. Then one can use + 

    +	  std::tr1::unordered_map<std::pair<std::string, unsigned long>, float, ...>
+

    + which hashes every combination of client and account-id. This + might work well, except for the fact that it is now impossible + to efficiently list all of the accounts of a specific client + (this would practically require iterating over all + entries). Instead, one can use + 

    +	  std::tr1::unordered_multimap<std::pair<std::string, unsigned long>, float, ...>
+

    + which hashes every client, and decides equivalence based on + client only. This will ensure that all accounts belonging to a + specific user are stored consecutively. +

    + Also, suppose one wants an integers' priority queue + (a container that supports push, + pop, and top operations, the last of which + returns the largest int) that also supports + operations such as find and lower_bound. A + reasonable solution is to build an adapter over + std::set<int>. In this adapter, + push will just call the tree-based + associative container's insert method; pop + will call its end method, and use it to return the + preceding element (which must be the largest). Then this might + work well, except that the container object cannot hold + multiple instances of the same integer (push(4), + will be a no-op if 4 is already in the + container object). If multiple keys are necessary, then one + might build the adapter over an + std::multiset<int>. +

    + The standard library's non-unique-mapping containers are useful + when (1) a key can be decomposed in to a primary key and a + secondary key, (2) a key is needed multiple times, or (3) any + combination of (1) and (2). +

    + The graphic below shows how the standard library's container + design works internally; in this figure nodes shaded equally + represent equivalent-key values. Equivalent keys are stored + consecutively using the properties of the underlying data + structure: binary search trees (label A) store equivalent-key + values consecutively (in the sense of an in-order walk) + naturally; collision-chaining hash tables (label B) store + equivalent-key values in the same bucket, the bucket can be + arranged so that equivalent-key values are consecutive. +

    Figure 22.8. Non-unique Mapping Standard Containers

    Non-unique Mapping Standard Containers

    + Put differently, the standards' non-unique mapping + associative-containers are associative containers that map + primary keys to linked lists that are embedded into the + container. The graphic below shows again the two + containers from the first graphic above, this time with + the embedded linked lists of the grayed nodes marked + explicitly. +

    Figure 22.9.  + Effect of embedded lists in + std::multimap +

    Effect of embedded lists in std::multimap

    + These embedded linked lists have several disadvantages. +

    1. + The underlying data structure embeds the linked lists + according to its own consideration, which means that the + search path for a value might include several different + equivalent-key values. For example, the search path for the + the black node in either of the first graphic, labels A or B, + includes more than a single gray node. +

    2. + The links of the linked lists are the underlying data + structures' nodes, which typically are quite structured. In + the case of tree-based containers (the grapic above, label + B), each "link" is actually a node with three pointers (one + to a parent and two to children), and a + relatively-complicated iteration algorithm. The linked + lists, therefore, can take up quite a lot of memory, and + iterating over all values equal to a given key (through the + return value of the standard + library's equal_range) can be + expensive. +

    3. + The primary key is stored multiply; this uses more memory. +

    4. + Finally, the interface of this design excludes several + useful underlying data structures. Of all the unordered + self-organizing data structures, practically only + collision-chaining hash tables can (efficiently) guarantee + that equivalent-key values are stored consecutively. +

    + The above reasons hold even when the ratio of secondary keys to + primary keys (or average number of identical keys) is small, but + when it is large, there are more severe problems: +

    1. + The underlying data structures order the links inside each + embedded linked-lists according to their internal + considerations, which effectively means that each of the + links is unordered. Irrespective of the underlying data + structure, searching for a specific value can degrade to + linear complexity. +

    2. + Similarly to the above point, it is impossible to apply + to the secondary keys considerations that apply to primary + keys. For example, it is not possible to maintain secondary + keys by sorted order. +

    3. + While the interface "understands" that all equivalent-key + values constitute a distinct list (through + equal_range), the underlying data + structure typically does not. This means that operations such + as erasing from a tree-based container all values whose keys + are equivalent to a a given key can be super-linear in the + size of the tree; this is also true also for several other + operations that target a specific list. +

    + In this library, all associative containers map + (or store) unique-key values. One can (1) map primary keys to + secondary associative-containers (containers of + secondary keys) or non-associative containers (2) map identical + keys to a size-type representing the number of times they + occur, or (3) any combination of (1) and (2). Instead of + allowing multiple equivalent-key values, this library + supplies associative containers based on underlying + data structures that are suitable as secondary + associative-containers. +

    + In the figure below, labels A and B show the equivalent + underlying data structures in this library, as mapped to the + first graphic above. Labels A and B, respectively. Each shaded + box represents some size-type or secondary + associative-container. +

    Figure 22.10. Non-unique Mapping Containers

    Non-unique Mapping Containers

    + In the first example above, then, one would use an associative + container mapping each user to an associative container which + maps each application id to a start time (see + example/basic_multimap.cc); in the second + example, one would use an associative container mapping + each int to some size-type indicating the + number of times it logically occurs + (see example/basic_multiset.cc. +

    + See the discussion in list-based container types for containers + especially suited as secondary associative-containers. +

    + Iterator concepts are bifurcated in this design, and are + comprised of point-type and range-type iteration. +

    + A point-type iterator is an iterator that refers to a specific + element as returned through an + associative-container's find method. +

    + A range-type iterator is an iterator that is used to go over a + sequence of elements, as returned by a container's + find method. +

    + A point-type method is a method that + returns a point-type iterator; a range-type method is a method + that returns a range-type iterator. +

    For most containers, these types are synonymous; for + self-organizing containers, such as hash-based containers or + priority queues, these are inherently different (in any + implementation, including that of C++ standard library + components), but in this design, it is made explicit. They are + distinct types. +

    When using this library, is necessary to differentiate + between two types of methods and iterators: point-type methods and + iterators, and range-type methods and iterators. Each associative + container's interface includes the methods:

    +	  point_const_iterator
+	  find(const_key_reference r_key) const;
+
+	  point_iterator
+	  find(const_key_reference r_key);
+
+	  std::pair<point_iterator,bool>
+	  insert(const_reference r_val);
+

    The relationship between these iterator types varies between + container types. The figure below + shows the most general invariant between point-type and + range-type iterators: In A iterator, can + always be converted to point_iterator. In B + shows invariants for order-preserving containers: point-type + iterators are synonymous with range-type iterators. + Orthogonally, Cshows invariants for "set" + containers: iterators are synonymous with const iterators.

    Figure 22.11. Point Iterator Hierarchy

    Point Iterator Hierarchy

    Note that point-type iterators in self-organizing containers + (hash-based associative containers) lack movement + operators, such as operator++ - in fact, this + is the reason why this library differentiates from the standard C++ librarys + design on this point.

    Typically, one can determine an iterator's movement + capabilities using + std::iterator_traits<It>iterator_category, + which is a struct indicating the iterator's + movement capabilities. Unfortunately, none of the standard predefined + categories reflect a pointer's not having any + movement capabilities whatsoever. Consequently, + pb_ds adds a type + trivial_iterator_tag (whose name is taken from + a concept in C++ standardese, which is the category of iterators + with no movement capabilities.) All other standard C++ library + tags, such as forward_iterator_tag retain their + common use.

    + If one manipulates a container object, then iterators previously + obtained from it can be invalidated. In some cases a + previously-obtained iterator cannot be de-referenced; in other cases, + the iterator's next or previous element might have changed + unpredictably. This corresponds exactly to the question whether a + point-type or range-type iterator (see previous concept) is valid or + not. In this design, one can query a container (in compile time) about + its invalidation guarantees. +

    + Given three different types of associative containers, a modifying + operation (in that example, erase) invalidated + iterators in three different ways: the iterator of one container + remained completely valid - it could be de-referenced and + incremented; the iterator of a different container could not even be + de-referenced; the iterator of the third container could be + de-referenced, but its "next" iterator changed unpredictably. +

    + Distinguishing between find and range types allows fine-grained + invalidation guarantees, because these questions correspond exactly + to the question of whether point-type iterators and range-type + iterators are valid. The graphic below shows tags corresponding to + different types of invalidation guarantees. +

    Figure 22.12. Invalidation Guarantee Tags Hierarchy

    Invalidation Guarantee Tags Hierarchy

    • + basic_invalidation_guarantee + corresponds to a basic guarantee that a point-type iterator, + a found pointer, or a found reference, remains valid as long + as the container object is not modified. +

    • + point_invalidation_guarantee + corresponds to a guarantee that a point-type iterator, a + found pointer, or a found reference, remains valid even if + the container object is modified. +

    • + range_invalidation_guarantee + corresponds to a guarantee that a range-type iterator remains + valid even if the container object is modified. +

    To find the invalidation guarantee of a + container, one can use

    +	  typename container_traits<Cntnr>::invalidation_guarantee
+

    Note that this hierarchy corresponds to the logic it + represents: if a container has range-invalidation guarantees, + then it must also have find invalidation guarantees; + correspondingly, its invalidation guarantee (in this case + range_invalidation_guarantee) + can be cast to its base class (in this case point_invalidation_guarantee). + This means that this this hierarchy can be used easily using + standard metaprogramming techniques, by specializing on the + type of invalidation_guarantee.

    + These types of problems were addressed, in a more general + setting, in [biblio.meyers96more] - Item 2. In + our opinion, an invalidation-guarantee hierarchy would solve + these problems in all container types - not just associative + containers. +

    + The design attempts to address the following problem of + data-structure genericity. When writing a function manipulating + a generic container object, what is the behavior of the object? + Suppose one writes + 

    +	template<typename Cntnr>
+	void
+	some_op_sequence(Cntnr &r_container)
+	{
+	...
+	}
+

    + then one needs to address the following questions in the body + of some_op_sequence: +

    The remainder of this section explains these issues in + detail.

    + Tags are very useful for manipulating generic types. For example, if + It is an iterator class, then typename + It::iterator_category or typename + std::iterator_traits<It>::iterator_category will + yield its category, and typename + std::iterator_traits<It>::value_type will yield its + value type. +

    + This library contains a container tag hierarchy corresponding to the + diagram below. +

    Figure 22.13. Container Tag Hierarchy

    Container Tag Hierarchy

    + Given any container Cntnr, the tag of + the underlying data structure can be found via typename + Cntnr::container_category. +

    Additionally, a traits mechanism can be used to query a + container type for its attributes. Given any container + Cntnr, then <Cntnr> + is a traits class identifying the properties of the + container.

    To find if a container can throw when a key is erased (which + is true for vector-based trees, for example), one can + use + 

    container_traits<Cntnr>::erase_can_throw

    + Some of the definitions in container_traits + are dependent on other + definitions. If container_traits<Cntnr>::order_preserving + is true (which is the case for containers + based on trees and tries), then the container can be split or + joined; in this + case, container_traits<Cntnr>::split_join_can_throw + indicates whether splits or joins can throw exceptions (which is + true for vector-based trees); + otherwise container_traits<Cntnr>::split_join_can_throw + will yield a compilation error. (This is somewhat similar to a + compile-time version of the COM model). +

    + The collision-chaining hash-based container has the + following declaration.

    +	  template<
+	  typename Key,
+	  typename Mapped,
+	  typename Hash_Fn = std::hash<Key>,
+	  typename Eq_Fn = std::equal_to<Key>,
+	  typename Comb_Hash_Fn =  direct_mask_range_hashing<>
+	  typename Resize_Policy = default explained below.
+	  bool Store_Hash = false,
+	  typename Allocator = std::allocator<char> >
+	  class cc_hash_table;
+

    The parameters have the following meaning:

    1. Key is the key type.

    2. Mapped is the mapped-policy.

    3. Hash_Fn is a key hashing functor.

    4. Eq_Fn is a key equivalence functor.

    5. Comb_Hash_Fn is a range-hashing_functor; + it describes how to translate hash values into positions + within the table.

    6. Resize_Policy describes how a container object + should change its internal size.

    7. Store_Hash indicates whether the hash value + should be stored with each entry.

    8. Allocator is an allocator + type.

    The probing hash-based container has the following + declaration.

    +	  template<
+	  typename Key,
+	  typename Mapped,
+	  typename Hash_Fn = std::hash<Key>,
+	  typename Eq_Fn = std::equal_to<Key>,
+	  typename Comb_Probe_Fn = direct_mask_range_hashing<>
+	  typename Probe_Fn = default explained below.
+	  typename Resize_Policy = default explained below.
+	  bool Store_Hash = false,
+	  typename Allocator =  std::allocator<char> >
+	  class gp_hash_table;
+

    The parameters are identical to those of the + collision-chaining container, except for the following.

    1. Comb_Probe_Fn describes how to transform a probe + sequence into a sequence of positions within the table.

    2. Probe_Fn describes a probe sequence policy.

    Some of the default template values depend on the values of + other parameters, and are explained below.

    Following is an explanation of some functions which hashing + involves. The graphic below illustrates the discussion.

    Figure 22.14. Hash functions, ranged-hash functions, and + range-hashing functions

    Hash functions, ranged-hash functions, and range-hashing functions

    Let U be a domain (e.g., the integers, or the + strings of 3 characters). A hash-table algorithm needs to map + elements of U "uniformly" into the range [0,..., m - + 1] (where m is a non-negative integral value, and + is, in general, time varying). I.e., the algorithm needs + a ranged-hash function

    + f : U × Z+ → Z+ +

    such that for any u in U ,

    0 ≤ f(u, m) ≤ m - 1

    and which has "good uniformity" properties (say + [biblio.knuth98sorting].) + One + common solution is to use the composition of the hash + function

    h : U → Z+ ,

    which maps elements of U into the non-negative + integrals, and

    g : Z+ × Z+ → + Z+,

    which maps a non-negative hash value, and a non-negative + range upper-bound into a non-negative integral in the range + between 0 (inclusive) and the range upper bound (exclusive), + i.e., for any r in Z+,

    0 ≤ g(r, m) ≤ m - 1

    The resulting ranged-hash function, is

    Equation 22.1. Ranged Hash Function

    + f(u , m) = g(h(u), m) +

    From the above, it is obvious that given g and + h, f can always be composed (however the converse + is not true). The standard's hash-based containers allow specifying + a hash function, and use a hard-wired range-hashing function; + the ranged-hash function is implicitly composed.

    The above describes the case where a key is to be mapped + into a single position within a hash table, e.g., + in a collision-chaining table. In other cases, a key is to be + mapped into a sequence of positions within a table, + e.g., in a probing table. Similar terms apply in this + case: the table requires a ranged probe function, + mapping a key into a sequence of positions withing the table. + This is typically achieved by composing a hash function + mapping the key into a non-negative integral type, a + probe function transforming the hash value into a + sequence of hash values, and a range-hashing function + transforming the sequence of hash values into a sequence of + positions.

    Some common choices for range-hashing functions are the + division, multiplication, and middle-square methods ([biblio.knuth98sorting]), defined + as

    Equation 22.2. Range-Hashing, Division Method

    + g(r, m) = r mod m +

    g(r, m) = ⌈ u/v ( a r mod v ) ⌉

    and

    g(r, m) = ⌈ u/v ( r2 mod v ) ⌉

    respectively, for some positive integrals u and + v (typically powers of 2), and some a. Each of + these range-hashing functions works best for some different + setting.

    The division method (see above) is a + very common choice. However, even this single method can be + implemented in two very different ways. It is possible to + implement using the low + level % (modulo) operation (for any m), or the + low level & (bit-mask) operation (for the case where + m is a power of 2), i.e.,

    Equation 22.3. Division via Prime Modulo

    + g(r, m) = r % m +

    and

    Equation 22.4. Division via Bit Mask

    + g(r, m) = r & m - 1, (with m = + 2k for some k) +

    respectively.

    The % (modulo) implementation has the advantage that for + m a prime far from a power of 2, g(r, m) is + affected by all the bits of r (minimizing the chance of + collision). It has the disadvantage of using the costly modulo + operation. This method is hard-wired into SGI's implementation + .

    The & (bit-mask) implementation has the advantage of + relying on the fast bit-wise and operation. It has the + disadvantage that for g(r, m) is affected only by the + low order bits of r. This method is hard-wired into + Dinkumware's implementation.

    In cases it is beneficial to allow the + client to directly specify a ranged-hash hash function. It is + true, that the writer of the ranged-hash function cannot rely + on the values of m having specific numerical properties + suitable for hashing (in the sense used in [biblio.knuth98sorting]), since + the values of m are determined by a resize policy with + possibly orthogonal considerations.

    There are two cases where a ranged-hash function can be + superior. The firs is when using perfect hashing: the + second is when the values of m can be used to estimate + the "general" number of distinct values required. This is + described in the following.

    Let

    + s = [ s0,..., st - 1] +

    be a string of t characters, each of which is from + domain S. Consider the following ranged-hash + function:

    Equation 22.5.  + A Standard String Hash Function +

    + f1(s, m) = ∑ i = + 0t - 1 si ai mod m +

    where a is some non-negative integral value. This is + the standard string-hashing function used in SGI's + implementation (with a = 5). Its advantage is that + it takes into account all of the characters of the string.

    Now assume that s is the string representation of a + of a long DNA sequence (and so S = {'A', 'C', 'G', + 'T'}). In this case, scanning the entire string might be + prohibitively expensive. A possible alternative might be to use + only the first k characters of the string, where

    |S|k ≥ m ,

    i.e., using the hash function

    Equation 22.6.  + Only k String DNA Hash +

    + f2(s, m) = ∑ i + = 0k - 1 si ai mod m +

    requiring scanning over only

    k = log4( m )

    characters.

    Other more elaborate hash-functions might scan k + characters starting at a random position (determined at each + resize), or scanning k random positions (determined at + each resize), i.e., using

    f3(s, m) = ∑ i = + r0r0 + k - 1 si + ai mod m ,

    or

    f4(s, m) = ∑ i = 0k - + 1 sri ari mod + m ,

    respectively, for r0,..., rk-1 + each in the (inclusive) range [0,...,t-1].

    It should be noted that the above functions cannot be + decomposed as per a ranged hash composed of hash and range hashing.

    This sub-subsection describes the implementation of + the above in this library. It first explains range-hashing + functions in collision-chaining tables, then ranged-hash + functions in collision-chaining tables, then probing-based + tables, and finally lists the relevant classes in this + library.

    cc_hash_table is + parametrized by Hash_Fn and Comb_Hash_Fn, a + hash functor and a combining hash functor, respectively.

    In general, Comb_Hash_Fn is considered a + range-hashing functor. cc_hash_table + synthesizes a ranged-hash function from Hash_Fn and + Comb_Hash_Fn. The figure below shows an insert sequence + diagram for this case. The user inserts an element (point A), + the container transforms the key into a non-negative integral + using the hash functor (points B and C), and transforms the + result into a position using the combining functor (points D + and E).

    Figure 22.15. Insert hash sequence diagram

    Insert hash sequence diagram

    If cc_hash_table's + hash-functor, Hash_Fn is instantiated by null_type , then Comb_Hash_Fn is taken to be + a ranged-hash function. The graphic below shows an insert sequence + diagram. The user inserts an element (point A), the container + transforms the key into a position using the combining functor + (points B and C).

    Figure 22.16. Insert hash sequence diagram with a null policy

    Insert hash sequence diagram with a null policy

    gp_hash_table is parametrized by + Hash_Fn, Probe_Fn, + and Comb_Probe_Fn. As before, if + Hash_Fn and Probe_Fn + are both null_type, then + Comb_Probe_Fn is a ranged-probe + functor. Otherwise, Hash_Fn is a hash + functor, Probe_Fn is a functor for offsets + from a hash value, and Comb_Probe_Fn + transforms a probe sequence into a sequence of positions within + the table.

    This library contains some pre-defined classes + implementing range-hashing and probing functions:

    1. direct_mask_range_hashing + and direct_mod_range_hashing + are range-hashing functions based on a bit-mask and a modulo + operation, respectively.

    2. linear_probe_fn, and + quadratic_probe_fn are + a linear probe and a quadratic probe function, + respectively.

    + The graphic below shows the relationships. +

    Figure 22.17. Hash policy class diagram

    Hash policy class diagram

    Hash-tables, as opposed to trees, do not naturally grow or + shrink. It is necessary to specify policies to determine how + and when a hash table should change its size. Usually, resize + policies can be decomposed into orthogonal policies:

    1. A size policy indicating how a hash table + should grow (e.g., it should multiply by powers of + 2).

    2. A trigger policy indicating when a hash + table should grow (e.g., a load factor is + exceeded).

    Size policies determine how a hash table changes size. These + policies are simple, and there are relatively few sensible + options. An exponential-size policy (with the initial size and + growth factors both powers of 2) works well with a mask-based + range-hashing function, and is the + hard-wired policy used by Dinkumware. A + prime-list based policy works well with a modulo-prime range + hashing function and is the hard-wired policy used by SGI's + implementation.

    Trigger policies determine when a hash table changes size. + Following is a description of two policies: load-check + policies, and collision-check policies.

    Load-check policies are straightforward. The user specifies + two factors, Αmin and + Αmax, and the hash table maintains the + invariant that

    Αmin ≤ (number of + stored elements) / (hash-table size) ≤ + Αmaxload factor min max

    Collision-check policies work in the opposite direction of + load-check policies. They focus on keeping the number of + collisions moderate and hoping that the size of the table will + not grow very large, instead of keeping a moderate load-factor + and hoping that the number of collisions will be small. A + maximal collision-check policy resizes when the longest + probe-sequence grows too large.

    Consider the graphic below. Let the size of the hash table + be denoted by m, the length of a probe sequence be denoted by k, + and some load factor be denoted by Α. We would like to + calculate the minimal length of k, such that if there were Α + m elements in the hash table, a probe sequence of length k would + be found with probability at most 1/m.

    Figure 22.18. Balls and bins

    Balls and bins

    Denote the probability that a probe sequence of length + k appears in bin i by pi, the + length of the probe sequence of bin i by + li, and assume uniform distribution. Then

    Equation 22.7.  + Probability of Probe Sequence of Length k +

    + p1 = +

    P(l1 ≥ k) =

    + P(l1 ≥ α ( 1 + k / α - 1) ≤ (a) +

    + e ^ ( - ( α ( k / α - 1 )2 ) /2) +

    where (a) follows from the Chernoff bound ([biblio.motwani95random]). To + calculate the probability that some bin contains a probe + sequence greater than k, we note that the + li are negatively-dependent + ([biblio.dubhashi98neg]) + . Let + I(.) denote the indicator function. Then

    Equation 22.8.  + Probability Probe Sequence in Some Bin +

    + P( existsi li ≥ k ) = +

    P ( ∑ i = 1m + I(li ≥ k) ≥ 1 ) =

    P ( ∑ i = 1m I ( + li ≥ k ) ≥ m p1 ( 1 + 1 / (m + p1) - 1 ) ) ≤ (a)

    e ^ ( ( - m p1 ( 1 / (m p1) + - 1 ) 2 ) / 2 ) ,

    where (a) follows from the fact that the Chernoff bound can + be applied to negatively-dependent variables ([biblio.dubhashi98neg]). Inserting the first probability + equation into the second one, and equating with 1/m, we + obtain

    k ~ √ ( 2 α ln 2 m ln(m) ) + ) .

    This sub-subsection describes the implementation of the + above in this library. It first describes resize policies and + their decomposition into trigger and size policies, then + describes pre-defined classes, and finally discusses controlled + access the policies' internals.

    Each hash-based container is parametrized by a + Resize_Policy parameter; the container derives + publicly from Resize_Policy. For + example:

    +		cc_hash_table<typename Key,
+		typename Mapped,
+		...
+		typename Resize_Policy
+		...> : public Resize_Policy
+

    As a container object is modified, it continuously notifies + its Resize_Policy base of internal changes + (e.g., collisions encountered and elements being + inserted). It queries its Resize_Policy base whether + it needs to be resized, and if so, to what size.

    The graphic below shows a (possible) sequence diagram + of an insert operation. The user inserts an element; the hash + table notifies its resize policy that a search has started + (point A); in this case, a single collision is encountered - + the table notifies its resize policy of this (point B); the + container finally notifies its resize policy that the search + has ended (point C); it then queries its resize policy whether + a resize is needed, and if so, what is the new size (points D + to G); following the resize, it notifies the policy that a + resize has completed (point H); finally, the element is + inserted, and the policy notified (point I).

    Figure 22.19. Insert resize sequence diagram

    Insert resize sequence diagram

    In practice, a resize policy can be usually orthogonally + decomposed to a size policy and a trigger policy. Consequently, + the library contains a single class for instantiating a resize + policy: hash_standard_resize_policy + is parametrized by Size_Policy and + Trigger_Policy, derives publicly from + both, and acts as a standard delegate ([biblio.gof]) + to these policies.

    The two graphics immediately below show sequence diagrams + illustrating the interaction between the standard resize policy + and its trigger and size policies, respectively.

    Figure 22.20. Standard resize policy trigger sequence + diagram

    Standard resize policy trigger sequence diagram

    Figure 22.21. Standard resize policy size sequence + diagram

    Standard resize policy size sequence diagram

    The library includes the following + instantiations of size and trigger policies:

    1. hash_load_check_resize_trigger + implements a load check trigger policy.

    2. cc_hash_max_collision_check_resize_trigger + implements a collision check trigger policy.

    3. hash_exponential_size_policy + implements an exponential-size policy (which should be used + with mask range hashing).

    4. hash_prime_size_policy + implementing a size policy based on a sequence of primes + (which should + be used with mod range hashing

    The graphic below gives an overall picture of the resize-related + classes. basic_hash_table + is parametrized by Resize_Policy, which it subclasses + publicly. This class is currently instantiated only by hash_standard_resize_policy. + hash_standard_resize_policy + itself is parametrized by Trigger_Policy and + Size_Policy. Currently, Trigger_Policy is + instantiated by hash_load_check_resize_trigger, + or cc_hash_max_collision_check_resize_trigger; + Size_Policy is instantiated by hash_exponential_size_policy, + or hash_prime_size_policy.

    There are cases where (controlled) access to resize + policies' internals is beneficial. E.g., it is sometimes + useful to query a hash-table for the table's actual size (as + opposed to its size() - the number of values it + currently holds); it is sometimes useful to set a table's + initial size, externally resize it, or change load factors.

    Clearly, supporting such methods both decreases the + encapsulation of hash-based containers, and increases the + diversity between different associative-containers' interfaces. + Conversely, omitting such methods can decrease containers' + flexibility.

    In order to avoid, to the extent possible, the above + conflict, the hash-based containers themselves do not address + any of these questions; this is deferred to the resize policies, + which are easier to change or replace. Thus, for example, + neither cc_hash_table nor + gp_hash_table + contain methods for querying the actual size of the table; this + is deferred to hash_standard_resize_policy.

    Furthermore, the policies themselves are parametrized by + template arguments that determine the methods they support + ( + [biblio.alexandrescu01modern] + shows techniques for doing so). hash_standard_resize_policy + is parametrized by External_Size_Access that + determines whether it supports methods for querying the actual + size of the table or resizing it. hash_load_check_resize_trigger + is parametrized by External_Load_Access that + determines whether it supports methods for querying or + modifying the loads. cc_hash_max_collision_check_resize_trigger + is parametrized by External_Load_Access that + determines whether it supports methods for querying the + load.

    Some operations, for example, resizing a container at + run time, or changing the load factors of a load-check trigger + policy, require the container itself to resize. As mentioned + above, the hash-based containers themselves do not contain + these types of methods, only their resize policies. + Consequently, there must be some mechanism for a resize policy + to manipulate the hash-based container. As the hash-based + container is a subclass of the resize policy, this is done + through virtual methods. Each hash-based container has a + private virtual method:

    +		virtual void
+		do_resize
+		(size_type new_size);
+

    which resizes the container. Implementations of + Resize_Policy can export public methods for resizing + the container externally; these methods internally call + do_resize to resize the table.

    +

    Hash-tables are unfortunately especially susceptible to + choice of policies. One of the more complicated aspects of this + is that poor combinations of good policies can form a poor + container. Following are some considerations.

    Some combinations do not work well for probing containers. + For example, combining a quadratic probe policy with an + exponential size policy can yield a poor container: when an + element is inserted, a trigger policy might decide that there + is no need to resize, as the table still contains unused + entries; the probe sequence, however, might never reach any of + the unused entries.

    Unfortunately, this library cannot detect such problems at + compilation (they are halting reducible). It therefore defines + an exception class insert_error to throw an + exception in this case.

    Some trigger policies are especially susceptible to poor + hash functions. Suppose, as an extreme case, that the hash + function transforms each key to the same hash value. After some + inserts, a collision detecting policy will always indicate that + the container needs to grow.

    The library, therefore, by design, limits each operation to + one resize. For each insert, for example, it queries + only once whether a resize is needed.

    cc_hash_table and + gp_hash_table are + parametrized by an equivalence functor and by a + Store_Hash parameter. If the latter parameter is + true, then the container stores with each entry + a hash value, and uses this value in case of collisions to + determine whether to apply a hash value. This can lower the + cost of collision for some types, but increase the cost of + collisions for other types.

    If a ranged-hash function or ranged probe function is + directly supplied, however, then it makes no sense to store the + hash value with each entry. This library's container will + fail at compilation, by design, if this is attempted.

    Assume a size policy issues an increasing sequence of sizes + a, a q, a q1, a q2, ... For + example, an exponential size policy might issue the sequence of + sizes 8, 16, 32, 64, ...

    If a load-check trigger policy is used, with loads + αmin and αmax, + respectively, then it is a good idea to have:

    1. αmax ~ 1 / q

    2. αmin < 1 / (2 q)

    This will ensure that the amortized hash cost of each + modifying operation is at most approximately 3.

    αmin ~ αmax is, in + any case, a bad choice, and αmin > + α max is horrendous.

    The tree-based container has the following declaration:

    +	  template<
+	  typename Key,
+	  typename Mapped,
+	  typename Cmp_Fn = std::less<Key>,
+	  typename Tag = rb_tree_tag,
+	  template<
+	  typename Const_Node_Iterator,
+	  typename Node_Iterator,
+	  typename Cmp_Fn_,
+	  typename Allocator_>
+	  class Node_Update = null_node_update,
+	  typename Allocator = std::allocator<char> >
+	  class tree;
+

    The parameters have the following meaning:

    1. Key is the key type.

    2. Mapped is the mapped-policy.

    3. Cmp_Fn is a key comparison functor

    4. Tag specifies which underlying data structure + to use.

    5. Node_Update is a policy for updating node + invariants.

    6. Allocator is an allocator + type.

    The Tag parameter specifies which underlying + data structure to use. Instantiating it by rb_tree_tag, splay_tree_tag, or + ov_tree_tag, + specifies an underlying red-black tree, splay tree, or + ordered-vector tree, respectively; any other tag is illegal. + Note that containers based on the former two contain more types + and methods than the latter (e.g., + reverse_iterator and rbegin), and different + exception and invalidation guarantees.

    Consider the two trees in the graphic below, labels A and B. The first + is a tree of floats; the second is a tree of pairs, each + signifying a geometric line interval. Each element in a tree is refered to as a node of the tree. Of course, each of + these trees can support the usual queries: the first can easily + search for 0.4; the second can easily search for + std::make_pair(10, 41).

    Each of these trees can efficiently support other queries. + The first can efficiently determine that the 2rd key in the + tree is 0.3; the second can efficiently determine + whether any of its intervals overlaps + 

    std::make_pair(29,42)

    (useful in geometric + applications or distributed file systems with leases, for + example). It should be noted that an std::set can + only solve these types of problems with linear complexity.

    In order to do so, each tree stores some metadata in + each node, and maintains node invariants (see [biblio.clrs2001].) The first stores in + each node the size of the sub-tree rooted at the node; the + second stores at each node the maximal endpoint of the + intervals at the sub-tree rooted at the node.

    Figure 22.22. Tree node invariants

    Tree node invariants

    Supporting such trees is difficult for a number of + reasons:

    1. There must be a way to specify what a node's metadata + should be (if any).

    2. Various operations can invalidate node + invariants. The graphic below shows how a right rotation, + performed on A, results in B, with nodes x and y having + corrupted invariants (the grayed nodes in C). The graphic shows + how an insert, performed on D, results in E, with nodes x and y + having corrupted invariants (the grayed nodes in F). It is not + feasible to know outside the tree the effect of an operation on + the nodes of the tree.

    3. The search paths of standard associative containers are + defined by comparisons between keys, and not through + metadata.

    4. It is not feasible to know in advance which methods trees + can support. Besides the usual find method, the + first tree can support a find_by_order method, while + the second can support an overlaps method.

    Figure 22.23. Tree node invalidation

    Tree node invalidation

    These problems are solved by a combination of two means: + node iterators, and template-template node updater + parameters.

    Each tree-based container defines two additional iterator + types, const_node_iterator + and node_iterator. + These iterators allow descending from a node to one of its + children. Node iterator allow search paths different than those + determined by the comparison functor. The tree + supports the methods:

    +	      const_node_iterator
+	      node_begin() const;
+
+	      node_iterator
+	      node_begin();
+
+	      const_node_iterator
+	      node_end() const;
+
+	      node_iterator
+	      node_end(); 
+

    The first pairs return node iterators corresponding to the + root node of the tree; the latter pair returns node iterators + corresponding to a just-after-leaf node.

    The tree-based containers are parametrized by a + Node_Update template-template parameter. A + tree-based container instantiates + Node_Update to some + node_update class, and publicly subclasses + node_update. The graphic below shows this + scheme, as well as some predefined policies (which are explained + below).

    Figure 22.24. A tree and its update policy

    A tree and its update policy

    node_update (an instantiation of + Node_Update) must define metadata_type as + the type of metadata it requires. For order statistics, + e.g., metadata_type might be size_t. + The tree defines within each node a metadata_type + object.

    node_update must also define the following method + for restoring node invariants:

    +	      void 
+	      operator()(node_iterator nd_it, const_node_iterator end_nd_it)
+

    In this method, nd_it is a + node_iterator corresponding to a node whose + A) all descendants have valid invariants, and B) its own + invariants might be violated; end_nd_it is + a const_node_iterator corresponding to a + just-after-leaf node. This method should correct the node + invariants of the node pointed to by + nd_it. For example, say node x in the + graphic below label A has an invalid invariant, but its' children, + y and z have valid invariants. After the invocation, all three + nodes should have valid invariants, as in label B.

    Figure 22.25. Restoring node invariants

    Restoring node invariants

    When a tree operation might invalidate some node invariant, + it invokes this method in its node_update base to + restore the invariant. For example, the graphic below shows + an insert operation (point A); the tree performs some + operations, and calls the update functor three times (points B, + C, and D). (It is well known that any insert, + erase, split or join, can restore + all node invariants by a small number of node invariant updates ([biblio.clrs2001]) + .

    Figure 22.26. Insert update sequence

    Insert update sequence

    To complete the description of the scheme, three questions + need to be answered:

    1. How can a tree which supports order statistics define a + method such as find_by_order?

    2. How can the node updater base access methods of the + tree?

    3. How can the following cyclic dependency be resolved? + node_update is a base class of the tree, yet it + uses node iterators defined in the tree (its child).

    The first two questions are answered by the fact that + node_update (an instantiation of + Node_Update) is a public base class + of the tree. Consequently:

    1. Any public methods of + node_update are automatically methods of + the tree ([biblio.alexandrescu01modern]). + Thus an order-statistics node updater, + tree_order_statistics_node_update defines + the find_by_order method; any tree + instantiated by this policy consequently supports this method as + well.

    2. In C++, if a base class declares a method as + virtual, it is + virtual in its subclasses. If + node_update needs to access one of the + tree's methods, say the member function + end, it simply declares that method as + virtual abstract.

    The cyclic dependency is solved through template-template + parameters. Node_Update is parametrized by + the tree's node iterators, its comparison functor, and its + allocator type. Thus, instantiations of + Node_Update have all information + required.

    This library assumes that constructing a metadata object and + modifying it are exception free. Suppose that during some method, + say insert, a metadata-related operation + (e.g., changing the value of a metadata) throws an exception. Ack! + Rolling back the method is unusually complex.

    Previously, a distinction was made between redundant + policies and null policies. Node invariants show a + case where null policies are required.

    Assume a regular tree is required, one which need not + support order statistics or interval overlap queries. + Seemingly, in this case a redundant policy - a policy which + doesn't affect nodes' contents would suffice. This, would lead + to the following drawbacks:

    1. Each node would carry a useless metadata object, wasting + space.

    2. The tree cannot know if its + Node_Update policy actually modifies a + node's metadata (this is halting reducible). In the graphic + below, assume the shaded node is inserted. The tree would have + to traverse the useless path shown to the root, applying + redundant updates all the way.

    Figure 22.27. Useless update path

    Useless update path

    A null policy class, null_node_update + solves both these problems. The tree detects that node + invariants are irrelevant, and defines all accordingly.

    Tree-based containers support split and join methods. + It is possible to split a tree so that it passes + all nodes with keys larger than a given key to a different + tree. These methods have the following advantages over the + alternative of externally inserting to the destination + tree and erasing from the source tree:

    1. These methods are efficient - red-black trees are split + and joined in poly-logarithmic complexity; ordered-vector + trees are split and joined at linear complexity. The + alternatives have super-linear complexity.

    2. Aside from orders of growth, these operations perform + few allocations and de-allocations. For red-black trees, allocations are not performed, + and the methods are exception-free.

    The trie-based container has the following declaration:

    +	  template<typename Key,
+	  typename Mapped,
+	  typename Cmp_Fn = std::less<Key>,
+	  typename Tag = pat_trie_tag,
+	  template<typename Const_Node_Iterator,
+	  typename Node_Iterator,
+	  typename E_Access_Traits_,
+	  typename Allocator_>
+	  class Node_Update = null_node_update,
+	  typename Allocator = std::allocator<char> >
+	  class trie;
+

    The parameters have the following meaning:

    1. Key is the key type.

    2. Mapped is the mapped-policy.

    3. E_Access_Traits is described in below.

    4. Tag specifies which underlying data structure + to use, and is described shortly.

    5. Node_Update is a policy for updating node + invariants. This is described below.

    6. Allocator is an allocator + type.

    The Tag parameter specifies which underlying + data structure to use. Instantiating it by pat_trie_tag, specifies an + underlying PATRICIA trie (explained shortly); any other tag is + currently illegal.

    Following is a description of a (PATRICIA) trie + (this implementation follows [biblio.okasaki98mereable] and + [biblio.filliatre2000ptset]). +

    A (PATRICIA) trie is similar to a tree, but with the + following differences:

    1. It explicitly views keys as a sequence of elements. + E.g., a trie can view a string as a sequence of + characters; a trie can view a number as a sequence of + bits.

    2. It is not (necessarily) binary. Each node has fan-out n + + 1, where n is the number of distinct + elements.

    3. It stores values only at leaf nodes.

    4. Internal nodes have the properties that A) each has at + least two children, and B) each shares the same prefix with + any of its descendant.

    A (PATRICIA) trie has some useful properties:

    1. It can be configured to use large node fan-out, giving it + very efficient find performance (albeit at insertion + complexity and size).

    2. It works well for common-prefix keys.

    3. It can support efficiently queries such as which + keys match a certain prefix. This is sometimes useful in file + systems and routers, and for "type-ahead" aka predictive text matching + on mobile devices.

    A trie inherently views its keys as sequences of elements. + For example, a trie can view a string as a sequence of + characters. A trie needs to map each of n elements to a + number in {0, n - 1}. For example, a trie can map a + character c to + 

    static_cast<size_t>(c)

    .

    Seemingly, then, a trie can assume that its keys support + (const) iterators, and that the value_type of this + iterator can be cast to a size_t. There are several + reasons, though, to decouple the mechanism by which the trie + accesses its keys' elements from the trie:

    1. In some cases, the numerical value of an element is + inappropriate. Consider a trie storing DNA strings. It is + logical to use a trie with a fan-out of 5 = 1 + |{'A', 'C', + 'G', 'T'}|. This requires mapping 'T' to 3, though.

    2. In some cases the keys' iterators are different than what + is needed. For example, a trie can be used to search for + common suffixes, by using strings' + reverse_iterator. As another example, a trie mapping + UNICODE strings would have a huge fan-out if each node would + branch on a UNICODE character; instead, one can define an + iterator iterating over 8-bit (or less) groups.

    trie is, + consequently, parametrized by E_Access_Traits - + traits which instruct how to access sequences' elements. + string_trie_e_access_traits + is a traits class for strings. Each such traits define some + types, like:

    +	    typename E_Access_Traits::const_iterator
+

    is a const iterator iterating over a key's elements. The + traits class must also define methods for obtaining an iterator + to the first and last element of a key.

    The graphic below shows a + (PATRICIA) trie resulting from inserting the words: "I wish + that I could ever see a poem lovely as a trie" (which, + unfortunately, does not rhyme).

    The leaf nodes contain values; each internal node contains + two typename E_Access_Traits::const_iterator + objects, indicating the maximal common prefix of all keys in + the sub-tree. For example, the shaded internal node roots a + sub-tree with leafs "a" and "as". The maximal common prefix is + "a". The internal node contains, consequently, to const + iterators, one pointing to 'a', and the other to + 's'.

    Figure 22.28. A PATRICIA trie

    A PATRICIA trie

    Trie-based containers support node invariants, as do + tree-based containers. There are two minor + differences, though, which, unfortunately, thwart sharing them + sharing the same node-updating policies:

    1. A trie's Node_Update template-template + parameter is parametrized by E_Access_Traits, while + a tree's Node_Update template-template parameter is + parametrized by Cmp_Fn.

    2. Tree-based containers store values in all nodes, while + trie-based containers (at least in this implementation) store + values in leafs.

    The graphic below shows the scheme, as well as some predefined + policies (which are explained below).

    Figure 22.29. A trie and its update policy

    A trie and its update policy

    This library offers the following pre-defined trie node + updating policies:

    1. + trie_order_statistics_node_update + supports order statistics. +

    2. trie_prefix_search_node_update + supports searching for ranges that match a given prefix.

    3. null_node_update + is the null node updater.

    Trie-based containers support split and join methods; the + rationale is equal to that of tree-based containers supporting + these methods.

    The list-based container has the following declaration:

    +	  template<typename Key,
+	  typename Mapped,
+	  typename Eq_Fn = std::equal_to<Key>,
+	  typename Update_Policy = move_to_front_lu_policy<>,
+	  typename Allocator = std::allocator<char> >
+	  class list_update;
+

    The parameters have the following meaning:

    1. + Key is the key type. +

    2. + Mapped is the mapped-policy. +

    3. + Eq_Fn is a key equivalence functor. +

    4. + Update_Policy is a policy updating positions in + the list based on access patterns. It is described in the + following subsection. +

    5. + Allocator is an allocator type. +

    A list-based associative container is a container that + stores elements in a linked-list. It does not order the elements + by any particular order related to the keys. List-based + containers are primarily useful for creating "multimaps". In fact, + list-based containers are designed in this library expressly for + this purpose.

    List-based containers might also be useful for some rare + cases, where a key is encapsulated to the extent that only + key-equivalence can be tested. Hash-based containers need to know + how to transform a key into a size type, and tree-based containers + need to know if some key is larger than another. List-based + associative containers, conversely, only need to know if two keys + are equivalent.

    Since a list-based associative container does not order + elements by keys, is it possible to order the list in some + useful manner? Remarkably, many on-line competitive + algorithms exist for reordering lists to reflect access + prediction. (See [biblio.motwani95random] and [biblio.andrew04mtf]). +

    +

    The graphic below shows a + simple list of integer keys. If we search for the integer 6, we + are paying an overhead: the link with key 6 is only the fifth + link; if it were the first link, it could be accessed + faster.

    Figure 22.30. A simple list

    A simple list

    List-update algorithms reorder lists as elements are + accessed. They try to determine, by the access history, which + keys to move to the front of the list. Some of these algorithms + require adding some metadata alongside each entry.

    For example, in the graphic below label A shows the counter + algorithm. Each node contains both a key and a count metadata + (shown in bold). When an element is accessed (e.g. 6) its count is + incremented, as shown in label B. If the count reaches some + predetermined value, say 10, as shown in label C, the count is set + to 0 and the node is moved to the front of the list, as in label + D. +

    Figure 22.31. The counter algorithm

    The counter algorithm

    this library allows instantiating lists with policies + implementing any algorithm moving nodes to the front of the + list (policies implementing algorithms interchanging nodes are + unsupported).

    Associative containers based on lists are parametrized by a + Update_Policy parameter. This parameter defines the + type of metadata each node contains, how to create the + metadata, and how to decide, using this metadata, whether to + move a node to the front of the list. A list-based associative + container object derives (publicly) from its update policy. +

    An instantiation of Update_Policy must define + internally update_metadata as the metadata it + requires. Internally, each node of the list contains, besides + the usual key and data, an instance of typename + Update_Policy::update_metadata.

    An instantiation of Update_Policy must define + internally two operators:

    +	    update_metadata
+	    operator()();
+
+	    bool
+	    operator()(update_metadata &);
+

    The first is called by the container object, when creating a + new node, to create the node's metadata. The second is called + by the container object, when a node is accessed ( + when a find operation's key is equivalent to the key of the + node), to determine whether to move the node to the front of + the list. +

    The library contains two predefined implementations of + list-update policies. The first + is lu_counter_policy, which implements the + counter algorithm described above. The second is + lu_move_to_front_policy, + which unconditionally move an accessed element to the front of + the list. The latter type is very useful in this library, + since there is no need to associate metadata with each element. + (See [biblio.andrew04mtf] +

    In this library, there are no equivalents for the standard's + multimaps and multisets; instead one uses an associative + container mapping primary keys to secondary keys.

    List-based containers are especially useful as associative + containers for secondary keys. In fact, they are implemented + here expressly for this purpose.

    To begin with, these containers use very little per-entry + structure memory overhead, since they can be implemented as + singly-linked lists. (Arrays use even lower per-entry memory + overhead, but they are less flexible in moving around entries, + and have weaker invalidation guarantees).

    More importantly, though, list-based containers use very + little per-container memory overhead. The memory overhead of an + empty list-based container is practically that of a pointer. + This is important for when they are used as secondary + associative-containers in situations where the average ratio of + secondary keys to primary keys is low (or even 1).

    In order to reduce the per-container memory overhead as much + as possible, they are implemented as closely as possible to + singly-linked lists.

    1. + List-based containers do not store internally the number + of values that they hold. This means that their size + method has linear complexity (just like std::list). + Note that finding the number of equivalent-key values in a + standard multimap also has linear complexity (because it must be + done, via std::distance of the + multimap's equal_range method), but usually with + higher constants. +

    2. + Most associative-container objects each hold a policy + object (a hash-based container object holds a + hash functor). List-based containers, conversely, only have + class-wide policy objects. +

    The priority queue container has the following + declaration: + 

    +	  template<typename  Value_Type,
+	  typename  Cmp_Fn = std::less<Value_Type>,
+	  typename  Tag = pairing_heap_tag,
+	  typename  Allocator = std::allocator<char > >
+	  class priority_queue;
+

    The parameters have the following meaning:

    1. Value_Type is the value type.

    2. Cmp_Fn is a value comparison functor

    3. Tag specifies which underlying data structure + to use.

    4. Allocator is an allocator + type.

    The Tag parameter specifies which underlying + data structure to use. Instantiating it bypairing_heap_tag,binary_heap_tag, + binomial_heap_tag, + rc_binomial_heap_tag, + or thin_heap_tag, + specifies, respectively, + an underlying pairing heap ([biblio.fredman86pairing]), + binary heap ([biblio.clrs2001]), + binomial heap ([biblio.clrs2001]), + a binomial heap with a redundant binary counter ([biblio.maverik_lowerbounds]), + or a thin heap ([biblio.kt99fat_heaps]). +

    + As mentioned in the tutorial, + __gnu_pbds::priority_queue shares most of the + same interface with std::priority_queue. + E.g. if q is a priority queue of type + Q, then q.top() will + return the "largest" value in the container (according to + typename + Q::cmp_fn). __gnu_pbds::priority_queue + has a larger (and very slightly different) interface than + std::priority_queue, however, since typically + push and pop are deemed + insufficient for manipulating priority-queues.

    Different settings require different priority-queue + implementations which are described in later; see traits + discusses ways to differentiate between the different traits of + different implementations.

    There are many different underlying-data structures for + implementing priority queues. Unfortunately, most such + structures are oriented towards making push and + top efficient, and consequently don't allow efficient + access of other elements: for instance, they cannot support an efficient + find method. In the use case where it + is important to both access and "do something with" an + arbitrary value, one would be out of luck. For example, many graph algorithms require + modifying a value (typically increasing it in the sense of the + priority queue's comparison functor).

    In order to access and manipulate an arbitrary value in a + priority queue, one needs to reference the internals of the + priority queue from some form of an associative container - + this is unavoidable. Of course, in order to maintain the + encapsulation of the priority queue, this needs to be done in a + way that minimizes exposure to implementation internals.

    In this library the priority queue's insert + method returns an iterator, which if valid can be used for subsequent modify and + erase operations. This both preserves the priority + queue's encapsulation, and allows accessing arbitrary values (since the + returned iterators from the push operation can be + stored in some form of associative container).

    Priority queues' iterators present a problem regarding their + invalidation guarantees. One assumes that calling + operator++ on an iterator will associate it + with the "next" value. Priority-queues are + self-organizing: each operation changes what the "next" value + means. Consequently, it does not make sense that push + will return an iterator that can be incremented - this can have + no possible use. Also, as in the case of hash-based containers, + it is awkward to define if a subsequent push operation + invalidates a prior returned iterator: it invalidates it in the + sense that its "next" value is not related to what it + previously considered to be its "next" value. However, it might not + invalidate it, in the sense that it can be + de-referenced and used for modify and erase + operations.

    Similarly to the case of the other unordered associative + containers, this library uses a distinction between + point-type and range type iterators. A priority queue's iterator can always be + converted to a point_iterator, and a + const_iterator can always be converted to a + point_const_iterator.

    The following snippet demonstrates manipulating an arbitrary + value:

    +	    // A priority queue of integers.
+	    priority_queue<int > p;
+
+	    // Insert some values into the priority queue.
+	    priority_queue<int >::point_iterator it = p.push(0);
+
+	    p.push(1);
+	    p.push(2);
+
+	    // Now modify a value.
+	    p.modify(it, 3);
+
+	    assert(p.top() == 3);
+

    It should be noted that an alternative design could embed an + associative container in a priority queue. Could, but most + probably should not. To begin with, it should be noted that one + could always encapsulate a priority queue and an associative + container mapping values to priority queue iterators with no + performance loss. One cannot, however, "un-encapsulate" a priority + queue embedding an associative container, which might lead to + performance loss. Assume, that one needs to associate each value + with some data unrelated to priority queues. Then using + this library's design, one could use an + associative container mapping each value to a pair consisting of + this data and a priority queue's iterator. Using the embedded + method would need to use two associative containers. Similar + problems might arise in cases where a value can reside + simultaneously in many priority queues.

    There are three main implementations of priority queues: the + first employs a binary heap, typically one which uses a + sequence; the second uses a tree (or forest of trees), which is + typically less structured than an associative container's tree; + the third simply uses an associative container. These are + shown in the graphic below, in labels A1 and A2, label B, and label C.

    Figure 22.32. Underlying Priority-Queue Data-Structures.

    Underlying Priority-Queue Data-Structures.

    Roughly speaking, any value that is both pushed and popped + from a priority queue must incur a logarithmic expense (in the + amortized sense). Any priority queue implementation that would + avoid this, would violate known bounds on comparison-based + sorting (see [biblio.clrs2001] and [biblio.brodal96priority]). +

    Most implementations do + not differ in the asymptotic amortized complexity of + push and pop operations, but they differ in + the constants involved, in the complexity of other operations + (e.g., modify), and in the worst-case + complexity of single operations. In general, the more + "structured" an implementation (i.e., the more internal + invariants it possesses) - the higher its amortized complexity + of push and pop operations.

    This library implements different algorithms using a + single class: priority_queue. + Instantiating the Tag template parameter, "selects" + the implementation:

    1. + Instantiating Tag = binary_heap_tag creates + a binary heap of the form in represented in the graphic with labels A1 or A2. The former is internally + selected by priority_queue + if Value_Type is instantiated by a primitive type + (e.g., an int); the latter is + internally selected for all other types (e.g., + std::string). This implementations is relatively + unstructured, and so has good push and pop + performance; it is the "best-in-kind" for primitive + types, e.g., ints. Conversely, it has + high worst-case performance, and can support only linear-time + modify and erase operations.

    2. Instantiating Tag = + pairing_heap_tag creates a pairing heap of the form + in represented by label B in the graphic above. This + implementations too is relatively unstructured, and so has good + push and pop + performance; it is the "best-in-kind" for non-primitive types, + e.g., std:strings. It also has very good + worst-case push and + join performance (O(1)), but has high + worst-case pop + complexity.

    3. Instantiating Tag = + binomial_heap_tag creates a binomial heap of the + form repsented by label B in the graphic above. This + implementations is more structured than a pairing heap, and so + has worse push and pop + performance. Conversely, it has sub-linear worst-case bounds for + pop, e.g., and so it might be preferred in + cases where responsiveness is important.

    4. Instantiating Tag = + rc_binomial_heap_tag creates a binomial heap of the + form represented in label B above, accompanied by a redundant + counter which governs the trees. This implementations is + therefore more structured than a binomial heap, and so has worse + push and pop + performance. Conversely, it guarantees O(1) + push complexity, and so it might be + preferred in cases where the responsiveness of a binomial heap + is insufficient.

    5. Instantiating Tag = + thin_heap_tag creates a thin heap of the form + represented by the label B in the graphic above. This + implementations too is more structured than a pairing heap, and + so has worse push and + pop performance. Conversely, it has better + worst-case and identical amortized complexities than a Fibonacci + heap, and so might be more appropriate for some graph + algorithms.

    Of course, one can use any order-preserving associative + container as a priority queue, as in the graphic above label C, possibly by creating an adapter class + over the associative container (much as + std::priority_queue can adapt std::vector). + This has the advantage that no cross-referencing is necessary + at all; the priority queue itself is an associative container. + Most associative containers are too structured to compete with + priority queues in terms of push and pop + performance.

    It would be nice if all priority queues could + share exactly the same behavior regardless of implementation. Sadly, this is not possible. Just one for instance is in join operations: joining + two binary heaps might throw an exception (not corrupt + any of the heaps on which it operates), but joining two pairing + heaps is exception free.

    Tags and traits are very useful for manipulating generic + types. __gnu_pbds::priority_queue + publicly defines container_category as one of the tags. Given any + container Cntnr, the tag of the underlying + data structure can be found via typename + Cntnr::container_category; this is one of the possible tags shown in the graphic below. +

    Figure 22.33. Priority-Queue Data-Structure Tags.

    Priority-Queue Data-Structure Tags.

    Additionally, a traits mechanism can be used to query a + container type for its attributes. Given any container + Cntnr, then 

    __gnu_pbds::container_traits<Cntnr>

    + is a traits class identifying the properties of the + container.

    To find if a container might throw if two of its objects are + joined, one can use + 

    +	    container_traits<Cntnr>::split_join_can_throw
+

    +

    + Different priority-queue implementations have different invalidation guarantees. This is + especially important, since there is no way to access an arbitrary + value of priority queues except for iterators. Similarly to + associative containers, one can use + 

    +	      container_traits<Cntnr>::invalidation_guarantee
+

    + to get the invalidation guarantee type of a priority queue.

    It is easy to understand from the graphic above, what container_traits<Cntnr>::invalidation_guarantee + will be for different implementations. All implementations of + type represented by label B have point_invalidation_guarantee: + the container can freely internally reorganize the nodes - + range-type iterators are invalidated, but point-type iterators + are always valid. Implementations of type represented by labels A1 and A2 have basic_invalidation_guarantee: + the container can freely internally reallocate the array - both + point-type and range-type iterators might be invalidated.

    + This has major implications, and constitutes a good reason to avoid + using binary heaps. A binary heap can perform modify + or erase efficiently given a valid point-type + iterator. However, in order to supply it with a valid point-type + iterator, one needs to iterate (linearly) over all + values, then supply the relevant iterator (recall that a + range-type iterator can always be converted to a point-type + iterator). This means that if the number of modify or + erase operations is non-negligible (say + super-logarithmic in the total sequence of operations) - binary + heaps will perform badly. +

    Prev Up Next
    Using Home Testing
    diff --git a/libstdc++-v3/doc/html/manual/policy_data_structures_using.html b/libstdc++-v3/doc/html/manual/policy_data_structures_using.html new file mode 100644 index 00000000000..0e2fdb3d1c4 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/policy_data_structures_using.html @@ -0,0 +1,483 @@ + + +Using
    Using
    Prev Chapter 22. Policy-Based Data Structures Next

    The library contains only header files, and does not require any + other libraries except the standard C++ library . All classes are + defined in namespace __gnu_pbds. The library internally + uses macros beginning with PB_DS, but + #undefs anything it #defines (except for + header guards). Compiling the library in an environment where macros + beginning in PB_DS are defined, may yield unpredictable + results in compilation, execution, or both.

    + Further dependencies are necessary to create the visual output + for the performance tests. To create these graphs, an + additional package is needed: pychart. +

    + The various data structures are organized as follows. +

    + The hierarchy is composed naturally so that commonality is + captured by base classes. Thus operator[] + is defined at the base of any hierarchy, since all derived + containers support it. Conversely split is + defined in basic_branch, since only + tree-like containers support it. +

    + In addition, there are the following diagnostics classes, + used to report errors specific to this library's data + structures. +

    Figure 22.7. Exception Hierarchy

    Exception Hierarchy

    + For the most part, the policy-based containers containers in + namespace __gnu_pbds have the same interface as + the equivalent containers in the standard C++ library, except for + the names used for the container classes themselves. For example, + this shows basic operations on a collision-chaining hash-based + container: + 

    +	  #include <ext/pb_ds/assoc_container.h>
+
+	  int main()
+	  {
+	  __gnu_pbds::cc_hash_table<int, char> c;
+	  c[2] = 'b';
+	  assert(c.find(1) == c.end());
+	  };
+

    + The container is called + __gnu_pbds::cc_hash_table instead of + std::unordered_map, since “unordered + map” does not necessarily mean a hash-based map as implied by + the C++ library (C++0x or TR1). For example, list-based associative + containers, which are very useful for the construction of + "multimaps," are also unordered. +

    This snippet shows a red-black tree based container:

    +	  #include <ext/pb_ds/assoc_container.h>
+
+	  int main()
+	  {
+	  __gnu_pbds::tree<int, char> c;
+	  c[2] = 'b';
+	  assert(c.find(2) != c.end());
+	  };
+

    The container is called tree instead of + map since the underlying data structures are + being named with specificity. +

    + The member function naming convention is to strive to be the same as + the equivalent member functions in other C++ standard library + containers. The familiar methods are unchanged: + begin, end, + size, empty, and + clear. +

    + This isn't to say that things are exactly as one would expect, given + the container requirments and interfaces in the C++ standard. +

    + The names of containers' policies and policy accessors are + different then the usual. For example, if hash_type is + some type of hash-based container, then

    +	  hash_type::hash_fn
+

    + gives the type of its hash functor, and if obj is + some hash-based container object, then + 

    +	  obj.get_hash_fn()
+

    will return a reference to its hash-functor object.

    + Similarly, if tree_type is some type of tree-based + container, then + 

    +	  tree_type::cmp_fn
+

    + gives the type of its comparison functor, and if + obj is some tree-based container object, + then + 

    +	  obj.get_cmp_fn()
+

    will return a reference to its comparison-functor object.

    + It would be nice to give names consistent with those in the existing + C++ standard (inclusive of TR1). Unfortunately, these standard + containers don't consistently name types and methods. For example, + std::tr1::unordered_map uses + hasher for the hash functor, but + std::map uses key_compare for + the comparison functor. Also, we could not find an accessor for + std::tr1::unordered_map's hash functor, but + std::map uses compare + for accessing the comparison functor. +

    + Instead, __gnu_pbds attempts to be internally + consistent, and uses standard-derived terminology if possible. +

    + Another source of difference is in scope: + __gnu_pbds contains more types of associative + containers than the standard C++ library, and more opportunities + to configure these new containers, since different types of + associative containers are useful in different settings. +

    + Namespace __gnu_pbds contains different classes for + hash-based containers, tree-based containers, trie-based containers, + and list-based containers. +

    + Since associative containers share parts of their interface, they + are organized as a class hierarchy. +

    Each type or method is defined in the most-common ancestor + in which it makes sense. +

    For example, all associative containers support iteration + expressed in the following form: + 

    +	  const_iterator
+	  begin() const;
+
+	  iterator
+	  begin();
+
+	  const_iterator
+	  end() const;
+
+	  iterator
+	  end();
+

    + But not all containers contain or use hash functors. Yet, both + collision-chaining and (general) probing hash-based associative + containers have a hash functor, so + basic_hash_table contains the interface: + 

    +	  const hash_fn&
+	  get_hash_fn() const;
+
+	  hash_fn&
+	  get_hash_fn();
+

    + so all hash-based associative containers inherit the same + hash-functor accessor methods. +

    + In general, each of this library's containers is + parametrized by more policies than those of the standard library. For + example, the standard hash-based container is parametrized as + follows: + 

    +	  template<typename Key, typename Mapped, typename Hash,
+	  typename Pred, typename Allocator, bool Cache_Hashe_Code>
+	  class unordered_map;
+

    + and so can be configured by key type, mapped type, a functor + that translates keys to unsigned integral types, an equivalence + predicate, an allocator, and an indicator whether to store hash + values with each entry. this library's collision-chaining + hash-based container is parametrized as + 

    +	  template<typename Key, typename Mapped, typename Hash_Fn,
+	  typename Eq_Fn, typename Comb_Hash_Fn,
+	  typename Resize_Policy, bool Store_Hash
+	  typename Allocator>
+	  class cc_hash_table;
+

    + and so can be configured by the first four types of + std::tr1::unordered_map, then a + policy for translating the key-hash result into a position + within the table, then a policy by which the table resizes, + an indicator whether to store hash values with each entry, + and an allocator (which is typically the last template + parameter in standard containers). +

    + Nearly all policy parameters have default values, so this + need not be considered for casual use. It is important to + note, however, that hash-based containers' policies can + dramatically alter their performance in different settings, + and that tree-based containers' policies can make them + useful for other purposes than just look-up. +

    As opposed to associative containers, priority queues have + relatively few configuration options. The priority queue is + parametrized as follows:

    +	  template<typename Value_Type, typename Cmp_Fn,typename Tag,
+	  typename Allocator>
+	  class priority_queue;
+

    The Value_Type, Cmp_Fn, and + Allocator parameters are the container's value type, + comparison-functor type, and allocator type, respectively; + these are very similar to the standard's priority queue. The + Tag parameter is different: there are a number of + pre-defined tag types corresponding to binary heaps, binomial + heaps, etc., and Tag should be instantiated + by one of them.

    Note that as opposed to the + std::priority_queue, + __gnu_pbds::priority_queue is not a + sequence-adapter; it is a regular container.

    A containers underlying data structure + affect their performance; Unfortunately, they can also affect + their interface. When manipulating generically associative + containers, it is often useful to be able to statically + determine what they can support and what the cannot. +

    Happily, the standard provides a good solution to a similar + problem - that of the different behavior of iterators. If + It is an iterator, then + 

    +	  typename std::iterator_traits<It>::iterator_category
+

    is one of a small number of pre-defined tag classes, and + 

    +	  typename std::iterator_traits<It>::value_type
+

    is the value type to which the iterator "points".

    + Similarly, in this library, if C is a + container, then container_traits is a + trait class that stores information about the kind of + container that is implemented. + 

    +	  typename container_traits<C>::container_category
+

    + is one of a small number of predefined tag structures that + uniquely identifies the type of underlying data structure. +

    In most cases, however, the exact underlying data + structure is not really important, but what is important is + one of its other attributes: whether it guarantees storing + elements by key order, for example. For this one can + use

    +	  typename container_traits<C>::order_preserving
+

    + Also, + 

    +	  typename container_traits<C>::invalidation_guarantee
+

    is the container's invalidation guarantee. Invalidation + guarantees are especially important regarding priority queues, + since in this library's design, iterators are practically the + only way to manipulate them.

    This library differentiates between two types of methods + and iterators: point-type, and range-type. For example, + find and insert are point-type methods, since + they each deal with a specific element; their returned + iterators are point-type iterators. begin and + end are range-type methods, since they are not used to + find a specific element, but rather to go over all elements in + a container object; their returned iterators are range-type + iterators. +

    Most containers store elements in an order that is + determined by their interface. Correspondingly, it is fine that + their point-type iterators are synonymous with their range-type + iterators. For example, in the following snippet + 

    +	  std::for_each(c.find(1), c.find(5), foo);
+

    + two point-type iterators (returned by find) are used + for a range-type purpose - going over all elements whose key is + between 1 and 5. +

    + Conversely, the above snippet makes no sense for + self-organizing containers - ones that order (and reorder) + their elements by implementation. It would be nice to have a + uniform iterator system that would allow the above snippet to + compile only if it made sense. +

    + This could trivially be done by specializing + std::for_each for the case of iterators returned by + std::tr1::unordered_map, but this would only solve the + problem for one algorithm and one container. Fundamentally, the + problem is that one can loop using a self-organizing + container's point-type iterators. +

    + This library's containers define two families of + iterators: point_const_iterator and + point_iterator are the iterator types returned by + point-type methods; const_iterator and + iterator are the iterator types returned by range-type + methods. + 

    +	  class <- some container ->
+	  {
+	  public:
+	  ...
+
+	  typedef <- something -> const_iterator;
+
+	  typedef <- something -> iterator;
+
+	  typedef <- something -> point_const_iterator;
+
+	  typedef <- something -> point_iterator;
+
+	  ...
+
+	  public:
+	  ...
+
+	  const_iterator begin () const;
+
+	  iterator begin();
+
+	  point_const_iterator find(...) const;
+
+	  point_iterator find(...);
+	  };
+

    For + containers whose interface defines sequence order , it + is very simple: point-type and range-type iterators are exactly + the same, which means that the above snippet will compile if it + is used for an order-preserving associative container. +

    + For self-organizing containers, however, (hash-based + containers as a special example), the preceding snippet will + not compile, because their point-type iterators do not support + operator++. +

    In any case, both for order-preserving and self-organizing + containers, the following snippet will compile: + 

    +	  typename Cntnr::point_iterator it = c.find(2);
+

    + because a range-type iterator can always be converted to a + point-type iterator. +

    Distingushing between iterator types also + raises the point that a container's iterators might have + different invalidation rules concerning their de-referencing + abilities and movement abilities. This now corresponds exactly + to the question of whether point-type and range-type iterators + are valid. As explained above, container_traits allows + querying a container for its data structure attributes. The + iterator-invalidation guarantees are certainly a property of + the underlying data structure, and so + 

    +	  container_traits<C>::invalidation_guarantee
+

    + gives one of three pre-determined types that answer this + query. +

    + Additional code examples are provided in the source + distribution, as part of the regression and performance + testsuite. +

    Prev Up Next
    Chapter 22. Policy-Based Data Structures Home Design
    diff --git a/libstdc++-v3/doc/html/manual/profile_mode.html b/libstdc++-v3/doc/html/manual/profile_mode.html index 1c1c5990249..2543fdb0c86 100644 --- a/libstdc++-v3/doc/html/manual/profile_mode.html +++ b/libstdc++-v3/doc/html/manual/profile_mode.html @@ -1,9 +1,9 @@ -Chapter 19. Profile Mode
    Chapter 19. Profile Mode
    Prev Part III.  +Chapter 19. Profile Mode
    Chapter 19. Profile Mode
    Prev Part III.  Extensions - Next

    Table of Contents

    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Algorithms
    Data Locality
    Multithreaded Data Access
    Statistics
    Bibliography

    +

    		 Next

    Table of Contents

    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Hashtable Too Small
    Hashtable Too Large
    Inefficient Hash
    Vector Too Small
    Vector Too Large
    Vector to Hashtable
    Hashtable to Vector
    Vector to List
    List to Vector
    List to Forward List (Slist)
    Ordered to Unordered Associative Container
    Algorithms
    Sort Algorithm Performance
    Data Locality
    Need Software Prefetch
    Linked Structure Locality
    Multithreaded Data Access
    Data Dependence Violations at Container Level
    False Sharing
    Statistics
    Bibliography

    Goal: Give performance improvement advice based on recognition of suboptimal usage patterns of the standard library.

    @@ -138,9 +138,9 @@ vector-size: improvement = 3: call stack = 0x804842c ... call context. (Environment variable not supported.)

    -

    +

    Perflint: A Context Sensitive Performance Advisor for C++ Programs . Lixia Liu. Silvius Rus. Copyright © 2009 . Proceedings of the 2009 International Symposium on Code Generation and Optimization - .

    Prev Up Next
    Testing Home Design
    + .

    Prev Up Next
    Testing Home Design
    diff --git a/libstdc++-v3/doc/html/manual/setup.html b/libstdc++-v3/doc/html/manual/setup.html index e0b5caee6e0..6615390b526 100644 --- a/libstdc++-v3/doc/html/manual/setup.html +++ b/libstdc++-v3/doc/html/manual/setup.html @@ -1,6 +1,6 @@ -Chapter 2. Setup
    Chapter 2. Setup
    Prev Part I.  +Chapter 2. Setup
    Chapter 2. Setup
    Prev Part I.  Introduction  Next

    Table of Contents

    Prerequisites
    Configure
    Make

    To transform libstdc++ sources into installed include files @@ -99,4 +99,4 @@ zh_TW BIG5

  • install just the necessary locales

    • with Debian Linux:

      Add the above list, as shown, to the file /etc/locale.gen

      run /usr/sbin/locale-gen

    • on most Unix-like operating systems:

      localedef -i de_DE -f ISO-8859-1 de_DE

      (repeat for each entry in the above list)

    • Instructions for other operating systems solicited. -

    • Prev Up Next
    Bugs Home Configure
    +

    Prev Up Next
    Bugs Home Configure
    diff --git a/libstdc++-v3/doc/html/manual/source_code_style.html b/libstdc++-v3/doc/html/manual/source_code_style.html index ff4b4db2f39..3de6bb2de61 100644 --- a/libstdc++-v3/doc/html/manual/source_code_style.html +++ b/libstdc++-v3/doc/html/manual/source_code_style.html @@ -1,6 +1,6 @@ -Coding Style
    Coding Style
    Prev Appendix A.  +Coding Style
    Coding Style
    Prev Appendix A.  Contributing  Next

    @@ -617,4 +617,4 @@         }
          } // namespace std
          
    -    

    Prev Up Next
    Directory Layout and Source Conventions Home Design Notes
    +    

    Prev Up Next
    Directory Layout and Source Conventions Home Design Notes
    diff --git a/libstdc++-v3/doc/html/manual/source_design_notes.html b/libstdc++-v3/doc/html/manual/source_design_notes.html index fab57a64792..8f9b0bef5e0 100644 --- a/libstdc++-v3/doc/html/manual/source_design_notes.html +++ b/libstdc++-v3/doc/html/manual/source_design_notes.html @@ -1,6 +1,6 @@ -Design Notes
    Design Notes
    Prev Appendix A.  +Design Notes
    Design Notes
    Prev Appendix A.  Contributing  Next

    @@ -857,7 +857,7 @@     subdirectories ext/ and backward/. (Note that it is better to
        include them via "<backward/hash_map.h>" or "<ext/hash_map>" than
        to search the subdirectory itself via a "-I" directive.
    -  

    Prev Up Next
    Coding Style Home Appendix B.  +  

    Prev Up Next
    Coding Style Home Appendix B.  Porting and Maintenance
    diff --git a/libstdc++-v3/doc/html/manual/source_organization.html b/libstdc++-v3/doc/html/manual/source_organization.html index 3e17c8b48b4..b7329bb88ec 100644 --- a/libstdc++-v3/doc/html/manual/source_organization.html +++ b/libstdc++-v3/doc/html/manual/source_organization.html @@ -1,6 +1,6 @@ -Directory Layout and Source Conventions
    Directory Layout and Source Conventions
    Prev Appendix A.  +Directory Layout and Source Conventions
    Directory Layout and Source Conventions
    Prev Appendix A.  Contributing  Next

    @@ -94,4 +94,4 @@ indicate a place that may require attention for multi-thread safety.

    Prev Up Next
    Appendix A.  Contributing - Home Coding Style
    +     		Home Coding Style
    diff --git a/libstdc++-v3/doc/html/manual/spine.html b/libstdc++-v3/doc/html/manual/spine.html deleted file mode 100644 index 688d0625510..00000000000 --- a/libstdc++-v3/doc/html/manual/spine.html +++ /dev/null @@ -1,67 +0,0 @@ - - -The GNU C++ Library Manual
    The GNU C++ Library Manual
    Prev   Next

    Table of Contents

    I. - Introduction - -
    1. Status
    Implementation Status
    C++ 1998/2003
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs
    2. Setup
    Prerequisites
    Configure
    Make
    3. Using
    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Data Race Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis
    II. - Standard Contents -
    4. - Support - -
    Types
    Fundamental Types
    Numeric Properties
    NULL
    Dynamic Memory
    Termination
    Termination Handlers
    Verbose Terminate Handler
    5. - Diagnostics - -
    Exceptions
    API Reference
    Adding Data to exception
    Concept Checking
    6. - Utilities - -
    Functors
    Pairs
    Memory
    Allocators
    auto_ptr
    shared_ptr
    Traits
    7. - Strings - -
    String Classes
    Simple Transformations
    Case Sensitivity
    Arbitrary Character Types
    Tokenizing
    Shrink to Fit
    CString (MFC)
    8. - Localization - -
    Locales
    locale
    Facets
    ctype
    codecvt
    messages
    9. - Containers - -
    Sequences
    list
    vector
    Associative
    Insertion Hints
    bitset
    Interacting with C
    Containers vs. Arrays
    10. - Iterators - -
    Predefined
    Iterators vs. Pointers
    One Past the End
    11. - Algorithms - -
    Mutating
    swap
    12. - Numerics - -
    Complex
    complex Processing
    Generalized Operations
    Interacting with C
    Numerics vs. Arrays
    C99
    13. - Input and Output - -
    Iostream Objects
    Stream Buffers
    Derived streambuf Classes
    Buffering
    Memory Based Streams
    Compatibility With strstream
    File Based Streams
    Copying a File
    Binary Input and Output
    Interacting with C
    Using FILE* and file descriptors
    Performance
    14. - Atomics - -
    API Reference
    15. - Concurrency - -
    API Reference
    III. - Extensions - -
    16. Compile Time Checks
    17. Debug Mode
    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    Other Implementations
    18. Parallel Mode
    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Implementation Namespaces
    Testing
    Bibliography
    19. Profile Mode
    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Algorithms
    Data Locality
    Multithreaded Data Access
    Statistics
    Bibliography
    20. Allocators
    mt_allocator
    Intro
    Design Issues
    Implementation
    Single Thread Example
    Multiple Thread Example
    bitmap_allocator
    Design
    Implementation
    21. Containers
    Policy Based Data Structures
    HP/SGI
    Deprecated HP/SGI
    22. Utilities
    23. Algorithms
    24. Numerics
    25. Iterators
    26. Input and Output
    Derived filebufs
    27. Demangling
    28. Concurrency
    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use
    IV. - Appendices -
    A. - Contributing - -
    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Design Notes
    B. - Porting and Maintenance - -
    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Docbook
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Running the Testsuite
    Writing a new test case
    Test Harness and Utilities
    Special Topics
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    Second
    Third
    C. - Free Software Needs Free Documentation - -
    D. - GNU General Public License version 3 -
    E. GNU Free Documentation License

    List of Figures

    B.1. Configure and Build File Dependencies

    List of Tables

    1.1. C++ 1998/2003 Implementation Status
    1.2. C++ 200x Implementation Status
    1.3. C++ TR1 Implementation Status
    1.4. C++ TR 24733 Implementation Status
    3.1. C++ Command Options
    3.2. C++ 1998 Library Headers
    3.3. C++ 1998 Library Headers for C Library Facilities
    3.4. C++ 200x Library Headers
    3.5. C++ 200x Library Headers for C Library Facilities
    3.6. C++ TR 1 Library Headers
    3.7. C++ TR 1 Library Headers for C Library Facilities
    3.8. C++ TR 24733 Decimal Floating-Point Header
    3.9. C++ ABI Headers
    3.10. Extension Headers
    3.11. Extension Debug Headers
    3.12. Extension Profile Headers
    3.13. Extension Parallel Headers
    17.1. Debugging Containers
    17.2. Debugging Containers C++0x
    18.1. Parallel Algorithms
    19.1. Profile Code Location
    19.2. Profile Diagnostics
    20.1. Bitmap Allocator Memory Map
    B.1. Doxygen Prerequisites
    B.2. HTML to Doxygen Markup Comparison
    B.3. Docbook Prerequisites
    B.4. HTML to Docbook XML Markup Comparison
    B.5. Docbook XML Element Use
    B.6. Extension Allocators
    B.7. Extension Allocators Continued
    Prev   Next
    The GNU C++ Library Home Part I.  - Introduction - -
    diff --git a/libstdc++-v3/doc/html/manual/status.html b/libstdc++-v3/doc/html/manual/status.html index f7fdb486604..8e68bb29fc5 100644 --- a/libstdc++-v3/doc/html/manual/status.html +++ b/libstdc++-v3/doc/html/manual/status.html @@ -1,14 +1,14 @@ -Chapter 1. Status
    Chapter 1. Status
    Prev Part I.  +Chapter 1. Status
    Chapter 1. Status
    Prev Part I.  Introduction - Next

    Table of Contents

    Implementation Status
    C++ 1998/2003
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs

    +

    		 Next

    Table of Contents

    Implementation Status
    C++ 1998/2003
    Implementation Status
    Implementation Specific Behavior
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs

    This status table is based on the table of contents of ISO/IEC 14882:2003.

    This page describes the C++ support in mainline GCC SVN, not in any particular release. -

    Table 1.1. C++ 1998/2003 Implementation Status

    SectionDescriptionStatusComments
    +

    Table 1.1. C++ 1998/2003 Implementation Status

    SectionDescriptionStatusComments
    18 Language support @@ -90,7 +90,7 @@ particular release. class. But they are the mangled names; you will need to call c++filt and pass the names as command-line parameters to demangle them, or call a - runtime demangler function. + runtime demangler function. (The classes in <stdexcept> have constructors which require an argument to use later for what() calls, so the problem of what()'s value does not arise in most @@ -157,7 +157,7 @@ presence of the required flag.

    This page describes the C++0x support in mainline GCC SVN, not in any particular release. -

    Table 1.2. C++ 200x Implementation Status

    SectionDescriptionStatusComments
    +

    Table 1.2. C++ 200x Implementation Status

    SectionDescriptionStatusComments
    18 Language support @@ -169,7 +169,7 @@ particular release. 20 General utilities -
    20.1General  
    20.2Utility components  
    20.2.1OperatorsY 
    20.2.2SwapY 
    20.2.3forward and move helpersY 
    20.2.4Function template declvalY 
    20.3Pairs  
    20.3.1In general  
    20.3.2Class template pairY 
    20.3.3Specialized algorithmsY 
    20.3.4Tuple-like access to pairY 
    20.3.5Piecewise constructionY 
    20.4Tuples  
    20.4.1In general  
    20.4.2Class template tuple  
    20.4.2.1ConstructionY 
    20.4.2.2AssignmentY 
    20.4.2.3SwapY 
    20.4.2.4Tuple creation functionsPartialtuple_cat should be a single variadic signature (DR 1385)
    20.4.2.5Tuple helper classesY 
    20.4.2.6Element accessY 
    20.4.2.7Relational operatorsY 
    20.4.2.8Tuple traitsY 
    20.4.2.9Tuple specialized algorithmsY 
    20.5Class template bitsetY 
    20.5.1bitset constructorsY 
    20.5.2bitset membersY 
    20.5.3bitset hash supportY 
    20.5.4bitset operatorsY 
    20.6Memory  
    20.6.1In general  
    20.6.2Header <memory> synopsis  
    20.6.3Pointer traitsPartialMissing rebind
    20.6.4Pointer safetyPartial 
    20.6.5AlignN 
    20.6.6Allocator argument tagY 
    20.6.7uses_allocatorY 
    20.6.8Allocator traitsPartialMissing rebind_alloc and rebind_traits
    20.6.9The default allocatorY 
    20.6.10Raw storage iteratorY 
    20.6.11Temporary buffersY 
    20.6.12Specialized algorithms  
    20.6.12.1addressofY 
    20.6.12.2uninitialized_copyY 
    20.6.12.3uninitialized_fillY 
    20.6.12.4uninitialized_fill_nY 
    20.6.13C libraryY 
    20.7Smart pointers  
    20.7.1Class template unique_ptrY 
    20.7.2Shared-ownership pointersY 
    20.7.2.1Class bad_weak_ptrY 
    20.7.2.2Class template shared_ptrY +
    20.1General  
    20.2Utility components  
    20.2.1OperatorsY 
    20.2.2SwapY 
    20.2.3forward and move helpersY 
    20.2.4Function template declvalY 
    20.3Pairs  
    20.3.1In general  
    20.3.2Class template pairY 
    20.3.3Specialized algorithmsY 
    20.3.4Tuple-like access to pairY 
    20.3.5Piecewise constructionY 
    20.4Tuples  
    20.4.1In general  
    20.4.2Class template tuple  
    20.4.2.1ConstructionY 
    20.4.2.2AssignmentY 
    20.4.2.3SwapY 
    20.4.2.4Tuple creation functionsY 
    20.4.2.5Tuple helper classesY 
    20.4.2.6Element accessY 
    20.4.2.7Relational operatorsY 
    20.4.2.8Tuple traitsY 
    20.4.2.9Tuple specialized algorithmsY 
    20.5Class template bitsetY 
    20.5.1bitset constructorsY 
    20.5.2bitset membersY 
    20.5.3bitset hash supportY 
    20.5.4bitset operatorsY 
    20.6Memory  
    20.6.1In general  
    20.6.2Header <memory> synopsis  
    20.6.3Pointer traitsPartialMissing rebind
    20.6.4Pointer safetyPartial 
    20.6.5AlignN 
    20.6.6Allocator argument tagY 
    20.6.7uses_allocatorY 
    20.6.8Allocator traitsPartialMissing rebind_alloc and rebind_traits
    20.6.9The default allocatorY 
    20.6.10Raw storage iteratorY 
    20.6.11Temporary buffersY 
    20.6.12Specialized algorithms  
    20.6.12.1addressofY 
    20.6.12.2uninitialized_copyY 
    20.6.12.3uninitialized_fillY 
    20.6.12.4uninitialized_fill_nY 
    20.6.13C libraryY 
    20.7Smart pointers  
    20.7.1Class template unique_ptrY 
    20.7.2Shared-ownership pointersY 
    20.7.2.1Class bad_weak_ptrY 
    20.7.2.2Class template shared_ptrY

    Uses code from boost::shared_ptr. @@ -184,7 +184,7 @@ particular release. is_nothrow_assignable, is_nothrow_copy_assignable, is_nothrow_move_assignable, is_nothrow_destructible -

    20.9.5Type property queriesY 
    20.9.6Relationships between typesY 
    20.9.7Transformations between types  
    20.9.7.1Const-volatile modificationsY 
    20.9.7.2Reference modificationsY 
    20.9.7.3Sign modificationsY 
    20.9.7.4Array modificationsY 
    20.9.7.5Pointer modificationsY 
    20.9.7.6Other transformationsY 
    20.10Compile-time rational arithmetic  
    20.10.1In general  
    20.10.2Header <ratio> synopsis  
    20.10.3Class template ratioY 
    20.10.4Arithmetic on ratiosY 
    20.10.5Comparison of ratiosY 
    20.10.6SI types for ratioY 
    20.11Time utilities  
    20.11.3Clock requirementsY 
    20.11.4Time-related traits  
    20.11.4.1treat_as_floating_pointY 
    20.11.4.2duration_valuesY 
    20.11.4.3Specializations of common_typeY 
    20.11.5Class template durationPartialMissing constexpr for non-member arithmetic operations
    20.11.6Class template time_pointY 
    20.11.7Clocks  
    20.11.7.1Class system_clockY 
    20.11.7.2Class steady_clockNSupport old monotonic_clock spec instead
    20.11.7.3Class high_resolution_clockY 
    20.11.8Date and time functionsY 
    20.12Scoped allocator adaptor  
    20.12.1Header <scoped_allocator> synopsis  
    20.12.2Scoped allocator adaptor member typesN 
    20.12.3Scoped allocator adaptor constructorsN 
    20.12.4Scoped allocator adaptor membersN 
    20.12.5Scoped allocator operatorsN 
    20.13Class type_indexN 
    +
    20.9.5Type property queriesY 
    20.9.6Relationships between typesY 
    20.9.7Transformations between types  
    20.9.7.1Const-volatile modificationsY 
    20.9.7.2Reference modificationsY 
    20.9.7.3Sign modificationsY 
    20.9.7.4Array modificationsY 
    20.9.7.5Pointer modificationsY 
    20.9.7.6Other transformationsY 
    20.10Compile-time rational arithmetic  
    20.10.1In general  
    20.10.2Header <ratio> synopsis  
    20.10.3Class template ratioY 
    20.10.4Arithmetic on ratiosY 
    20.10.5Comparison of ratiosY 
    20.10.6SI types for ratioY 
    20.11Time utilities  
    20.11.3Clock requirementsY 
    20.11.4Time-related traits  
    20.11.4.1treat_as_floating_pointY 
    20.11.4.2duration_valuesY 
    20.11.4.3Specializations of common_typeY 
    20.11.5Class template durationPartialMissing constexpr for non-member arithmetic operations
    20.11.6Class template time_pointY 
    20.11.7Clocks  
    20.11.7.1Class system_clockY 
    20.11.7.2Class steady_clockNSupport old monotonic_clock spec instead
    20.11.7.3Class high_resolution_clockY 
    20.11.8Date and time functionsY 
    20.12Scoped allocator adaptorPartial 
    20.12.1Header <scoped_allocator> synopsis  
    20.12.2Scoped allocator adaptor member typesY 
    20.12.3Scoped allocator adaptor constructorsY 
    20.12.4Scoped allocator adaptor membersPartial 
    20.12.5Scoped allocator operatorsY 
    20.13Class type_indexY 
    21 Strings @@ -245,7 +245,7 @@ In this implementation the header names are prefixed by

    This page describes the TR1 support in mainline GCC SVN, not in any particular release. -

    Table 1.3. C++ TR1 Implementation Status

    SectionDescriptionStatusComments
    2General Utilities
    2.1Reference wrappers  
    2.1.1Additions to header <functional> synopsisY 
    2.1.2Class template reference_wrapper  
    2.1.2.1reference_wrapper construct/copy/destroyY 
    2.1.2.2reference_wrapper assignmentY 
    2.1.2.3reference_wrapper accessY 
    2.1.2.4reference_wrapper invocationY 
    2.1.2.5reference_wrapper helper functionsY 
    2.2Smart pointers  
    2.2.1Additions to header <memory> synopsisY 
    2.2.2Class bad_weak_ptrY 
    2.2.3Class template shared_ptr  +

    Table 1.3. C++ TR1 Implementation Status

    SectionDescriptionStatusComments
    2General Utilities
    2.1Reference wrappers  
    2.1.1Additions to header <functional> synopsisY 
    2.1.2Class template reference_wrapper  
    2.1.2.1reference_wrapper construct/copy/destroyY 
    2.1.2.2reference_wrapper assignmentY 
    2.1.2.3reference_wrapper accessY 
    2.1.2.4reference_wrapper invocationY 
    2.1.2.5reference_wrapper helper functionsY 
    2.2Smart pointers  
    2.2.1Additions to header <memory> synopsisY 
    2.2.2Class bad_weak_ptrY 
    2.2.3Class template shared_ptr 

    Uses code from boost::shared_ptr. @@ -258,7 +258,7 @@ decimal floating-point arithmetic

    This page describes the TR 24733 support in mainline GCC SVN, not in any particular release. -

    Table 1.4. C++ TR 24733 Implementation Status

    SectionDescriptionStatusComments
    +

    Table 1.4. C++ TR 24733 Implementation Status

    SectionDescriptionStatusComments
    0 Introduction @@ -281,4 +281,4 @@ particular release.

    Prev Up Next
    Part I.  Introduction - Home License
    +     		Home License
    diff --git a/libstdc++-v3/doc/html/manual/streambufs.html b/libstdc++-v3/doc/html/manual/streambufs.html index 92c148dfcde..12d9ee698ea 100644 --- a/libstdc++-v3/doc/html/manual/streambufs.html +++ b/libstdc++-v3/doc/html/manual/streambufs.html @@ -1,6 +1,6 @@ -Stream Buffers
    Stream Buffers
    Prev Chapter 13.  +Stream Buffers
    Stream Buffers
    Prev Chapter 13.  Input and Output  Next

    @@ -134,4 +134,4 @@

    Prev Up Next
    Chapter 13.  Input and Output - Home Memory Based Streams
    +     		Home Memory Based Streams
    diff --git a/libstdc++-v3/doc/html/manual/strings.html b/libstdc++-v3/doc/html/manual/strings.html index fd13422585d..6e4adf23d7c 100644 --- a/libstdc++-v3/doc/html/manual/strings.html +++ b/libstdc++-v3/doc/html/manual/strings.html @@ -1,13 +1,13 @@ -Chapter 7.  Strings
    Chapter 7.  +Chapter 7.  Strings
    Chapter 7.  Strings
    Prev Part II.  Standard Contents  Next

    Table of Contents

    String Classes
    Simple Transformations
    Case Sensitivity
    Arbitrary Character Types
    Tokenizing
    Shrink to Fit
    CString (MFC)

    Here are Standard, simple, and portable ways to perform common transformations on a string instance, such as @@ -360,7 +360,7 @@ stringtok(Container &container, string const &in, libstdc++ string, the SGI string, and the SGI rope, and this is all before any allocator or traits customizations! (More choices than you can shake a stick at -- want fries with that?) -

    Prev Up Next
    Traits Home Chapter 8.  +

    Prev Up Next
    Traits Home Chapter 8.  Localization
    diff --git a/libstdc++-v3/doc/html/manual/stringstreams.html b/libstdc++-v3/doc/html/manual/stringstreams.html index 1107d61b1b3..e267e6b3c7b 100644 --- a/libstdc++-v3/doc/html/manual/stringstreams.html +++ b/libstdc++-v3/doc/html/manual/stringstreams.html @@ -1,6 +1,6 @@ -Memory Based Streams
    Memory Based Streams
    Prev Chapter 13.  +Memory Based Streams
    Memory Based Streams
    Prev Chapter 13.  Input and Output  Next

    @@ -34,4 +34,4 @@ memory yourself. The strstreams have been officially deprecated, which means that 1) future revisions of the C++ Standard won't support them, and 2) if you use them, people will laugh at you. -

    Prev Up Next
    Stream Buffers Home File Based Streams
    +

    Prev Up Next
    Stream Buffers Home File Based Streams
    diff --git a/libstdc++-v3/doc/html/manual/support.html b/libstdc++-v3/doc/html/manual/support.html index 842eb11d924..7a978473fb7 100644 --- a/libstdc++-v3/doc/html/manual/support.html +++ b/libstdc++-v3/doc/html/manual/support.html @@ -1,13 +1,13 @@ -Chapter 4.  Support
    Chapter 4.  +Chapter 4.  Support
    Chapter 4.  Support
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Types
    Fundamental Types
    Numeric Properties
    NULL
    Dynamic Memory
    Termination
    Termination Handlers
    Verbose Terminate Handler

    This part deals with the functions called and objects created automatically during the course of a program's existence. @@ -127,4 +127,4 @@ Effective C++ CD example

    Prev Up Next
    Part II.  Standard Contents -  Home Dynamic Memory
    +      		Home Dynamic Memory
    diff --git a/libstdc++-v3/doc/html/manual/termination.html b/libstdc++-v3/doc/html/manual/termination.html index cc523594354..9fe47502eeb 100644 --- a/libstdc++-v3/doc/html/manual/termination.html +++ b/libstdc++-v3/doc/html/manual/termination.html @@ -1,6 +1,6 @@ -Termination
    Termination
    Prev Chapter 4.  +Termination
    Termination
    Prev Chapter 4.  Support  Next

    @@ -118,7 +118,7 @@ int main(int argc) inappropriate location, __verbose_terminate_handler will behave in an unspecified manner. -

    Prev Up Next
    Dynamic Memory Home Chapter 5.  +

    Prev Up Next
    Dynamic Memory Home Chapter 5.  Diagnostics
    diff --git a/libstdc++-v3/doc/html/manual/test.html b/libstdc++-v3/doc/html/manual/test.html index f6523c09359..802d4159a07 100644 --- a/libstdc++-v3/doc/html/manual/test.html +++ b/libstdc++-v3/doc/html/manual/test.html @@ -1,6 +1,6 @@ -Test
    Test
    Prev Appendix B.  +Test
    Test
    Prev Appendix B.  Porting and Maintenance  Next

    @@ -493,7 +493,7 @@ only default variables. reporting functions including:

    Testing is composed of running a particular test sequence, and looking at what happens to the surrounding code when @@ -636,4 +636,4 @@ C++0x Requirements Test Sequence Descriptions The general form demonstrated in testsuite/23_containers/list/requirements/exception/propagation_coherent.cc . The instantiating test object is __gnu_test::propagation_coherent and is detailed in testsuite/util/exception/safety.h. -

    Prev Up Next
    Porting to New Hardware or Operating Systems Home ABI Policy and Guidelines
    +

    Prev Up Next
    Porting to New Hardware or Operating Systems Home ABI Policy and Guidelines
    diff --git a/libstdc++-v3/doc/html/manual/traits.html b/libstdc++-v3/doc/html/manual/traits.html index 4c04c7b15c3..93610f607f2 100644 --- a/libstdc++-v3/doc/html/manual/traits.html +++ b/libstdc++-v3/doc/html/manual/traits.html @@ -1,10 +1,10 @@ -Traits
    Traits
    Prev Chapter 6.  +Traits
    Traits
    Prev Chapter 6.  Utilities  Next

    -

    Prev Up Next
    Memory Home Chapter 7.  +

    Prev Up Next
    Memory Home Chapter 7.  Strings
    diff --git a/libstdc++-v3/doc/html/manual/using.html b/libstdc++-v3/doc/html/manual/using.html index a425e022371..529577e5eb6 100644 --- a/libstdc++-v3/doc/html/manual/using.html +++ b/libstdc++-v3/doc/html/manual/using.html @@ -1,9 +1,9 @@ -Chapter 3. Using
    Chapter 3. Using
    Prev Part I.  +Chapter 3. Using
    Chapter 3. Using
    Prev Part I.  Introduction - Next

    Table of Contents

    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Data Race Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis

    +

    		 Next

    Table of Contents

    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Structure
    Defaults
    Future
    Alternatives
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    With C
    With POSIX thread cancellation
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Data Race Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis

    The set of features available in the GNU C++ library is shaped by several GCC @@ -11,5 +11,5 @@ enumerated and detailed in the table below.

    By default, g++ is equivalent to g++ -std=gnu++98. The standard library also defaults to this dialect. -

    Table 3.1. C++ Command Options

    Option FlagsDescription
    -std=c++98Use the 1998 ISO C++ standard plus amendments.
    -std=gnu++98As directly above, with GNU extensions.
    -std=c++0xUse the working draft of the upcoming ISO C++0x standard.
    -std=gnu++0xAs directly above, with GNU extensions.
    -fexceptionsSee exception-free dialect
    -frttiAs above, but RTTI-free dialect.
    -pthread or -pthreadsFor ISO C++0x <thread>, <future>, - <mutex>, or <condition_variable>.
    -fopenmpFor parallel mode.

    Prev Up Next
    Make Home Headers
    +

    Table 3.1. C++ Command Options

    Option FlagsDescription
    -std=c++98Use the 1998 ISO C++ standard plus amendments.
    -std=gnu++98As directly above, with GNU extensions.
    -std=c++0xUse the working draft of the upcoming ISO C++0x standard.
    -std=gnu++0xAs directly above, with GNU extensions.
    -fexceptionsSee exception-free dialect
    -frttiAs above, but RTTI-free dialect.
    -pthread or -pthreadsFor ISO C++0x <thread>, <future>, + <mutex>, or <condition_variable>.
    -fopenmpFor parallel mode.

    Prev Up Next
    Make Home Headers
    diff --git a/libstdc++-v3/doc/html/manual/using_concurrency.html b/libstdc++-v3/doc/html/manual/using_concurrency.html index a0ca2a651af..671ebdd3a4b 100644 --- a/libstdc++-v3/doc/html/manual/using_concurrency.html +++ b/libstdc++-v3/doc/html/manual/using_concurrency.html @@ -1,6 +1,6 @@ -Concurrency
    Concurrency
    Prev Chapter 3. Using Next

    This section discusses issues surrounding the proper compilation +Concurrency

    Concurrency
    Prev Chapter 3. Using Next

    This section discusses issues surrounding the proper compilation of multithreaded applications which use the Standard C++ library. This information is GCC-specific since the C++ standard does not address matters of multithreaded applications. @@ -202,4 +202,4 @@ gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) useful are details on allocator options and capabilities. -

    Prev Up Next
    Linking Home Exceptions
    +

    Prev Up Next
    Linking Home Exceptions
    diff --git a/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html b/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html index 6ca06caa713..9796e4e8a60 100644 --- a/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html +++ b/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html @@ -1,6 +1,6 @@ -Linking
    Linking
    Prev Chapter 3. Using Next

    +Linking

    Linking
    Prev Chapter 3. Using Next

    Or as close as it gets: freestanding. This is a minimal configuration, with only partial support for the standard library. Assume only the following header files can be used: @@ -106,4 +106,4 @@ A quick read of the relevant part of the GCC also installed, for use with Libtool. If you use Libtool to create your executables, these details are taken care of for you. -

    Prev Up Next
    Namespaces Home Concurrency
    +

    Prev Up Next
    Namespaces Home Concurrency
    diff --git a/libstdc++-v3/doc/html/manual/using_exceptions.html b/libstdc++-v3/doc/html/manual/using_exceptions.html index a0adc01d1af..19c72cdb113 100644 --- a/libstdc++-v3/doc/html/manual/using_exceptions.html +++ b/libstdc++-v3/doc/html/manual/using_exceptions.html @@ -1,6 +1,6 @@ -Exceptions
    Exceptions
    Prev Chapter 3. Using Next

    +Exceptions

    Exceptions
    Prev Chapter 3. Using Next

    The C++ language provides language support for stack unwinding with try and catch blocks and the throw keyword. @@ -266,42 +266,49 @@ is called. } catch(...) { this->_M_setstate(ios_base::badbit); } -

    - . +

    + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + . 2.9.5 Thread Cancellation . Copyright © 2008 The Open Group/The Institute of Electrical and Electronics Engineers, Inc. - .

    - . + .

    + Error and Exception Handling + . David Abrahams . Boost - .

    - . + .

    + Exception-Safety in Generic Components + . David Abrahams. Boost - .

    - . + .

    + Standard Library Exception Policy + . Matt Austern. WG21 N1077 - .

    - . + .

    + ia64 c++ abi exception handling + . Richard Henderson. GNU - .

    - . + .

    + Appendix E: Standard-Library Exception Safety - . Bjarne Stroustrup.

    + + . Bjarne Stroustrup.

    Exceptional C++ . Exception-Safety Issues and Techniques - . Herb Sutter.

    - . + . Herb Sutter.

    + GCC Bug 25191: exception_defines.h #defines try/catch - .

    Prev Up Next
    Concurrency Home Debugging Support
    + + .

    Prev Up Next
    Concurrency Home Debugging Support
    diff --git a/libstdc++-v3/doc/html/manual/using_headers.html b/libstdc++-v3/doc/html/manual/using_headers.html index 073070960b8..71fee7de525 100644 --- a/libstdc++-v3/doc/html/manual/using_headers.html +++ b/libstdc++-v3/doc/html/manual/using_headers.html @@ -1,6 +1,6 @@ -Headers
    Headers
    Prev Chapter 3. Using Next

    +Headers

    Headers
    Prev Chapter 3. Using Next

    The C++ standard specifies the entire set of header files that must be available to all hosted implementations. Actually, the word "files" is a misnomer, since the contents of the @@ -20,19 +20,19 @@ upcoming 200x standard.

    C++98/03 include files. These are available in the default compilation mode, i.e. -std=c++98 or -std=gnu++98. -

    Table 3.2. C++ 1998 Library Headers

    algorithmbitsetcomplexdequeexception
    fstreamfunctionaliomanipiosiosfwd
    iostreamistreamiteratorlimitslist
    localemapmemorynewnumeric
    ostreamqueuesetsstreamstack
    stdexceptstreambufstringutilitytypeinfo
    valarrayvector   

    Table 3.3. C++ 1998 Library Headers for C Library Facilities

    cassertcerrnocctypecfloatciso646
    climitsclocalecmathcsetjmpcsignal
    cstdargcstddefcstdiocstdlibcstring
    ctimecwcharcwctype  

    +

    Table 3.2. C++ 1998 Library Headers

    algorithmbitsetcomplexdequeexception
    fstreamfunctionaliomanipiosiosfwd
    iostreamistreamiteratorlimitslist
    localemapmemorynewnumeric
    ostreamqueuesetsstreamstack
    stdexceptstreambufstringutilitytypeinfo
    valarrayvector   

    Table 3.3. C++ 1998 Library Headers for C Library Facilities

    cassertcerrnocctypecfloatciso646
    climitsclocalecmathcsetjmpcsignal
    cstdargcstddefcstdiocstdlibcstring
    ctimecwcharcwctype  

    C++0x include files. These are only available in C++0x compilation mode, i.e. -std=c++0x or -std=gnu++0x. -

    Table 3.4. C++ 200x Library Headers

    algorithmarraybitsetchronocomplex
    condition_variabledequeexceptionforward_listfstream
    functionalfutureinitalizer_listiomanipios
    iosfwdiostreamistreamiteratorlimits
    listlocalemapmemorymutex
    newnumericostreamqueuerandom
    ratioregexsetsstreamstack
    stdexceptstreambufstringsystem_errorthread
    tupletype_traitstypeinfounordered_mapunordered_set
    utilityvalarrayvector  

    Table 3.5. C++ 200x Library Headers for C Library Facilities

    cassertccomplexcctypecerrnocfenv
    cfloatcinttypesciso646climitsclocale
    cmathcsetjmpcsignalcstdargcstdbool
    cstddefcstdintcstdlibcstdiocstring
    ctgmathctimecucharcwcharcwctype

    +

    Table 3.4. C++ 200x Library Headers

    algorithmarraybitsetchronocomplex
    condition_variabledequeexceptionforward_listfstream
    functionalfutureinitalizer_listiomanipios
    iosfwdiostreamistreamiteratorlimits
    listlocalemapmemorymutex
    newnumericostreamqueuerandom
    ratioregexsetsstreamstack
    stdexceptstreambufstringsystem_errorthread
    tupletype_traitstypeinfounordered_mapunordered_set
    utilityvalarrayvector  

    Table 3.5. C++ 200x Library Headers for C Library Facilities

    cassertccomplexcctypecerrnocfenv
    cfloatcinttypesciso646climitsclocale
    cmathcsetjmpcsignalcstdargcstdbool
    cstddefcstdintcstdlibcstdiocstring
    ctgmathctimecucharcwcharcwctype

    In addition, TR1 includes as: -

    Table 3.6. C++ TR 1 Library Headers

    tr1/arraytr1/complextr1/memorytr1/functionaltr1/random
    tr1/regextr1/tupletr1/type_traitstr1/unordered_maptr1/unordered_set
    tr1/utility    

    Table 3.7. C++ TR 1 Library Headers for C Library Facilities

    tr1/ccomplextr1/cfenvtr1/cfloattr1/cmathtr1/cinttypes
    tr1/climitstr1/cstdargtr1/cstdbooltr1/cstdinttr1/cstdio
    tr1/cstdlibtr1/ctgmathtr1/ctimetr1/cwchartr1/cwctype

    Decimal floating-point arithmetic is available if the C++ +

    Table 3.6. C++ TR 1 Library Headers

    tr1/arraytr1/complextr1/memorytr1/functionaltr1/random
    tr1/regextr1/tupletr1/type_traitstr1/unordered_maptr1/unordered_set
    tr1/utility    

    Table 3.7. C++ TR 1 Library Headers for C Library Facilities

    tr1/ccomplextr1/cfenvtr1/cfloattr1/cmathtr1/cinttypes
    tr1/climitstr1/cstdargtr1/cstdbooltr1/cstdinttr1/cstdio
    tr1/cstdlibtr1/ctgmathtr1/ctimetr1/cwchartr1/cwctype

    Decimal floating-point arithmetic is available if the C++ compiler supports scalar decimal floating-point types defined via __attribute__((mode(SD|DD|LD))). -

    Table 3.8. C++ TR 24733 Decimal Floating-Point Header

    decimal/decimal

    +

    Table 3.8. C++ TR 24733 Decimal Floating-Point Header

    decimal/decimal

    Also included are files for the C++ ABI interface: -

    Table 3.9. C++ ABI Headers

    cxxabi.hcxxabi_forced.h

    +

    Table 3.9. C++ ABI Headers

    cxxabi.hcxxabi_forced.h

    And a large variety of extensions. -

    Table 3.10. Extension Headers

    ext/algorithmext/atomicity.hext/array_allocator.hext/bitmap_allocator.hext/cast.h
    ext/codecvt_specializations.hext/concurrence.hext/debug_allocator.hext/enc_filebuf.hext/extptr_allocator.h
    ext/functionalext/iteratorext/malloc_allocator.hext/memoryext/mt_allocator.h
    ext/new_allocator.hext/numericext/numeric_traits.hext/pb_ds/assoc_container.hext/pb_ds/priority_queue.h
    ext/pod_char_traits.hext/pool_allocator.hext/rb_treeext/ropeext/slist
    ext/stdio_filebuf.hext/stdio_sync_filebuf.hext/throw_allocator.hext/typelist.hext/type_traits.h
    ext/vstring.h    

    Table 3.11. Extension Debug Headers

    debug/bitsetdebug/dequedebug/listdebug/mapdebug/set
    debug/stringdebug/unordered_mapdebug/unordered_setdebug/vector 

    Table 3.12. Extension Profile Headers

    profile/bitsetprofile/dequeprofile/listprofile/map
    profile/setprofile/unordered_mapprofile/unordered_setprofile/vector

    Table 3.13. Extension Parallel Headers

    parallel/algorithmparallel/numeric

    A few simple rules. +

    Table 3.10. Extension Headers

    ext/algorithmext/atomicity.hext/array_allocator.hext/bitmap_allocator.hext/cast.h
    ext/codecvt_specializations.hext/concurrence.hext/debug_allocator.hext/enc_filebuf.hext/extptr_allocator.h
    ext/functionalext/iteratorext/malloc_allocator.hext/memoryext/mt_allocator.h
    ext/new_allocator.hext/numericext/numeric_traits.hext/pb_ds/assoc_container.hext/pb_ds/priority_queue.h
    ext/pod_char_traits.hext/pool_allocator.hext/rb_treeext/ropeext/slist
    ext/stdio_filebuf.hext/stdio_sync_filebuf.hext/throw_allocator.hext/typelist.hext/type_traits.h
    ext/vstring.h    

    Table 3.11. Extension Debug Headers

    debug/bitsetdebug/dequedebug/listdebug/mapdebug/set
    debug/stringdebug/unordered_mapdebug/unordered_setdebug/vector 

    Table 3.12. Extension Profile Headers

    profile/bitsetprofile/dequeprofile/listprofile/map
    profile/setprofile/unordered_mapprofile/unordered_setprofile/vector

    Table 3.13. Extension Parallel Headers

    parallel/algorithmparallel/numeric

    A few simple rules.

    First, mixing different dialects of the standard headers is not possible. It's an all-or-nothing affair. Thus, code like 

    @@ -101,4 +101,4 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
 . /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream
 . /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string

    The exclamation point to the left of the stdc++.h.gch listing means that the generated PCH file was used, and thus the

    Detailed information about creating precompiled header files can be found in the GCC documentation. -

    Prev Up Next
    Chapter 3. Using Home Macros
    +

    Prev Up Next
    Chapter 3. Using Home Macros
    diff --git a/libstdc++-v3/doc/html/manual/using_macros.html b/libstdc++-v3/doc/html/manual/using_macros.html index 3e124e90984..6fdd4bd8af0 100644 --- a/libstdc++-v3/doc/html/manual/using_macros.html +++ b/libstdc++-v3/doc/html/manual/using_macros.html @@ -1,6 +1,6 @@ -Macros
    Macros
    Prev Chapter 3. Using Next

    +Macros

    Macros
    Prev Chapter 3. Using Next

    All library macros begin with _GLIBCXX_.

    Furthermore, all pre-processor macros, switches, and @@ -74,4 +74,4 @@

    _GLIBCXX_PROFILE

    Undefined by default. When defined, compiles user code using the profile mode. -

    Prev Up Next
    Headers Home Namespaces
    +

    Prev Up Next
    Headers Home Namespaces
    diff --git a/libstdc++-v3/doc/html/manual/using_namespaces.html b/libstdc++-v3/doc/html/manual/using_namespaces.html index ffd6c6f6376..17aeea322ad 100644 --- a/libstdc++-v3/doc/html/manual/using_namespaces.html +++ b/libstdc++-v3/doc/html/manual/using_namespaces.html @@ -1,6 +1,6 @@ -Namespaces
    Namespaces
    Prev Chapter 3. Using Next

    There are three main namespaces. +Namespaces

    Namespaces
    Prev Chapter 3. Using Next

    There are three main namespaces.

    Prev Up Next
    Macros Home Linking
    +

    Prev Up Next
    Macros Home Linking
    diff --git a/libstdc++-v3/doc/html/manual/utilities.html b/libstdc++-v3/doc/html/manual/utilities.html index 61dc2c8c862..8b718138812 100644 --- a/libstdc++-v3/doc/html/manual/utilities.html +++ b/libstdc++-v3/doc/html/manual/utilities.html @@ -1,17 +1,17 @@ -Chapter 6.  Utilities
    Chapter 6.  +Chapter 6.  Utilities
    Chapter 6.  Utilities
    Prev Part II.  Standard Contents  Next

    Table of Contents

    Functors
    Pairs
    Memory
    Allocators
    auto_ptr
    shared_ptr
    Traits

    If you don't know what functors are, you're not alone. Many people + +

    Table of Contents

    Functors
    Pairs
    Memory
    Allocators
    Requirements
    Design Issues
    Implementation
    Interface Design
    Selecting Default Allocation Policy
    Disabling Memory Caching
    Using a Specific Allocator
    Custom Allocators
    Extension Allocators
    auto_ptr
    Limitations
    Use in Containers
    shared_ptr
    Requirements
    Design Issues
    Implementation
    Class Hierarchy
    Thread Safety
    Selecting Lock Policy
    Dual C++0x and TR1 Implementation
    Related functions and classes
    Use
    Examples
    Unresolved Issues
    Acknowledgments
    Traits

    If you don't know what functors are, you're not alone. Many people get slightly the wrong idea. In the interest of not reinventing the wheel, we will refer you to the introduction to the functor concept written by SGI as chapter of their STL, in their http://www.sgi.com/tech/stl/functors.html. -

    Prev Up Next
    Concept Checking Home Pairs
    +

    Prev Up Next
    Concept Checking Home Pairs
    diff --git a/libstdc++-v3/doc/html/spine.html b/libstdc++-v3/doc/html/spine.html deleted file mode 100644 index e3522b7daaf..00000000000 --- a/libstdc++-v3/doc/html/spine.html +++ /dev/null @@ -1,62 +0,0 @@ - - -The GNU C++ Library
    The GNU C++ Library
       Next

    Table of Contents

    The GNU C++ Library Manual
    I. - Introduction - -
    1. Status
    Implementation Status
    C++ 1998/2003
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs
    2. Setup
    Prerequisites
    Configure
    Make
    3. Using
    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Data Race Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis
    II. - Standard Contents -
    4. - Support - -
    Types
    Fundamental Types
    Numeric Properties
    NULL
    Dynamic Memory
    Termination
    Termination Handlers
    Verbose Terminate Handler
    5. - Diagnostics - -
    Exceptions
    API Reference
    Adding Data to exception
    Concept Checking
    6. - Utilities - -
    Functors
    Pairs
    Memory
    Allocators
    auto_ptr
    shared_ptr
    Traits
    7. - Strings - -
    String Classes
    Simple Transformations
    Case Sensitivity
    Arbitrary Character Types
    Tokenizing
    Shrink to Fit
    CString (MFC)
    8. - Localization - -
    Locales
    locale
    Facets
    ctype
    codecvt
    messages
    9. - Containers - -
    Sequences
    list
    vector
    Associative
    Insertion Hints
    bitset
    Interacting with C
    Containers vs. Arrays
    10. - Iterators - -
    Predefined
    Iterators vs. Pointers
    One Past the End
    11. - Algorithms - -
    Mutating
    swap
    12. - Numerics - -
    Complex
    complex Processing
    Generalized Operations
    Interacting with C
    Numerics vs. Arrays
    C99
    13. - Input and Output - -
    Iostream Objects
    Stream Buffers
    Derived streambuf Classes
    Buffering
    Memory Based Streams
    Compatibility With strstream
    File Based Streams
    Copying a File
    Binary Input and Output
    Interacting with C
    Using FILE* and file descriptors
    Performance
    14. - Atomics - -
    API Reference
    15. - Concurrency - -
    API Reference
    III. - Extensions - -
    16. Compile Time Checks
    17. Debug Mode
    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    Other Implementations
    18. Parallel Mode
    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Implementation Namespaces
    Testing
    Bibliography
    19. Profile Mode
    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Algorithms
    Data Locality
    Multithreaded Data Access
    Statistics
    Bibliography
    20. Allocators
    mt_allocator
    Intro
    Design Issues
    Implementation
    Single Thread Example
    Multiple Thread Example
    bitmap_allocator
    Design
    Implementation
    21. Containers
    Policy Based Data Structures
    HP/SGI
    Deprecated HP/SGI
    22. Utilities
    23. Algorithms
    24. Numerics
    25. Iterators
    26. Input and Output
    Derived filebufs
    27. Demangling
    28. Concurrency
    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use
    IV. - Appendices -
    A. - Contributing - -
    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Design Notes
    B. - Porting and Maintenance - -
    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Docbook
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Running the Testsuite
    Writing a new test case
    Test Harness and Utilities
    Special Topics
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    Second
    Third
    C. - Free Software Needs Free Documentation - -
    D. - GNU General Public License version 3 -
    E. GNU Free Documentation License
    The GNU C++ Library API Reference
    Frequently Asked Questions
       Next
       The GNU C++ Library Manual
    diff --git a/libstdc++-v3/doc/xml/api.xml b/libstdc++-v3/doc/xml/api.xml index dcd88d7e360..7c02dffc841 100644 --- a/libstdc++-v3/doc/xml/api.xml +++ b/libstdc++-v3/doc/xml/api.xml @@ -20,12 +20,12 @@ - License + License - + The GNU C++ library sources have been specially formatted so that with the proper invocation of another tool (Doxygen), a set of @@ -77,6 +77,12 @@ + + + for the 4.6 release + + + "the latest collection" diff --git a/libstdc++-v3/doc/xml/manual/spine.xml b/libstdc++-v3/doc/xml/manual/spine.xml index fd4b6fd910a..806f4ec118d 100644 --- a/libstdc++-v3/doc/xml/manual/spine.xml +++ b/libstdc++-v3/doc/xml/manual/spine.xml @@ -1,11 +1,21 @@ - + - + The GNU C++ Library Manual + 2000 + 2001 + 2002 + 2003 + 2004 + 2005 + 2006 + 2007 + 2008 2009 2010 2011 @@ -13,11 +23,128 @@ FSF - - - License - - + + + + + + + + + + + PaoloCarlini + + TR1, LWG Active, Closed, Defects lists. + + + + PhilEdwards + + Originating author, started HOWTO and FAQ, worked on sections + Demangling, Macros, Strings, Iterators, Backwards + Compatibility, SGI Extensions, Configure, Build, Install. + + + + DougGregor + + Debug Mode, TR1 function objects + + + + BenjaminKosnik + + Allocators, ABI, API evolution and deprecation history, + Backwards Compatibility, Thread, Debug Support, Locales, + Facets, Parallel Mode, Headers, Namespaces, Construction and + Structure, Using Exceptions, DocBook conversion and layout. + + + + + DhruvMatani + + bitmap_allocator + + + + JasonMerrill + + License, __verbose_terminate_handler + + + + MarkMitchell + + Porting + + + + NathanMyers + + Referenced counted string, C++1998 implementation status. + + + + FelixNatter + + Namespace composition, Backwards Compatibility. + + + + + StefanOlsson + + mt_allocator + + + + SilviusRus + + Profile mode + + + + JohannesSingler + + Parallel mode + + + + AmiTavory + + Policy Based Data Structures, Associative Containers, Unordered + Containers. + + + + JonathanWakely + + shared_ptr, markup editing and styling + + + + + diff --git a/libstdc++-v3/doc/xml/spine.xml b/libstdc++-v3/doc/xml/spine.xml index 5b12d48547d..5fd913e94d4 100644 --- a/libstdc++-v3/doc/xml/spine.xml +++ b/libstdc++-v3/doc/xml/spine.xml @@ -1,150 +1,68 @@ - - - - The GNU C++ Library +The GNU C++ Library + - - 2000 - 2001 - 2002 - 2003 - 2004 - 2005 - 2006 - 2007 - 2008 - 2009 - 2010 - 2011 - - FSF - - + + + ISO C++ + + + runtime + + + library + + + + Short Contents - + + Copyright 2008, 2009, 2011 + FSF + + - + + - - - - + + + Manual + + - PaoloCarlini - - TR1, LWG Active, Closed, Defects lists. - - + + + Frequently Asked Questions + + - PhilEdwards - - Originating author, started HOWTO and FAQ, worked on sections - Demangling, Macros, Strings, Iterators, Backwards - Compatibility, SGI Extensions, Configure, Build, Install. - - + + + API and Source Documentation + + - DougGregor - - Debug Mode, TR1 function objects - - - - BenjaminKosnik - - Allocators, ABI, API evolution and deprecation history, - Backwards Compatibility, Thread, Debug Support, Locales, - Facets, Parallel Mode, Headers, Namespaces, Construction and - Structure, Using Exceptions, DocBook conversion and layout. - - - - - DhruvMatani - - bitmap_allocator - - - - JasonMerrill - - License, __verbose_terminate_handler - - - - MarkMitchell - - Porting - - - - NathanMyers - - Referenced counted string, C++1998 implementation status. - - - - FelixNatter - - Namespace composition, Backwards Compatibility. - - - - - StefanOlsson - - mt_allocator - - - - SilviusRus - - Profile mode - - - - JohannesSingler - - Parallel mode - - - - AmiTavory - - Policy Based Data Structures, Associative Containers, Unordered - Containers. - - - - JonathanWakely - - shared_ptr, markup editing and styling - - - - + + +