// bslma_mallocfreeallocator.h -*-C++-*-
#ifndef INCLUDED_BSLMA_MALLOCFREEALLOCATOR
#define INCLUDED_BSLMA_MALLOCFREEALLOCATOR
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
//@PURPOSE: Provide malloc/free adaptor to 'bslma::Allocator' protocol.
//
//@CLASSES:
// bslma::MallocFreeAllocator: support malloc/free style allocate/deallocate
//
//@SEE_ALSO: bslma_newdeleteallocator, bslma_allocator
//
//@DESCRIPTION: This component provides an allocator,
// 'bslma::MallocFreeAllocator', that implements the 'bslma::Allocator'
// protocol and supplies memory using the system-supplied (native)
// 'std::malloc' and 'std::free' operators.
//..
// ,--------------------------.
// ( bslma::MallocFreeAllocator )
// `--------------------------'
// | ctor/dtor
// | singleton
// V
// ,----------------.
// ( bslma::Allocator )
// `----------------'
// allocate
// deallocate
//..
// The key purpose of this component is to facilitate the use of 'malloc' and
// 'free' when the default 'bslma::NewDeleteAllocator' is not desirable (such
// as the case of 'bslma::TestAllocator'). To accomplish this goal, 'malloc'
// and 'free' are wrapped in a singleton object whose lifetime is guaranteed to
// exceed any possibility of its use.
//
///Thread Safety
///-------------
// A single object of 'bslma::MallocFreeAllocator' is safe for concurrent
// access by multiple threads. The underlying implementation of 'malloc' and
// 'free' will ensure that heap corruption does not occur. Note that this
// allocator therefore has a stronger thread safety guarantee than is required
// by the base-class contract or than is provided by other allocators.
//
///Usage
///-----
// This component is intended to be used when the use of 'new' and 'delete' are
// not desirable, such as the case of 'bslma::TestAllocator'. Instead of using
// 'bslma::Default' which uses the 'bslma::NewDeleteAllocator', this component
// can be used to bypass the use of 'new' and 'delete'.
//
// The following example demonstrates the use of this component for a user
// defined allocator instead of using the default allocator:
//..
// // my_allocator.h
// // ...
//
// class my_Allocator : public bslma::Allocator {
// // This class provides a mechanism for allocation and deallocation.
//
// // DATA
// bslma::Allocator *d_allocator_p; // allocator (held, not owned)
//
// public:
// // CREATORS
// my_Allocator(bslma::Allocator *basicAllocator = 0);
// // Create a 'my_Allcoator'. Optionally specify 'basicAllocator' to
// // supply memory. If 'basicAllocator' is 0, the
// // 'bslma::MallocFreeAllocator' will be used.
//
// ~my_Allocator();
// // Destroy this allocator. Note that the behavior of destroying an
// // allocator while memory is allocated from it is not specified.
// // (Unless you *know* that it is valid to do so, don't!)
//
// // MANIPULATORS
// void *allocate(size_type size);
// // Return a newly allocated block of memory of (at least) the
// // specified positive 'size' (bytes). If 'size' is 0, a null
// // pointer is returned with no effect. Note that the alignment of
// // the address returned is the maximum alignment for any
// // fundamental type defined for this platform.
//
// void deallocate(void *address);
// // Return the memory at the specified 'address' back to this
// // allocator. If 'address' is 0, this function has no effect. The
// // behavior is undefined if 'address' was not allocated using this
// // allocator, or has already been deallocated.
// };
//..
// The constructor is implemented using 'bslma::MallocFreeAllocator'.
//..
// // my_allocator.cpp
// // ...
//
// // CREATORS
// my_Allocator::my_Allocator(bslma::Allocator *basicAllocator)
// : d_allocator_p(basicAllocator
// ? basicAllocator
// : &bslma::MallocFreeAllocator::singleton())
// {
// }
//
// // ...
//..
// When the 'basicAllocator' is not specified, the 'bslma::MallocFreeAllocator'
// will be used. That allocator then then calls 'std::malloc' and 'std::free'
// for allocating and deallocating memory.
#include <bslscm_version.h>
#include <bslma_allocator.h>
#include <cstdlib> // 'std::malloc', 'std::free'
namespace BloombergLP {
namespace bslma {
// =========================
// class MallocFreeAllocator
// =========================
class MallocFreeAllocator : public Allocator {
// This class provides direct access to the system-supplied (native) global
// 'std::malloc' and 'std::free'. A 'static' method is provided for
// obtaining a unique, process wide object of this class, which is valid
// from the time the method is called until after the program (not just
// 'main') exits.
private:
// NOT IMPLEMENTED
MallocFreeAllocator(const MallocFreeAllocator&);
MallocFreeAllocator& operator=(const MallocFreeAllocator&);
public:
// CLASS METHODS
static MallocFreeAllocator& singleton();
// Return a reference to a valid object of this class. Note that this
// object is guaranteed to be valid from the time of this call onward
// (i.e., not just until exiting 'main').
// CREATORS
MallocFreeAllocator();
// Create an allocator that uses 'std::malloc' and 'std::free' to
// supply memory. Note that all objects of this class share the same
// underlying resource.
virtual ~MallocFreeAllocator();
// Destroy this allocator. Note that the behavior of destroying an
// allocator while memory is allocated from it is not specified.
// (Unless you *know* that it is valid to do so, don't!)
//
// For this concrete implementation, destroying this allocator object
// has no effect on allocated memory.
// MANIPULATORS
virtual void *allocate(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 return a null pointer. The
// behavior is undefined unless '0 <= size'. Note that the alignment
// of the address returned is the maximum alignment for any type
// defined on this platform. Also note that 'std::malloc' is *not*
// called when 'size' is 0 (in order to avoid having to acquire a lock,
// and potential contention in multi-treaded programs).
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. Note that
// 'std::free' is *not* called when 'address' is 0 (in order to avoid
// having to acquire a lock, and potential contention in multi-treaded
// programs).
};
// ============================================================================
// INLINE DEFINITIONS
// ============================================================================
// -------------------------
// class MallocFreeAllocator
// -------------------------
// CREATORS
inline
MallocFreeAllocator::MallocFreeAllocator()
{
}
inline
MallocFreeAllocator::~MallocFreeAllocator()
{
}
// MANIPULATORS
inline
void MallocFreeAllocator::deallocate(void *address)
{
// While the C and C++ standard guarantees that calling free(0) is safe
// (3.7.3.2 paragraph 3), some libc implementations take out a lock to deal
// with the free(0) case, so this check can improve efficiency of threaded
// programs.
if (address) {
std::free(address);
}
}
} // close package namespace
#ifndef BDE_OPENSOURCE_PUBLICATION // BACKWARD_COMPATIBILITY
// ============================================================================
// BACKWARD COMPATIBILITY
// ============================================================================
typedef bslma::MallocFreeAllocator bslma_MallocFreeAllocator;
// This alias is defined for backward compatibility.
#endif // BDE_OPENSOURCE_PUBLICATION -- BACKWARD_COMPATIBILITY
} // close enterprise namespace
#endif
// ----------------------------------------------------------------------------
// Copyright 2013 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 ----------------------------------