[v3] allocator documentation revamp
Jonathan Wakely
cow@compsoc.man.ac.uk
Wed Feb 25 13:02:00 GMT 2004
On Wed, Feb 11, 2004 at 07:15:20PM -0600, Benjamin Kosnik wrote:
> Not the final word, of course. I'm going to be off-line for a bit and
> wanted to get this in, so that people who wanted to do edits could go at
> it. (Editors, remember: diff -cp and ChangeLogs are required.)
OK, here's an edit, adds <link> tags to the <head>, so it's reachable by
navigation toolbars etc. and replaces spaces in name attributes with
underscores. Also adds <link> tags to new ext/mt_allocators.html file.
2004-02-25 Jonathan Wakely <redi@gcc.gnu.org>
* docs/html/20_util/howto.html, docs/html/20_util/allocator.html,
docs/html/ext/howto.html, docs/html/ext/mt_allocator.html:
Fix markup, more <link> tags.
* docs/html/documentation.html: Regenerate.
Will commit shortly, barring objections.
jon
--
"Accept the contradictions"
- The KLF
-------------- next part --------------
Index: docs/html/20_util/allocator.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/20_util/allocator.html,v
retrieving revision 1.1
diff -c -p -r1.1 allocator.html
*** docs/html/20_util/allocator.html 12 Feb 2004 01:11:47 -0000 1.1
--- docs/html/20_util/allocator.html 25 Feb 2004 12:50:32 -0000
***************
*** 11,16 ****
--- 11,20 ----
<meta name="GENERATOR" content="emacs and ten fingers" />
<title>Allocators and allocation</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
+ <link rel="Start" href="../documentation.html" type="text/html"
+ title="GNU C++ Standard Library" />
+ <link rel="Bookmark" href="howto.html" type="text/html"
+ title="General Utilities" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
</head>
<body>
***************
*** 35,41 ****
</p>
<h3 class="left">
! <a name="standard requirements">Standard requirements</a>
</h3>
<p>The C++ standard only gives a few directives in this area:
</p>
--- 39,45 ----
</p>
<h3 class="left">
! <a name="standard_requirements">Standard requirements</a>
</h3>
<p>The C++ standard only gives a few directives in this area:
</p>
***************
*** 74,80 ****
</p>
<h3 class="left">
! <a name="probs possibilities">Problems and Possibilities</a>
</h3>
<p>The easiest way of fulfilling the requirements is to call operator new
each time a container needs memory, and to call operator delete each
--- 78,84 ----
</p>
<h3 class="left">
! <a name="probs_possibilities">Problems and Possibilities</a>
</h3>
<p>The easiest way of fulfilling the requirements is to call operator new
each time a container needs memory, and to call operator delete each
***************
*** 256,262 ****
</p>
<h3 class="left">
! <a name="ext allocators">Other allocators</a>
</h3>
<p> Several other allocators are provided as part of this
implementation. The location of the extension allocators and their
--- 260,266 ----
</p>
<h3 class="left">
! <a name="ext_allocators">Other allocators</a>
</h3>
<p> Several other allocators are provided as part of this
implementation. The location of the extension allocators and their
***************
*** 381,387 ****
<h3 class="left">
! <a name="using custom allocators">Using a specific allocator</a>
</h3>
<p>You can specify different memory management schemes on a
per-container basis, by overriding the default
--- 385,391 ----
<h3 class="left">
! <a name="using_custom_allocators">Using a specific allocator</a>
</h3>
<p>You can specify different memory management schemes on a
per-container basis, by overriding the default
***************
*** 397,403 ****
<h3 class="left">
! <a name="custom allocators">Writing custom allocators</a>
</h3>
<p> Writing a portable C++ allocator would dictate that the
interface would look much like the one specified for <code>
--- 401,407 ----
<h3 class="left">
! <a name="custom_allocators">Writing custom allocators</a>
</h3>
<p> Writing a portable C++ allocator would dictate that the
interface would look much like the one specified for <code>
Index: docs/html/20_util/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/20_util/howto.html,v
retrieving revision 1.19
diff -c -p -r1.19 howto.html
*** docs/html/20_util/howto.html 12 Feb 2004 01:11:47 -0000 1.19
--- docs/html/20_util/howto.html 25 Feb 2004 12:50:32 -0000
***************
*** 18,23 ****
--- 18,25 ----
title="Diagnostics" />
<link rel="Next" href="../21_strings/howto.html" type="text/html"
title="Strings" />
+ <link rel="Bookmark" href="allocator.html" type="text/html"
+ title="Allocators and allocation" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</head>
Index: docs/html/ext/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/ext/howto.html,v
retrieving revision 1.43
diff -c -p -r1.43 howto.html
*** docs/html/ext/howto.html 12 Feb 2004 01:11:47 -0000 1.43
--- docs/html/ext/howto.html 25 Feb 2004 12:50:32 -0000
***************
*** 18,23 ****
--- 18,25 ----
title="Input/Output" />
<link rel="Bookmark" href="sgiexts.html" type="text/html"
title="SGI extensions" />
+ <link rel="Bookmark" href="mt_allocator.html" type="text/html"
+ title="__mt_alloc" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
</head>
<body>
Index: docs/html/ext/mt_allocator.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/ext/mt_allocator.html,v
retrieving revision 1.2
diff -c -p -r1.2 mt_allocator.html
*** docs/html/ext/mt_allocator.html 18 Feb 2004 01:21:10 -0000 1.2
--- docs/html/ext/mt_allocator.html 25 Feb 2004 12:50:32 -0000
***************
*** 5,16 ****
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
! <meta name="AUTHOR" content="Stefan Olsson <stefan@xapa.se>" />
<meta name="KEYWORDS" content="c++, libstdc++, g++, allocator, memory" />
<meta name="DESCRIPTION" content="Allocators and allocation" />
<meta name="GENERATOR" content="emacs and ten fingers" />
<title>A fixed-size, multi-thread optimized allocator</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
</head>
<body>
--- 5,19 ----
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
! <meta name="AUTHOR" content="Stefan Olsson <stefan@xapa.se>" />
<meta name="KEYWORDS" content="c++, libstdc++, g++, allocator, memory" />
<meta name="DESCRIPTION" content="Allocators and allocation" />
<meta name="GENERATOR" content="emacs and ten fingers" />
<title>A fixed-size, multi-thread optimized allocator</title>
<link rel="StyleSheet" href="../lib3styles.css" type="text/css" />
+ <link rel="Start" href="../documentation.html" type="text/html"
+ title="GNU C++ Standard Library" />
+ <link rel="Bookmark" href="howto.html" type="text/html" title="Extensions" />
<link rel="Copyright" href="../17_intro/license.html" type="text/html" />
</head>
<body>
*************** are initialized to their default values
*** 61,68 ****
</p>
<pre>
! template<typename _Tp> size_t
! __mt_alloc<_Tp>::_S_freelist_headroom = 10;
</pre>
<p>
--- 64,71 ----
</p>
<pre>
! template<typename _Tp> size_t
! __mt_alloc<_Tp>::_S_freelist_headroom = 10;
</pre>
<p>
*************** The _S_init() function:
*** 100,106 ****
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).
--- 103,109 ----
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).
*************** The _S_init() function:
*** 127,133 ****
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 ]
--- 130,136 ----
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 ]
*************** The _S_init() function:
*** 140,151 ****
</p>
<p>
- 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.
--- 143,154 ----
</p>
<p>
- 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 _S_init() function:
*** 155,161 ****
</p>
<p>
- 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
--- 158,164 ----
</p>
<p>
- 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
*************** This is the first two blocks in freelist
*** 194,200 ****
| | |
+----------------+ |
+----------------+ |
! | next* |<-+ (If next == NULL it's the last one on the list)
| |
| |
| |
--- 197,203 ----
| | |
+----------------+ |
+----------------+ |
! | next* |<-+ (If next == NULL it's the last one on the list)
| |
| |
| |
*************** assigned this id since they span from 1
*** 223,229 ****
</p>
<p>
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.
</p>
<p>
If the requested size is within limits we start by finding out from which
--- 226,232 ----
</p>
<p>
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.
</p>
<p>
If the requested size is within limits we start by finding out from which
*************** not when a deallocation occurs.
*** 297,303 ****
<p>
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.
</p>
--- 300,306 ----
<p>
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.
</p>
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.41
diff -c -p -r1.41 documentation.html
*** docs/html/documentation.html 12 Feb 2004 01:11:46 -0000 1.41
--- docs/html/documentation.html 25 Feb 2004 12:53:06 -0000
***************
*** 145,151 ****
<li><a href="20_util/howto.html#2"><code>auto_ptr</code> inside container classes</a></li>
<li><a href="20_util/howto.html#3">Functors</a></li>
<li><a href="20_util/howto.html#4">Pairs</a></li>
! <li><a href="20_util/allocator.html">Allocators and allocation</a></li>
</ul>
</li>
--- 145,151 ----
<li><a href="20_util/howto.html#2"><code>auto_ptr</code> inside container classes</a></li>
<li><a href="20_util/howto.html#3">Functors</a></li>
<li><a href="20_util/howto.html#4">Pairs</a></li>
! <li><a href="20_util/howto.html#5">Memory allocators</a></li>
</ul>
</li>
More information about the Libstdc++
mailing list