From 0f647e802efce6de25ee58b78b2bbd5bcf04d693 Mon Sep 17 00:00:00 2001 From: Andreas Huber Date: Tue, 5 Dec 2006 12:49:43 +0000 Subject: [PATCH] Merged L & C issue fixes & HTML conversions from trunk to branch. [SVN r36276] --- TODO.txt | 5 + doc/concepts.html | 507 ++++++-- doc/implementation/alignment.html | 1154 ++++++++++++----- doc/implementation/ct_gcd_lcm.html | 180 ++- doc/implementation/for.html | 220 +++- doc/implementation/gcd_lcm.html | 156 ++- doc/implementation/guard.html | 202 ++- doc/implementation/mutex.html | 167 ++- doc/implementation/object_pool.html | 111 +- doc/implementation/pool.html | 307 +++-- doc/implementation/pool_alloc.html | 142 +- doc/implementation/pool_construct.html | 107 +- .../simple_segregated_storage.html | 118 +- doc/implementation/singleton.html | 153 ++- doc/implementation/singleton_pool.html | 116 +- doc/index.html | 313 +++-- doc/interfaces.html | 172 +-- doc/interfaces/object_pool.html | 323 +++-- doc/interfaces/pool.html | 416 ++++-- doc/interfaces/pool_alloc.html | 244 ++-- doc/interfaces/simple_segregated_storage.html | 483 +++++-- doc/interfaces/singleton_pool.html | 345 +++-- doc/interfaces/user_allocator.html | 188 ++- doc/pool.css | 8 +- include/boost/pool/detail/for.m4 | 6 +- include/boost/pool/detail/pool_construct.bat | 11 +- include/boost/pool/detail/pool_construct.m4 | 12 +- include/boost/pool/detail/pool_construct.sh | 6 +- .../pool/detail/pool_construct_simple.bat | 6 +- .../pool/detail/pool_construct_simple.m4 | 6 +- .../pool/detail/pool_construct_simple.sh | 6 +- 31 files changed, 4261 insertions(+), 1929 deletions(-) diff --git a/TODO.txt b/TODO.txt index 37c4a9b..76f479a 100644 --- a/TODO.txt +++ b/TODO.txt @@ -1,3 +1,8 @@ +Copyright (C) 2000 Stephen Cleary + +Distributed under the Boost Software License, Version 1.0. (See accompany- +ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + Here's a list of things TODO on the Pool library; these things will be done on an "as-I-get-around-to-it" basis: . Evaluate changes necessary for MSVC 6sp4 (Could use some help from people who own MSVC...) . Create more exhaustive test/example files, possibly other timing tests; convert to the new Boost testing harness diff --git a/doc/concepts.html b/doc/concepts.html index 1565faf..86765d9 100644 --- a/doc/concepts.html +++ b/doc/concepts.html @@ -1,176 +1,407 @@ - - - -Pool Concepts - - - + -C++ Boost + + + + + -

Pool Concepts

+ Pool Concepts + -

-

-"Dynamic memory allocation has been a fundamental part of most computer systems since roughly 1960..."1 -
+ + C++ Boost -

-Everyone uses dynamic memory allocation. If you have ever called malloc or new, then you have used dynamic memory allocation. Most programmers have a tendency to treat the heap as a "magic bag": we ask it for memory, and it magically creates some for us. Sometimes we run into problems because the heap is not magic. +

Pool Concepts

-

-The heap is limited. Even on large systems (i.e., not embedded) with huge amounts of virtual memory available, there is a limit. Everyone is aware of the physical limit, but there is a more subtle, "virtual" limit, that limit at which your program (or the entire system) slows down due to the use of virtual memory. This virtual limit is much closer to your program than the physical limit, especially if you are running on a multitasking system. Therefore, when running on a large system, it is considered "nice" to make your program use as few resources as necessary, and release them as soon as possible. When using an embedded system, programmers usually have no memory to waste. +

+ "Dynamic memory allocation has been a fundamental part of most computer + systems since roughly 1960..."1 +
-

-The heap is complicated. It has to satisfy any type of memory request, for any size, and do it fast. The common approaches to memory management have to do with splitting the memory up into portions, and keeping them ordered by size in some sort of a tree or list structure. Add in other factors, such as locality and estimating lifetime, and heaps quickly become very complicated. So complicated, in fact, that there is no known "perfect" answer to the problem of how to do dynamic memory allocation. The diagrams below illustrate how most common memory managers work: for each chunk of memory, it uses part of that memory to maintain its internal tree or list structure. Even when a chunk is malloc'ed out to a program, the memory manager must "save" some information in it — usually just its size. Then, when the block is free'd, the memory manager can easily tell how large it is. +

Everyone uses dynamic memory allocation. If you have ever called + malloc or new, then you + have used dynamic memory allocation. Most programmers have a tendency to + treat the heap as a "magic bag": we ask it for memory, and it magically + creates some for us. Sometimes we run into problems because the heap is + not magic.

- - - - - - -
Memory block, not allocated
Memory not belonging to process
Memory used internally by memory allocator algorithm (usually 8-12 bytes)
Unused memory
Memory not belonging to process
+

The heap is limited. Even on large systems (i.e., not embedded) with + huge amounts of virtual memory available, there is a limit. Everyone is + aware of the physical limit, but there is a more subtle, "virtual" limit, + that limit at which your program (or the entire system) slows down due to + the use of virtual memory. This virtual limit is much closer to your + program than the physical limit, especially if you are running on a + multitasking system. Therefore, when running on a large system, it is + considered "nice" to make your program use as few resources as necessary, + and release them as soon as possible. When using an embedded system, + programmers usually have no memory to waste.

- - - - - - -
Memory block, allocated (used by program)
Memory not belonging to process
Memory used internally by memory allocator algorithm (usually 4 bytes)
Memory usable by program
Memory not belonging to process
+

The heap is complicated. It has to satisfy any type of memory request, + for any size, and do it fast. The common approaches to memory + management have to do with splitting the memory up into portions, and + keeping them ordered by size in some sort of a tree or list structure. Add + in other factors, such as locality and estimating lifetime, and heaps + quickly become very complicated. So complicated, in fact, that there is no + known "perfect" answer to the problem of how to do dynamic memory + allocation. The diagrams below illustrate how most common memory managers + work: for each chunk of memory, it uses part of that memory to maintain its + internal tree or list structure. Even when a chunk is malloc'ed out to a program, the memory manager must "save" + some information in it — usually just its size. Then, when the block + is free'd, the memory manager can easily tell how + large it is.

-

-Because of the complication of dynamic memory allocation, it is often inefficient in terms of time and/or space. Most memory allocation algorithms store some form of information with each memory block, either the block size or some relational information, such as its position in the internal tree or list structure. It is common for such "header fields" to take up one machine word in a block that is being used by the program. The obvious problem, then, is when small objects are dynamically allocated. For example, if ints were dynamically allocated, then automatically the algorithm will reserve space for the header fields as well, and we end up with a 50% waste of memory. Of course, this is a worst-case scenario. However, more modern programs are making use of small objects on the heap; and that is making this problem more and more apparent. Wilson et. al. state that an average-case memory overhead is about ten to twenty percent2. This memory overhead will grow higher as more programs use more smaller objects. It is this memory overhead that brings programs closer to the virtual limit. + + -

-In larger systems, the memory overhead is not as big of a problem (compared to the amount of time it would take to work around it), and thus is often ignored. However, there are situations where many allocations and/or deallocations of smaller objects are taking place as part of a time-critical algorithm, and in these situations, the system-supplied memory allocator is often too slow. +

+ + -

-Simple segregated storage addresses both of these issues. Almost all memory overhead is done away with, and all allocations can take place in a small amount of (amortized) constant time. However, this is done at the loss of generality; simple segregated storage only can allocate memory chunks of a single size. +

+ + -

-

+ + + -

-

Simple Segregated Storage

+ + + +
+ Memory block, not allocated +
Memory not + belonging to process
+ Memory used internally by memory allocator algorithm (usually 8-12 + bytes)
Unused + memory
Memory not + belonging to process
-

-Simple Segregated Storage is the basic idea behind the Boost Pool library. Simple Segregated Storage is the simplest, and probably the fastest, memory allocation/deallocation algorithm. It begins by partitioning a memory block into fixed-size chunks. Where the block comes from is not important until implementation time. A Pool is some object that uses Simple Segregated Storage in this fashion. To illustrate: + + -
+ Memory block, allocated (used by program) +
- - - - - - - -
Memory block, split into chunks
Memory not belonging to process
Chunk 0
Chunk 1
Chunk 2
Chunk 3
Memory not belonging to process
+ + Memory not + belonging to process + -

-Each of the chunks in any given block are always the same size. This is the fundamental restriction of Simple Segregated Storage: you cannot ask for chunks of different sizes. For example, you cannot ask a Pool of integers for a character, or a Pool of characters for an integer (assuming that characters and integers are different sizes). + + Memory used + internally by memory allocator algorithm (usually 4 bytes) + -

-Simple Segregated Storage works by interleaving a free list within the unused chunks. For example: + + Memory + usable by program + - - - - - - - - -
Memory block, with no chunks allocated
Memory not belonging to process
Chunk 0; points to Chunk 1
Chunk 1; points to Chunk 2
Chunk 2; points to Chunk 3
Chunk 3; end-of-list
Memory not belonging to process
+ + Memory not + belonging to process + + - - - - - - - - -
Memory block, with two chunks allocated
Memory not belonging to process
Chunk 0; points to Chunk 2
Chunk 1 (in use by process)
Chunk 2; end-of-list
Chunk 3 (in use by process)
Memory not belonging to process
+

Because of the complication of dynamic memory allocation, it is often + inefficient in terms of time and/or space. Most memory allocation + algorithms store some form of information with each memory block, either + the block size or some relational information, such as its position in the + internal tree or list structure. It is common for such "header fields" to + take up one machine word in a block that is being used by the program. The + obvious problem, then, is when small objects are dynamically allocated. For + example, if ints were dynamically allocated, then + automatically the algorithm will reserve space for the header fields as + well, and we end up with a 50% waste of memory. Of course, this is a + worst-case scenario. However, more modern programs are making use of small + objects on the heap; and that is making this problem more and more + apparent. Wilson et. al. state that an average-case memory + overhead is about ten to twenty percent2. + This memory overhead will grow higher as more programs use more smaller + objects. It is this memory overhead that brings programs closer to the + virtual limit.

-

-By interleaving the free list inside the chunks, each Simple Segregated Storage only has the overhead of a single pointer (the pointer to the first element in the list). It has no memory overhead for chunks that are in use by the process. +

In larger systems, the memory overhead is not as big of a problem + (compared to the amount of time it would take to work around it), and thus + is often ignored. However, there are situations where many allocations + and/or deallocations of smaller objects are taking place as part of a + time-critical algorithm, and in these situations, the system-supplied + memory allocator is often too slow.

-

-Simple Segregated Storage is also extremely fast. In the simplest case, memory allocation is merely removing the first chunk from the free list, a O(1) operation. In the case where the free list is empty, another block may have to be acquired and partitioned, which would result in an amortized O(1) time. Memory deallocation may be as simple as adding that chunk to the front of the free list, a O(1) operation. However, more complicated uses of Simple Segregated Storage may require a sorted free list, which makes deallocation O(N). +

Simple segregated storage addresses both of these issues. Almost all + memory overhead is done away with, and all allocations can take place in a + small amount of (amortized) constant time. However, this is done at the + loss of generality; simple segregated storage only can allocate memory + chunks of a single size.

+
-

-Simple Segregated Storage gives faster execution and less memory overhead than a system-supplied allocator, but at the loss of generality. A good place to use a Pool is in situations where many (noncontiguous) small objects may be allocated on the heap, or if allocation and deallocation of the same-sized objects happens repeatedly. +

Simple Segregated Storage

-

-

+

Simple Segregated Storage is the basic idea behind the Boost Pool + library. Simple Segregated Storage is the simplest, and probably the + fastest, memory allocation/deallocation algorithm. It begins by + partitioning a memory block into fixed-size + chunks. Where the block comes from is not important until + implementation time. A Pool is some object that uses Simple + Segregated Storage in this fashion. To illustrate:

-

-

References

+ + -

-

    -
  1. Doug Lea, A Memory Allocator. Available on the web at http://gee.cs.oswego.edu/dl/html/malloc.html
    2. -
  2. Paul R. Wilson, Mark S. Johnstone, Michael Neely, and David Boles, "Dynamic Storage Allocation: A Survey and Critical Review" in International Workshop on Memory Management, September 1995, pg. 28, 36. Available on the web at ftp://ftp.cs.utexas.edu/pub/garbage/allocsrv.ps
    3. -
+ + + -

-

Other Implementations

+ + + -

-Pool allocators are found in many programming languages, and in many variations. The beginnings of many implementations may be found in common programming literature; some of these are given below. Note that none of these are complete implementations of a Pool; most of these leave some aspects of a Pool as a user exercise. However, in each case, even though some aspects are missing, these examples use the same underlying concept of a Simple Segregated Storage described in this document. +

+ + -

-

+ + -
  • -"The C++ Programming Language", 3rd ed., by Bjarne Stroustrup, Section 19.4.2. Missing aspects: -
      -
    1. Not portable
      2. -
    2. Cannot handle allocations of arbitrary numbers of objects (this was left as an exercise)
      3. -
    3. Not thread-safe
      4. -
    4. Suffers from the static initialization problem
      5. -
    -
    • + + + -
  • -"MicroC/OS-II: The Real-Time Kernel", by Jean J. Labrosse, Chapter 7 and Appendix B.04. This is an example of the Simple Segregated Storage scheme at work in the internals of an actual OS. Missing aspects: -
      -
    1. Not portable (though this is OK, since it's part of its own OS)
      2. -
    2. Cannot handle allocations of arbitrary numbers of blocks (which is also OK, since this feature is not needed)
      3. -
    3. Requires non-intuitive user code to create and destroy the Pool
      4. -
    -
    • + + + +
    + Memory block, split into chunks +
    Memory not + belonging to process
    Chunk + 0
    Chunk + 1
    Chunk + 2
    Chunk + 3
    Memory not + belonging to process
    -
  • -"Efficient C++: Performance Programming Techniques", by Dov Bulka and David Mayhew, Chapters 6 and 7. This is a good example of iteratively developing a Pool solution; however, their premise (that the system-supplied allocation mechanism is hopelessly inefficient) is flawed on every system I've tested on. Run their timings on your system before you accept their conclusions. Missing aspects: -
      -
    1. Requires non-intuitive user code to create and destroy the Pool
      2. -
    -
    • +

    Each of the chunks in any given block are always the + same size. This is the fundamental restriction of Simple Segregated + Storage: you cannot ask for chunks of different sizes. For example, you + cannot ask a Pool of integers for a character, or a Pool of characters for + an integer (assuming that characters and integers are different sizes).

    -
  • -"Advanced C++: Programming Styles and Idioms", by James O. Coplien, Section 3.6. This has examples of both static and dynamic pooling. Missing aspects: -
      -
    1. Not thread-safe
      2. -
    2. The static pooling example is not portable
      3. -
    -
    • +

    Simple Segregated Storage works by interleaving a free list + within the unused chunks. For example:

    - + + -

    -

    + + + -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    + + -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    + + -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    + + - - + + + + + + + +
    + Memory block, with no chunks allocated +
    Memory not + belonging to process
    Chunk + 0; points to Chunk 1
    Chunk + 1; points to Chunk 2
    Chunk + 2; points to Chunk 3
    Chunk + 3; end-of-list
    Memory not + belonging to process
    + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Memory block, with two chunks allocated +
    Memory not + belonging to process
    Chunk + 0; points to Chunk 2
    Chunk + 1 (in use by process)
    Chunk + 2; end-of-list
    Chunk + 3 (in use by process)
    Memory not + belonging to process
    + +

    By interleaving the free list inside the chunks, each Simple Segregated + Storage only has the overhead of a single pointer (the pointer to the first + element in the list). It has no memory overhead for chunks that + are in use by the process.

    + +

    Simple Segregated Storage is also extremely fast. In the simplest case, + memory allocation is merely removing the first chunk from the free list, a + O(1) operation. In the case where the free list is empty, another block may + have to be acquired and partitioned, which would result in an amortized + O(1) time. Memory deallocation may be as simple as adding that chunk to the + front of the free list, a O(1) operation. However, more complicated uses of + Simple Segregated Storage may require a sorted free list, which makes + deallocation O(N).

    + +

    Simple Segregated Storage gives faster execution and less memory + overhead than a system-supplied allocator, but at the loss of generality. A + good place to use a Pool is in situations where many (noncontiguous) small + objects may be allocated on the heap, or if allocation and deallocation of + the same-sized objects happens repeatedly.

    +
    + +

    References

    + +
      +
    1. Doug Lea, A Memory Allocator. + Available on the web at http://gee.cs.oswego.edu/dl/html/malloc.html
      2. + +
    2. Paul R. Wilson, Mark S. Johnstone, Michael + Neely, and David Boles, "Dynamic Storage Allocation: A Survey and + Critical Review" in International Workshop on Memory Management, + September 1995, pg. 28, 36. Available on the web at ftp://ftp.cs.utexas.edu/pub/garbage/allocsrv.ps
      3. +
    + +

    Other Implementations

    + +

    Pool allocators are found in many programming languages, and in many + variations. The beginnings of many implementations may be found in common + programming literature; some of these are given below. Note that none of + these are complete implementations of a Pool; most of these leave some + aspects of a Pool as a user exercise. However, in each case, even though + some aspects are missing, these examples use the same underlying concept of + a Simple Segregated Storage described in this document.

    + + +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 + December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/alignment.html b/doc/implementation/alignment.html index 6051fe5..3aad2fd 100644 --- a/doc/implementation/alignment.html +++ b/doc/implementation/alignment.html @@ -1,383 +1,871 @@ - - - -Guaranteeing Alignment - - - + -C++ Boost + + + + + -

    Guaranteeing Alignment

    + Guaranteeing Alignment + -

    -

    Terminology

    + + C++ Boost -

    -Review the concepts document if you are not already familiar with it. Remember that block is a contiguous section of memory, which is partitioned or segregated into fixed-size chunks. These chunks are what are allocated and deallocated by the user. +

    Guaranteeing Alignment

    -

    -

    Overview

    +

    Terminology

    -

    -Each Pool has a single free list that can extend over a number of memory blocks. Thus, Pool also has a linked list of allocated memory blocks. Each memory block, by default, is allocated using new[], and all memory blocks are freed on destruction. It is the use of new[] that allows us to guarantee alignment. +

    Review the concepts document if you are + not already familiar with it. Remember that block is a contiguous + section of memory, which is partitioned or segregated + into fixed-size chunks. These chunks are what are + allocated and deallocated by the user.

    -

    -

    Proof of Concept: Guaranteeing Alignment

    +

    Overview

    -

    -Each block of memory is allocated as a POD type (specifically, an array of characters) through operator new[]. Let POD_size be the number of characters allocated. +

    Each Pool has a single free list that can + extend over a number of memory blocks. Thus, Pool + also has a linked list of allocated memory blocks. Each memory block, by + default, is allocated using new[], and all memory + blocks are freed on destruction. It is the use of new[] that allows us to guarantee alignment.

    -

    -

    Predicate 1: Arrays may not have padding

    +

    Proof of Concept: Guaranteeing Alignment

    -

    -This follows from the following quote: +

    Each block of memory is allocated as a POD type (specifically, an array + of characters) through operator new[]. Let + POD_size be the number of characters allocated.

    -

    -[5.3.3/2] (Expressions::Unary expressions::Sizeof) "... When applied to an array, the result is the total number of bytes in the array. This implies that the size of an array of n elements is n times the size of an element." +

    Predicate 1: Arrays may not have padding

    -

    -Therefore, arrays cannot contain padding, though the elements within the arrays may contain padding. +

    This follows from the following quote:

    -

    -

    Predicate 2: Any block of memory allocated as an array of characters through operator new[] (hereafter referred to as the block) is properly aligned for any object of that size or smaller

    +

    [5.3.3/2] (Expressions::Unary expressions::Sizeof) "... When applied to + an array, the result is the total number of bytes in the array. This implies + that the size of an array of n elements is n + times the size of an element."

    -

    -This follows from: +

    Therefore, arrays cannot contain padding, though the elements within the + arrays may contain padding.

    - +

    Predicate 2: Any block of memory allocated as an array of characters + through operator new[] (hereafter referred to as + the block) is properly aligned for any object of that size or + smaller

    -

    -

    Consider: imaginary object type Element of a size which is a multiple of some actual object size; assume sizeof(Element) > POD_size

    +

    This follows from:

    -

    -Note that an object of that size can exist. One object of that size is an array of the "actual" objects. +

    -

    -

    Corollary 1: The block is properly aligned for an array of Elements

    +

    Consider: imaginary object type Element of a size which is a + multiple of some actual object size; assume sizeof(Element) > POD_size

    -

    -This follows from Predicates 1 and 2, and the following quote: +

    Note that an object of that size can exist. One object of that + size is an array of the "actual" objects.

    -

    -[3.9/9] (Basic concepts::Types) "An object type is a (possibly cv-qualified) type that is not a function type, not a reference type, and not a void type." (Specifically, array types are object types.) +

    Note that the block is properly aligned for an Element. This directly + follows from Predicate 2.

    -

    -

    Corollary 2: For any pointer p and integer i, if p is properly aligned for the type it points to, then p + i (when well-defined) is properly aligned for that type; in other words, if an array is properly aligned, then each element in that array is properly aligned

    +

    Corollary 1: The block is properly aligned for an array of Elements

    -

    -There are no quotes from the Standard to directly support this argument, but it fits the common conception of the meaning of "alignment". +

    This follows from Predicates 1 and 2, and the following quote:

    -

    -Note that the conditions for p + i being well-defined are outlined in [5.7/5]. We do not quote that here, but only make note that it is well-defined if p and p + i both point into or one past the same array. +

    [3.9/9] (Basic concepts::Types) "An object type is a (possibly + cv-qualified) type that is not a function type, not a reference type, and + not a void type." (Specifically, array types are object types.)

    -

    -

    Let: sizeof(Element) be the least common multiple of sizes of several actual objects (T1, T2, T3, ...)

    +

    Corollary 2: For any pointer p and integer i, if p is + properly aligned for the type it points to, then p + i (when well-defined) + is properly aligned for that type; in other words, if an array is properly + aligned, then each element in that array is properly aligned

    -

    -

    Let: block be a pointer to the memory block, pe be (Element *) block, and pn be (Tn *) block

    +

    There are no quotes from the Standard to directly support this argument, + but it fits the common conception of the meaning of "alignment".

    -

    -

    Corollary 3: For each integer i, such that pe + i is well-defined, then for each n, there exists some integer jn such that pn + jn is well-defined and refers to the same memory address as pe + i

    +

    Note that the conditions for p + i being well-defined are outlined in + [5.7/5]. We do not quote that here, but only make note that it is + well-defined if p and p + i both point into or one past the same array.

    -

    -This follows naturally, since the memory block is an array of Elements, and for each n, sizeof(Element) % sizeof(Tn) == 0; thus, the boundary of each element in the array of Elements is also a boundary of each element in each array of Tn. +

    Let: sizeof(Element) be the least common multiple of sizes of several + actual objects (T1, T2, T3, ...)

    -

    -

    Theorem: For each integer i, such that pe + i is well-defined, that address (pe + i) is properly aligned for each type Tn

    +

    Let: block be a pointer to the memory block, pe be + (Element *) block, and pn be (Tn *) block

    -

    -Since pe + i is well-defined, then by Corollary 3, pn + jn is well-defined. It is properly aligned from Predicate 2 and Corollaries 1 and 2. +

    Corollary 3: For each integer i, such that pe + i is + well-defined, then for each n, there exists some integer + jn such that pn + jn is + well-defined and refers to the same memory address as pe + i

    -

    -

    Use of the Theorem

    +

    This follows naturally, since the memory block is an array of Elements, + and for each n, sizeof(Element) % sizeof(Tn) == 0; thus, the + boundary of each element in the array of Elements is also a boundary of each + element in each array of Tn.

    -

    -The proof above covers alignment requirements for cutting chunks out of a block. The implementation uses actual object sizes of: +

    Theorem: For each integer i, such that pe + i is well-defined, + that address (pe + i) is properly aligned for each type Tn

    - +

    Since pe + i is well-defined, then by Corollary 3, pn + jn + is well-defined. It is properly aligned from Predicate 2 and Corollaries 1 + and 2.

    -

    -Each block also contains a pointer to the next block; but that is stored as a pointer to void and cast when necessary, to simplify alignment requirements to the three types above. +

    Use of the Theorem

    -

    -Therefore, alloc_size is defined to be the lcm of the sizes of the three types above. +

    The proof above covers alignment requirements for cutting chunks out of a + block. The implementation uses actual object sizes of:

    -

    -

    A Look at the Memory Block

    + -

    -Here's an example memory block, where requested_size == sizeof(void *) == sizeof(size_type) == 4: +

    Each block also contains a pointer to the next block; but that is stored + as a pointer to void and cast when necessary, to simplify alignment + requirements to the three types above.

    - - +

    Therefore, alloc_size is defined to be the lcm + of the sizes of the three types above.

    -
    Memory block containing 4 chunks, showing overlying array structures; FLP = Interleaved Free List Pointer
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment +

    A Look at the Memory Block

    -
    Memory not belonging to process +

    Each memory block consists of three main sections. The first section is + the part that chunks are cut out of, and contains the interleaved free list. + The second section is the pointer to the next block, and the third section + is the size of the next block.

    -
    Chunks section (16 bytes) - (4 bytes) - FLP for Chunk 1 (4 bytes) - Chunk 1 (4 bytes) -
    (4 bytes) - FLP for Chunk 2 (4 bytes) - Chunk 2 (4 bytes) -
    (4 bytes) - FLP for Chunk 3 (4 bytes) - Chunk 3 (4 bytes) -
    (4 bytes) - FLP for Chunk 4 (4 bytes) - Chunk 4 (4 bytes) - -
    Pointer to next Block (4 bytes) - (4 bytes) - Pointer to next Block (4 bytes) - -
    Size of next Block (4 bytes) - Size of next Block (4 bytes) - -
    Memory not belonging to process -
    - -

    -To show a visual example of possible padding, here's an example memory block where requested_size == 8 and sizeof(void *) == sizeof(size_type) == 4: - - - - -
    Memory block containing 4 chunks, showing overlying array structures; FLP = Interleaved Free List Pointer
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment - -
    Memory not belonging to process - -
    Chunks section (32 bytes) - (4 bytes) - FLP for Chunk 1 (4 bytes) - Chunk 1 (8 bytes) -
    (4 bytes) - (4 bytes) -
    (4 bytes) - FLP for Chunk 2 (4 bytes) - Chunk 2 (8 bytes) -
    (4 bytes) - (4 bytes) -
    (4 bytes) - FLP for Chunk 3 (4 bytes) - Chunk 3 (8 bytes) -
    (4 bytes) - (4 bytes) -
    (4 bytes) - FLP for Chunk 4 (4 bytes) - Chunk 4 (8 bytes) -
    (4 bytes) - (4 bytes) - -
    Pointer to next Block (4 bytes) - (4 bytes) - Pointer to next Block (4 bytes) - -
    Size of next Block (4 bytes) - Size of next Block (4 bytes) - -
    Memory not belonging to process -
    - -

    -Finally, here is a convoluted example where the requested_size is 7, sizeof(void *) == 3, and sizeof(size_type) == 5, showing how the least common multiple guarantees alignment requirements even in the oddest of circumstances: - - - - -
    Memory block containing 2 chunks, showing overlying array structures
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment - -
    Memory not belonging to process - - - -
    Chunks section (210 bytes) - (5 bytes) - Interleaved free list pointer for Chunk 1 (15 bytes; 3 used) - Chunk 1 (105 bytes; 7 used) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - Interleaved free list pointer for Chunk 2 (15 bytes; 3 used) - Chunk 2 (105 bytes; 7 used) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) -
    (5 bytes) - (15 bytes) -
    (5 bytes) -
    (5 bytes) - - - -
    Pointer to next Block (15 bytes; 3 used) - (5 bytes) - Pointer to next Block (15 bytes; 3 used) -
    (5 bytes) -
    (5 bytes) - - - -
    Size of next Block (5 bytes; 5 used) - Size of next Block (5 bytes; 5 used) - -
    Memory not belonging to process -
    - -

    -

    How Contiguous Chunks are Handled

    - -

    -The theorem above guarantees all alignment requirements for allocating chunks and also implementation details such as the interleaved free list. However, it does so by adding padding when necessary; therefore, we have to treat allocations of contiguous chunks in a different way. - -

    -Using array arguments similar to the above, we can translate any request for contiguous memory for n objects of requested_size into a request for m contiguous chunks. m is simply ceil(n * requested_size / alloc_size), where alloc_size is the actual size of the chunks. To illustrate: - -

    -Here's an example memory block, where requested_size == 1 and sizeof(void *) == sizeof(size_type) == 4: - - - - -
    Memory block containing 4 chunks; requested_size is 1
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment - -
    Memory not belonging to process - -
    Chunks section (16 bytes) - (4 bytes) - FLP to Chunk 2 (4 bytes) - Chunk 1 (4 bytes) -
    (4 bytes) - FLP to Chunk 3 (4 bytes) - Chunk 2 (4 bytes) -
    (4 bytes) - FLP to Chunk 4 (4 bytes) - Chunk 3 (4 bytes) -
    (4 bytes) - FLP to end-of-list (4 bytes) - Chunk 4 (4 bytes) - -
    Pointer to next Block (4 bytes) - (4 bytes) - Ptr to end-of-list (4 bytes) - -
    Size of next Block (4 bytes) - 0 (4 bytes) - -
    Memory not belonging to process -
    - - - - -
    After user requests 7 contiguous elements of requested_size
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment - -
    Memory not belonging to process - -
    Chunks section (16 bytes) - (4 bytes) - (4 bytes) - 4 bytes in use by program -
    (4 bytes) - (4 bytes) - 3 bytes in use by program (1 byte unused) -
    (4 bytes) - FLP to Chunk 4 (4 bytes) - Chunk 3 (4 bytes) -
    (4 bytes) - FLP to end-of-list (4 bytes) - Chunk 4 (4 bytes) - -
    Pointer to next Block (4 bytes) - (4 bytes) - Ptr to end-of-list (4 bytes) - -
    Size of next Block (4 bytes) - 0 (4 bytes) - -
    Memory not belonging to process -
    +

    Each of these sections may contain padding as necessary to guarantee + alignment for each of the next sections. The size of the first section is + number_of_chunks * lcm(requested_size, sizeof(void *), sizeof(size_type)); + the size of the second section is lcm(sizeof(void *), sizeof(size_type); and + the size of the third section is sizeof(size_type).

    -

    -Then, when the user deallocates the contiguous memory, we can split it up into chunks again. +

    Here's an example memory block, where requested_size == sizeof(void *) == + sizeof(size_type) == 4:

    -

    -Note that the implementation provided for allocating contiguous chunks uses a linear instead of quadratic algorithm. This means that it may not find contiguous free chunks if the free list is not ordered. Thus, it is recommended to always use an ordered free list when dealing with contiguous allocation of chunks. (In the example above, if Chunk 1 pointed to Chunk 3 pointed to Chunk 2 pointed to Chunk 4, instead of being in order, the contiguous allocation algorithm would have failed to find any of the contiguous chunks). + + -

    -

    + + -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    + - - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Memory block containing 4 chunks, showing overlying array + structures; FLP = Interleaved Free List Pointer +
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment
    + Memory not belonging to process
    + Chunks section (16 bytes)(4 bytes)FLP for Chunk 1 + (4 bytes)Chunk 1 (4 + bytes)
    (4 bytes)FLP for Chunk + 2 (4 bytes)Chunk 2 (4 + bytes)
    (4 bytes)FLP for Chunk 3 + (4 bytes)Chunk 3 (4 + bytes)
    (4 bytes)FLP for Chunk + 4 (4 bytes)Chunk 4 (4 + bytes)
    Pointer to + next Block (4 bytes)(4 bytes)Pointer to next + Block (4 bytes)
    Size of next + Block (4 bytes)Size of next + Block (4 bytes)
    + Memory not belonging to process
    + +

    To show a visual example of possible padding, here's an example memory + block where requested_size == 8 and sizeof(void *) == sizeof(size_type) == + 4:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Memory block containing 4 chunks, showing overlying array + structures; FLP = Interleaved Free List Pointer +
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment
    + Memory not belonging to process
    + Chunks section (32 bytes)(4 bytes)FLP for Chunk 1 + (4 bytes) + Chunk 1 (8 bytes)
    (4 bytes)(4 bytes)
    (4 bytes)FLP for Chunk 2 + (4 bytes) + Chunk 2 (8 bytes)
    (4 bytes)(4 bytes)
    (4 bytes)FLP for Chunk 3 + (4 bytes) + Chunk 3 (8 bytes)
    (4 bytes)(4 bytes)
    (4 bytes)FLP for Chunk 4 + (4 bytes) + Chunk 4 (8 bytes)
    (4 bytes)(4 bytes)
    Pointer to + next Block (4 bytes)(4 bytes)Pointer to next + Block (4 bytes)
    Size of next + Block (4 bytes)Size of next + Block (4 bytes)
    + Memory not belonging to process
    + +

    Finally, here is a convoluted example where the requested_size is 7, + sizeof(void *) == 3, and sizeof(size_type) == 5, showing how the least + common multiple guarantees alignment requirements even in the oddest of + circumstances:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Memory block containing 2 chunks, showing overlying array structures +
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment
    + Memory not belonging to process
    + Chunks section (210 bytes)(5 bytes) + Interleaved free list pointer for Chunk 1 (15 bytes; 3 used) + Chunk 1 (105 bytes; 7 used)
    (5 bytes)
    (5 bytes)
    (5 bytes) + (15 bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes)(15 + bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes) + (15 bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes)(15 + bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes) + (15 bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes)(15 + bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes) + Interleaved free list pointer for Chunk 2 (15 bytes; 3 used) + Chunk 2 (105 bytes; 7 used)
    (5 bytes)
    (5 bytes)
    (5 bytes)(15 + bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes) + (15 bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes)(15 + bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes) + (15 bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes)(15 + bytes)
    (5 bytes)
    (5 bytes)
    (5 bytes) + (15 bytes)
    (5 bytes)
    (5 bytes) +
    + Pointer to next Block (15 bytes; 3 used)(5 bytes) + Pointer to next Block (15 bytes; 3 used)
    (5 bytes)
    (5 bytes) +
    Size of next + Block (5 bytes; 5 used)Size of next + Block (5 bytes; 5 used)
    + Memory not belonging to process
    + +

    How Contiguous Chunks are Handled

    + +

    The theorem above guarantees all alignment requirements for allocating + chunks and also implementation details such as the interleaved free list. + However, it does so by adding padding when necessary; therefore, we have to + treat allocations of contiguous chunks in a different way.

    + +

    Using array arguments similar to the above, we can translate any request + for contiguous memory for n objects of requested_size into a + request for m contiguous chunks. m is simply ceil(n * + requested_size / alloc_size), where alloc_size is the actual size of the + chunks. To illustrate:

    + +

    Here's an example memory block, where requested_size == 1 and sizeof(void + *) == sizeof(size_type) == 4:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Memory block containing 4 chunks; requested_size is 1 +
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment
    + Memory not belonging to process
    + Chunks section (16 bytes)(4 bytes)FLP to Chunk 2 + (4 bytes)Chunk 1 (4 + bytes)
    (4 bytes)FLP to Chunk 3 + (4 bytes)Chunk 2 (4 + bytes)
    (4 bytes)FLP to Chunk 4 + (4 bytes)Chunk 3 (4 + bytes)
    (4 bytes)FLP to + end-of-list (4 bytes)Chunk 4 (4 + bytes)
    Pointer to + next Block (4 bytes)(4 bytes)Ptr to + end-of-list (4 bytes)
    Size of next + Block (4 bytes)0 (4 bytes)
    + Memory not belonging to process
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + After user requests 7 contiguous elements of requested_size +
    Sectionssize_type alignmentvoid * alignmentrequested_size alignment
    + Memory not belonging to process
    + Chunks section (16 bytes)(4 bytes)(4 bytes)4 bytes in use + by program
    (4 bytes)(4 bytes)3 bytes in use + by program (1 byte unused)
    (4 bytes)FLP to Chunk 4 + (4 bytes)Chunk 3 (4 + bytes)
    (4 bytes)FLP to + end-of-list (4 bytes)Chunk 4 (4 + bytes)
    Pointer to + next Block (4 bytes)(4 bytes)Ptr to + end-of-list (4 bytes)
    Size of next + Block (4 bytes)0 (4 bytes)
    + Memory not belonging to process
    + +

    Then, when the user deallocates the contiguous memory, we can split it up + into chunks again.

    + +

    Note that the implementation provided for allocating contiguous chunks + uses a linear instead of quadratic algorithm. This means that it + may not find contiguous free chunks if the free list is not + ordered. Thus, it is recommended to always use an ordered free list when + dealing with contiguous allocation of chunks. (In the example above, if + Chunk 1 pointed to Chunk 3 pointed to Chunk 2 pointed to Chunk 4, instead of + being in order, the contiguous allocation algorithm would have failed to + find any of the contiguous chunks).

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/ct_gcd_lcm.html b/doc/implementation/ct_gcd_lcm.html index dd21604..8e41d6b 100644 --- a/doc/implementation/ct_gcd_lcm.html +++ b/doc/implementation/ct_gcd_lcm.html @@ -1,24 +1,28 @@ - - - -ct_gcd_lcm - Compile-Time GCD and LCM - - - + -C++ Boost + + + + + -

    ct_gcd_lcm - Compile-Time GCD and LCM

    + ct_gcd_lcm - Compile-Time GCD and LCM + -

    -

    Introduction

    + + C++ Boost -

    -detail/ct_gcd_lcm.hpp provides two compile-time algorithms: greatest common divisor and least common multiple. +

    ct_gcd_lcm - Compile-Time GCD and LCM

    -

    -

    Synopsis

    -
    namespace details {
+  
    Introduction
    
+
+  
    detail/ct_gcd_lcm.hpp provides two compile-time algorithms: greatest
+  common divisor and least common multiple.
    
+
+  
    Synopsis
    
+  
    +namespace details {
 namespace pool {
 
 template <unsigned A, unsigned B>
@@ -33,62 +37,120 @@ struct ct_lcm
 };
 
 } // namespace pool
-} // namespace details
    
+} // namespace details
+
    -

    -

    Semantics

    +

    Semantics

    - - - - -
    Symbol Table
    SymbolMeaning
    A, Bcompile-time unsigned integer constants[5.19/1]
    + + -
    + Symbol Table +
    - -
    Semantics
    ExpressionResult TypeValuePrecondition -
    ct_gcd<A, B>::valuecompile-time unsigned integer constantThe greatest common divisor of A and BA != 0 && B != 0 -
    ct_lcm<A, B>::valuecompile-time unsigned integer constantThe least common multiple of A and BA != 0 && B != 0 -
    + + Symbol -

    -

    Notes

    + Meaning + -

    -Since these are compile-time algorithms, violation of the preconditions will result in a compile-time error. + + A, B -

    -

    Dependencies

    + compile-time unsigned integer constants[5.19/1] + +
    - + + -

    -

    Selected Quotations from the Standard

    + + -

    - -5.19/1: Expressions: Constant Expressions: ". . . An integral constant expression can involve only literals (2.13), enumerators, const variables or static data members of integral or enumeration types initialized with constant expressions (8.5), non-type template parameters of integral or enumeration types, and sizeof expressions. Floating literals (2.13.3) can appear only if they are cast to integral or enumeration types. Only type conversions to integral or enumeration types can be used. In particular, except in sizeof expressions, functions, class objects, pointers, or references shall not be used, and assignment, increment, decrement, function-call, or comma operators shall not be used." +

    -

    -

    Future Directions

    + -

    -This header may be replaced by a Boost compile-time algorithms library. +

    + -

    -

    + + -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    + - - \ No newline at end of file + + + + + + + + + +
    + Semantics +
    ExpressionResult TypeValuePrecondition
    ct_gcd<A, B>::valuecompile-time unsigned integer constantThe greatest common divisor of A and + BA != 0 && B != 0
    ct_lcm<A, B>::valuecompile-time unsigned integer constantThe least common multiple of A and + BA != 0 && B != 0
    + +

    Notes

    + +

    Since these are compile-time algorithms, violation of the preconditions + will result in a compile-time error.

    + +

    Dependencies

    + + + +

    Selected Quotations from the Standard

    + +

    5.19/1: Expressions: Constant + Expressions: ". . . An integral constant expression can + involve only literals (2.13), enumerators, const + variables or static data members of integral or enumeration types + initialized with constant expressions (8.5), non-type template parameters + of integral or enumeration types, and sizeof + expressions. Floating literals (2.13.3) can appear only if they are cast to + integral or enumeration types. Only type conversions to integral or + enumeration types can be used. In particular, except in sizeof expressions, functions, class objects, pointers, or + references shall not be used, and assignment, increment, decrement, + function-call, or comma operators shall not be used."

    + +

    Future Directions

    + +

    This header may be replaced by a Boost compile-time algorithms + library.

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 + December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/for.html b/doc/implementation/for.html index 41d9858..21e0e10 100644 --- a/doc/implementation/for.html +++ b/doc/implementation/for.html @@ -1,75 +1,179 @@ - - - -for - m4 FOR Macro - - - + -C++ Boost + + + + + -

    for - m4 FOR Macro

    + for - m4 FOR Macro + -

    -

    Introduction

    + + C++ Boost -

    -detail/for.m4 provides BOOST_M4_FOR, an m4 macro that provides the equivalent of a #for preprocessor instruction. +

    for - m4 FOR Macro

    -

    -

    Usage

    +

    Introduction

    -

    -This macro must be used by an m4 file. This file assumes that the option -P is used, to force an m4_ prefix on all builtin symbols. +

    detail/for.m4 provides BOOST_M4_FOR, an + m4 macro that provides the equivalent of a #for preprocessor instruction.

    -

    -

    Arguments

    +

    Usage

    -
      -
    1. The name of a variable to hold the current value.
      2. -
    2. The starting value of the variable.
      3. -
    3. The ending value of the variable.
      4. -
    4. The text to repeat. This text may contain references to the variable, which will be replaced with the variable's current value.
      5. -
    5. The delimeter text (optional).
      6. -
    +

    This macro must be used by an m4 file. This file + assumes that the option -P is used, to force an + m4_ prefix on all builtin symbols.

    -

    -If called with the wrong number of arguments (less than 4 or more than 5), BOOST_M4_FOR will exit with an error. If the starting value ($2) is greater than or equal to the ending value ($3), BOOST_M4_FOR will do nothing. Otherwise, it will repeat the text ($4), binding the variable ($1) to the values in the range [starting value ($2), ending value ($3)), and repeat the delimeter text ($5) in-between each occurrence of the repeat text ($4). +

    Arguments

    -

    -

    Examples

    +
      +
    1. The name of a variable to hold the current value.
      2. -

      -Note of the quotation marks (") used in the table below are in the input or output; they are shown to delimit whitespace. All code within a pair of quotation marks is intended to be on one line. +

    2. The starting value of the variable.
      3. -

      - - - - - - - - - - - - - - -
      InputOutput
      "BOOST_M4_FOR(i, 1, 3)"Boost m4 script: BOOST_M4_FOR: Wrong number of arguments (3)
      "BOOST_M4_FOR(i, 1, 3, i, ` ', 13)"Boost m4 script: BOOST_M4_FOR: Wrong number of arguments (6)
      "BOOST_M4_FOR(i, 7, 0, i )"(nothing)
      "BOOST_M4_FOR(i, 0, 0, i )"(nothing)
      "BOOST_M4_FOR(i, 0, 7, i )""0 1 2 3 4 5 6 "
      "BOOST_M4_FOR(i, -13, -10, i )""-13 -12 -11 "
      "BOOST_M4_FOR(i, 0, 8, BOOST_M4_FOR(j, 0, 4, (i, j) )"
      ")"      		"(0, 0) (0, 1) (0, 2) (0, 3) "
      "(1, 0) (1, 1) (1, 2) (1, 3) "
      "(2, 0) (2, 1) (2, 2) (2, 3) "
      "(3, 0) (3, 1) (3, 2) (3, 3) "
      "(4, 0) (4, 1) (4, 2) (4, 3) "
      "(5, 0) (5, 1) (5, 2) (5, 3) "
      "(6, 0) (6, 1) (6, 2) (6, 3) "
      "(7, 0) (7, 1) (7, 2) (7, 3) "
      ""
      "BOOST_M4_FOR(i, 7, 0, i, |)"(nothing)
      "BOOST_M4_FOR(i, 0, 0, i, |)"(nothing)
      "BOOST_M4_FOR(i, 0, 7, i, |)""0|1|2|3|4|5|6"
      "BOOST_M4_FOR(i, -13, -10, i, `, ')""-13, -12, -11"
      "BOOST_M4_FOR(i, 0, 8, `[BOOST_M4_FOR(j, 0, 4, (i, j), `, ')]', `,"
      "')"      		"[(0, 0), (0, 1), (0, 2), (0, 3)],"
      "[(1, 0), (1, 1), (1, 2), (1, 3)],"
      "[(2, 0), (2, 1), (2, 2), (2, 3)],"
      "[(3, 0), (3, 1), (3, 2), (3, 3)],"
      "[(4, 0), (4, 1), (4, 2), (4, 3)],"
      "[(5, 0), (5, 1), (5, 2), (5, 3)],"
      "[(6, 0), (6, 1), (6, 2), (6, 3)],"
      "[(7, 0), (7, 1), (7, 2), (7, 3)]"
      +

    3. The ending value of the variable.
      4. -

      -

      +
    4. The text to repeat. This text may contain references to the variable, + which will be replaced with the variable's current value.
      5. -

      -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    5. The delimeter text (optional).
      6. +
    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    If called with the wrong number of arguments (less than 4 or more than + 5), BOOST_M4_FOR will exit with an error. If the + starting value ($2) is greater than or equal to + the ending value ($3), BOOST_M4_FOR will do nothing. Otherwise, it will repeat the + text ($4), binding the variable ($1) to the values in the range [starting value ($2), ending value ($3)), and repeat + the delimeter text ($5) in-between each + occurrence of the repeat text ($4).

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    Examples

    - - \ No newline at end of file +

    Note of the quotation marks (") used in the + table below are in the input or output; they are shown to delimit + whitespace. All code within a pair of quotation marks is intended to be on + one line.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    InputOutput
    "BOOST_M4_FOR(i, 1, 3)"Boost m4 script: BOOST_M4_FOR: Wrong number of arguments (3)
    "BOOST_M4_FOR(i, 1, 3, i, ` ', 13)"Boost m4 script: BOOST_M4_FOR: Wrong number of arguments (6)
    "BOOST_M4_FOR(i, 7, 0, i )"(nothing)
    "BOOST_M4_FOR(i, 0, 0, i )"(nothing)
    "BOOST_M4_FOR(i, 0, 7, i )""0 1 2 3 4 5 6 "
    "BOOST_M4_FOR(i, -13, -10, i )""-13 -12 -11 "
    "BOOST_M4_FOR(i, 0, 8, BOOST_M4_FOR(j, 0, 4, (i, j) + )"
    + ")"    		"(0, 0) (0, 1) (0, 2) (0, 3) "
    + "(1, 0) (1, 1) (1, 2) (1, 3) "
    + "(2, 0) (2, 1) (2, 2) (2, 3) "
    + "(3, 0) (3, 1) (3, 2) (3, 3) "
    + "(4, 0) (4, 1) (4, 2) (4, 3) "
    + "(5, 0) (5, 1) (5, 2) (5, 3) "
    + "(6, 0) (6, 1) (6, 2) (6, 3) "
    + "(7, 0) (7, 1) (7, 2) (7, 3) "
    + ""
    "BOOST_M4_FOR(i, 7, 0, i, |)"(nothing)
    "BOOST_M4_FOR(i, 0, 0, i, |)"(nothing)
    "BOOST_M4_FOR(i, 0, 7, i, |)""0|1|2|3|4|5|6"
    "BOOST_M4_FOR(i, -13, -10, i, `, ')""-13, -12, -11"
    "BOOST_M4_FOR(i, 0, 8, `[BOOST_M4_FOR(j, 0, 4, (i, j), + `, ')]', `,"
    + "')"    		"[(0, 0), (0, 1), (0, 2), (0, 3)],"
    + "[(1, 0), (1, 1), (1, 2), (1, 3)],"
    + "[(2, 0), (2, 1), (2, 2), (2, 3)],"
    + "[(3, 0), (3, 1), (3, 2), (3, 3)],"
    + "[(4, 0), (4, 1), (4, 2), (4, 3)],"
    + "[(5, 0), (5, 1), (5, 2), (5, 3)],"
    + "[(6, 0), (6, 1), (6, 2), (6, 3)],"
    + "[(7, 0), (7, 1), (7, 2), (7, 3)]"
    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 + December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/gcd_lcm.html b/doc/implementation/gcd_lcm.html index b5e0ac0..7d0bbe8 100644 --- a/doc/implementation/gcd_lcm.html +++ b/doc/implementation/gcd_lcm.html @@ -1,24 +1,28 @@ - - - -gcd_lcm - GCD and LCM - - - + -C++ Boost + + + + + -

    gcd_lcm - GCD and LCM

    + gcd_lcm - GCD and LCM + -

    -

    Introduction

    + + C++ Boost -

    -detail/gcd_lcm.hpp provides two generic integer algorithms: greatest common divisor and least common multiple. +

    gcd_lcm - GCD and LCM

    -

    -

    Synopsis

    -
    namespace details {
+  
    Introduction
    
+
+  
    detail/gcd_lcm.hpp provides two generic integer algorithms: greatest
+  common divisor and least common multiple.
    
+
+  
    Synopsis
    
+  
    +namespace details {
 namespace pool {
 
 template <typename Integer>
@@ -28,54 +32,100 @@ template <typename Integer>
 Integer lcm(Integer A, Integer B);
 
 } // namespace pool
-} // namespace details
    
+} // namespace details
+
    -

    -

    Semantics

    +

    Semantics

    - - - - - -
    Symbol Table
    SymbolMeaning
    IntegerAn integral type
    A, BValues of type Integer
    + + -
    + Symbol Table +
    - -
    Semantics
    ExpressionResult TypePreconditionNotes -
    gcd(A, B)IntegerA > 0 && B > 0Returns the greatest common divisor of A and B -
    lcm(A, B)IntegerA > 0 && B > 0Returns the least common multiple of A and B -
    + + Symbol -

    -

    Implementation Notes

    + Meaning + -

    -For faster results, ensure A > B + + Integer -

    -

    Dependencies

    + An integral type + -

    -None. + + A, B -

    -

    Future Directions

    + Values of type Integer + +
    -

    -This header may be replaced by a Boost algorithms library. + + -

    -

    + + -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    + - - \ No newline at end of file + + + + + + + + + + + + + + + + + + + +
    + Semantics +
    ExpressionResult TypePreconditionNotes
    gcd(A, B)IntegerA > 0 && B > 0Returns the greatest common divisor of A + and B
    lcm(A, B)IntegerA > 0 && B > 0Returns the least common multiple of A + and B
    + +

    Implementation Notes

    + +

    For faster results, ensure A > B

    + +

    Dependencies

    + +

    None.

    + +

    Future Directions

    + +

    This header may be replaced by a Boost algorithms library.

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 + December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/guard.html b/doc/implementation/guard.html index 39492df..98b5a7d 100644 --- a/doc/implementation/guard.html +++ b/doc/implementation/guard.html @@ -1,25 +1,31 @@ - - - -guard - Auto-lock/unlock-er - - - + -C++ Boost + + + + + -

    guard - Auto-lock/unlock-er

    + guard - Auto-lock/unlock-er + -

    -

    Introduction

    + + C++ Boost -

    -detail/guard.hpp provides a type guard<Mutex> that allows scoped access to the Mutex's locking and unlocking operations. It is used to ensure that a Mutex is unlocked, even if an exception is thrown. +

    guard - Auto-lock/unlock-er

    -

    -

    Synopsis

    +

    Introduction

    -
    namespace details {
+  
    detail/guard.hpp provides a type guard<Mutex> that allows scoped access to the
+  Mutex's locking and unlocking operations. It is
+  used to ensure that a Mutex is unlocked, even if
+  an exception is thrown.
    
+
+  
    Synopsis
    
+  
    +namespace details {
 namespace pool {
 
 template <typename Mutex>
@@ -35,77 +41,139 @@ class guard
 };
 
 } // namespace pool
-} // namespace details
    
+} // namespace details
+
    -

    -

    Semantics

    +

    Semantics

    -

    - - -
    Symbol Table
    SymbolMeaning -
    Tguard<Mutex> -
    mvalue of type Mutex & -
    gvalue of type guard<Mutex> -
    + + -

    -

    + Symbol Table +
    - -
    Requirements on Mutex
    ExpressionReturn TypeAssertion/Note/Pre/Post-Condition -
    m.lock()not usedLocks the mutex referred to by m -
    m.unlock()not usedUnlocks the mutex referred to by m -
    + + Symbol -

    - - -
    Requirements satisfied by guard
    ExpressionAssertion/Note/Pre/Post-Condition -
    T(m)Locks the mutex referred to by m; binds T(m) to m -
    (&g)->~T()Unlocks the mutex that g is bound to -
    + Meaning + -

    -

    Example

    + + T -

    -Given a (platform-specific) mutex class, we can wrap code as follows: -

    extern mutex global_lock;
+      guard<Mutex>
+    
+
+    
+      m
+
+      value of type Mutex &
+    
+
+    
+      g
+
+      value of type guard<Mutex>
+    
+  
    
+
+  
+    
+
+    
+      
+
+      
+
+      
+    
+
+    
+      
+
+      
+
+      
+    
+
+    
+      
+
+      
+
+      
+    
+  
    
+      Requirements on Mutex
+    
    ExpressionReturn TypeAssertion/Note/Pre/Post-Condition
    m.lock()not usedLocks the mutex referred to by m
    m.unlock()not usedUnlocks the mutex referred to by m

    
+
+  
+    
+
+    
+      
+
+      
+    
+
+    
+      
+
+      
+    
+
+    
+      
+
+      
+    
+  
    
+      Requirements satisfied by guard
+    
    ExpressionAssertion/Note/Pre/Post-Condition
    T(m)Locks the mutex referred to by m; binds
+      T(m) to m
    (&g)->~T()Unlocks the mutex that g is bound to
    
+
+  
    Example
    
+
+  
    Given a (platform-specific) mutex class, we
+  can wrap code as follows:
    
+  
    +extern mutex global_lock;
 
 static void f()
 {
   boost::details::pool::guard<mutex> g(global_lock);
-  // g's constructor locks "global_lock"
+  // g's constructor locks "global_lock"
 
   ... // do anything:
       //   throw exceptions
       //   return
       //   or just fall through
-} // g's destructor unlocks "global_lock"
    
+} // g's destructor unlocks "global_lock"
+
    -

    -

    Dependencies

    +

    Dependencies

    -

    -None. +

    None.

    -

    -

    Future Directions

    +

    Future Directions

    -

    -This header will eventually be replaced by a Boost multithreading library. +

    This header will eventually be replaced by a Boost multithreading + library.

    +
    -

    -

    +

    Valid HTML 4.01 Transitional

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Revised + 05 + December, 2006

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. - - - \ No newline at end of file +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/mutex.html b/doc/implementation/mutex.html index 190521f..1573633 100644 --- a/doc/implementation/mutex.html +++ b/doc/implementation/mutex.html @@ -1,31 +1,38 @@ - - - -mutex - Mutex - - - + -C++ Boost + + + + + -

    mutex - Mutex

    + mutex - Mutex + -

    -

    Introduction

    + + C++ Boost -

    -detail/mutex.hpp provides several mutex types that provide a consistent interface for OS-supplied mutex types. These are all thread-level mutexes; interprocess mutexes are not supported. +

    mutex - Mutex

    -

    -

    Configuration

    +

    Introduction

    -

    -This header file will try to guess what kind of system it is on. It will auto-configure itself for Win32 or POSIX+pthread systems. To stub out all mutex code, bypassing the auto-configuration, #define BOOST_NO_MT before any inclusion of this header. To prevent ODR violations, this should be defined in every translation unit in your project, including any library files. +

    detail/mutex.hpp provides several mutex types that provide a consistent + interface for OS-supplied mutex types. These are all thread-level mutexes; + interprocess mutexes are not supported.

    -

    -

    Synopsis

    +

    Configuration

    -
    namespace details {
+  
    This header file will try to guess what kind of system it is on. It will
+  auto-configure itself for Win32 or POSIX+pthread systems. To stub out all
+  mutex code, bypassing the auto-configuration, #define
+  BOOST_NO_MT before any inclusion of this header. To prevent ODR
+  violations, this should be defined in every translation
+  unit in your project, including any library files.
    
+
+  
    Synopsis
    
+  
    +namespace details {
 namespace pool {
 
 // Only present if on a Win32 system
@@ -77,53 +84,99 @@ class null_mutex
 typedef ... default_mutex;
 
 } // namespace pool
-} // namespace details
    
+} // namespace details
+
    -

    -

    Semantics

    +

    Semantics

    -

    - - -
    Symbol Table
    SymbolMeaning -
    MutexAny type defined in this header -
    tvalue of type Mutex -
    + + -

    -

    + Symbol Table +
    - -
    Requirements satisfied by mutex
    ExpressionReturn TypeAssertion/Note/Pre/Post-Condition -
    m.lock()not usedLocks the mutex -
    m.unlock()not usedUnlocks the mutex -
    + + Symbol -

    -Each mutex is always either owned or unowned. If owned, then it is owned by a particular thread. To "lock" a mutex means to wait until the mutex is unowned, and then make it owned by the current thread. To "unlock" a mutex means to release ownership from the current thread (note that the current thread must own the mutex to release that ownership!). As a special case, the null_mutex never waits. + Meaning + -

    -

    Dependencies

    + + Mutex -

    -May include the system headers <windows.h>, <unistd.h>, and/or <pthread.h>. + Any type defined in this header + -

    -

    Future Directions

    + + t -

    -This header will eventually be replaced by a Boost multithreading library. + value of type Mutex + +
    -

    -

    + + -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    + -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    + - - \ No newline at end of file + + + + + + + + + + + + + + + +
    + Requirements satisfied by mutex +
    ExpressionReturn TypeAssertion/Note/Pre/Post-Condition
    m.lock()not usedLocks the mutex
    m.unlock()not usedUnlocks the mutex
    + +

    Each mutex is always either owned or unowned. If owned, then it is owned + by a particular thread. To "lock" a mutex means to wait until the mutex is + unowned, and then make it owned by the current thread. To "unlock" a mutex + means to release ownership from the current thread (note that the current + thread must own the mutex to release that ownership!). As + a special case, the null_mutex never waits.

    + +

    Dependencies

    + +

    May include the system headers <windows.h>, <unistd.h>, and/or <pthread.h>.

    + +

    Future Directions

    + +

    This header will eventually be replaced by a Boost multithreading + library.

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 + December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/object_pool.html b/doc/implementation/object_pool.html index d9618b8..4dc0a98 100644 --- a/doc/implementation/object_pool.html +++ b/doc/implementation/object_pool.html @@ -1,70 +1,85 @@ - - - -Object Pool Implementation - - - + -C++ Boost + + + + + -

    Object Pool Implementation

    + Object Pool Implementation + -

    -

    Dependencies

    + + C++ Boost -

    -Includes the Boost header "pool.hpp" (see pool.html). +

    Object Pool Implementation

    -

    -

    Extensions to Public Interface

    +

    Dependencies

    -

    -Whenever an object of type ObjectPool needs memory from the system, it will request it from its UserAllocator template parameter. The amount requested is determined using a doubling algorithm; that is, each time more system memory is allocated, the amount of system memory requested is doubled. Users may control the doubling algorithm by using the following extensions. +

    Includes the Boost header "pool.hpp" (see + pool.html).

    -

    -

    Additional constructor parameter

    +

    Extensions to Public Interface

    -

    -Users may pass an additional constructor parameter to ObjectPool. This parameter is of type size_type, and is the number of chunks to request from the system the first time that object needs to allocate system memory. The default is 32. This parameter may not be 0. +

    Whenever an object of type ObjectPool needs + memory from the system, it will request it from its UserAllocator template parameter. The amount requested is + determined using a doubling algorithm; that is, each time more system + memory is allocated, the amount of system memory requested is doubled. + Users may control the doubling algorithm by using the following + extensions.

    -

    -

    next_size accessor functions

    +

    Additional constructor parameter

    -

    -The pair of functions size_type get_next_size() const; and void set_next_size(size_type); allow users to explicitly read and write the next_size value. This value is the number of chunks to request from the system the next time that object needs to allocate system memory. This value should never be set to 0. +

    Users may pass an additional constructor parameter to ObjectPool. This parameter is of type size_type, and is the number of chunks to request from the + system the first time that object needs to allocate system memory. The + default is 32. This parameter may not be 0.

    -

    -

    Protected Interface

    +

    next_size accessor functions

    -

    -

    Synopsis

    +

    The pair of functions size_type get_next_size() + const; and void set_next_size(size_type); + allow users to explicitly read and write the next_size value. This value is the number of chunks to + request from the system the next time that object needs to allocate system + memory. This value should never be set to 0.

    -
    template <typename ElementType, typename UserAllocator = default_user_allocator_new_delete>
+  
    Protected Interface
    
+
+  
    Synopsis
    
+  
    +template <typename ElementType, typename UserAllocator = default_user_allocator_new_delete>
 class object_pool: protected pool<UserAllocator>
 {
   ... // public interface
-};
    
+};
+
    -

    -

    Protected Derivation

    +

    Protected Derivation

    ObjectPool derives from a simple segregated + storage via protected derivation; this exposes all the Pool implementation details to all classes derived from + ObjectPool as well. -ObjectPool derives from a simple segregated storage via protected derivation; this exposes all the Pool implementation details to all classes derived from ObjectPool as well. +

    Interface Description

    +
    -

    -

    Interface Description

    +

    Valid HTML 4.01 Transitional

    -

    -

    +

    Revised + 05 + December, 2006

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html - -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. - - - \ No newline at end of file +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/pool.html b/doc/implementation/pool.html index 6745989..fcf00b7 100644 --- a/doc/implementation/pool.html +++ b/doc/implementation/pool.html @@ -1,28 +1,39 @@ - - - -Pool Implementation - - - + -C++ Boost + + + + + -

    Pool Implementation

    + Pool Implementation + -

    -

    Dependencies

    + + C++ Boost -

    -Includes the system headers <functional>, <new>, <cstddef>, <cstdlib>, and <exception>. +

    Pool Implementation

    -

    -Includes the Boost headers "detail/ct_gcd_lcm.hpp" (see ct_gcd_lcm.html), "detail/gcd_lcm.hpp" (see gcd_lcm.html), and "simple_segregated_storage.hpp" (see simple_segregated_storage.html). +

    Dependencies

    -

    -

    Synopsis

    +

    Includes the system headers <functional>, <new>, + <cstddef>, <cstdlib>, and <exception>.

    -
    namespace details {
+  
    Includes the Boost headers "detail/ct_gcd_lcm.hpp" (see ct_gcd_lcm.html), "detail/gcd_lcm.hpp" (see gcd_lcm.html), and "simple_segregated_storage.hpp" (see simple_segregated_storage.html).
    
+
+  
    Synopsis
    
+  
    +namespace details {
 
 template <typename SizeType>
 class PODptr
@@ -37,17 +48,17 @@ class PODptr
 
     bool valid() const;
     void invalidate();
-    char * & begin();
+    char * & begin();
     char * begin() const;
     char * end() const;
     size_type total_size() const;
     size_type element_size() const;
 
-    size_type & next_size() const;
-    char * & next_ptr() const;
+    size_type & next_size() const;
+    char * & next_ptr() const;
 
     PODptr next() const;
-    void next(const PODptr & arg) const;
+    void next(const PODptr & arg) const;
 };
 
 } // namespace details
