3.0 allocation changes

Author: kay-kim

source/core/storage.txt

@@ -167,42 +167,40 @@ Power of 2 Sized Allocations
 MongoDB 3.0 uses the power of 2 sizes allocation as the default record
 allocation strategy for MMAPv1. With the power of 2 sizes allocation
 strategy, each record has a size in bytes that is a power of 2 (e.g.
-32, 64, 128, 256, 512 ... 16777216). The smallest allocation for a
-document is 32 bytes.
+32, 64, 128, 256, 512 ... 2MB). For documents larger than 2MB, the
+allocation is rounded up to the nearest multiple of 2MB.
 
 The power of 2 sizes allocation strategy has the following key
 properties:
 
-- Can efficiently reuse freed records to reduce fragmentation. The
-  limited number of record allocation sizes help ensure that MongoDB
-  can efficiently reuse free space created by document deletion or
-  relocation.
+- Can efficiently reuse freed records to reduce fragmentation.
+  Quantizing record allocation sizes into a fixed set of sizes
+  increases the probability that an insert will fit into the free space
+  created by an earlier document deletion or relocation.
 
-- Can minimize the occurrence of re-allocation. In many cases, the
-  record allocations are significantly larger than the documents they
-  hold. This significantly larger size minimizes the chance that the
-  :program:`mongod` will need to allocate a new record if the document
-  grows. Although the power of 2 sizes strategy can minimize the
-  occurrence of reallocation, it does not eliminate
-  document re-allocation.
+- Can reduce moves. The added padding space gives a document room to
+  grow without requiring a move. In addition to saving the cost of
+  moving, this results in less updates to indexes. Although the power
+  of 2 sizes strategy can minimize moves, it does not eliminate them
+  entirely.
 
 .. _exact-fit-allocation:
 
-Exact Fit Allocation with No Padding
-````````````````````````````````````
+No Padding Allocation Strategy
+``````````````````````````````
 
 .. versionchanged:: 3.0.0
 
 For collections whose workloads do not change the document sizes, such
-as workloads that consist of insert-only operations, insert-and-remove
-operations on documents of uniform size, or update operations that do
-not increase document size, you can disable the :ref:`power of 2
-allocation <power-of-2-allocation>` using the :dbcommand:`collMod`
-command with the :collflag:`noPadding` flag or the
-:method:`db.createCollection()` method with the ``noPadding`` option.
-
-Prior to version 3.0.0, MongoDB used an exact fit allocation strategy
-that included a dynamically calculated :data:`padding
+as workloads that consist of insert-only operations or update
+operations that do not increase document size (such as incrementing a
+counter), you can disable the :ref:`power of 2 allocation
+<power-of-2-allocation>` using the :dbcommand:`collMod` command with
+the :collflag:`noPadding` flag or the :method:`db.createCollection()`
+method with the ``noPadding`` option.
+
+Prior to version 3.0.0, MongoDB used an allocation strategy that
+included a dynamically calculated :data:`padding
 <collStats.paddingFactor>` as a factor of the document size.
 
 Capped Collections

source/includes/apiargs-method-db.createCollection-options-param.yaml

@@ -82,10 +82,17 @@ description: |2
      flag set to true, the allocation strategy does not include
      additional space to accomodate document growth, as such, document
      growth will result in new allocation. Use for collections with
-     workloads that are insert-only or insert-and-remove-only.
+     workloads that are insert-only or in-place updates (such as
+     incrementing counters).
 
      Defaults to ``false``.
 
+  .. warning:: 
+
+     Do not set ``noPadding`` if the workload includes any removes or
+     updates that may cause documents to grow. For more information,
+     see :ref:`exact-fit-allocation`.
+   
 interface: method
 name: noPadding
 operation: db.createCollection

source/reference/command/collMod.txt

@@ -84,10 +84,12 @@ Disable All Record Padding
    document size, and any updates that results in document growth will
    require a new allocation.
 
-   *Only* set :collflag:`noPadding` to ``true`` for collections whose
-   workloads have *no* update operations that cause documents to grow,
-   such as for collections with workloads that are insert-only. For
-   more information, see :ref:`exact-fit-allocation`.
+   .. warning::
+
+      Only set :collflag:`noPadding` to ``true`` for collections whose
+      workloads have *no* update operations that cause documents to grow,
+      such as for collections with workloads that are insert-only. For
+      more information, see :ref:`exact-fit-allocation`.
 
 Powers of Two Record Allocation
 ```````````````````````````````

