CE_HotSwapPool.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 */

#pragma once

#include "CE_API.h"

#include "CE_HotSwapPoolEntry.h"

#include <list>

#include <UT/UT_Cache.h>
#include <UT/UT_Map.h>
#include <UT/UT_MemoryResource.h>

/// This is a memory manager that is responsible for allocating GPU storage for
/// CE buffers. It has a watermark for the maximum amount of live GPU usage
/// that it tries to stay under.
/// There should only ever be one memory pool active. It can be accessed using
/// the static getMemoryPool() method (or CEgetHotSwapPool() free-standing
/// function).
class CE_API CE_HotSwapPool : public UT_Cache
{
public:
    /// This static member returns the global memory pool.
    static CE_HotSwapPool &getMemoryPool();

    /// Registeres GPU storage of given buffer for its size.
    /// This will make it eligible for invoking unloadToGPU to reduce
    /// GPU memory usage.
    void registerCEBuffer(CE_HotSwapPoolEntry *buffer, exint nbytes);

    /// Ensures there is enough room to fit the desired number of bytes.
    /// Returns true if the memory pool will have that much room free.
    /// NOTE: You probably want to allocate anyways if false, this is more
    /// a warning.
    bool reserveSpace(exint nbytes);
    
    /// Releases the GPU memory held by buffer. The myGPUBuffer member of buffer
    /// will be automatically updated.
    void releaseCEBuffer(CE_HotSwapPoolEntry *buffer);

    /// Indicates that dst is to share the GPU buffer of src.
    void shareCEBuffer(CE_HotSwapPoolEntry *dst, const CE_HotSwapPoolEntry *src);

    /// Indicates that GPU buffers should be swapped between the two inputs.
    void swapCEBuffer(CE_HotSwapPoolEntry *buffer1, CE_HotSwapPoolEntry *buffer2);

    /// Mark the given buffer as currently in use. This will prevent it from
    /// getting unloaded to make room.
    /// This method should not be called directly (i.e. use setInUseGPUFlag()
    /// and clearInUseGPUFlag() on CE_HotSwapPoolEntry; or better yet, use
    /// CE_ScopedPoolEntryInUseGPU).
    void setInUse(const CE_HotSwapPoolEntry *buffer);
    /// This function should be called after setInUse(), once the GPU buffer has
    /// been used (to enqueue a kernel with it, for example). If nobody has
    /// marked a buffer in use, it will be a candidate for unloading when the
    /// pool needs to make space.
    /// This function also bumps recency of the buffer's use, making it less
    /// likely to get unloaded due the pool's LRU pollicy.
    /// This method should not be called directly (i.e. use setInUseGPUFlag()
    /// and clearInUseGPUFlag() on CE_HotSwapPoolEntry; or better yet, use
    /// CE_ScopedPoolEntryInUseGPU).
    void clearInUse(const CE_HotSwapPoolEntry *buffer);


    exint       numReductionRequests() const { return myStatsNumReductions; }
    exint       bytesFlushed() const { return myStatsFlushedBytes; }
    void        clearStats() { myStatsNumReductions = 0; myStatsFlushedBytes = 0; }

public:
    /// Returns name of this cache.
    const char *utGetCacheName() const override;

    /// Returns the amount of GPU memory currently in use by CE buffers.
    int64 utGetCurrentSize() const override
    {
        return myCurrentUsage;
    }

    /// Attempts to free the specified amount of GPU memory by unloading image
    /// data to main memory. Returns the actual amount of memory freed.
    int64 utReduceCacheSizeBy(int64 amount) override;

    /// Required override to indicate that this cache has a maximum size.
    bool utHasMaxSize() const override
    {
        return true;
    }

    /// Returns the maximum amount of GPU memory CE buffers are allowed to use.
    int64 utGetMaxSize() const override
    {
        return myMaximumUsage;
    }

    /// Change the maximum amount of GPU memory CE buffers are allowed to use.
    void utSetMaxSize(int64 size) override;

    /// Set maximum memory as a ratio of total GPU memory.
    static void setMemoryUsageRatio(fpreal ratio);

    ~CE_HotSwapPool() override;

    // PassKey idion to allow private construction via UTmakeUnique
private:
    struct PassKey {};
public:
    CE_HotSwapPool(PassKey);

private:
    /// Dumps out the current state of the pool.
    void printDebug(const UT_StringHolder& title);

    void internalSetMemoryUsageRatio(fpreal ratio);

private:
    /// This memory client is used to ensure that this memory pool plays nicely
    /// with other users of memory on the OpenCL device.
    class MemoryClient : public UT_MemoryClient
    {
    public:
        MemoryClient(CE_HotSwapPool &pool) : myMemoryPool(pool) {}

        const char *name() const override
        {
            return myMemoryPool.utGetCacheName();
        }

        bool freeMemoryRequest(const UT_MemoryResource *resource,
                               RequestSeverity severity, Niceness niceness,
                               exint amount, exint &freed_amount) override
        {
            freed_amount = myMemoryPool.utReduceCacheSizeBy(amount);
            return freed_amount > 0;
        }

        bool memoryUse(const UT_MemoryResource *resource, exint &in_use,
                       exint &cache) override
        {
            in_use = myMemoryPool.utGetCurrentSize();
            cache = 0;
            return true;
        }

    private:
        CE_HotSwapPool  &myMemoryPool;
    };

private:
    class ImageUsersRecord;

    /// Map of all known live buffers to their record with GPU data.
    UT_Map<CE_HotSwapPoolEntry *, ImageUsersRecord*>
                                    myLiveBuffers;
    /// List of most recently used records. Front of the list is the least
    /// recently used entry.
    std::list<ImageUsersRecord*>    myLRUList;
    /// Total amount of GPU memory usage by CE buffers.
    exint                           myCurrentUsage = 0;
    /// Maximum amount of GPU memory usage by CE buffers.
    exint                           myMaximumUsage = 0;
    /// Number of reduction attempts since last reset.
    exint                           myStatsNumReductions = 0;
    /// Number of bytes unloaded since last reset.
    exint                           myStatsFlushedBytes = 0;
    /// Lock to enforce exclusive access to the memory pool.
    UT_Lock                         myMutex;

    /// The memory client that's registered with with the OpenCL device.
    MemoryClient                    myMemoryClient;
};

/// Returns the global memory pool for CE GPU storage.
CE_API CE_HotSwapPool &CEgetHotSwapPool();