UT_MemoryResource.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:        UT_MemoryResource.h (UT Library, C++)
 *
 * COMMENTS:
 */
#ifndef UT_MemoryResource_h
#define UT_MemoryResource_h

#include <SYS/SYS_Types.h>

#include "UT_API.h"
#include "UT_Array.h"
#include "UT_Lock.h"
#include "UT_NonCopyable.h"
#include "UT_StringHolder.h"
#include "UT_StringMap.h"
#include "UT_UniquePtr.h"

class UT_MemoryResource;

/// Wrapper for a client of a limit memory resource.
class UT_API UT_MemoryClient
{
public:
    UT_MemoryClient() {} 
    virtual ~UT_MemoryClient() {}
    
    UT_NON_COPYABLE(UT_MemoryClient)

    /// Printable English name of the client
    virtual const char *name() const = 0;

    /// The urgency of the memory free request.
    enum RequestSeverity
    {
        NORMAL_REQUEST, // Almost always use this severity. 
        FATAL_REQUEST   // Memory must be freed or Houdini will become unusable.
    };
    
    /// How willingly a client can free memory for other clients.
    enum Niceness
    {
        SCRATCH_FREE,      // Free reusable scratch memory (kept for performance)
        READILY_FREE,      // Memory that can be freed without much impact
        NORMAL_FREE,       // Memory that is important but can still be freed.
        RELUCTANT_FREE,    // Memory that should only be freed if really needed
        CANNOT_FREE,       // Client is only reporting mem and cannot free any.

        MAX_NICENESS,
    };
    
    /// A 'resource' is requesting 'size_in_bytes' amount of memory be
    /// freed. If memory is freed, return true and the amount of memory freed in
    /// 'freed_amount_in_bytes'
    /// 'severity' - severity passed to UT_MemoryResource::requestMemoryFree()
    /// 'nice_level' - the current niceness level being asked to free. This will
    ///                always match once of the niceness levels the client was
    ///                registered with.
    virtual bool freeMemoryRequest(const UT_MemoryResource *resource,
                                   RequestSeverity severity,
                                   Niceness nice_level,
                                   exint size_in_bytes,
                                   exint &freed_amount_in_bytes) = 0;

    /// Report the amount of memory this client is using from 'resource'
    /// 'in_use' refers to memory that is currently being used, where as
    /// 'cached' refers to memory that'd being held either for reuse or scratch
    /// buffers.
    /// Return true if the size can be meaningully reported.
    virtual bool memoryUse(const UT_MemoryResource *resource,
                           exint &in_use_size_bytes,
                           exint &cached_size_bytes)
    {
        in_use_size_bytes = 0;
        cached_size_bytes = 0;
        return false;
    }
};

/// A named resource that represents a limited memory pool shared by several
/// clients.
class UT_API UT_MemoryResource : public UT_NonCopyable
{
public:
    /// Register a unqiue memory device, with a name and unique identifier.
    /// Returns a unique name based on the given name. If another device was
    /// already registered with the uuid, will return the same name used for it
    static const UT_StringHolder &registerDeviceName(
            const UT_StringHolder &name,
            const uint8 (&uuid)[16]);

    /// Query if a named memory resource exists, optionally returning it.
    static bool               hasMemoryResource(const UT_StringHolder &name,
                                                UT_MemoryResource **mem=nullptr);
    
    /// Find a memory resource and create if it does not exist.
    static UT_MemoryResource *getMemoryResource(const UT_StringHolder &name);

    /// List of memory resources
    static const UT_StringMap<UT_UniquePtr<UT_MemoryResource>> &memoryResources();

    /// Register as a client of the memory resource.
    bool  registerClient(UT_MemoryClient *client,
                         UT_MemoryClient::Niceness niceness);
    
    /// Register as a client of the memory resource but with several levels of
    /// 'niceness'. In this case, the client may have some higher priority data
    /// which it would rather hold onto, and some lower priority data which can
    /// be readily freed. This allows other clients to fulfill the free request
    /// at a lower priority level first, so that freeing the higher priority
    /// data may be avoided or reduced.
    bool  registerClient(UT_MemoryClient *client,
                         const UT_Array<UT_MemoryClient::Niceness> &niceness);
    
    /// Remove 'client' from this memory resource.
    bool  unregisterClient(UT_MemoryClient *client);

    /// Request that other clients of the memory resource free up memory.
    /// The 'from_client' parm is used to avoid the resource calling that client
    /// to free memory. The 'severity' is a hint to other clients. FATAL should
    /// be used only in cases where not respecting the request will result in
    /// app termination, so very sparingly.
    exint requestMemoryFree(exint size_in_bytes,
                            const UT_MemoryClient *from_client,
                            UT_MemoryClient::RequestSeverity severity
                                 = UT_MemoryClient::NORMAL_REQUEST);

    /// Notify other clients that 'returning_client' is freeing up
    /// 'size_in_bytes' of the resource. This doesn't have to be called
    /// constantly, but after large deallocations, it may be helpful to notify
    /// the other clients.
    void  returnMemory(const UT_MemoryClient *returning_client,
                       exint size_in_bytes);

    /// Total amount of memory in the resource (bytes). 
    exint totalMemory() const;

    /// The amount of memory currently used by clients (bytes). This calls into
    /// all clients and asks them for their memory use, so use sparingly.
    exint usedMemory();

    /// Query the device directly for free memory. Due to other applications,
    /// this will likely be less than 'totalMemory()-usedMemory()'
    // TODO.
    ///exint freeDeviceMemory();

    const UT_StringMap<std::pair<UT_MemoryClient *,int> > clients() const
        { return myClients; }

    /// Set the total amount of memory the resource has. 
    void setTotalMemory(exint mem_in_bytes) { myTotalMemory = mem_in_bytes; }

private:
    struct PassKey {}; // passkey idiom to make ctor "private"
public:
    UT_MemoryResource(const UT_StringHolder &name, PassKey);
    
private:
    UT_StringMap<std::pair<UT_MemoryClient *, int> > myClients;
    UT_Array<UT_MemoryClient *> myClientBuckets[UT_MemoryClient::MAX_NICENESS];
    int             myLastClientIndex[UT_MemoryClient::MAX_NICENESS];
    UT_Lock         myLock;
    UT_StringHolder myName;
    exint           myTotalMemory = -1; // unspecified
    bool            myAmFreeing = false;
};

#endif