@@ -60,8 +71,8 @@ class pool: protected simple_segregated_storage<typename UserAllocator::size_
   protected:
     details::PODptr<size_type> list;
 
-    simple_segregated_storage<size_type> & store();
-    const simple_segregated_storage<size_type> & store() const;
+    simple_segregated_storage<size_type> & store();
+    const simple_segregated_storage<size_type> & store() const;
 
     const size_type requested_size;
     size_type next_size;
@@ -74,143 +85,201 @@ class pool: protected simple_segregated_storage<typename UserAllocator::size_
     pool(size_type requested_size, size_type next_size);
     size_type get_next_size() const;
     void set_next_size(size_type);
-};
    
+};
+
    -

    -

    Extensions to Public Interface

    +

    Extensions to Public Interface

    -

    -Whenever an object of type pool needs memory from the system, it will request it from its UserAllocator template parameter. The amount requested is determined using a doubling algorithm; that is, each time more system memory is allocated, the amount of system memory requested is doubled. Users may control the doubling algorithm by using the following extensions. +

    Whenever an object of type pool needs memory + from the system, it will request it from its UserAllocator template parameter. The amount requested is + determined using a doubling algorithm; that is, each time more system + memory is allocated, the amount of system memory requested is doubled. + Users may control the doubling algorithm by using the following + extensions.

    -

    -

    Additional constructor parameter

    +

    Additional constructor parameter

    -

    -Users may pass an additional constructor parameter to pool. This parameter is of type size_type, and is the number of chunks to request from the system the first time that object needs to allocate system memory. The default is 32. This parameter may not be 0. +

    Users may pass an additional constructor parameter to pool. This parameter is of type size_type, and is the number of chunks to request from the + system the first time that object needs to allocate system memory. The + default is 32. This parameter may not be 0.

    -

    -

    next_size accessor functions

    +

    next_size accessor functions

    -

    -The pair of functions size_type get_next_size() const; and void set_next_size(size_type); allow users to explicitly read and write the next_size value. This value is the number of chunks to request from the system the next time that object needs to allocate system memory. This value should never be set to 0. +

    The pair of functions size_type get_next_size() + const; and void set_next_size(size_type); + allow users to explicitly read and write the next_size value. This value is the number of chunks to + request from the system the next time that object needs to allocate system + memory. This value should never be set to 0.

    -

    -

    Class PODptr

    +

    Class PODptr

    -

    -PODptr is a class that pretends to be a "pointer" to different class types that don't really exist. It provides member functions to access the "data" of the "object" it points to. Since these "class" types are of differing sizes, and contain some information at the end of their memory (for alignment reasons), PODptr must contain the size of this "class" as well as the pointer to this "object". +

    PODptr is a class that pretends to be a + "pointer" to different class types that don't really exist. It provides + member functions to access the "data" of the "object" it points to. Since + these "class" types are of differing sizes, and contain some information at + the end of their memory (for alignment reasons), PODptr must contain the size of this "class" as well as the + pointer to this "object".

    -

    -A PODptr holds the location and size of a memory block allocated from the system. Each memory block is split logically into three sections: -

      -
    1. Chunk area. This section may be different sizes. PODptr does not care what the size of the chunks is, but it does care (and keep track of) the total size of the chunk area.
      2. -
    2. Next pointer. This section is always the same size for a given SizeType. It holds a pointer to the location of the next memory block in the memory block list, or 0 if there is no such block.
      3. -
    3. Next size. This section is always the same size for a given SizeType. It holds the size of the next memory block in the memory block list.
      4. -
    +

    A PODptr holds the location and size of a + memory block allocated from the system. Each memory block is split + logically into three sections:

    -

    -The PODptr class just provides cleaner ways of dealing with raw memory blocks. +

      +
    1. Chunk area. This section may be different sizes. PODptr does not care what the size of the chunks is, but it + does care (and keep track of) the total size of the chunk area.
      2. -

      -

      Validity

      +
    2. Next pointer. This section is always the same size for a given + SizeType. It holds a pointer to the location of + the next memory block in the memory block list, or 0 if there is no such + block.
      3. -

      -A PODptr object is either valid or invalid. An invalid PODptr is analogous to a null pointer. +

    3. Next size. This section is always the same size for a given + SizeType. It holds the size of the next memory + block in the memory block list.
      4. +
    -

    -The default constructor for PODptr will result in an invalid object. Calling the member function invalidate will result in that object becoming invalid. The member function valid can be used to test for validity. +

    The PODptr class just provides cleaner ways of + dealing with raw memory blocks.

    -

    -

    Getting PODptr objects

    +

    Validity

    -

    -A PODptr may be created to point to a memory block by passing the address and size of that memory block into the constructor. A PODptr constructed in this way is valid. +

    A PODptr object is either valid or + invalid. An invalid PODptr is analogous + to a null pointer.

    -

    -A PODptr may also be created by a call to the member function next, which returns a PODptr which points to the next memory block in the memory block list, or an invalid PODptr if there is no such block. +

    The default constructor for PODptr will result + in an invalid object. Calling the member function invalidate will result in that object becoming invalid. The + member function valid can be used to test for + validity.

    -

    -

    Accessing the "pointer" data

    +

    Getting PODptr objects

    -

    -Each PODptr keeps the address and size of its memory block. The address may be read or written by the member functions begin. The size of the memory block may only be read, and is done so by the member function total_size. +

    A PODptr may be created to point to a memory + block by passing the address and size of that memory block into the + constructor. A PODptr constructed in this way is + valid.

    -

    -

    Accessing the sections of the memory block

    +

    A PODptr may also be created by a call to the + member function next, which returns a + PODptr which points to the next memory block in + the memory block list, or an invalid PODptr if + there is no such block.

    -

    -The chunk area may be accessed by the member functions begin and end, in conjunction with element_size. The value returned by end is always the value returned by begin plus element_size. Only begin is writeable. end is a past-the-end value; using pointers beginning at begin and ending before end allows one to iterate through the chunks in a memory block. +

    Accessing the "pointer" data

    -

    -The next pointer area may be accessed by the member function next_ptr. The next size area may be accessed by the member function next_size. Both of these are writeable. They may both be read or set at the same time through the member function next. +

    Each PODptr keeps the address and size of its + memory block. The address may be read or written by the member functions + begin. The size of the memory block may only be + read, and is done so by the member function total_size.

    -

    -

    Protected Interface

    +

    Accessing the sections of the memory block

    -

    -

    Protected Derivation

    +

    The chunk area may be accessed by the member functions begin and end, in conjunction with + element_size. The value returned by end is always the value returned by begin plus element_size. Only + begin is writeable. end + is a past-the-end value; using pointers beginning at begin and ending before end allows + one to iterate through the chunks in a memory block.

    -Pool derives from a simple segregated storage via protected derivation; this exposes all the simple segregated storage implementation details to all classes derived from Pool as well. +

    The next pointer area may be accessed by the member function + next_ptr. The next size area may be accessed by + the member function next_size. Both of these are + writeable. They may both be read or set at the same time through the member + function next.

    -

    -

    details::PODptr<size_type> list;

    +

    Protected Interface

    -

    -This is the list of memory blocks that have been allocated by this Pool object. It is not the same as the list of free memory chunks (exposed by simple segregated storage as first). +

    Protected Derivation

    Pool derives from a simple segregated storage + via protected derivation; this exposes all the simple segregated storage implementation + details to all classes derived from Pool as well. -

    -

    store functions

    +

    details::PODptr<size_type> list;

    -

    -These are convenience functions, used to return the base simple segregated storage object. +

    This is the list of memory blocks that have been allocated by this Pool + object. It is not the same as the list of free memory + chunks (exposed by simple segregated storage as first).

    -

    -

    const size_type requested_size;

    +

    store functions

    -

    -The first argument passed into the constructor. Represents the number of bytes in each chunk requested by the user. The actual size of the chunks may be different; see alloc_size, below. +

    These are convenience functions, used to return the base simple + segregated storage object.

    -

    -

    size_type next_size

    +

    const size_type requested_size;

    -

    -The number of chunks to request from the UserAllocator the next time we need to allocate system memory. See the extensions descriptions, above. +

    The first argument passed into the constructor. Represents the number of + bytes in each chunk requested by the user. The actual size of the chunks + may be different; see alloc_size, below.

    -

    -

    details::PODptr<size_type> find_POD(void * chunk) const;

    +

    size_type next_size

    -

    -Searches through the memory block list, looking for the block that chunk was allocated from or may be allocated from in the future. Returns that block if found, or an invalid value if chunk has been allocated from another Pool or may be allocated from another Pool in the future. Results for other values of chunk may be wrong. +

    The number of chunks to request from the UserAllocator the next time we need to allocate system + memory. See the extensions descriptions, above.

    -

    -

    static bool is_from(void * chunk, char * i, size_type sizeof_i);

    +

    details::PODptr<size_type> find_POD(void * chunk) + const;

    -

    -Tests chunk to see if it has been allocated from the memory chunk at i with an element size of sizeof_i. Note that sizeof_i is the size of the chunk area of that block, not the total size of that block. +

    Searches through the memory block list, looking for the block that + chunk was allocated from or may be allocated from + in the future. Returns that block if found, or an invalid value if + chunk has been allocated from another Pool or may + be allocated from another Pool in the future. Results for other values of + chunk may be wrong.

    -

    -Returns true if chunk has been allocated from that memory block or may be allocated from that block in the future. Returns false if chunk has been allocated from another block or may be allocated from another block in the future. Results for other values of chunk may be wrong. +

    static bool is_from(void * chunk, char * i, size_type + sizeof_i);

    -

    -

    size_type alloc_size() const;

    +

    Tests chunk to see if it has been allocated + from the memory chunk at i with an element size + of sizeof_i. Note that sizeof_i is the size of the chunk area of that block, not the + total size of that block.

    -

    -Returns the calculated size of the memory chunks that will be allocated by this Pool. For alignment reasons, this is defined to be lcm(requested_size, sizeof(void *), sizeof(size_type)). +

    Returns true if chunk has been allocated from that memory block or may be + allocated from that block in the future. Returns false if chunk has been allocated + from another block or may be allocated from another block in the future. + Results for other values of chunk may be + wrong.

    -

    -

    Interface Description

    +

    size_type alloc_size() const;

    -

    -

    +

    Returns the calculated size of the memory chunks that will be allocated + by this Pool. For alignment reasons, this is + defined to be lcm(requested_size, sizeof(void *), + sizeof(size_type)).

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Interface Description

    +
    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Valid HTML 4.01 Transitional

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    Revised + 05 + December, 2006

    - - \ No newline at end of file +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/pool_alloc.html b/doc/implementation/pool_alloc.html index 95dfa1d..650c4a2 100644 --- a/doc/implementation/pool_alloc.html +++ b/doc/implementation/pool_alloc.html @@ -1,28 +1,35 @@ - - - -pool_alloc - Boost Pool Standard Allocators Implementation - - - + -C++ Boost + + + + + -

    pool_alloc - Boost Pool Standard Allocators Implementation

    + pool_alloc - Boost Pool Standard Allocators Implementation + -

    -

    Dependencies

    + + C++ Boost -

    -Includes the system headers <new> and <limits>. +

    pool_alloc - Boost Pool Standard Allocators + Implementation

    -

    -Includes the Boost headers "singleton_pool.hpp" (see singleton_pool.html) and "detail/mutex.hpp" (see mutex.html). +

    Dependencies

    -

    -

    Synopsis

    +

    Includes the system headers <new> and + <limits>.

    -
    template <typename T,
