From patchwork Wed May 2 23:21:21 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 156575 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) by ozlabs.org (Postfix) with SMTP id 13F97B6FA9 for ; Thu, 3 May 2012 09:21:46 +1000 (EST) Comment: DKIM? See http://www.dkim.org DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d=gcc.gnu.org; s=default; x=1336605707; h=Comment: DomainKey-Signature:Received:Received:Received:Received: MIME-Version:Received:Received:Date:Message-ID:Subject:From:To: Content-Type:Mailing-List:Precedence:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:Sender:Delivered-To; bh=/cPdUW1 oBgEZ5x+VgICOP34j1uY=; b=KQeGtcOJ1wm5Pxtk9GAjuW1KR2UC9tMFwXJCs42 RNDUuaTOhyMrMhJRjxeD5VHC1DWWlQ5BBBbBLYDIUZrnk68EuHvtYeP1X9UqdnaO MmJJH92OU2b8KbDGOa9reHUP8Z0aLinMeFJcRFrRmUi8SBvaW+sBcOjG+zbAjnFI 0m1M= Comment: DomainKeys? See http://antispam.yahoo.com/domainkeys DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=default; d=gcc.gnu.org; h=Received:Received:X-SWARE-Spam-Status:X-Spam-Check-By:Received:Received:MIME-Version:Received:Received:Date:Message-ID:Subject:From:To:Content-Type:Mailing-List:Precedence:List-Id:List-Unsubscribe:List-Archive:List-Post:List-Help:Sender:Delivered-To; b=M9cekjxuVdYjSuR8bgCUJyOsguohL+Br3YnHnP6C4pAj93jMAiVDphRsjp81Hp +y+um8ih5nD1f60zkGoN43Au5j4jL9zqddv9DbyOmn6zBTIz1furviN12b7c+3zb gS93Dplv5gTI2hdOLR/fOzhPtd9hkzRit1oxiLNri/VWI=; Received: (qmail 7315 invoked by alias); 2 May 2012 23:21:38 -0000 Received: (qmail 7298 invoked by uid 22791); 2 May 2012 23:21:36 -0000 X-SWARE-Spam-Status: No, hits=-4.2 required=5.0 tests=AWL, BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, FREEMAIL_FROM, KHOP_RCVD_TRUST, RCVD_IN_DNSWL_LOW, RCVD_IN_HOSTKARMA_YE, TW_CX, TW_DC X-Spam-Check-By: sourceware.org Received: from mail-lb0-f175.google.com (HELO mail-lb0-f175.google.com) (209.85.217.175) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 02 May 2012 23:21:23 +0000 Received: by lbol5 with SMTP id l5so754968lbo.20 for ; Wed, 02 May 2012 16:21:21 -0700 (PDT) MIME-Version: 1.0 Received: by 10.112.24.164 with SMTP id v4mr4779lbf.52.1336000881412; Wed, 02 May 2012 16:21:21 -0700 (PDT) Received: by 10.112.59.230 with HTTP; Wed, 2 May 2012 16:21:21 -0700 (PDT) Date: Thu, 3 May 2012 00:21:21 +0100 Message-ID: Subject: [v3] update outdated allocator docs From: Jonathan Wakely To: "libstdc++" , gcc-patches Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Several places in the manual still imply mt_allocator is the default or refer to GLIBCXX_FORCE_NEW as affecting the default allocator, which hasn't been true since GCC 3.3! * doc/xml/faq.xml: Update outdated allocator documentation. * doc/xml/manual/allocator.xml: Likewise. * doc/xml/manual/debug.xml: Likewise. * doc/xml/manual/evolution.xml: Likewise. * doc/xml/manual/using.xml: Likewise. Tested x86_64-linux, committed to trunk. commit 54ea46758e35adc8b42ee35dafdf0b43e9980104 Author: Jonathan Wakely Date: Thu May 3 00:12:48 2012 +0100 * doc/xml/faq.xml: Update outdated allocator documentation. * doc/xml/manual/allocator.xml: Likewise. * doc/xml/manual/debug.xml: Likewise. * doc/xml/manual/evolution.xml: Likewise. * doc/xml/manual/using.xml: Likewise. diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml index e2cf49a..1408bd2 100644 --- a/libstdc++-v3/doc/xml/faq.xml +++ b/libstdc++-v3/doc/xml/faq.xml @@ -935,8 +935,8 @@ A few people have reported that the standard containers appear to leak memory when tested with memory checkers such as valgrind. - The library's default allocators keep free memory in a pool - for later reuse, rather than returning it to the OS. Although + Under some configurations the library's allocators keep free memory in a + pool for later reuse, rather than returning it to the OS. Although this memory is always reachable by the library and is never lost, memory debugging tools can report it as a leak. If you want to test the library for memory leaks please read diff --git a/libstdc++-v3/doc/xml/manual/allocator.xml b/libstdc++-v3/doc/xml/manual/allocator.xml index 55dc808..911aaf5 100644 --- a/libstdc++-v3/doc/xml/manual/allocator.xml +++ b/libstdc++-v3/doc/xml/manual/allocator.xml @@ -103,7 +103,7 @@ implements the simple operator new and operator delete semantics, while __gnu_cxx::malloc_allocator implements much the same thing, only with the C language functions - std::malloc and free. + std::malloc and std::free. @@ -236,12 +236,12 @@ In use, allocator may allocate and - deallocate using implementation-specified strategies and - heuristics. Because of this, every call to an allocator object's + deallocate using implementation-specific strategies and + heuristics. Because of this, a given call to an allocator object's allocate member function may not actually - call the global operator new. This situation is also duplicated - for calls to the deallocate member - function. + call the global operator new and a given call to + to the deallocate member function may not + call operator delete. @@ -250,7 +250,7 @@ In particular, this can make debugging memory errors more - difficult, especially when using third party tools like valgrind or + difficult, especially when using third-party tools like valgrind or debug versions of new. @@ -258,9 +258,9 @@ There are various ways to solve this problem. One would be to use a custom allocator that just called operators new and delete - directly, for every allocation. (See + directly, for every allocation. (See the default allocator, include/ext/new_allocator.h, for instance.) - However, that option would involve changing source code to use + However, that option may involve changing source code to use a non-default allocator. Another option is to force the default allocator to remove caching and pools, and to directly allocate with every call of allocate and @@ -271,8 +271,8 @@ - To globally disable memory caching within the library for the - default allocator, merely set + To globally disable memory caching within the library for some of + the optional non-default allocators, merely set GLIBCXX_FORCE_NEW (with any value) in the system's environment before running the program. If your program crashes with GLIBCXX_FORCE_NEW in the @@ -472,7 +472,8 @@ A high-performance fixed-size allocator with exponentially-increasing allocations. It has its own - documentation, found here. + chapter + in the documentation. @@ -483,7 +484,8 @@ 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. + chapter + in the documentation. diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml index 0a24c96..7a984bb 100644 --- a/libstdc++-v3/doc/xml/manual/debug.xml +++ b/libstdc++-v3/doc/xml/manual/debug.xml @@ -116,13 +116,13 @@ 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 - std::allocator is a high-performance pool allocator, and can + In a nutshell, the optional mt_allocator + is a high-performance pool allocator, and can give the mistaken impression that in a suspect executable, memory is being leaked, when in reality the memory "leak" is a pool being used by the library's allocator and is reclaimed after program diff --git a/libstdc++-v3/doc/xml/manual/evolution.xml b/libstdc++-v3/doc/xml/manual/evolution.xml index 145c11f..ce8c14e 100644 --- a/libstdc++-v3/doc/xml/manual/evolution.xml +++ b/libstdc++-v3/doc/xml/manual/evolution.xml @@ -81,8 +81,11 @@ Removal of ext/tree, moved to For GCC releases from 2.95 through the 3.1 series, defining __USE_MALLOC on the gcc command line would change the default allocation strategy to instead use malloc and - free. (This same functionality is now spelled _GLIBCXX_FORCE_NEW, see - this page + free. For the 3.2 and 3.3 release series the same + functionality was spelled _GLIBCXX_FORCE_NEW. From + GCC 3.4 onwards the functionality is enabled by setting + GLIBCXX_FORCE_NEW in the environment, see + the mt allocator chapter for details. diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml index 74a08ec..61190f5 100644 --- a/libstdc++-v3/doc/xml/manual/using.xml +++ b/libstdc++-v3/doc/xml/manual/using.xml @@ -847,17 +847,6 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe - _GLIBCXX_FORCE_NEW - - - Undefined by default. When defined, memory allocation and - allocators controlled by libstdc++ call operator new/delete - without caching and pooling. Configurable via - --enable-libstdcxx-allocator. ABI-changing. - - - - _GLIBCXX_CONCEPT_CHECKS