org.apache.mina.core.buffer

## Class CachedBufferAllocator

- java.lang.Object
- - org.apache.mina.core.buffer.CachedBufferAllocator

- All Implemented Interfaces:
    IoBufferAllocator

      public class CachedBufferAllocator
      extends Object
      implements IoBufferAllocator

  An `IoBufferAllocator` that caches the buffers which are likely to be reused during auto-expansion of the buffers.

  In `SimpleBufferAllocator`, the underlying `ByteBuffer` of the `IoBuffer` is reallocated on its capacity change, which means the newly allocated bigger `ByteBuffer` replaces the old small `ByteBuffer`. Consequently, the old `ByteBuffer` is marked for garbage collection.

  It's not a problem in most cases as long as the capacity change doesn't happen frequently. However, once it happens too often, it burdens the VM and the cost of filling the newly allocated `ByteBuffer` with `NUL` surpass the cost of accessing the cache. In 2 dual-core Opteron Italy 270 processors, `CachedBufferAllocator` outperformed `SimpleBufferAllocator` in the following situation:

  - when a 32 bytes buffer is expanded 4 or more times,
  - when a 64 bytes buffer is expanded 4 or more times,
  - when a 128 bytes buffer is expanded 2 or more times,
  - and when a 256 bytes or bigger buffer is expanded 1 or more times.
  Please note the observation above is subject to change in a different environment.

  `CachedBufferAllocator` uses `ThreadLocal` to store the cached buffer, allocates buffers whose capacity is power of 2 only and provides performance advantage if `IoBuffer.free()` is called properly.

  Author:
    Apache MINA Project

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CachedBufferAllocator()` Creates a new instance with the default parameters (#DEFAULT_MAX_POOL_SIZE and #DEFAULT_MAX_CACHED_BUFFER_SIZE).
    `CachedBufferAllocator(int maxPoolSize, int maxCachedBufferSize)` Creates a new instance.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `IoBuffer` | `allocate(int requestedCapacity, boolean direct)` Returns the buffer which is capable of the specified size.
    `ByteBuffer` | `allocateNioBuffer(int capacity, boolean direct)` Returns the NIO buffer which is capable of the specified size.
    `void` | `dispose()` Dispose of this allocator.
    `int` | `getMaxCachedBufferSize()` Returns the maximum capacity of a cached buffer.
    `int` | `getMaxPoolSize()` Returns the maximum number of buffers with the same capacity per thread.
    `IoBuffer` | `wrap(ByteBuffer nioBuffer)` Wraps the specified NIO `ByteBuffer` into MINA buffer.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CachedBufferAllocator

          public CachedBufferAllocator()

      Creates a new instance with the default parameters (#DEFAULT_MAX_POOL_SIZE and #DEFAULT_MAX_CACHED_BUFFER_SIZE).

    - #### CachedBufferAllocator

          public CachedBufferAllocator(int maxPoolSize,
                               int maxCachedBufferSize)

      Creates a new instance.
      Parameters:
        `maxPoolSize` - the maximum number of buffers with the same capacity per thread. `0` disables this limitation.
        `maxCachedBufferSize` - the maximum capacity of a cached buffer. A buffer whose capacity is bigger than this value is not pooled. `0` disables this limitation.

  - ### Method Detail

    - #### getMaxPoolSize

          public int getMaxPoolSize()

      Returns the maximum number of buffers with the same capacity per thread. `0` means 'no limitation'.

    - #### getMaxCachedBufferSize

          public int getMaxCachedBufferSize()

      Returns the maximum capacity of a cached buffer. A buffer whose capacity is bigger than this value is not pooled. `0` means 'no limitation'.

    - #### allocate

          public IoBuffer allocate(int requestedCapacity,
                          boolean direct)

      Description copied from interface: `IoBufferAllocator`
      Returns the buffer which is capable of the specified size.
      Specified by:
        `allocate` in interface `IoBufferAllocator`
      Parameters:
        `requestedCapacity` - the capacity of the buffer
        `direct` - `true` to get a direct buffer, `false` to get a heap buffer.

    - #### allocateNioBuffer

          public ByteBuffer allocateNioBuffer(int capacity,
                                     boolean direct)

      Description copied from interface: `IoBufferAllocator`
      Returns the NIO buffer which is capable of the specified size.
      Specified by:
        `allocateNioBuffer` in interface `IoBufferAllocator`
      Parameters:
        `capacity` - the capacity of the buffer
        `direct` - `true` to get a direct buffer, `false` to get a heap buffer.

    - #### wrap

          public IoBuffer wrap(ByteBuffer nioBuffer)

      Description copied from interface: `IoBufferAllocator`
      Wraps the specified NIO `ByteBuffer` into MINA buffer.
      Specified by:
        `wrap` in interface `IoBufferAllocator`

    - #### dispose

          public void dispose()

      Description copied from interface: `IoBufferAllocator`
      Dispose of this allocator.
      Specified by:
        `dispose` in interface `IoBufferAllocator`

Copyright © 2004-2012 Apache MINA Project. All Rights Reserved.