source/release-notes/3.0-compatibility.txt

@@ -114,6 +114,15 @@ parameter such that you can no longer use the parameter to disable the
 power of 2 sizes allocation for a collection. Instead, use the
 :dbcommand:`collMod` command with the :collflag:`noPadding` flag or the
 :method:`db.createCollection()` method with the ``noPadding`` option.
+Only set ``noPadding`` for collections with workloads that consist only
+of inserts or in-place updates (such as incrementing counters).
+
+.. warning::
+
+   Only set :collflag:`noPadding` to ``true`` for collections whose
+   workloads have *no* update operations that cause documents to grow,
+   such as for collections with workloads that are insert-only. For
+   more information, see :ref:`exact-fit-allocation`.
 
 For more information, see :ref:`3.0-mmapv1-padding`.
 

source/release-notes/3.0-downgrade.txt

@@ -38,6 +38,14 @@ Follow the downgrade procedures:
 
 - To downgrade a standalone MongoDB instance, see :ref:`3.0-downgrade-standalone`.
 
+.. note::
+
+   *Optional*. Consider :dbcommand:`compacting <compact>` collections
+   after downgrading. Otherwise, older versions will not be able to
+   reuse free space regions larger than 2MB created while running 3.0.
+   This can result in wasted space but no data loss following the
+   downgrade.
+
 Downgrade MongoDB Processes
 ---------------------------
 

source/release-notes/3.0.txt

@@ -110,15 +110,26 @@ MMAPv1 have changed. See :ref:`3.0-compatibility-configuration-file`.
 MMAPv1 Record Allocation Behavior Changes
 `````````````````````````````````````````
 
-The default allocation strategy for collections in instances that use
-MMAPv1 is :ref:`power of 2 allocation <power-of-2-allocation>`. For
-collections with insert-only or insert-and-remove-only workloads, you
-can disable the power of 2 strategy.
-
-To disable the power of 2 strategy for a collection, use the
+MongoDB 3.0 no longer implements dynamic record allocation and
+deprecates :term:`paddingFactor <padding factor>`. The default
+allocation strategy for collections in instances that use MMAPv1 is
+:ref:`power of 2 allocation <power-of-2-allocation>`, which has been
+improved to better handle large document sizes. In 3.0, the
+``usePowerOf2Sizes`` flag is ignored, so the power of 2 strategy is
+used for all collections that do not have ``noPadding`` flag set.
+
+For collections with workloads that consist only of inserts or in-place
+updates (such as incrementing counters), you can disable the power of 2
+strategy. To disable the power of 2 strategy for a collection, use the
 :dbcommand:`collMod` command with the :collflag:`noPadding` flag or the
-:method:`db.createCollection()` method with the ``noPadding`` option.
+:method:`db.createCollection()` method with the ``noPadding`` option. 
+
+.. warning:: 
 
+   Do not set ``noPadding`` if the workload includes any removes or
+   updates that may cause documents to grow. For more information, see
+   :ref:`exact-fit-allocation`.
+   
 .. seealso:: :ref:`3.0-compatiblity-record-alloc`
 
 .. _3.0-replica-sets:
@@ -407,4 +418,4 @@ Additional Resources
 
 - `All Third Party License Notices <https://github.com/mongodb/mongo/blob/v3.0/distsrc/THIRD-PARTY-NOTICES>`_.
 
-- `All JIRA issues resolved in 3.0 <https://jira.mongodb.org/issues/?filter=17007>`_.
+- `All JIRA issues resolved in 3.0 <http://bit.ly/1CpOu6t>`_.