Program Listing for File DynamicPoolList.hpp

Return to documentation for file (umpire/strategy/DynamicPoolList.hpp)

//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2016-20, Lawrence Livermore National Security, LLC and Umpire
// project contributors. See the COPYRIGHT file for details.
//
// SPDX-License-Identifier: (MIT)
//////////////////////////////////////////////////////////////////////////////
#ifndef UMPIRE_DynamicPoolList_HPP
#define UMPIRE_DynamicPoolList_HPP

#include <memory>
#include <vector>
#include <functional>

#include "umpire/strategy/AllocationStrategy.hpp"
#include "umpire/strategy/DynamicPoolHeuristic.hpp"
#include "umpire/strategy/DynamicSizePool.hpp"

namespace umpire {

class Allocator;

namespace strategy {

/*!
 * \brief Simple dynamic pool for allocations
 *
 * This AllocationStrategy uses Simpool to provide pooling for allocations of
 * any size. The behavior of the pool can be controlled by two parameters: the
 * initial allocation size, and the minimum allocation size.
 *
 * The initial size controls how large the first piece of memory allocated is,
 * and the minimum size controls the lower bound on all future chunk
 * allocations.
 */
class DynamicPoolList :
  public AllocationStrategy
{
  public:
    /*!
     * \brief Callback Heuristic to trigger coalesce of free blocks in pool.
     *
     * The registered heuristic callback function will be called immediately
     * after a deallocation() has completed from the pool.
     */
    using CoalesceHeuristic = std::function<bool( const strategy::DynamicPoolList& )>;

    /*!
     * \brief Construct a new DynamicPoolList.
     *
     * \param name Name of this instance of the DynamicPoolList.
     * \param id Id of this instance of the DynamicPoolList.
     * \param min_initial_alloc_size The minimum size of the first allocation
     *                               the pool will make.
     * \param min_alloc_size The minimum size of all future allocations.
     * \param coalesce_heuristic Heuristic callback function.
     */
    DynamicPoolList(
        const std::string& name,
        int id,
        Allocator allocator,
        const std::size_t min_initial_alloc_size = (512 * 1024 * 1024),
        const std::size_t min_alloc_size = (1 * 1024 *1024),
        CoalesceHeuristic coalesce_heuristic = heuristic_percent_releasable_list(100)) noexcept;

    void* allocate(size_t bytes) override;

    void deallocate(void* ptr) override;

    void release() override;

    std::size_t getActualSize() const noexcept override;

    Platform getPlatform() noexcept override;

    /*!
     * \brief Get the number of bytes that may be released back to resource
     *
     * A memory pool has a set of blocks that have no allocations
     * against them.  If the size of the set is greater than one, then
     * the pool will have a number of bytes that may be released back to
     * the resource or coalesced into a larger block.
     *
     * \return The total number of bytes that are releasable
     */
    std::size_t getReleasableSize() const noexcept;

    /*!
     * \brief Get the number of memory blocks that the pool has
     *
     * \return The total number of blocks that are allocated by the pool
     */
    std::size_t getBlocksInPool() const noexcept;

    /*!
     * \brief Get the largest allocatable number of bytes from pool before
     * the pool will grow.
     *
     * return The largest number of bytes that may be allocated without
     * causing pool growth
     */
    std::size_t getLargestAvailableBlock() const noexcept;

    void coalesce() noexcept;

    MemoryResourceTraits getTraits() const noexcept final override;

  private:
    DynamicSizePool<>* dpa;

    strategy::AllocationStrategy* m_allocator;
    CoalesceHeuristic do_coalesce;
};

} // end of namespace strategy
} // end namespace umpire

#endif // UMPIRE_DynamicPoolList_HPP