+  
    Includes the Boost headers "singleton_pool.hpp" (see singleton_pool.html) and "detail/mutex.hpp" (see mutex.html).
    
+
+  
    Synopsis
    
+  
    +template <typename T,
     typename UserAllocator = default_user_allocator_new_delete,
     typename Mutex = details::pool::default_mutex,
     unsigned NextSize = 32>
@@ -60,68 +67,77 @@ class fast_pool_allocator
     {
       typedef fast_pool_allocator<U, UserAllocator, Mutex, NextSize> other;
     };
-};
    
+};
+
    -

    -

    Extensions to Public Interface

    +

    Extensions to Public Interface

    -

    -

    Additional template parameters

    +

    Additional template parameters

    -

    -

    Mutex

    +

    Mutex

    -

    -This parameter allows the user to determine the type of synchronization to be used on the underlying singleton pool. See the extensions to the public interface of singleton pool for more information. +

    This parameter allows the user to determine the type of synchronization + to be used on the underlying singleton pool. See the extensions to the + public interface of singleton pool for + more information.

    -

    -

    NextSize

    +

    NextSize

    -

    -The value of this parameter is passed to the underlying Pool when it is created. See the extensions to the public interface of pool for more information. +

    The value of this parameter is passed to the underlying Pool when it is + created. See the extensions to the public interface of pool for more information.

    -

    -

    Modification of rebind

    +

    Modification of rebind

    -

    -The struct rebind has been redefined to preserve the values of the additional template parameters. +

    The struct rebind has been redefined to + preserve the values of the additional template parameters.

    -

    -

    Additional members

    +

    Additional members

    -

    -The typedef mutex and the static const value next_size publish the values of the template parameters Mutex and NextSize, respectively. +

    The typedef mutex and the static const value + next_size publish the values of the template + parameters Mutex and NextSize, respectively.

    -

    -

    Notes

    +

    Notes

    -

    -A number of common STL libraries contain bugs in their using of allocators. Specifically, they pass null pointers to the deallocate function, which is explicitly forbidden by the Standard [20.1.5 Table 32]. PoolAlloc will work around these libraries if it detects them; currently, workarounds are in place for: -

    +

    A number of common STL libraries contain bugs in their using of + allocators. Specifically, they pass null pointers to the deallocate function, which is explicitly forbidden by the + Standard [20.1.5 Table 32]. PoolAlloc will work around these libraries if + it detects them; currently, workarounds are in place for:

    -

    -

    Future Directions

    + -

    -

    Interface Description

    +

    Future Directions

    -

    -

    +

    When the Boost multithreading library is completed, the Mutex parameter will be replaced by something from that + library providing the same flexibility and will move from an implementation + detail into the interface specification.

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Interface Description

    +
    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Valid HTML 4.01 Transitional

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    Revised + 05 + December, 2006

    - - \ No newline at end of file +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/pool_construct.html b/doc/implementation/pool_construct.html index ae1c091..bd29f11 100644 --- a/doc/implementation/pool_construct.html +++ b/doc/implementation/pool_construct.html @@ -1,62 +1,83 @@ - - - -Object Pool Constructors Generator - - - + -C++ Boost + + + + + -

    Object Pool Constructors Generator

    + Object Pool Constructors Generator + -

    -

    Description

    + + C++ Boost -

    -The template class object_pool (see object_pool.html) contains a number of functions construct(..), which both allocate and construct an object in a single operation. +

    Object Pool Constructors Generator

    -

    -Since the number and type of arguments to this function is totally arbitrary, a simple system has been set up to automatically generate template construct functions. This system is based on the macro preprocessor m4, which is standard on UNIX systems and also available for Win32 systems. +

    Description

    -

    -detail/pool_construct.m4, when run with m4, will create the file detail/pool_construct.inc, which only defines the construct functions for the proper number of arguments. The number of arguments may be passed into the file as an m4 macro, NumberOfArguments; if not provided, it will default to 3. +

    The template class object_pool (see object_pool.html) contains a number of functions + construct(..), which both allocate and construct + an object in a single operation.

    -

    -For each different number of arguments (1 to NumberOfArguments), a template function is generated. There are the same number of template parameters as there are arguments, and each argument's type is a reference to that (possibly cv-qualified) template argument. Each possible permutation of the cv-qualifications is also generated. +

    Since the number and type of arguments to this function is totally + arbitrary, a simple system has been set up to automatically generate + template construct functions. This system is + based on the macro preprocessor m4, which is standard on + UNIX systems and also available for Win32 systems.

    -

    -Because each permutation is generated for each possible number of arguments, the included file size grows exponentially in terms of the number of constructor arguments, not linearly. For the sake of rational compile times, only use as many arguments as you need. +

    detail/pool_construct.m4, when run with m4, will create + the file detail/pool_construct.inc, which only defines the construct functions for the proper number of arguments. The + number of arguments may be passed into the file as an m4 macro, + NumberOfArguments; if not provided, it will + default to 3.

    -

    -detail/pool_construct.bat and detail/pool_construct.sh are also provided to call m4, defining NumberOfArguments to be their command-line parameter. See these files for more details. +

    For each different number of arguments (1 to + NumberOfArguments), a template function is + generated. There are the same number of template parameters as there are + arguments, and each argument's type is a reference to that (possibly + cv-qualified) template argument. Each possible permutation of the + cv-qualifications is also generated.

    -

    -

    Dependencies

    +

    Because each permutation is generated for each possible number of + arguments, the included file size grows exponentially in terms of the + number of constructor arguments, not linearly. For the sake of rational + compile times, only use as many arguments as you need.

    -

    -Dependent on for.m4 (see for.html). +

    detail/pool_construct.bat and detail/pool_construct.sh are also provided + to call m4, defining NumberOfArguments to be their command-line parameter. See + these files for more details.

    -

    -

    Future Directions

    +

    Dependencies

    -

    -This system may be complemented by or replaced by a Python (or some other language) script. +

    Dependent on for.m4 (see for.html).

    -

    -

    Interface Description

    +

    Future Directions

    -

    -

    +

    This system may be complemented by or replaced by a Python (or some + other language) script.

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Interface Description

    +
    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Valid HTML 4.01 Transitional

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    Revised + 05 + December, 2006

    - - \ No newline at end of file +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/simple_segregated_storage.html b/doc/implementation/simple_segregated_storage.html index c014400..ad24f83 100644 --- a/doc/implementation/simple_segregated_storage.html +++ b/doc/implementation/simple_segregated_storage.html @@ -1,76 +1,96 @@ - - - -Simple Segregated Storage Implementation - - - + -C++ Boost + + + + + -

    Simple Segregated Storage Implementation

    + Simple Segregated Storage Implementation + -

    -

    Dependencies

    + + C++ Boost -

    -Includes the system headers <cstddef> and <functional>. +

    Simple Segregated Storage Implementation

    -

    -

    Protected Interface

    +

    Dependencies

    -

    -

    Synopsis

    +

    Includes the system headers <cstddef> + and <functional>.

    -
    template <typename SizeType = std::size_t>
