bdlma_alignedallocator.h

Go to the documentation of this file.

/// @file bdlma_alignedallocator.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bdlma_alignedallocator.h                                           -*-C++-*-
#ifndef INCLUDED_BDLMA_ALIGNEDALLOCATOR
#define INCLUDED_BDLMA_ALIGNEDALLOCATOR
 
#include <bsls_ident.h>
BSLS_IDENT("$Id$")
 
/// @defgroup bdlma_alignedallocator bdlma_alignedallocator
/// @brief  Provide a protocol for memory allocators that support alignment.
/// @addtogroup bdl
/// @{
/// @addtogroup bdlma
/// @{
/// @addtogroup bdlma_alignedallocator
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bdlma_alignedallocator-purpose"> Purpose</a>
/// * <a href="#bdlma_alignedallocator-classes"> Classes </a>
/// * <a href="#bdlma_alignedallocator-description"> Description </a>
///   * <a href="#bdlma_alignedallocator-usage"> Usage </a>
///     * <a href="#bdlma_alignedallocator-example-1-implementing-bdlma-alignedallocator"> Example 1: Implementing bdlma::AlignedAllocator </a>
///     * <a href="#bdlma_alignedallocator-example-2-using-the-bdlma-alignedallocator-protocol"> Example 2: Using the bdlma::AlignedAllocator Protocol </a>
///
/// # Purpose {#bdlma_alignedallocator-purpose}
/// Provide a protocol for memory allocators that support alignment.
///
/// # Classes {#bdlma_alignedallocator-classes}
///
/// -  bdlma::AlignedAllocator: protocol for aligned memory allocators
///
/// @see  bslma_allocator
///
/// # Description {#bdlma_alignedallocator-description}
/// This component provides an implementation,
/// `bdlma::AlignedAllocator`, of the base-level protocol (pure abstract
/// interface) class, `bslma::Allocator`, providing the ability to allocate raw
/// memory with a specified alignment.  The following inheritance diagram shows
/// the classes involved and their methods:
/// @code
///  ,----------------------.
/// ( bdlma::AlignedAllocator )
///  `----------------------'
///              |       allocateAligned
///              V
///      ,----------------.
///     ( bslma::Allocator )
///      `----------------'
///                      allocate
///                      deallocate
/// @endcode
/// The `allocateAligned` method supplies the address of a contiguous block of
/// allocated memory of at least the indicated size, that is aligned to a given
/// boundary.  Note that this behavior is similar to the behavior of the POSIX
/// function @ref posix_memalign .
///
/// ## Usage {#bdlma_alignedallocator-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Implementing bdlma::AlignedAllocator {#bdlma_alignedallocator-example-1-implementing-bdlma-alignedallocator}
///
///
/// The `bdlma::AlignedAllocator` protocol provided in this component defines a
/// bilateral contract between suppliers and consumers of raw aligned memory.
/// In order for the `bdlma::AlignedAllocator` interface to be useful, we must
/// supply a concrete allocator that implements it.
///
/// In this example, we demonstrate how to adapt @ref posix_memalign  on Linux and
/// AIX, `memalign` on SunOS and `_aligned_malloc` on Windows, to this protocol
/// base class:
///
/// First, we specify the interface of the concrete implementation of
/// 'MyAlignedAllocator:
/// @code
/// // myposixmemalignallocator.h
/// // ...
///
/// class MyAlignedAllocator: public bdlma::AlignedAllocator {
///     // This class is a sample concrete implementation of the
///     // 'bdlma::AlignedAllocator' protocol that provides direct access to
///     // the system-supplied 'posix_memalign' and 'free' on Linux and AIX
///     // platforms, 'memalign' and 'free' on SunOS, or '_aligned_malloc' and
///     // '_aligned_free' on Windows.
///
///   private:
///     // NOT IMPLEMENTED
///     MyAlignedAllocator(const MyAlignedAllocator&);
///     MyAlignedAllocator& operator=(const MyAlignedAllocator&);
///
///   public:
///     // CREATORS
///     MyAlignedAllocator();
///         // Create a 'MyAlignedAllocator' object.  Note that all objects of
///         // this class share the same underlying resource.
///
///     virtual ~MyAlignedAllocator();
///         // Destroy this object.  Note that destroying this object has no
///         // effect on any outstanding allocated memory.
///
///     // MANIPULATORS
///     virtual void *allocate(bsls::Types::size_type size);
///         // Return a newly allocated block of memory of (at least) the
///         // specified positive 'size' (in bytes).  If 'size' is 0, a null
///         // pointer is returned with no other effect.  If this allocator
///         // cannot return the requested number of bytes, then it will throw
///         // an 'std::bad_alloc' exception in an exception-enabled build, or
///         // else it will abort the program in a non-exception build.  The
///         // behavior is undefined unless '0 <= size'.   Note that the
///         // alignment of the address returned conforms to the platform
///         // requirement for any object of the 'size'.  Also note that global
///         // 'operator new' is *not* called when 'size' is 0 (in order to
///         // avoid having to acquire a lock, and potential contention in
///         // multi-threaded programs).
///
///     virtual void *allocateAligned(bsls::Types::size_type size,
///                                   bsls::Types::size_type alignment);
///         // Return the address of a newly allocated block of memory of at
///         // least the specified positive 'size' (in bytes), sufficiently
///         // aligned such that the returned 'address' satisfies, for the
///         // specified 'alignment', '0 == (address & (alignment - 1))'.  If
///         // 'size' is 0, a null pointer is returned with no other effect.
///         // If the requested number of appropriately aligned bytes cannot be
///         // returned, then a 'bsl::bad_alloc' exception is thrown, or in a
///         // non-exception build the program is terminated.  The behavior is
///         // undefined unless 'alignment' is both a multiple of
///         // 'sizeof(void *)' and an integral non-negative power of two.
///
///     virtual void deallocate(void *address);
///         // Return the memory block at the specified 'address' back to this
///         // allocator.  If 'address' is 0, this function has no effect.  The
///         // behavior is undefined unless 'address' was allocated using this
///         // allocator object and has not already been deallocated.
/// };
/// // ...
/// @endcode
/// Then, we implement the creators, trivially, as this class contains no
/// instance data members.
/// @code
/// // CREATORS
/// MyAlignedAllocator::MyAlignedAllocator()
/// {
/// }
///
/// MyAlignedAllocator::~MyAlignedAllocator()
/// {
/// }
/// @endcode
/// Now, we define the virtual methods of `MyAlignedAllocator`.  Note that these
/// definitions are not `inline`, as they would not be inlined when invoked from
/// the base class (the typical usage in this case):
/// @code
/// // MANIPULATORS
/// void *MyAlignedAllocator::allocate(bsls::Types::size_type size)
/// {
///     if (0 == size) {
///         return 0;                                                 // RETURN
///     }
///
///     int alignment = bsls::AlignmentUtil::calculateAlignmentFromSize(size);
///     return allocateAligned(size, alignment);
/// }
///
/// void *MyAlignedAllocator::allocateAligned(bsls::Types::size_type size,
///                                           bsls::Types::size_type alignment)
/// {
///     BSLS_ASSERT_SAFE(0 == (alignment & (alignment - 1)));
///     BSLS_ASSERT_SAFE(0 == (alignment % sizeof(void *)));
///
///     if (0 == size) {
///         return 0;                                                 // RETURN
///     }
///
///     void *ret = 0;
///
/// #ifdef BSLS_PLATFORM_OS_WINDOWS
///     errno = 0;
///     ret = _aligned_malloc(size, alignment);
///     if (0 != errno) {
///         bsls::BslExceptionUtil::throwBadAlloc();
///     }
/// #elif defined(BSLS_PLATFORM_OS_SOLARIS)
///     ret = memalign(alignment, size);
///     if (0 == ret) {
///         bsls::BslExceptionUtil::throwBadAlloc();
///     }
/// #else
///     int rc = ::posix_memalign(&ret, alignment, size);
///     if (0 != rc) {
///         bsls::BslExceptionUtil::throwBadAlloc();
///     }
/// #endif
///
///     return ret;
/// }
///
/// void MyAlignedAllocator::deallocate(void *address)
/// {
///     if (0 == address) {
///         return;                                                   // RETURN
///     }
/// #ifdef BSLS_PLATFORM_WINDOWS
///     _aligned_free(address);
/// #else
///     ::free(address);
/// #endif
/// }
/// @endcode
/// Finally, we define a function `f` that instantiates an object of type
/// `MyAlignedAllocator`:
/// @code
/// void f() {
///     MyAlignedAllocator a;
/// }
/// @endcode
/// Note that the memory is not released when the allocator goes out of scope.
///
/// ### Example 2: Using the bdlma::AlignedAllocator Protocol {#bdlma_alignedallocator-example-2-using-the-bdlma-alignedallocator-protocol}
///
///
/// In this example we illustrate how to use the `bdlma::AlignedAllocator`
/// protocol to allocate memory that is aligned to the beginning of a memory
/// page.  Third party libraries, for example device drivers that perform DMA
/// access of device drivers, or some extreme optimizations to reduce the number
/// of page faults, might require page aligned allocations.
///
/// First, we create an aligned allocator `myAlignedAllocator` using the class
/// `MyAlignedAllocator` defined in the previous example, and obtain a
/// `bdlma::AlignedAllocator` pointer to it:
/// @code
/// MyAlignedAllocator myAlignedAllocator;
/// bdlma::AlignedAllocator *alignedAllocator = &myAlignedAllocator;
/// @endcode
/// Now, assuming a page size of 4K, we allocate a buffer of 1024 bytes of
/// memory and indicate that it should be aligned on a 4096 boundary:
/// @code
/// char *address = (char *) alignedAllocator->allocateAligned(1024, 4096);
/// @endcode
/// Finally, we verify that the obtained address actually is aligned as
/// expected:
/// @code
/// assert(0 == ((bsl::size_t)address & (4096 - 1)));
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bdl
 * @{
 */
/** @addtogroup bdlma
 * @{
 */
/** @addtogroup bdlma_alignedallocator
 * @{
 */
 
#include <bslscm_version.h>
 
#include <bslma_allocator.h>
 
#include <bsls_annotation.h>
#include <bsls_platform.h>
#include <bsls_types.h>
 
#include <bsl_cstddef.h>
 
 
namespace bdlma {
 
                          // ======================
                          // class AlignedAllocator
                          // ======================
 
/// This protocol provides a pure abstract interface and contract for
/// clients and suppliers of raw aligned memory.  If the requested memory
/// cannot be returned, the contract requires that an `std::bad_alloc`
/// exception be thrown.
///
/// See @ref bdlma_alignedallocator 
class AlignedAllocator : public bslma::Allocator {
 
  public:
    // MANIPULATORS
 
    /// Return the address of a newly allocated block of memory of at least
    /// the specified positive `size` (in bytes), sufficiently aligned such
    /// that the returned `address` satisfies, for the specified
    /// `alignment`, `0 == (address & (alignment - 1))`.  If `size` is 0, a
    /// null pointer is returned with no other effect.  If the requested
    /// number of appropriately aligned bytes cannot be returned, then a
    /// `bsl::bad_alloc` exception is thrown, or in a non-exception build
    /// the program is terminated.  The behavior is undefined unless
    /// `alignment` is both a multiple of `sizeof(void *)` and an integral
    /// non-negative power of two.
    virtual void *allocateAligned(bsls::Types::size_type size,
                                  bsls::Types::size_type alignment) = 0;
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2016 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */