Bug 847248 (part 1) - Improve documentation and reduce slop potential of nsFixedSizeAllocator. r=bz.
authorNicholas Nethercote <nnethercote@mozilla.com>
Sun, 03 Mar 2013 18:42:41 -0800
changeset 124063 47ada7ee45de0c570172e76b51dd446b5ce11eaf
parent 124062 0a80836e1a6bfe2815f3051fbb7bdd32bf6f7ab7
child 124064 f3ad021e88f083fdb851596679103153c5df648e
push id24406
push userryanvm@gmail.com
push dateThu, 07 Mar 2013 17:19:02 +0000
treeherdermozilla-central@71395a927025 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersbz
bugs847248
milestone22.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 847248 (part 1) - Improve documentation and reduce slop potential of nsFixedSizeAllocator. r=bz.
xpcom/ds/nsFixedSizeAllocator.cpp
xpcom/ds/nsFixedSizeAllocator.h
--- a/xpcom/ds/nsFixedSizeAllocator.cpp
+++ b/xpcom/ds/nsFixedSizeAllocator.cpp
@@ -1,20 +1,14 @@
 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-/*
-
-  Implementation for nsFixedSizeAllocator
-
-*/
-
-#include "nsCRT.h"
+#include "nsDebug.h"
 #include "nsFixedSizeAllocator.h"
 
 nsFixedSizeAllocator::Bucket *
 nsFixedSizeAllocator::AddBucket(size_t aSize)
 {
     void* p;
     PL_ARENA_ALLOCATE(p, &mPool, sizeof(Bucket));
     if (! p)
@@ -28,29 +22,28 @@ nsFixedSizeAllocator::AddBucket(size_t a
     mBuckets = bucket;
     return bucket;
 }
 
 nsresult
 nsFixedSizeAllocator::Init(const char* aName,
                            const size_t* aBucketSizes,
                            int32_t aNumBuckets,
-                           int32_t aInitialSize,
+                           int32_t aChunkSize,
                            int32_t aAlign)
 {
     NS_PRECONDITION(aNumBuckets > 0, "no buckets");
     if (aNumBuckets <= 0)
         return NS_ERROR_INVALID_ARG;
 
     // Blow away the old pool if we're being re-initialized.
     if (mBuckets)
         PL_FinishArenaPool(&mPool);
 
-    int32_t bucketspace = aNumBuckets * sizeof(Bucket);
-    PL_InitArenaPool(&mPool, aName, bucketspace + aInitialSize, aAlign);
+    PL_InitArenaPool(&mPool, aName, aChunkSize, aAlign);
 
     mBuckets = nullptr;
     for (int32_t i = 0; i < aNumBuckets; ++i)
         AddBucket(aBucketSizes[i]);
 
     return NS_OK;
 }
 
--- a/xpcom/ds/nsFixedSizeAllocator.h
+++ b/xpcom/ds/nsFixedSizeAllocator.h
@@ -1,24 +1,52 @@
 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 /*
-
   A simple fixed-size allocator that allocates its memory from an
   arena.
 
-  Although the allocator can handle blocks of any size, its
-  preformance will degrade rapidly if used to allocate blocks of
-  arbitrary size. Ideally, it should be used to allocate and recycle a
-  large number of fixed-size blocks.
+  WARNING: you probably shouldn't use this class.  If you are thinking of using
+  it, you should have measurements that indicate it has a clear advantage over
+  vanilla malloc/free or vanilla new/delete.
+
+  This allocator has the following notable properties.
+
+  - Although it can handle blocks of any size, its performance will degrade
+    rapidly if used to allocate blocks of many different sizes.  Ideally, it
+    should be used to allocate and recycle many fixed-size blocks.
+
+  - None of the chunks allocated are released back to the OS unless Init() is
+    re-called or the nsFixedSizeAllocator is destroyed.  So it's generally a
+    bad choice if it might live for a long time (e.g. see bug 847210).
 
-  Here is a typical usage pattern:
+  - You have to manually construct and destruct objects allocated with it.
+    Furthermore, any objects that haven't been freed when the allocator is
+    destroyed won't have their destructors run.  So if you are allocating
+    objects that have destructors they should all be manually freed (and
+    destructed) before the allocator is destroyed.
+
+  - It does no locking and so is not thread-safe.  If all allocations and
+    deallocations are on a single thread, this is fine and these operations
+    might be faster than vanilla malloc/free due to the lack of locking.
+
+    Otherwise, you need to add locking yourself.  In unusual circumstances,
+    this can be a good thing, because it reduces contention over the main
+    malloc/free lock.  See TimerEventAllocator and bug 733277 for an example.
+
+  - Because it's an arena-style allocator, it might reduce fragmentation,
+    because objects allocated with the arena won't be co-allocated with
+    longer-lived objects.  However, this is hard to demonstrate and you should
+    not assume the effects are significant without conclusive measurements.
+
+  Here is a typical usage pattern.  Note that no locking is done in this
+  example so it's only safe for use on a single thread.
 
     #include NEW_H // You'll need this!
     #include "nsFixedSizeAllocator.h"
 
     // Say this is the object you want to allocate a ton of
     class Foo {
     public:
       // Implement placement new & delete operators that will
@@ -37,63 +65,57 @@
         aAllocator.Free(aFoo, sizeof(Foo));
       }
 
       // ctor & dtor
       Foo() {}
       ~Foo() {}
     };
 
-
     int main(int argc, char* argv[])
     {
       // Somewhere in your code, you'll need to create an
       // nsFixedSizeAllocator object and initialize it:
       nsFixedSizeAllocator pool;
 
       // The fixed size allocator will support multiple fixed sizes.
       // This array lists an initial set of sizes that the allocator
       // should be prepared to support. In our case, there's just one,
       // which is Foo.
-      static const size_t kBucketSizes[]
-        = { sizeof(Foo) }
+      static const size_t kBucketSizes[] = { sizeof(Foo) }
 
       // This is the number of different "buckets" you'll need for
       // fixed size objects. In our example, this will be "1".
-      static const int32_t kNumBuckets
-        = sizeof(kBucketSizes) / sizeof(size_t);
+      static const int32_t kNumBuckets = sizeof(kBucketSizes) / sizeof(size_t);
 
-      // This is the intial size of the allocator, in bytes. We'll
-      // assume that we want to start with space for 1024 Foo objects.
-      static const int32_t kInitialPoolSize = sizeof(Foo) * 1024;
+      // This is the size of the chunks used by the allocator, which should be
+      // a power of two to minimize slop.
+      static const int32_t kInitialPoolSize = 4096;
 
-      // Initialize (or re-initialize) the pool
+      // Initialize (or re-initialize) the pool.
       pool.Init("TheFooPool", kBucketSizes, kNumBuckets, kInitialPoolSize);
 
-      // Now we can use the pool.
-
       // Create a new Foo object using the pool:
       Foo* foo = Foo::Create(pool);
-      if (! foo) {
+      if (!foo) {
         // uh oh, out of memory!
       }
 
       // Delete the object. The memory used by `foo' is recycled in
-      // the pool, and placed in a freelist
+      // the pool, and placed in a freelist.
       Foo::Destroy(foo);
 
       // Create another foo: this one will be allocated from the
-      // free-list
+      // free-list.
       foo = Foo::Create(pool);
 
       // When pool is destroyed, all of its memory is automatically
       // freed. N.B. it will *not* call your objects' destructors! In
       // this case, foo's ~Foo() method would never be called.
     }
-
 */
 
 #ifndef nsFixedSizeAllocator_h__
 #define nsFixedSizeAllocator_h__
 
 #include "nscore.h"
 #include "nsError.h"
 #include "plarena.h"
@@ -131,27 +153,33 @@ public:
     nsFixedSizeAllocator() : mBuckets(nullptr) {}
 
     ~nsFixedSizeAllocator() {
         if (mBuckets)
             PL_FinishArenaPool(&mPool);
     }
 
     /**
-     * Initialize the fixed size allocator. 'aName' is used to tag
-     * the underlying PLArena object for debugging and measurement
-     * purposes. 'aNumBuckets' specifies the number of elements in
-     * 'aBucketSizes', which is an array of integral block sizes
-     * that this allocator should be prepared to handle.
+     * Initialize the fixed size allocator.
+     * - 'aName' is used to tag the underlying PLArena object for debugging and
+     *   measurement purposes.
+     * - 'aNumBuckets' specifies the number of elements in 'aBucketSizes'.
+     * - 'aBucketSizes' is an array of integral block sizes that this allocator
+     *   should be prepared to handle.
+     * - 'aChunkSize' is the size of the chunks used.  It should be a power of
+     *   two to minimize slop bytes caused by the underlying malloc
+     *   implementation rounding up request sizes.  Some of the space in each
+     *   chunk will be used by the nsFixedSizeAllocator (or the underlying
+     *   PLArena) itself.
      */
     nsresult
     Init(const char* aName,
          const size_t* aBucketSizes,
          int32_t aNumBuckets,
-         int32_t aInitialSize,
+         int32_t aChunkSize,
          int32_t aAlign = 0);
 
     /**
      * Allocate a block of memory 'aSize' bytes big.
      */
     void* Alloc(size_t aSize);
 
     /**