+  
    Protected Interface
    
+
+  
    Synopsis
    
+  
    +template <typename SizeType = std::size_t>
 class simple_segregated_storage
 {
   ... // Public interface
 
   protected:
     void * first;
-    static void * & nextof(void * const ptr);
+    static void * & nextof(void * const ptr);
     void * find_prev(void * ptr);
-};
    
+};
+
    -

    -

    void * first;

    +

    void * first;

    -

    -This data member is the free list. It points to the first chunk in the free list, or is equal to 0 if the free list is empty. +

    This data member is the free list. It points to the first chunk in the + free list, or is equal to 0 if the free list is empty.

    -

    -

    static void * & nextof(void * const ptr);

    +

    static void * & nextof(void * const ptr);

    -

    -This is a convenience function. It helps clean up code dealing with the free list by making it more readable. The return value is just *ptr cast to the appropriate type. ptr must not be 0. +

    This is a convenience function. It helps clean up code dealing with the + free list by making it more readable. The return value is just *ptr cast to the appropriate type. ptr must not be 0.

    -

    -As an example, let us assume that we want to truncate the free list after the first chunk. That is, we want to set *first to 0; this will result in a free list with only one entry. The normal way to do this is to first cast first to a pointer to a pointer to void, and then dereference and assign (*static_cast<void **>(first) = 0;). This can be done more easily through the use of this convenience function (nextof(first) = 0;). +

    As an example, let us assume that we want to truncate the free list + after the first chunk. That is, we want to set *first to 0; this will result in a free list with only one + entry. The normal way to do this is to first cast first to a pointer to a pointer to void, and then dereference + and assign (*static_cast<void **>(first) = + 0;). This can be done more easily through the use of this + convenience function (nextof(first) = 0;).

    -

    -

    void * find_prev(void * ptr);

    +

    void * find_prev(void * ptr);

    -

    -Traverses the free list referred to by first, and returns the pointer previous to where ptr would go if it was in the free list. Returns 0 if ptr would go at the beginning of the free list (i.e., before first). +

    Traverses the free list referred to by first, + and returns the pointer previous to where ptr + would go if it was in the free list. Returns 0 if ptr would go at the beginning of the free list (i.e., before + first).

    -

    -Note that this function finds the location previous to where ptr would go if it was in the free list. It does not find the entry in the free list before ptr (unless ptr is already in the free list). Specifically, find_prev(0) will return 0, not the last entry in the free list. +

    Note that this function finds the location previous to where + ptr would go if it + was in the free list. It does not find the entry + in the free list before ptr (unless ptr is already in the free list). Specifically, find_prev(0) will return 0, not the last + entry in the free list.

    -

    -

    Interface Description

    +

    Interface + Description

    +
    -

    -

    +

    Valid HTML 4.01 Transitional

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Revised + 05 + December, 2006

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. - - - \ No newline at end of file +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/singleton.html b/doc/implementation/singleton.html index 681665b..ee92a49 100644 --- a/doc/implementation/singleton.html +++ b/doc/implementation/singleton.html @@ -1,25 +1,29 @@ - - - -singleton - Singleton - - - + -C++ Boost + + + + + -

    singleton - Singleton

    + singleton - Singleton + -

    -

    Introduction

    + + C++ Boost -

    -detail/singleton.hpp provides a way to access a Singleton of a class type. This is not a general Singleton solution! It is restricted in that the class type must have a default constructor. +

    singleton - Singleton

    -

    -

    Synopsis

    +

    Introduction

    -
    namespace details {
+  
    detail/singleton.hpp provides a way to access a Singleton of a class
+  type. This is not a general Singleton solution! It is
+  restricted in that the class type must have a default constructor.
    
+
+  
    Synopsis
    
+  
    +namespace details {
 namespace pool {
 
 template <typename T>
@@ -31,64 +35,97 @@ class singleton_default
   public:
     typedef T object_type;
 
-    static object_type & instance();
+    static object_type & instance();
 };
 
 } // namespace pool
-} // namespace details
    
+} // namespace details
+
    -

    -

    Semantics

    +

    Semantics

    -

    - - -
    Symbol Table
    SymbolMeaning -
    TAny class with a non-throwing default constructor and non-throwing destructor -
    + + -

    -

    + Symbol Table +
    - -
    Requirements satisfied by singleton_default<T>
    ExpressionReturn TypeAssertion/Note/Pre/Post-Condition -
    singleton_default<T>::instance()T &Returns a reference to the singleton instance -
    + + Symbol -

    -

    Guarantees

    + Meaning + -

    -The singleton instance is guaranteed to be constructed before main() begins, and destructed after main() ends. Furthermore, it is guaranteed to be constructed before the first call to singleton_default<T>::instance() is complete (even if called before main() begins). Thus, if there are not multiple threads running except within main(), and if all access to the singleton is restricted by mutexes, then this guarantee allows a thread-safe singleton. + + T -

    -

    Details

    + Any class with a non-throwing default constructor and non-throwing + destructor + +
    -

    -For details on how we provide the guarantees above, see the comments in the header file. + + -

    -

    Dependencies

    + + -

    -None. +

    -

    -

    Future Directions

    + + -

    -This header may be replaced by a Boost singleton library. +

    + -

    -

    + -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    + +
    + Requirements satisfied by singleton_default<T> +
    ExpressionReturn TypeAssertion/Note/Pre/Post-Condition
    singleton_default<T>::instance()T &Returns a reference to the singleton instance
    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Guarantees

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    The singleton instance is guaranteed to be constructed before + main() begins, and destructed after main() ends. Furthermore, it is guaranteed to be constructed + before the first call to singleton_default<T>::instance() is complete (even if + called before main() begins). Thus, if there are + not multiple threads running except within main(), and if all access to the singleton is restricted by + mutexes, then this guarantee allows a thread-safe singleton.

    - - \ No newline at end of file +

    Details

    + +

    For details on how we provide the guarantees above, see the comments in + the header file.

    + +

    Dependencies

    + +

    None.

    + +

    Future Directions

    + +

    This header may be replaced by a Boost singleton library.

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 + December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/implementation/singleton_pool.html b/doc/implementation/singleton_pool.html index b419bdf..176ae8c 100644 --- a/doc/implementation/singleton_pool.html +++ b/doc/implementation/singleton_pool.html @@ -1,25 +1,33 @@ - - - -Singleton Pool Implementation - - - + -C++ Boost + + + + + -

    Singleton Pool Implementation

    + Singleton Pool Implementation + -

    -

    Dependencies

    + + C++ Boost -

    -Includes the Boost headers "pool.hpp" (see pool.html), "detail/singleton.hpp" (see singleton.html), "detail/mutex.hpp" (see mutex.html), and "detail/guard.hpp" (see guard.html). +

    Singleton Pool Implementation

    -

    -

    Synopsis

    +

    Dependencies

    -
    template <typename Tag,
+  
    Includes the Boost headers "pool.hpp" (see
+  pool.html), "detail/singleton.hpp" (see singleton.html), "detail/mutex.hpp" (see mutex.html),
+  and "detail/guard.hpp" (see guard.html).
    
+
+  
    Synopsis
    
+  
    +template <typename Tag,
     unsigned RequestedSize,
     typename UserAllocator = default_user_allocator_new_delete,
     typename Mutex = details::pool::default_mutex,
@@ -31,52 +39,60 @@ class singleton_pool
   public: // extensions to public interface
     typedef Mutex mutex;
     static const unsigned next_size = NextSize;
-};
    
