CE_RampCache.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.
 *
 * NAME: CE_RampCache.h ( CE Library, C++)
 *
 * COMMENTS: Caches UT_Ramps on the GPU to avoid re-building.
 */

#ifndef __CE_RampCache__
#define __CE_RampCache__

#include "CE_API.h"

#include <UT/UT_Array.h>
#include <UT/UT_Lock.h>
#include <UT/UT_LRUCache.h>
#include <UT/UT_Map.h>
#include <UT/UT_MemoryResource.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_Ramp.h>
#include <UT/UT_NonCopyable.h>
#include <SYS/SYS_Types.h>

class CE_Context;


class CE_RampKey
{
public:
    CE_RampKey()
    {
    }
    CE_RampKey(UT_SharedPtr<UT_Ramp> ramp, int tuplesize, int rampsize)
    {
        myRamp = ramp;
        myTupleSize = tuplesize;
        myRampSize = rampsize;

        // Compute hash.
        myHash = myRamp.get() ? myRamp->hash() : 0;
        SYShashCombine(myHash, myTupleSize);
        SYShashCombine(myHash, myRampSize);
    }

    exint            numBytes() const
    {
        exint nbytes = sizeof(float);
        nbytes *= myTupleSize;
        nbytes *= myRampSize;
        return nbytes;
    }

    SYS_HashType     hash() const { return myHash; }
    bool                 operator==(const CE_RampKey &from) const
    {
        if (myHash != from.myHash) return false;
        if (myTupleSize != from.myTupleSize) return false;
        if (myRampSize != from.myRampSize) return false;
        if (from.myRamp.get() != myRamp.get())
        {
            if (!from.myRamp.get() || !myRamp.get())
                return false;

            if (*from.myRamp != *myRamp)
                return false;
        }
        return true;
    }

protected:
    SYS_HashType            myHash = 0;
    UT_SharedPtr<UT_Ramp>   myRamp;
    int                     myTupleSize = 0;
    int                     myRampSize = 0;
};

/// This must be defined before the map.
template <>
struct std::hash<CE_RampKey>
{
    std::size_t operator()(const CE_RampKey &key) const noexcept
    {
        return key.hash();
    }
};

/// This class implements a pool for UT_Ramps on the GPU.
class CE_API CE_RampCache
{
public:
    /// Initialize the pool with specified maximum size.
    CE_RampCache(exint size);
    ~CE_RampCache();

    /// Empty the memory pool of all held buffers.
    void        clear();

    /// Returns empty buffer if not in cache.
    /// This buffer remains owned by the cache; insofar as calling 
    /// CE_Context::releaseBuffer.
    cl::Buffer  lookupRamp(UT_SharedPtr<UT_Ramp> ramp, int tuplesize, int rampsize);

    /// Adds to the cache
    void        cacheRamp(cl::Buffer buffer, UT_SharedPtr<UT_Ramp> ramp, int tuplesize, int rampsize);

public:

    // This is the owner of the buffer, and it is responsilbe for
    // releasing the buffer to CE_Context, so must not be copyable
    // or we could get multiple releases.
    class RampEntry : public UT_NonCopyable
    {
    public:
        RampEntry() {}
        RampEntry(cl::Buffer buffer, exint numbytes)
        {
            myBuffer = buffer;
            myNumBytes = numbytes;
        }
        RampEntry(RampEntry &&b)
        {
            myNumBytes = b.myNumBytes;
            myBuffer = std::move(b.myBuffer);
            b.destroyBuffers();
        }

        RampEntry &operator=(RampEntry &&b)
        {
            destroyBuffers();
            myNumBytes = b.myNumBytes;
            myBuffer = std::move(b.myBuffer);
            b.destroyBuffers();
            return *this;
        }

        ~RampEntry();

        void            destroyBuffers();

        cl::Buffer      buffer() const { return myBuffer; }
        exint           numBytes() const { return myNumBytes; }

        static exint    computeNumBytes(const RampEntry &entry)
        { return entry.numBytes(); }


    protected:
        exint           myNumBytes = 0;
        cl::Buffer      myBuffer;
    };


public:

    /// Query the current usage; total is the total amount of memory held by the
    /// pool, not_in_use is the amount that can be freed immediately on demand.
    void        getUsage(exint& total, exint& not_in_use) const;

    /// Attempts to release the requested amount of memory back to the system.
    /// Returns the amount actually freed.
    exint       freeMemory(exint amount);

    /// 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_RampCache& cache) : myRampCache(cache) {}

        const char* name() const override
        {
            return "OpenCL Ramp Cache";
        }

        bool freeMemoryRequest(const UT_MemoryResource* resource,
                               RequestSeverity severity, Niceness niceness,
                               exint amount, exint& freed_amount) override
        {
            // Ramp caches are first against the wall.
            freed_amount = myRampCache.freeMemory(amount);
            return freed_amount > 0;
        }

        bool memoryUse(const UT_MemoryResource* resource, exint& in_use,
                       exint& cache) override
        {
            myRampCache.getUsage(in_use, cache);
            return true;
        }

    private:
        CE_RampCache           &myRampCache;
    };
    
protected:
    using RampLRU = UT_LRUCache<CE_RampKey, RampEntry, RampEntry::computeNumBytes>;
    RampLRU                     myRampCache;
    mutable UT_Lock             myRampCacheLock;

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

    friend size_t hash_value(const CE_RampKey &val);
};

CE_API CE_RampCache *CEgetRampCache();


#endif