+};
+
    -

    -

    Extensions to Public Interface

    +

    Extensions to Public Interface

    -

    -

    Additional template parameters

    +

    Additional template parameters

    -

    -

    Mutex

    +

    Mutex

    -

    -This class is the type of mutex to use to protect simultaneous access to the underlying Pool. It is exposed so that users may declare some singleton pools normally (i.e., with synchronization), but some singleton pools without synchronization (by specifying details::pool::null_mutex) for efficiency reasons. +

    This class is the type of mutex to use to + protect simultaneous access to the underlying Pool. It is exposed so that + users may declare some singleton pools normally (i.e., with + synchronization), but some singleton pools without synchronization (by + specifying details::pool::null_mutex) for + efficiency reasons.

    -

    -

    NextSize

    +

    NextSize

    -

    -The value of this parameter is passed to the underlying Pool when it is created. See the extensions to the public interface of pool for more information. +

    The value of this parameter is passed to the underlying Pool when it is + created. See the extensions to the public interface of pool for more information.

    -

    -

    Additional members

    +

    Additional members

    -

    -The typedef mutex and the static const value next_size publish the values of the template parameters Mutex and NextSize, respectively. +

    The typedef mutex and the static const value + next_size publish the values of the template + parameters Mutex and NextSize, respectively.

    -

    -

    Future Directions

    +

    Future Directions

    -

    -When the Boost multithreading library is completed, the Mutex parameter will be replaced by something from that library providing the same flexibility and will move from an implementation detail into the interface specification. +

    When the Boost multithreading library is completed, the Mutex parameter will be replaced by something from that + library providing the same flexibility and will move from an implementation + detail into the interface specification.

    -

    -

    Interface Description

    +

    Interface + Description

    +
    -

    -

    +

    Valid HTML 4.01 Transitional

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Revised + 05 + December, 2006

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. - - - \ No newline at end of file +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/index.html b/doc/index.html index 480e576..0ddad05 100644 --- a/doc/index.html +++ b/doc/index.html @@ -1,154 +1,231 @@ - - - -Boost Pool Library - - - + -C++ Boost + + + + + -

    Boost Pool Library

    + Boost Pool Library + -

    -

    Introduction

    + + C++ Boost -

    -

    What is Pool?

    +

    Boost Pool Library

    -

    -Pool allocation is a memory allocation scheme that is very fast, but limited in its usage. For more information on pool allocation (also called "simple segregated storage"), see the concepts document. +

    Introduction

    -

    -

    Why should I use Pool?

    +

    What is Pool?

    -

    -Using Pools gives you more control over how memory is used in your program. For example, you could have a situation where you want to allocate a bunch of small objects at one point, and then reach a point in your program where none of them are needed any more. Using pool interfaces, you can choose to run their destructors or just drop them off into oblivion; the pool interface will guarantee that there are no system memory leaks. +

    Pool allocation is a memory allocation scheme that is very fast, but + limited in its usage. For more information on pool allocation (also called + "simple segregated storage"), see the concepts + document.

    -

    -

    When should I use Pool?

    +

    Why should I use Pool?

    -

    -Pools are generally used when there is a lot of allocation and deallocation of small objects. Another common usage is the situation above, where many objects may be dropped out of memory. +

    Using Pools gives you more control over how memory is used in your + program. For example, you could have a situation where you want to allocate + a bunch of small objects at one point, and then reach a point in your + program where none of them are needed any more. Using pool interfaces, you + can choose to run their destructors or just drop them off into oblivion; the + pool interface will guarantee that there are no system memory leaks.

    -

    -In general, use Pools when you need a more efficient way to do unusual memory control. +

    When should I use Pool?

    -

    -

    How do I use Pool?

    +

    Pools are generally used when there is a lot of allocation and + deallocation of small objects. Another common usage is the situation above, + where many objects may be dropped out of memory.

    -

    -See the pool interfaces document, which covers the different Pool interfaces supplied by this library. +

    In general, use Pools when you need a more efficient way to do unusual + memory control.

    -

    -

    Library Structure and Dependencies

    +

    How do I use Pool?

    -

    -Forward declarations of all the exposed symbols for this library are in the header <boost/pool/poolfwd.hpp>. +

    See the pool interfaces document, which + covers the different Pool interfaces supplied by this library.

    -

    -The library may use macros, which will be prefixed with BOOST_POOL_. The exception to this rule are the include file guards, which (for file xxx.hpp) is BOOST_xxx_HPP. +

    Library Structure and Dependencies

    -

    -All exposed symbols defined by the library will be in namespace boost. All symbols used only by the implementation will be in namespace boost::details::pool. +

    Forward declarations of all the exposed symbols for this library are in + the header <boost/pool/poolfwd.hpp>.

    -

    -Every header used only by the implementation is in the subdirectory detail/. +

    The library may use macros, which will be prefixed with BOOST_POOL_. The exception to this rule are the include file + guards, which (for file xxx.hpp) is BOOST_xxx_HPP.

    -

    -Any header in the library may include any other header in the library or any system-supplied header at its discretion. +

    All exposed symbols defined by the library will be in namespace + boost. All symbols used only by the implementation + will be in namespace boost::details::pool.

    -

    -

    Installation

    +

    Every header used only by the implementation is in the subdirectory + detail/.

    -

    -The Boost Pool library is a header file library. That means there is no .lib, .dll, or .so to build; just add the Boost directory to your compiler's include file path, and you should be good to go! +

    Any header in the library may include any other header in the library or + any system-supplied header at its discretion.

    -

    -

    Building the Test Programs

    +

    Installation

    -

    -The subdirectory "build" contains subdirectories for several different platforms. These subdirectories contain all necessary work-around code for that platform, as well as makefiles or IDE project files as appropriate. +

    The Boost Pool library is a header file library. That means there is no + .lib, .dll, or .so to build; just add the Boost directory to your compiler's + include file path, and you should be good to go!

    -

    -Read the "readme.txt" in the proper subdirectory, if it exists. +

    Building the Test Programs

    -

    -The standard makefile targets are "all", "clean" (which deletes any intermediate files), and "veryclean" (which deletes any intermediate files and executables). All intermediate and executable files are built in the same directory as the makefile/project file. If there is a project file supplied instead of a makefile, "clean" and "veryclean" shell scripts/batch files will be provided. +

    The subdirectory "build" contains subdirectories for several different + platforms. These subdirectories contain all necessary work-around code for + that platform, as well as makefiles or IDE project files as appropriate.

    -

    -Project files and makefiles for additional platforms may be sent to Stephen Cleary at scleary AT jerviswebb DOT com. +

    Read the "readme.txt" in the proper subdirectory, if it exists.

    -

    -

    Documentation Map

    +

    The standard makefile targets are "all", "clean" (which deletes any + intermediate files), and "veryclean" (which deletes any intermediate files + and executables). All intermediate and executable files are built in the + same directory as the makefile/project file. If there is a project file + supplied instead of a makefile, "clean" and "veryclean" shell scripts/batch + files will be provided.

    - +

    Project files and makefiles for additional platforms may be sent to + Stephen Cleary at scleary AT jerviswebb DOT com.

    -

    -

    Future Directions

    +

    Documentation Map

    -

    -Another pool interface will be written: a base class for per-class pool allocation. +

    + +

    Future Directions

    + +

    Another pool interface will be written: a base class for per-class pool + allocation.

    + +

    Acknowledgements

    + +

    Many, many thanks to the Boost peers, notably Jeff Garland, Beman Dawes, + Ed Brey, Gary Powell, Peter Dimov, and Jens Maurer for providing helpful + suggestions!

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/interfaces.html b/doc/interfaces.html index 423204f..3b6f22e 100644 --- a/doc/interfaces.html +++ b/doc/interfaces.html @@ -1,137 +1,153 @@ - - - -Boost Pool Interfaces - - - + -C++ Boost + + + + + -

    Boost Pool Interfaces

    + Boost Pool Interfaces + -

    -

    Introduction

    + + C++ Boost -

    -There are several interfaces provided which allow users great flexibility in how they want to use Pools. Review the concepts document to get the basic understanding of how Pools work. +

    Boost Pool Interfaces

    -

    -

    Terminology and Tradeoffs

    +

    Introduction

    -

    -

    Object Usage vs. Singleton Usage

    +

    There are several interfaces provided which allow users great flexibility + in how they want to use Pools. Review the concepts document to get the basic understanding of how + Pools work.

    -

    -Object Usage is the method where each Pool is an object that may be created and destroyed. Destroying a Pool implicitly frees all chunks that have been allocated from it. +

    Terminology and Tradeoffs

    -

    -Singleton Usage is the method where each Pool is an object with static duration; that is, it will not be destroyed until program exit. Pool objects with Singleton Usage may be shared; thus, Singleton Usage implies thread-safety as well. System memory allocated by Pool objects with Singleton Usage may be freed through release_memory or purge_memory. +

    Object Usage vs. Singleton Usage

    -

    -

    Out-of-Memory Conditions: Exceptions vs. Null Return

    +

    Object Usage is the method where each Pool is an object that may + be created and destroyed. Destroying a Pool implicitly frees all chunks that + have been allocated from it.

    -

    -Some Pool interfaces throw exceptions when out-of-memory; others will return 0. In general, unless mandated by the Standard, Pool interfaces will always prefer to return 0 instead of throw an exception. +

    Singleton Usage is the method where each Pool is an object with + static duration; that is, it will not be destroyed until program exit. Pool + objects with Singleton Usage may be shared; thus, Singleton Usage implies + thread-safety as well. System memory allocated by Pool objects with + Singleton Usage may be freed through release_memory or purge_memory.

    -

    -

    The Interfaces

    +

    Out-of-Memory Conditions: Exceptions vs. Null Return

    -

    -

    pool

    +

    Some Pool interfaces throw exceptions when out-of-memory; others will + return 0. In general, unless mandated by the Standard, Pool interfaces will + always prefer to return 0 instead of throw an exception.

    -

    -The pool interface is a simple Object Usage interface with Null Return. +

    The Interfaces

    -

    -Example: -

    void func()
+  
    pool
    
+
+  
    The pool interface is a simple Object 
+  Usage interface with Null Return.
    
+
+  
    Example:
    
+  
    +void func()
 {
   boost::pool<> p(sizeof(int));
-  for (int i = 0; i < 10000; ++i)
+  for (int i = 0; i < 10000; ++i)
   {
     int * const t = p.malloc();
     ... // Do something with t; don't take the time to free() it
   }
-} // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed
    
+} // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed
+
    -

    -

    object_pool

    +

    object_pool

    -

    -The object_pool interface is an Object Usage interface with Null Return, but is aware of the type of the object for which it is allocating chunks. On destruction, any chunks that have been allocated from that object_pool will have their destructors called. +

    The object_pool interface is an + Object Usage interface with Null Return, but is aware of the type of the + object for which it is allocating chunks. On destruction, any chunks that + have been allocated from that object_pool will have their destructors + called.

    -

    -Example: -

    struct X { ... }; // has destructor with side-effects
+  
    Example:
    
+  
    +struct X { ... }; // has destructor with side-effects
 
 void func()
 {
   boost::object_pool<X> p;
-  for (int i = 0; i < 10000; ++i)
+  for (int i = 0; i < 10000; ++i)
   {
     X * const t = p.malloc();
     ... // Do something with t; don't take the time to free() it
   }
-} // on function exit, p is destroyed, and all destructors for the X objects are called
    
+} // on function exit, p is destroyed, and all destructors for the X objects are called
+
    -

    -

    singleton_pool

    +

    singleton_pool

    -

    -The singleton_pool interface is a Singleton Usage interface with Null Return. It's just the same as the pool interface but with Singleton Usage instead. +

    The singleton_pool interface + is a Singleton Usage interface with Null Return. It's just the same as the + pool interface but with Singleton Usage instead.

    -

    -Example: -

    struct MyPoolTag { };
+  
    Example:
    
+  
    +struct MyPoolTag { };
 
 typedef boost::singleton_pool<MyPoolTag, sizeof(int)> my_pool;
 void func()
 {
-  for (int i = 0; i < 10000; ++i)
+  for (int i = 0; i < 10000; ++i)
   {
     int * const t = my_pool::malloc();
     ... // Do something with t; don't take the time to free() it
   }
   // Explicitly free all malloc()'ed int's
   my_pool::purge_memory();
-}
    
+}
+
    -

    -

    pool_alloc

    +

    pool_alloc

    -

    -The pool_alloc interface is a Singleton Usage interface with Exceptions. It is built on the singleton_pool interface, and provides a Standard Allocator-compliant class (for use in containers, etc.). +

    The pool_alloc interface is a + Singleton Usage interface with Exceptions. It is built on the singleton_pool + interface, and provides a Standard Allocator-compliant class (for use in + containers, etc.).

    -

    -Example: -

    void func()
+  
    Example:
    
+  
    +void func()
 {
   std::vector<int, boost::pool_allocator<int> > v;
-  for (int i = 0; i < 10000; ++i)
+  for (int i = 0; i < 10000; ++i)
     v.push_back(13);
 } // Exiting the function does NOT free the system memory allocated by the pool allocator
   // You must call
   //  boost::singleton_pool<boost::pool_allocator_tag, sizeof(int)>::release_memory()
-  // in order to force that
    
+  // in order to force that
+
    -

    -

    Future Directions

    +

    Future Directions

    -

    -Another pool interface will be written: a base class for per-class pool allocation. This "pool_base" interface will be Singleton Usage with Exceptions, and built on the singleton_pool interface. +

    Another pool interface will be written: a base class for per-class pool + allocation. This "pool_base" interface will be Singleton Usage with + Exceptions, and built on the singleton_pool interface.

    +
    -

    -

    +

    Valid HTML 4.01 Transitional

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Revised + 05 December, 2006

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. - - - \ No newline at end of file +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/interfaces/object_pool.html b/doc/interfaces/object_pool.html index 7e050dc..d68b5c1 100644 --- a/doc/interfaces/object_pool.html +++ b/doc/interfaces/object_pool.html @@ -1,25 +1,30 @@ - - - -object_pool - Boost Object Pool Allocator - - - + -C++ Boost + + + + + -

    object_pool - Boost Object Pool Allocator

    + object_pool - Boost Object Pool Allocator + -

    -

    Introduction

    + + C++ Boost -

    -object_pool.hpp provides a template type that can be used for fast and efficient memory allocation. It also provides automatic destruction of non-deallocated objects. For information on other pool-based interfaces, see the other pool interfaces. +

    object_pool - Boost Object Pool Allocator

    -

    -

    Synopsis

    +

    Introduction

    -
    template <typename ElementType, typename UserAllocator = default_user_allocator_new_delete>
+  
    object_pool.hpp provides a template type that can be used for fast and 
+  efficient memory allocation. It also provides automatic destruction of 
+  non-deallocated objects. For information on other pool-based interfaces, see 
+  the other pool interfaces.
    
+
+  
    Synopsis
    
+  
    +template <typename ElementType, typename UserAllocator = default_user_allocator_new_delete>
 class object_pool
 {
   private:
@@ -42,87 +47,241 @@ class object_pool
     element_type * construct();
     // other construct() functions
     void destroy(element_type * p);
-};
    
+};
+
    -

    -

    Template Parameters

    +

    Template Parameters

    -

    -

    ElementType

    +

    ElementType

    -

    -The template parameter is the type of object to allocate/deallocate. It must have a non-throwing destructor. +

    The template parameter is the type of object to allocate/deallocate. It + must have a non-throwing destructor.

    -

    -

    UserAllocator

    +

    UserAllocator

    -

    -Defines the method that the underlying Pool will use to allocate memory from the system. See User Allocators for details. +

    Defines the method that the underlying Pool will use to allocate memory + from the system. See User Allocators for + details.

    -

    -

    Semantics

    +

    Semantics

    -

    - - -
    Symbol Table
    SymbolMeaning -
    ObjectPoolobject_pool<ElementType, UserAllocator> -
    tvalue of type ObjectPool -
    uvalue of type const ObjectPool -
    pvalue of type ElementType * -
    + + -

    -

    + Symbol Table +
    - -
    Typedefs
    ExpressionType -
    ObjectPool::element_typeElementType -
    ObjectPool::user_allocatorUserAllocator -
    ObjectPool::size_typepool<UserAllocator>::size_type -
    ObjectPool::difference_typepool<UserAllocator>::difference_type -
    + + Symbol -

    - - -
    Constructors, Destructors, and Testing
    ExpressionReturn TypeNotes -
    ObjectPool()not usedConstructs a new empty ObjectPool -
    (&t)->~ObjectPool()not usedDestructs the ObjectPool; ~ElementType() is called for each allocated ElementType that has not been deallocated. O(N). -
    u.is_from(p)boolReturns true if p was allocated from u or may be returned as the result of a future allocation from u. Returns false if p was allocated from some other pool or may be returned as the result of a future allocation from some other pool. Otherwise, the return value is meaningless; note that this function may not be used to reliably test random pointer values. -
    + Meaning + -

    - - -
    Allocation and Deallocation
    ExpressionReturn TypePre-ConditionSemantic EquivalenceNotes -
    t.malloc()ElementType *Allocates memory that can hold an object of type ElementType. If out of memory, returns 0. Amortized O(1). -
    t.free(p)not usedp must have been previously allocated from tDeallocates a chunk of memory. Note that p may not be 0. Note that the destructor for p is not called. O(N). -
    t.construct(???)ElementType *ElementType must have a constructor matching ???; the number of parameters given must not exceed what is supported through pool_constructAllocates and initializes an object of type ElementType. If out of memory, returns 0. Amortized O(1). -
    t.destroy(p)not usedp must have been previously allocated from tp->~ElementType(); t.free(p); -
    + + ObjectPool -

    -

    Symbols

    + object_pool<ElementType, UserAllocator> + -

    -

    + + t -

    -

    Implementation Details

    + value of type ObjectPool + -

    -

    + + u -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) + value of type const ObjectPool + -

    -This file can be redistributed and/or modified under the terms found in copyright.html + + p -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. + value of type ElementType * + +
    - - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Typedefs +
    ExpressionType
    ObjectPool::element_typeElementType
    ObjectPool::user_allocatorUserAllocator
    ObjectPool::size_typepool<UserAllocator>::size_type
    ObjectPool::difference_typepool<UserAllocator>::difference_type

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Constructors, Destructors, and Testing +
    ExpressionReturn TypeNotes
    ObjectPool()not usedConstructs a new empty ObjectPool
    (&t)->~ObjectPool()not usedDestructs the ObjectPool; ~ElementType() is called for each allocated ElementType + that has not been deallocated. O(N).
    u.is_from(p)boolReturns true if p was allocated from u or may be + returned as the result of a future allocation from u. Returns false if + p was allocated from some other pool or may be + returned as the result of a future allocation from some other pool. + Otherwise, the return value is meaningless; note that this function may + not be used to reliably test random pointer values.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Allocation and Deallocation +
    ExpressionReturn TypePre-ConditionSemantic EquivalenceNotes
    t.malloc()ElementType *Allocates memory that can hold an object of type ElementType. If out of memory, returns 0. Amortized O(1).
    t.free(p)not usedp must have been previously allocated from + tDeallocates a chunk of memory. Note that p may not be 0. Note that the + destructor for p is not called. O(N).
    t.construct(???)ElementType *ElementType must have a constructor + matching ???; the number of parameters given + must not exceed what is supported through pool_constructAllocates and initializes an object of type ElementType. If out of memory, returns 0. Amortized O(1).
    t.destroy(p)not usedp must have been previously allocated from + tp->~ElementType(); t.free(p);
    + +

    Symbols

    + + + +

    Implementation Details

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/interfaces/pool.html b/doc/interfaces/pool.html index 8738e61..defde50 100644 --- a/doc/interfaces/pool.html +++ b/doc/interfaces/pool.html @@ -1,29 +1,38 @@ - - - -Pool - - - + -C++ Boost + + + + + -

    Pool

    + Pool + -

    -

    Introduction

    + + C++ Boost -

    -pool is a fast memory allocator, and guarantees proper alignment of all allocated chunks. +

    Pool

    -

    -pool.hpp provides two UserAllocator classes and a template class pool, which extends and generalizes the framework provided by the simple segregated storage solution. For information on other pool-based interfaces, see the other pool interfaces. +

    Introduction

    -

    -

    Synopsis

    +

    pool is a fast memory allocator, and + guarantees proper alignment of all allocated chunks.

    -
    struct default_user_allocator_new_delete; // see User Allocators
-struct default_user_allocator_malloc_free; // see User Allocators
+  
    pool.hpp provides two UserAllocator
+  classes and a template class pool, which extends
+  and generalizes the framework provided by the simple segregated storage solution.
+  For information on other pool-based interfaces, see the other pool interfaces.
    
+
+  
    Synopsis
    
+  
    +struct default_user_allocator_new_delete; // see User Allocators
+struct default_user_allocator_malloc_free; // see User Allocators
 
 template <typename UserAllocator = default_user_allocator_new_delete>
 class pool
@@ -54,90 +63,317 @@ class pool
     void ordered_free(void * chunk);
     void free(void * chunks, size_type n);
     void ordered_free(void * chunks, size_type n);
-};
    
+};
+
    -

    -

    Template Parameters

    +

    Template Parameters

    -

    -

    UserAllocator

    +

    UserAllocator

    -

    -Defines the method that the Pool will use to allocate memory from the system. See User Allocators for details. +

    Defines the method that the Pool will use to allocate memory from the + system. See User Allocators for + details.

    -

    -

    Semantics

    +

    Semantics

    -

    - - -
    Symbol Table
    SymbolMeaning -
    Poolpool<UserAllocator> -
    tvalue of type Pool -
    uvalue of type const Pool -
    chunkvalue of type void * -
    nvalue of type size_type -
    RequestedSizevalue of type Pool::size_type; must be greater than 0 -
    + + -

    -

    + Symbol Table +
    - -
    Typedefs
    ExpressionType -
    Pool::user_allocatorUserAllocator -
    Pool::size_typeUserAllocator::size_type -
    Pool::difference_typeUserAllocator::difference_type -
    + + Symbol -

    - - -
    Constructors, Destructors, and Testing
    ExpressionReturn TypeNotes -
    Pool(RequestedSize)not usedConstructs a new empty Pool that can be used to allocate chunks of size RequestedSize -
    (&t)->~Pool()not usedDestructs the Pool, freeing its list of memory blocks -
    u.is_from(chunk)boolReturns true if chunk was allocated from u or may be returned as the result of a future allocation from u. Returns false if chunk was allocated from some other pool or may be returned as the result of a future allocation from some other pool. Otherwise, the return value is meaningless; note that this function may not be used to reliably test random pointer values. -
    u.get_requested_size()size_typeReturns the value passed into the constructor. This value will not change during the lifetime of a Pool object. -
    + Meaning + -

    - - -
    Allocation and Deallocation
    ExpressionReturn TypePre-ConditionNotes -
    t.malloc()void *Allocates a chunk of memory. Searches in the list of memory blocks for a block that has a free chunk, and returns that free chunk if found. Otherwise, creates a new memory block, adds its free list to t's free list, and returns a free chunk from that block. If a new memory block cannot be allocated, returns 0. Amortized O(1). -
    t.ordered_malloc()void *Same as above, only merges the free lists, to preserve order. Amortized O(1). -
    t.ordered_malloc(n)void *Same as above, only allocates enough contiguous chunks to cover n * requested_size bytes. Amortized O(n). -
    t.free(chunk)voidchunk must have been previously returned by t.malloc() or t.ordered_malloc().Deallocates a chunk of memory. Note that chunk may not be 0. O(1). -
    t.ordered_free(chunk)voidSame as aboveSame as above, but is order-preserving. Note that chunk may not be 0. O(N) with respect to the size of the free list -
    t.free(chunk, n)voidchunk must have been previously returned by t.ordered_malloc(n).Assumes that chunk actually refers to a block of chunks spanning n * partition_sz bytes; deallocates each chunk in that block. Note that chunk may not be 0. O(n). -
    t.ordered_free(chunk, n)voidchunk must have been previously returned by t.ordered_malloc(n).Assumes that chunk actually refers to a block of chunks spanning n * partition_sz bytes; deallocates each chunk in that block. Note that chunk may not be 0. Order-preserving. O(N + n) where N is the size of the free list. -
    t.release_memory()boolt must be ordered.Frees every memory block that doesn't have any allocated chunks. Returns true if at least one memory block was freed. -
    t.purge_memory()boolFrees every memory block. This function invalidates any pointers previously returned by allocation functions of t. Returns true if at least one memory block was freed. -
    + + Pool -

    -

    Symbols

    + pool<UserAllocator> + -

    -

    + + t -

    -

    Implementation Details

    + value of type Pool + -

    -

    + + u -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) + value of type const Pool + -

    -This file can be redistributed and/or modified under the terms found in copyright.html + + chunk -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. + value of type void * + - - \ No newline at end of file + + n + + value of type size_type + + + + RequestedSize + + value of type Pool::size_type; must be + greater than 0 + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Typedefs +
    ExpressionType
    Pool::user_allocatorUserAllocator
    Pool::size_typeUserAllocator::size_type
    Pool::difference_typeUserAllocator::difference_type

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Constructors, Destructors, and Testing +
    ExpressionReturn TypeNotes
    Pool(RequestedSize)not usedConstructs a new empty Pool that can be + used to allocate chunks of size RequestedSize
    (&t)->~Pool()not usedDestructs the Pool, freeing its list of + memory blocks
    u.is_from(chunk)boolReturns true if chunk was allocated from u or + may be returned as the result of a future allocation from u. Returns false if + chunk was allocated from some other pool or + may be returned as the result of a future allocation from some other + pool. Otherwise, the return value is meaningless; note that this + function may not be used to reliably test random + pointer values.
    u.get_requested_size()size_typeReturns the value passed into the constructor. This value will not + change during the lifetime of a Pool + object.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Allocation and Deallocation +
    ExpressionReturn TypePre-ConditionNotes
    t.malloc()void *Allocates a chunk of memory. Searches in the list of memory blocks + for a block that has a free chunk, and returns that free chunk if + found. Otherwise, creates a new memory block, adds its free list to + t's free list, and returns a free chunk from + that block. If a new memory block cannot be allocated, returns + 0. Amortized O(1).
    t.ordered_malloc()void *Same as above, only merges the free lists, to preserve order. + Amortized O(1).
    t.ordered_malloc(n)void *Same as above, only allocates enough contiguous chunks to cover + n * requested_size bytes. Amortized + O(n).
    t.free(chunk)voidchunk must have been previously returned + by t.malloc() or t.ordered_malloc().Deallocates a chunk of memory. Note that chunk may not be 0. O(1).
    t.ordered_free(chunk)voidSame as aboveSame as above, but is order-preserving. Note that chunk may not be 0. O(N) with + respect to the size of the free list
    t.free(chunk, n)voidchunk must have been previously returned + by t.ordered_malloc(n).Assumes that chunk actually refers to a + block of chunks spanning n * partition_sz + bytes; deallocates each chunk in that block. Note that chunk may not be 0. O(n).
    t.ordered_free(chunk, n)voidchunk must have been previously returned + by t.ordered_malloc(n).Assumes that chunk actually refers to a + block of chunks spanning n * partition_sz + bytes; deallocates each chunk in that block. Note that chunk may not be 0. + Order-preserving. O(N + n) where N is the size of the free list.
    t.release_memory()boolt must be ordered.Frees every memory block that doesn't have any allocated chunks. + Returns true if at least one memory block was + freed.
    t.purge_memory()boolFrees every memory block. This function invalidates any pointers + previously returned by allocation functions of t. Returns true if at least one + memory block was freed.
    + +

    Symbols

    + + + +

    Implementation Details

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 + December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/interfaces/pool_alloc.html b/doc/interfaces/pool_alloc.html index d10ec58..7daaaaa 100644 --- a/doc/interfaces/pool_alloc.html +++ b/doc/interfaces/pool_alloc.html @@ -1,25 +1,32 @@ - - - -pool_alloc - Boost Pool Standard Allocators - - - + -C++ Boost + + + + + -

    pool_alloc - Boost Pool Standard Allocators

    + pool_alloc - Boost Pool Standard Allocators + -

    -

    Introduction

    + + C++ Boost -

    -pool_alloc.hpp provides two template types that can be used for fast and efficient memory allocation. These types both satisfy the Standard Allocator requirements [20.1.5] and the additional requirements in [20.1.5/4], so they can be used with Standard or user-supplied containers. For information on other pool-based interfaces, see the other pool interfaces. +

    pool_alloc - Boost Pool Standard Allocators

    -

    -

    Synopsis

    +

    Introduction

    -
    struct pool_allocator_tag { };
+  
    pool_alloc.hpp provides two template types that can be used for fast and
+  efficient memory allocation. These types both satisfy the Standard
+  Allocator requirements [20.1.5] and the additional requirements in
+  [20.1.5/4], so they can be used with Standard or user-supplied containers.
+  For information on other pool-based interfaces, see the other pool interfaces.
    
+
+  
    Synopsis
    
+  
    +struct pool_allocator_tag { };
 
 template <typename T,
     typename UserAllocator = default_user_allocator_new_delete>
@@ -106,97 +113,166 @@ class fast_pool_allocator
 
     static pointer allocate();
     static void deallocate(pointer ptr);
-};
    
+};
+
    -

    -

    Template Parameters

    +

    Template Parameters

    -

    -

    T

    +

    T

    -

    -The first template parameter is the type of object to allocate/deallocate. +

    The first template parameter is the type of object to + allocate/deallocate.

    -

    -

    UserAllocator

    +

    UserAllocator

    -

    -Defines the method that the underlying Pool will use to allocate memory from the system. See User Allocators for details. +

    Defines the method that the underlying Pool will use to allocate memory + from the system. See User Allocators for + details.

    -

    -

    Semantics

    +

    Semantics

    -

    -Both of the pool allocators above satisfy all Standard Allocator requirements, as laid out in the Standard [20.1.5]. They also both satisfy the additional requirements found in [20.1.5/4]; this permits their usage with any Standard-compliant container. +

    Both of the pool allocators above satisfy all Standard Allocator + requirements, as laid out in the Standard [20.1.5]. They also both satisfy + the additional requirements found in [20.1.5/4]; this permits their usage + with any Standard-compliant container.

    -

    -In addition, the fast_pool_allocator also provides an additional allocation and an additional deallocation function: +

    In addition, the fast_pool_allocator also + provides an additional allocation and an additional deallocation + function:

    -

    - - -
    Symbol Table
    SymbolMeaning -
    PoolAllocfast_pool_allocator<T, UserAllocator> -
    pvalue of type T * -
    + + -

    -

    + Symbol Table +
    - -
    Additional allocation/deallocation functions (fast_pool_allocator only)
    ExpressionReturn TypeSemantic Equivalence -
    PoolAlloc::allocate()T *PoolAlloc::allocate(1) -
    PoolAlloc::deallocate(p)voidPoolAlloc::deallocate(p, 1) -
    + + Symbol -

    -The typedef user_allocator publishes the value of the UserAllocator template parameter. + Meaning + -

    -

    Notes

    + + PoolAlloc -

    -If the allocation functions run out of memory, they will throw std::bad_alloc. + fast_pool_allocator<T, + UserAllocator> + -

    -The underlying Pool type used by the allocators is accessible through the Singleton Pool Interface. The identifying tag used for pool_allocator is pool_allocator_tag, and the tag used for fast_pool_allocator is fast_pool_allocator_tag. All template parameters of the allocators (including implementation-specific ones) determine the type of the underlying Pool, with the exception of the first parameter T, whose size is used instead. + + p -

    -Since the size of T is used to determine the type of the underlying Pool, each allocator for different types of the same size will share the same underlying pool. The tag class prevents pools from being shared between pool_allocator and fast_pool_allocator. For example, on a system where sizeof(int) == sizeof(void *), pool_allocator<int> and pool_allocator<void *> will both allocate/deallocate from/to the same pool. + value of type T * + +
    -

    -If there is only one thread running before main() starts and after main() ends, then both allocators are completely thread-safe. + + -

    -

    The Fast Pool Allocator

    + + -

    -pool_allocator is a more general-purpose solution, geared towards efficiently servicing requests for any number of contiguous chunks. fast_pool_allocator is also a general-purpose solution, but is geared towards efficiently servicing requests for one chunk at a time; it will work for contiguous chunks, but not as well as pool_allocator. If you are seriously concerned about performance, use fast_pool_allocator when dealing with containers such as std::list, and use pool_allocator when dealing with containers such as std::vector. +

    -

    -

    Symbols

    + + -

    -

    + + -

    -

    Implementation Details

    + -

    -

    + + -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    + -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    + +
    + Additional allocation/deallocation functions (fast_pool_allocator only) +
    ExpressionReturn TypeSemantic Equivalence
    PoolAlloc::allocate()T *PoolAlloc::allocate(1)
    PoolAlloc::deallocate(p)voidPoolAlloc::deallocate(p, 1)
    - - \ No newline at end of file +

    The typedef user_allocator publishes the value + of the UserAllocator template parameter.

    + +

    Notes

    + +

    If the allocation functions run out of memory, they will throw + std::bad_alloc.

    + +

    The underlying Pool type used by the allocators is accessible through + the Singleton Pool Interface. The + identifying tag used for pool_allocator is + pool_allocator_tag, and the tag used for + fast_pool_allocator is fast_pool_allocator_tag. All template parameters of the + allocators (including implementation-specific ones) + determine the type of the underlying Pool, with the exception of the first + parameter T, whose size is used instead.

    + +

    Since the size of T is used to determine the + type of the underlying Pool, each allocator for different types of the same + size will share the same underlying pool. The tag class prevents + pools from being shared between pool_allocator + and fast_pool_allocator. For example, on a system + where sizeof(int) == sizeof(void *), pool_allocator<int> and pool_allocator<void *> will both allocate/deallocate + from/to the same pool.

    + +

    If there is only one thread running before main() starts and after main() + ends, then both allocators are completely thread-safe.

    + +

    The Fast Pool Allocator

    + +

    pool_allocator is a more general-purpose + solution, geared towards efficiently servicing requests for any number of + contiguous chunks. fast_pool_allocator is also a + general-purpose solution, but is geared towards efficiently servicing + requests for one chunk at a time; it will work for contiguous chunks, but + not as well as pool_allocator. If you are + seriously concerned about performance, use fast_pool_allocator when dealing with containers such as + std::list, and use pool_allocator when dealing with containers such as + std::vector.

    + +

    Symbols

    + + + +

    Implementation + Details

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 + December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/interfaces/simple_segregated_storage.html b/doc/interfaces/simple_segregated_storage.html index fe35e37..cc608b3 100644 --- a/doc/interfaces/simple_segregated_storage.html +++ b/doc/interfaces/simple_segregated_storage.html @@ -1,25 +1,35 @@ - - - -Simple Segregated Storage - - - + -C++ Boost + + + + + -

    Simple Segregated Storage

    + Simple Segregated Storage + -

    -

    Introduction

    + + C++ Boost -

    -simple_segregated_storage.hpp provides a template class simple_segregated_storage that controls access to a free list of memory chunks. Please note that this is a very simple class, with preconditions on almost all its functions. It is intended to be the fastest and smallest possible quick memory allocator — e.g., something to use in embedded systems. This class delegates many difficult preconditions to the user (i.e., alignment issues). For more general usage, see the other pool interfaces. +

    Simple Segregated Storage

    -

    -

    Synopsis

    +

    Introduction

    -
    template <typename SizeType = std::size_t>
+  
    simple_segregated_storage.hpp provides a template class simple_segregated_storage that controls access to a free
+  list of memory chunks. Please note that this is a
+  very simple class, with preconditions on almost all its
+  functions. It is intended to be the fastest and smallest possible quick
+  memory allocator — e.g., something to use in embedded systems. This
+  class delegates many difficult preconditions to the user (i.e., alignment
+  issues). For more general usage, see the other
+  pool interfaces.
    
+
+  
    Synopsis
    
+  
    +template <typename SizeType = std::size_t>
 class simple_segregated_storage
 {
   private:
@@ -50,101 +60,396 @@ class simple_segregated_storage
         size_type partition_sz);
     void ordered_free_n(void * chunks, size_type n,
         size_type partition_sz);
-};
    
+};
+
    -

    -

    Semantics

    +

    Semantics

    -

    -An object of type simple_segregated_storage<SizeType> is empty if its free list is empty. If it is not empty, then it is ordered if its free list is ordered. A free list is ordered if repeated calls to malloc() will result in a constantly-increasing sequence of values, as determined by std::less<void *>. A member function is order-preserving if the free list maintains its order orientation (that is, an ordered free list is still ordered after the member function call). +

    An object of type simple_segregated_storage<SizeType> is empty + if its free list is empty. If it is not empty, then it is ordered + if its free list is ordered. A free list is ordered if repeated calls to + malloc() will result in a constantly-increasing + sequence of values, as determined by std::less<void + *>. A member function is order-preserving if the free + list maintains its order orientation (that is, an ordered free list is + still ordered after the member function call).

    -

    - - -
    Symbol Table
    SymbolMeaning -
    Storesimple_segregated_storage<SizeType> -
    tvalue of type Store -
    uvalue of type const Store -
    block, chunk, endvalues of type void * -
    partition_sz, sz, nvalues of type Store::size_type -
    + + -

    -

    + Symbol Table +
    - -
    Template Parameters
    ParameterDefaultRequirements -
    SizeTypestd::size_tAn unsigned integral type -
    + + Symbol -

    - - -
    Typedefs
    SymbolType -
    size_typeSizeType -
    + Meaning + -

    - - -
    Constructors, Destructors, and State
    ExpressionReturn TypePost-ConditionNotes -
    Store()not usedempty()Constructs a new Store -
    (&t)->~Store()not usedDestructs the Store -
    u.empty()boolReturns true if u is empty. Order-preserving. -
    + + Store -

    - - - + - + - + - + -
    Segregation
    ExpressionReturn TypePre-ConditionPost-ConditionSemantic EquivalenceNotes + simple_segregated_storage<SizeType>
    Store::segregate(block, sz, partition_sz, end)void *partition_sz >= sizeof(void *)
    partition_sz = sizeof(void *) * i, for some integer i
    sz >= partition_sz
    block is properly aligned for an array of objects of size partition_sz
    block is properly aligned for an array of void *    		Interleaves a free list through the memory block specified by block of size sz bytes, partitioning it into as many partition_sz-sized chunks as possible. The last chunk is set to point to end, and a pointer to the first chunck is returned (this is always equal to block). This interleaved free list is ordered. O(sz). +
    t
    Store::segregate(block, sz, partition_sz)void *Same as aboveStore::segregate(block, sz, partition_sz, 0) + value of type Store
    t.add_block(block, sz, partition_sz)voidSame as above!t.empty()Segregates the memory block specified by block of size sz bytes into partition_sz-sized chunks, and adds that free list to its own. If t was empty before this call, then it is ordered after this call. O(sz). +
    u
    t.add_ordered_block(block, sz, partition_sz)voidSame as above!t.empty()Segregates the memory block specified by block of size sz bytes into partition_sz-sized chunks, and merges that free list into its own. Order-preserving. O(sz). -
    + value of type const Store + -

    - - - + - + - + - + +
    Allocation and Deallocation
    ExpressionReturn TypePre-ConditionPost-ConditionSemantic EquivalenceNotes -
    t.malloc()void *!t.empty()Takes the first available chunk from the free list and returns it. Order-preserving. O(1). +
    block, chunk, end
    t.free(chunk)voidchunk was previously returned from a call to t.malloc()!t.empty()Places chunk back on the free list. Note that chunk may not be 0. O(1). + values of type void *
    t.ordered_free(chunk)voidSame as above!t.empty()Places chunk back on the free list. Note that chunk may not be 0. Order-preserving. O(N) with respect to the size of the free list. +
    partition_sz, sz, n
    t.malloc_n(n, partition_sz)void *Attempts to find a contiguous sequence of n partition_sz-sized chunks. If found, removes them all from the free list and returns a pointer to the first. If not found, returns 0. It is strongly recommended (but not required) that the free list be ordered, as this algorithm will fail to find a contiguous sequence unless it is contiguous in the free list as well. Order-preserving. O(N) with respect to the size of the free list. + values of type Store::size_type

    -t.free_n(chunk, n, partition_sz)voidchunk was previously returned from a call to t.malloc_n(n, partition_sz)!t.empty()t.add_block(chunk, n * partition_sz, partition_sz)Assumes that chunk actually refers to a block of chunks spanning n * partition_sz bytes; segregates and adds in that block. Note that chunk may not be 0. O(n). + + -
    + Template Parameters +
    t.ordered_free_n(chunk, n, partition_sz)voidsame as abovesame as abovet.add_ordered_block(chunk, n * partition_sz, partition_sz)Same as above, except it merges in the free list. Order-preserving. O(N + n) where N is the size of the free list. -
    + + Parameter -

    -

    Symbols

    + Default -

    -

    + Requirements + -

    -

    Implementation Details

    + + SizeType -

    -

    + std::size_t -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) + An unsigned integral type + +
    -

    -This file can be redistributed and/or modified under the terms found in copyright.html + + -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    + - - \ No newline at end of file + + + + + + + + +
    + Typedefs +
    SymbolType
    size_typeSizeType

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Constructors, Destructors, and State +
    ExpressionReturn TypePost-ConditionNotes
    Store()not usedempty()Constructs a new Store
    (&t)->~Store()not usedDestructs the Store
    u.empty()boolReturns true if u is empty. Order-preserving.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Segregation +
    ExpressionReturn TypePre-ConditionPost-ConditionSemantic EquivalenceNotes
    Store::segregate(block, sz, partition_sz, end)void *partition_sz >= sizeof(void *)
    + partition_sz = sizeof(void *) * i, for some + integer i
    + sz >= partition_sz
    + block is properly aligned for an array of + objects of size partition_sz
    + block is properly aligned for an array of + void *    		Interleaves a free list through the memory block specified by + block of size sz + bytes, partitioning it into as many partition_sz-sized chunks as possible. The last chunk is + set to point to end, and a pointer to the + first chunck is returned (this is always equal to block). This interleaved free list is ordered. + O(sz).
    Store::segregate(block, sz, partition_sz)void *Same as aboveStore::segregate(block, sz, partition_sz, 0)
    t.add_block(block, sz, partition_sz)voidSame as above!t.empty()Segregates the memory block specified by block of size sz bytes into + partition_sz-sized chunks, and adds that free + list to its own. If t was empty before this + call, then it is ordered after this call. O(sz).
    t.add_ordered_block(block, sz, partition_sz)voidSame as above!t.empty()Segregates the memory block specified by block of size sz bytes into + partition_sz-sized chunks, and merges that + free list into its own. Order-preserving. O(sz).

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Allocation and Deallocation +
    ExpressionReturn TypePre-ConditionPost-ConditionSemantic EquivalenceNotes
    t.malloc()void *!t.empty()Takes the first available chunk from the free list and returns it. + Order-preserving. O(1).
    t.free(chunk)voidchunk was previously returned from a call + to t.malloc()!t.empty()Places chunk back on the free list. Note + that chunk may not be 0. O(1).
    t.ordered_free(chunk)voidSame as above!t.empty()Places chunk back on the free list. Note + that chunk may not be 0. Order-preserving. O(N) with respect to the size of the + free list.
    t.malloc_n(n, partition_sz)void *Attempts to find a contiguous sequence of n partition_sz-sized chunks. If + found, removes them all from the free list and returns a pointer to the + first. If not found, returns 0. It is + strongly recommended (but not required) that the free list be ordered, + as this algorithm will fail to find a contiguous sequence unless it is + contiguous in the free list as well. Order-preserving. O(N) with + respect to the size of the free list.
    t.free_n(chunk, n, partition_sz)voidchunk was previously returned from a call + to t.malloc_n(n, partition_sz)!t.empty()t.add_block(chunk, n * partition_sz, + partition_sz)Assumes that chunk actually refers to a + block of chunks spanning n * partition_sz + bytes; segregates and adds in that block. Note that chunk may not be 0. O(n).
    t.ordered_free_n(chunk, n, partition_sz)voidsame as abovesame as abovet.add_ordered_block(chunk, n * partition_sz, + partition_sz)Same as above, except it merges in the free list. Order-preserving. + O(N + n) where N is the size of the free list.
    + +

    Symbols

    + + + +

    Implementation + Details

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/interfaces/singleton_pool.html b/doc/interfaces/singleton_pool.html index a1d2b9b..16e9e07 100644 --- a/doc/interfaces/singleton_pool.html +++ b/doc/interfaces/singleton_pool.html @@ -1,25 +1,31 @@ - - - -Singleton Pool - - - + -C++ Boost + + + + + -

    Singleton Pool

    + Singleton Pool + -

    -

    Introduction

    + + C++ Boost -

    -singleton_pool.hpp provides a template class singleton_pool, which provides access to a pool as a singleton object. For information on other pool-based interfaces, see the other pool interfaces. +

    Singleton Pool

    -

    -

    Synopsis

    +

    Introduction

    -
    template <typename Tag, unsigned RequestedSize,
+  
    singleton_pool.hpp provides a template class singleton_pool, which provides access to a pool as a singleton object. For information on other
+  pool-based interfaces, see the other pool
+  interfaces.
    
+
+  
    Synopsis
    
+  
    +template <typename Tag, unsigned RequestedSize,
     typename UserAllocator = default_user_allocator_new_delete>
 struct singleton_pool
 {
@@ -50,108 +56,253 @@ struct singleton_pool
 
     static bool release_memory();
     static bool purge_memory();
-};
    
+};
+
    -

    -

    Notes

    +

    Notes

    -

    -The underlying pool p referenced by the static functions in singleton_pool is actually declared in a way that it is: -

    +

    The underlying pool p referenced by the static + functions in singleton_pool is actually declared + in a way that it is:

    -

    -Note that a different underlying pool p exists for each different set of template parameters, including implementation-specific ones. +

    -

    -

    Tag

    +

    Note that a different underlying pool p exists + for each different set of template parameters, including implementation-specific + ones.

    -

    -The Tag template parameter allows different unbounded sets of singleton pools to exist. For example, the pool allocators use two tag classes to ensure that the two different allocator types never share the same underlying singleton pool. +

    Template Parameters

    -

    -Tag is never actually used by singleton_pool. +

    Tag

    -

    -

    RequestedSize

    +

    The Tag template parameter allows different + unbounded sets of singleton pools to exist. For example, the pool allocators use two tag classes to ensure that + the two different allocator types never share the same underlying singleton + pool.

    -

    -The requested size of memory chunks to allocate. This is passed as a constructor parameter to the underlying pool. Must be greater than 0. +

    Tag is never actually used by singleton_pool.

    -

    -

    UserAllocator

    +

    RequestedSize

    -

    -Defines the method that the underlying pool will use to allocate memory from the system. See User Allocators for details. +

    The requested size of memory chunks to allocate. This is passed as a + constructor parameter to the underlying pool. + Must be greater than 0.

    -

    -

    Semantics

    +

    UserAllocator

    -

    - - -
    Symbol Table
    SymbolMeaning -
    SingletonPoolsingleton_pool<Tag, RequestedSize, UserAllocator> -
    chunkvalue of type void * -
    nvalue of type size_type -
    +

    Defines the method that the underlying pool + will use to allocate memory from the system. See User Allocators for details.

    -

    - - -
    Typedefs/Static Const Values
    ExpressionType/Value -
    SingletonPool::tagTag -
    SingletonPool::user_allocatorUserAllocator -
    SingletonPool::size_typepool<UserAllocator>::size_type -
    SingletonPool::difference_typepool<UserAllocator>::difference_type -
    SingletonPool::requested_sizeRequestedSize -
    +

    Semantics

    -

    - - -
    Functions
    ExpressionReturn TypeSemantic Equivalent -
    SingletonPool::is_from(chunk)boolSingletonPool::p.is_from(chunk); synchronized -
    SingletonPool::malloc()void *SingletonPool::p.malloc(); synchronized -
    SingletonPool::ordered_malloc(n)void *SingletonPool::p.ordered_malloc(n); synchronized -
    SingletonPool::free(chunk)voidSingletonPool::p.free(chunk); synchronized -
    SingletonPool::ordered_free(chunk)voidSingletonPool::p.ordered_free(chunk); synchronized -
    SingletonPool::free(chunk, n)voidSingletonPool::p.free(chunk, n); synchronized -
    SingletonPool::ordered_free(chunk, n)voidSingletonPool::p.ordered_free(chunk, n); synchronized -
    SingletonPool::release_memory()boolSingletonPool::p.release_memory(); synchronized -
    SingletonPool::purge_memory()boolSingletonPool::p.purge_memory(); synchronized -
    + + -

    -For more information on the semantics of these functions, see the pool interface. +

    + -

    -

    Symbols

    + + -

    -

    + + -

    -

    Implementation Details

    + + -

    -

    + + -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    + -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    + -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. +

    + +
    + Symbol Table +
    SymbolMeaning
    SingletonPoolsingleton_pool<Tag, RequestedSize, + UserAllocator>
    chunkvalue of type void *
    nvalue of type size_type

    - - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Typedefs/Static Const Values +
    ExpressionType/Value
    SingletonPool::tagTag
    SingletonPool::user_allocatorUserAllocator
    SingletonPool::size_typepool<UserAllocator>::size_type
    SingletonPool::difference_typepool<UserAllocator>::difference_type
    SingletonPool::requested_sizeRequestedSize

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Functions +
    ExpressionReturn TypeSemantic Equivalent
    SingletonPool::is_from(chunk)boolSingletonPool::p.is_from(chunk); + synchronized
    SingletonPool::malloc()void *SingletonPool::p.malloc(); + synchronized
    SingletonPool::ordered_malloc(n)void *SingletonPool::p.ordered_malloc(n); + synchronized
    SingletonPool::free(chunk)voidSingletonPool::p.free(chunk); + synchronized
    SingletonPool::ordered_free(chunk)voidSingletonPool::p.ordered_free(chunk); + synchronized
    SingletonPool::free(chunk, n)voidSingletonPool::p.free(chunk, n); + synchronized
    SingletonPool::ordered_free(chunk, n)voidSingletonPool::p.ordered_free(chunk, n); + synchronized
    SingletonPool::release_memory()boolSingletonPool::p.release_memory(); + synchronized
    SingletonPool::purge_memory()boolSingletonPool::p.purge_memory(); + synchronized
    + +

    For more information on the semantics of these functions, see the + pool interface.

    + +

    Symbols

    + + + +

    Implementation + Details

    +
    + +

    Valid HTML 4.01 Transitional

    + +

    Revised + 05 December, 2006

    + +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)

    + +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/interfaces/user_allocator.html b/doc/interfaces/user_allocator.html index 7197198..fc03a37 100644 --- a/doc/interfaces/user_allocator.html +++ b/doc/interfaces/user_allocator.html @@ -1,59 +1,130 @@ - - - -Pool - - - + -C++ Boost + + + + + -

    User Allocators

    + Pool + -

    -

    Introduction

    + + C++ Boost -

    -Pool objects need to request memory blocks from the system, which the Pool then splits into chunks to allocate to the user. By specifying a UserAllocator template parameter to various Pool interfaces, users can control how those system memory blocks are allocated. +

    User Allocators

    -

    -

    Semantics

    +

    Introduction

    -

    - - -
    Symbol Table
    SymbolMeaning -
    UserAllocatorA User Allocator type -
    blockvalue of type char * -
    nvalue of type UserAllocator::size_type -
    +

    Pool objects need to request memory blocks from the system, which the + Pool then splits into chunks to allocate to the user. By specifying a + UserAllocator template parameter to various Pool + interfaces, users can control how those system memory blocks are + allocated.

    -

    - - -
    Typedefs
    ExpressionType -
    UserAllocator::size_typeAn unsigned integral type that can represent the size of the largest object to be allocated -
    UserAllocator::difference_typeA signed integral type that can represent the difference of any two pointers -
    +

    Semantics

    -

    - - -
    Allocation and Deallocation
    ExpressionReturn TypePre-Condition/Notes -
    UserAllocator::malloc(n)char *Attempts to allocate n bytes from the system. Returns 0 if out-of-memory. -
    UserAllocator::free(block)voidblock must have been previously returned from a call to UserAllocator::malloc. -
    + + -

    -

    Provided Implementations

    + + -

    -There are two UserAllocator classes provided. Both of them are in pool.hpp (see pool). The default value for the template parameter UserAllocator is always default_user_allocator_new_delete. +

    + -

    -

    Synopsis

    + + -
    struct default_user_allocator_new_delete
+
    + + + + + + + + + + + + + +
    + Symbol Table +
    SymbolMeaning
    UserAllocatorA User Allocator type
    blockvalue of type char *
    nvalue of type UserAllocator::size_type

    + + + + + + + + + + + + + + + + + + + + + +
    + Typedefs +
    ExpressionType
    UserAllocator::size_typeAn unsigned integral type that can represent the size of the + largest object to be allocated
    UserAllocator::difference_typeA signed integral type that can represent the difference of any two + pointers

    + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Allocation and Deallocation +
    ExpressionReturn TypePre-Condition/Notes
    UserAllocator::malloc(n)char *Attempts to allocate n bytes from the + system. Returns 0 if out-of-memory.
    UserAllocator::free(block)voidblock must have been previously returned + from a call to UserAllocator::malloc.
    + +

    Provided Implementations

    + +

    There are two UserAllocator classes provided. + Both of them are in pool.hpp (see pool). The + default value for the template parameter UserAllocator is always default_user_allocator_new_delete.

    + +

    Synopsis

    + 
    +struct default_user_allocator_new_delete
 {
   typedef std::size_t size_type;
   typedef std::ptrdiff_t difference_type;
@@ -73,19 +144,24 @@ struct default_user_allocator_malloc_free
   { return reinterpret_cast<char *>(std::malloc(bytes)); }
   static void free(char * const block)
   { std::free(block); }
-};
    +}; + +
    -

    -

    +

    Valid HTML 4.01 Transitional

    -

    -Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com) +

    Revised + 05 + December, 2006

    -

    -This file can be redistributed and/or modified under the terms found in copyright.html +

    Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT + com)

    -

    -This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose. - - - \ No newline at end of file +

    Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt + or copy at http://www.boost.org/LICENSE_1_0.txt)

    + + diff --git a/doc/pool.css b/doc/pool.css index 35d7618..6dc8f8d 100644 --- a/doc/pool.css +++ b/doc/pool.css @@ -1,11 +1,9 @@ /* Copyright (C) 2000 Stephen Cleary - This file can be redistributed and/or modified under the terms found - in "copyright.html" - This software and its documentation is provided "as is" without express or - implied warranty, and with no claim as to its suitability for any purpose. + Distributed under the Boost Software License, Version 1.0. (See accompany- + ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) */ *.code { font-family: monospace; } -*.m4 { white-space: pre; font-family: monospace; font-size: 75% } +*.m4 { white-space: pre; font-family: monospace; font-size: 75% } \ No newline at end of file diff --git a/include/boost/pool/detail/for.m4 b/include/boost/pool/detail/for.m4 index 38d8b75..f926a11 100644 --- a/include/boost/pool/detail/for.m4 +++ b/include/boost/pool/detail/for.m4 @@ -1,10 +1,8 @@ m4_dnl m4_dnl Copyright (C) 2000 Stephen Cleary m4_dnl -m4_dnl This file can be redistributed and/or modified under the terms found -m4_dnl in "copyright.html" -m4_dnl This software and its documentation is provided "as is" without express or -m4_dnl implied warranty, and with no claim as to its suitability for any purpose. +m4_dnl Distributed under the Boost Software License, Version 1.0. (See accompany- +m4_dnl ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) m4_dnl m4_dnl See http://www.boost.org for updates, documentation, and revision history. m4_dnl diff --git a/include/boost/pool/detail/pool_construct.bat b/include/boost/pool/detail/pool_construct.bat index e53e41d..2ae365f 100755 --- a/include/boost/pool/detail/pool_construct.bat +++ b/include/boost/pool/detail/pool_construct.bat @@ -2,13 +2,10 @@ rem rem Copyright (C) 2000, 2001 Stephen Cleary rem -rem This file can be redistributed and/or modified under the terms found -rem in "copyright.html" -rem This software and its documentation is provided "as is" without express or -rem implied warranty, and with no claim as to its suitability for any purpose. -rem -rem See http://www.boost.org for updates, documentation, and revision history. -rem +rem Distributed under the Boost Software License, Version 1.0. (See accompany- +rem ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + + rem Check for Windows NT if %OS%==Windows_NT goto NT diff --git a/include/boost/pool/detail/pool_construct.m4 b/include/boost/pool/detail/pool_construct.m4 index d923749..91671b4 100644 --- a/include/boost/pool/detail/pool_construct.m4 +++ b/include/boost/pool/detail/pool_construct.m4 @@ -1,10 +1,8 @@ m4_dnl m4_dnl Copyright (C) 2000 Stephen Cleary m4_dnl -m4_dnl This file can be redistributed and/or modified under the terms found -m4_dnl in "copyright.html" -m4_dnl This software and its documentation is provided "as is" without express or -m4_dnl implied warranty, and with no claim as to its suitability for any purpose. +m4_dnl Distributed under the Boost Software License, Version 1.0. (See accompany- +m4_dnl ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) m4_dnl m4_dnl See http://www.boost.org for updates, documentation, and revision history. m4_dnl @@ -42,10 +40,8 @@ m4_dnl Begin the generated file. m4_dnl // Copyright (C) 2000 Stephen Cleary // -// This file can be redistributed and/or modified under the terms found -// in "copyright.html" -// This software and its documentation is provided "as is" without express or -// implied warranty, and with no claim as to its suitability for any purpose. +// Distributed under the Boost Software License, Version 1.0. (See accompany- +// ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) // // See http://www.boost.org for updates, documentation, and revision history. diff --git a/include/boost/pool/detail/pool_construct.sh b/include/boost/pool/detail/pool_construct.sh index a6027bf..aa09035 100644 --- a/include/boost/pool/detail/pool_construct.sh +++ b/include/boost/pool/detail/pool_construct.sh @@ -2,10 +2,8 @@ # # Copyright (C) 2000 Stephen Cleary # -# This file can be redistributed and/or modified under the terms found -# in "copyright.html" -# This software and its documentation is provided "as is" without express or -# implied warranty, and with no claim as to its suitability for any purpose. +# Distributed under the Boost Software License, Version 1.0. (See accompany- +# ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) # # See http://www.boost.org for updates, documentation, and revision history. # diff --git a/include/boost/pool/detail/pool_construct_simple.bat b/include/boost/pool/detail/pool_construct_simple.bat index f85140e..23ac2a3 100755 --- a/include/boost/pool/detail/pool_construct_simple.bat +++ b/include/boost/pool/detail/pool_construct_simple.bat @@ -2,10 +2,8 @@ rem rem Copyright (C) 2001 Stephen Cleary rem -rem This file can be redistributed and/or modified under the terms found -rem in "copyright.html" -rem This software and its documentation is provided "as is" without express or -rem implied warranty, and with no claim as to its suitability for any purpose. +rem Distributed under the Boost Software License, Version 1.0. (See accompany- +rem ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) rem rem See http://www.boost.org for updates, documentation, and revision history. rem diff --git a/include/boost/pool/detail/pool_construct_simple.m4 b/include/boost/pool/detail/pool_construct_simple.m4 index 7c03d5f..11a27e7 100644 --- a/include/boost/pool/detail/pool_construct_simple.m4 +++ b/include/boost/pool/detail/pool_construct_simple.m4 @@ -1,10 +1,8 @@ m4_dnl m4_dnl Copyright (C) 2001 Stephen Cleary m4_dnl -m4_dnl This file can be redistributed and/or modified under the terms found -m4_dnl in "copyright.html" -m4_dnl This software and its documentation is provided "as is" without express or -m4_dnl implied warranty, and with no claim as to its suitability for any purpose. +m4_dnl Distributed under the Boost Software License, Version 1.0. (See accompany- +m4_dnl ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) m4_dnl m4_dnl See http://www.boost.org for updates, documentation, and revision history. m4_dnl diff --git a/include/boost/pool/detail/pool_construct_simple.sh b/include/boost/pool/detail/pool_construct_simple.sh index bca0e25..413b5d7 100644 --- a/include/boost/pool/detail/pool_construct_simple.sh +++ b/include/boost/pool/detail/pool_construct_simple.sh @@ -2,10 +2,8 @@ # # Copyright (C) 2001 Stephen Cleary # -# This file can be redistributed and/or modified under the terms found -# in "copyright.html" -# This software and its documentation is provided "as is" without express or -# implied warranty, and with no claim as to its suitability for any purpose. +# Distributed under the Boost Software License, Version 1.0. (See accompany- +# ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) # # See http://www.boost.org for updates, documentation, and revision history. #