GA_ATIString.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:        GA_ATIString.h ( GA Library, C++)
 *
 * COMMENTS:    String ATI (Attribute Type Implementation)
 */

#pragma once

#ifndef __GA_ATIString__
#define __GA_ATIString__

#include "GA_API.h"
#include "GA_AIFSharedStringTuple.h"    // For GA_StringIndexType type
#include "GA_ATIBlob.h"
#include "GA_Attribute.h"
#include "GA_AttributeType.h"
#include "GA_Types.h"

#include <UT/UT_IndexedHashSet.h>
#include <UT/UT_ArrayMap.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_VectorTypes.h>

#include <SYS/SYS_Inline.h>
#include <SYS/SYS_Types.h>

#include <iosfwd>

class GA_AIFJSON;
class GA_AIFStringTuple;
class GA_IndexMap;
class GA_Range;

class UT_IStream;

class GA_API GA_ATIString : public GA_Attribute
{
public:
    static void registerType();
    SYS_FORCE_INLINE
    static const UT_StringHolder &getTypeName()
    { return theAttributeType->getTypeName(); }
    SYS_FORCE_INLINE
    static const GA_AttributeType &getType() { return *theAttributeType; }

    SYS_FORCE_INLINE
    static bool isType(const GA_Attribute *attrib)
    {
        return attrib && &attrib->getType() == theAttributeType;
    }
    SYS_FORCE_INLINE
    static GA_ATIString *cast(GA_Attribute *attrib)
    {
        if (attrib && &attrib->getType() == theAttributeType)
            return static_cast<GA_ATIString *>(attrib);
        return nullptr;
    }
    SYS_FORCE_INLINE
    static const GA_ATIString *cast(const GA_Attribute *attrib)
    {
        if (attrib && &attrib->getType() == theAttributeType)
            return static_cast<const GA_ATIString *>(attrib);
        return nullptr;
    }

    static GA_Attribute *create(const GA_IndexMap &index_map,
                                GA_AttributeScope scope,
                                const UT_StringHolder &name,
                                int tuple_size,
                                const GA_AttributeOptions *attribute_options=nullptr);
    static GA_Attribute *create(const GA_IndexMap &index_map,
                                const UT_StringHolder &name,
                                int tuple_size)
                { return create(index_map, GA_SCOPE_PUBLIC, name, tuple_size); }

    GA_ATIString(const GA_AttributeType &type,
                        const GA_IndexMap &index_map,
                        GA_AttributeScope scope,
                        const UT_StringHolder &name,
                        int tuple_size);
    ~GA_ATIString() override;

    /// Report approximate memory usage
    int64 getMemoryUsage(bool inclusive) const override;

    void countMemory(UT_MemoryCounter &counter, bool inclusive) const override;

    /// Interface for defragmentation
    void defragment(const GA_Defragment &defrag) override;

    void reconstructElementBlock(GA_Offset offset,
                                 GA_Offset nelements) override;

    /// Get the tuple size
    SYS_FORCE_INLINE
    int getTupleSize() const
    { return myHandles.getTupleSize(); }

    /// Return the entries in the string container
    exint entries() const
    { return myStrings.entries(); }

    /// Return the maximum index of any string in the container.  This may be
    /// more than the number of strings in the container.  If the maximum index
    /// is less than 0, there are no strings in the container.
    GA_BlobIndex getMaximumIndex() const
    { return myStrings.getItemIdUpperBound(); }

    /// Return the capacity of the string container
    exint capacity() const
    { return myStrings.getItemIdUpperBound()+1; }

    virtual bool        loadStringsH9(UT_IStream &is, UT_IntArray &handlemap);
    virtual void        loadStringsFinishH9(const UT_IntArray &handlemap);

    virtual bool        saveStringsH9(std::ostream &os, int binary,
                                        UT_IntArray &handlemap) const;

    /// Grow or shrink the tuple size
    bool setTupleSize(int tuplesize);

    /// This method will "compact" the attribute container, possibly changing
    /// all the handles in the attribute data.
    void compactStorage() override;

    /// Get a measure of the vacancy entropy of the storage container.  This
    fpreal getStorageOccupancy()
    { return myStrings.getOccupancy(); }

    /// Adding strings is thread-safe, so we're only subject to GA_PageArray
    /// limitations.
    WriteConcurrence getSupportedWriteConcurrence() const override
    { return WRITE_CONCURRENCE_PAGE; }

    const GA_AIFMerge               *getAIFMerge() const override
                                        { return myAIFMerge; }
    const GA_AIFCompare             *getAIFCompare() const override
                                        { return myAIFCompare;}
    const GA_AIFCopyData            *getAIFCopyData() const override
                                        { return myAIFCopyData; }
    const GA_AIFInterp              *getAIFInterp() const override
                                        { return myAIFInterp; }
    const GA_AIFSharedStringTuple   *getAIFSharedStringTuple() const override
                                        { return myAIFStringTuple; }
    const GA_AIFStringTuple         *getAIFStringTuple() const override
                                        { return myAIFStringTuple; }

    /// @section JSON-GA_ATIString JSON Schema: GA_ATIString
    /// @code
    /// {
    ///     "name"          : "GA_ATIString",
    ///     "description"   : "An tuple array of indexed strings",
    ///     "type"          : "orderedmap",
    ///     "properties": {
    ///         "size": {
    ///             "type"          : "integer",
    ///             "minimum"       : 1,
    ///             "description"   : "Tuple size",
    ///             "default"       : 1,
    ///             "optional"      : true,
    ///         },
    ///         "storage": {
    ///             "type"        : "string",
    ///             "description" : "Tuple storage",
    ///             "enum"        : [ "int8", "int16", "int32", "int64" ],
    ///         },
    ///         "strings": {
    ///             "type"  : { "$ref":"GA_BlobData", },
    ///             "description" : "Array of strings used in the attribute",
    ///         },
    ///         "indices": {
    ///             "type"  : {"$ref":"GA_DataArrayTuple"},
    ///             "description" : "Int index for each element of the array",
    ///         },
    ///     },
    /// }
    /// @endcode
    /// @see @ref JSON_FileFormat
    const GA_AIFJSON *getAIFJSON() const override    { return myAIFJSON; }

    /// Debug code
    bool debugValidateArrayCapacity(GA_Offset sz) const override;

    /// @{
    /// Get a string
    const UT_StringHolder &getString(GA_Offset offset, int component = 0) const
    {
        using namespace UT::Literal;

        const GA_StringIndexType handle = getStringIndex(offset, component);
        if (handle < 0)
            return UT_StringHolder::theEmptyString;
        const UT_StringHolder *ps = myStrings.get(handle);
        UT_ASSERT_P(ps);
        return *ps;
    }
    SYS_FORCE_INLINE
    const UT_StringHolder &getHolder(GA_Offset offset, int component = 0) const
    {
        return getString(offset, component);
    }
    SYS_FORCE_INLINE
    GA_StringIndexType getStringIndex(GA_Offset offset, int component = 0) const
    {
        return GA_StringIndexType(myHandles.get(offset, component));
    }
    SYS_FORCE_INLINE
    GA_StringIndexType getHolderIndex(GA_Offset offset, int component = 0) const
    {
        return getStringIndex(offset, component);
    }
    /// @}
    /// @{
    /// Set a string
    void setString(GA_Offset offset, const UT_StringHolder &str, int component=0);
    void setHolder(GA_Offset offset, const UT_StringHolder &str, int component=0)
    {
        setString(offset, str, component);
    }
    void setStringIndex(GA_Offset offset, GA_StringIndexType i, int component=0);
    void setHolderIndex(GA_Offset offset, GA_StringIndexType i, int component=0)
    {
        setStringIndex(offset, i, component);
    }
    void setStringIndex(const GA_Range &dst_range, GA_StringIndexType i, int component=0);
    void setHolderIndex(const GA_Range &dst_range, GA_StringIndexType i, int component=0)
    {
        setStringIndex(dst_range, i, component);
    }
    /// @}

    const char          *lookupString(GA_StringIndexType handle) const;
    const char          *lookupOrderedString(exint handle) const;
    GA_StringIndexType lookupHandle(const UT_StringHolder &s) const;
    GA_StringIndexType validateHandle(GA_StringIndexType h) const;
    bool replaceString(GA_StringIndexType handle,
        const UT_StringHolder &new_string);
    bool replaceStrings(const UT_Array<GA_StringIndexType> &handles,
        const UT_StringArray &new_strings);

    bool jsonSave(UT_JSONWriter &w, const GA_SaveMap &s,
            const char *token) const;
    bool jsonLoad(UT_JSONParser &p,
            const GA_LoadMap &load, const char *token);
    bool jsonLoadStrings(UT_JSONParser &p,
        const GA_LoadMap &lmap,
        UT_StringArray &strings);

    /// Convenience function to extract all the strings (and their handles)
    /// The string handles are guaranteed to be in ascending order, but
    /// may or may not be contiguous.
    /// @{
    exint extractStrings(UT_StringArray &strings,
        UT_IntArray &handles) const;
    exint extractStrings(UT_StringArray &strings,
        UT_IntArray &handles, exint maxstrings) const;
    /// @}

    bool setArraySize(GA_Offset new_size) override;
    void tryCompressAllPages(
        GA_Offset start_offset = GA_Offset(0),
        GA_Offset end_offset = GA_INVALID_OFFSET) override;
    void hardenAllPages(
        GA_Offset start_offset = GA_Offset(0),
        GA_Offset end_offset = GA_INVALID_OFFSET) override;

    /// Returns true iff that is an attribute whose content can be copied
    /// from this without any type conversions.  This is important to
    /// avoid reallocation of an attribute if its storage type,
    /// including tuple size, matches the source attribute exactly.
    bool matchesStorage(const GA_Attribute *that) const override
    {
        if (!GA_Attribute::matchesStorage(that))
            return false;
        const GA_ATIString *thatn = UTverify_cast<const GA_ATIString *>(that);
        if (getTupleSize() != thatn->getTupleSize())
            return false;
        return true;
    }

    /// This replaces the entirety of this attribute's content and non-
    /// storage metadata (except the name) with that of the src attribute.
    /// matchesStorage(src) should already return true.
    /// This is primarily for use by GA_AttributeSet::replace().
    /// NOTE: The internal content sizes may not match exactly if the
    ///       attribute type may overallocate, but the sizes should be such
    ///       that any real data will fit in the destination, so be careful
    ///       and deal with the myTailInitialize flag appropriately if
    ///       any extra elements aren't equal to the default.
    void replace(const GA_Attribute &src) override;

    /// Copy attribute values for a single element.
    /// @{
    bool copy(GA_Offset desti, GA_Offset srci) override final
    {
        copyData(desti, this, srci);
        return true;
    }
    bool copy(GA_Offset desti,
              const GA_Attribute &src, GA_Offset srci) override final
    {
        if (!GA_ATIString::isType(&src))
            return false;
        copyData(desti, UTverify_cast<const GA_ATIString *>(&src), srci);
        return true;
    }
    bool copy(GA_Offset desti, const GA_ATIString &src, GA_Offset srci)
    {
        copyData(desti, &src, srci);
        return true;
    }
    /// @}

    /// Copy attribute values for a range of elements.
    /// @{
    bool copy(const GA_Range &destrange,
              const GA_Range &srcrange) override final
    {
        return copyData(destrange, this, srcrange);
    }
    bool copy(const GA_Range &destrange,
              const GA_Attribute &src, const GA_Range &srcrange) override final
    {
        if (!GA_ATIString::isType(&src))
            return false;
        return copyData(destrange, UTverify_cast<const GA_ATIString*>(&src), srcrange);
    }
    bool copy(const GA_Range &destrange, const GA_ATIString &src, const GA_Range &srcrange)
    {
        return copyData(destrange, &src, srcrange);
    }
    /// @}

    /// Assign all elements of a range from a single attribute value.
    /// @{
    bool fill(const GA_Range &destrange, GA_Offset srci) override final
    {
        fillData(destrange, this, srci);
        return true;
    }
    bool fill(const GA_Range &destrange,
              const GA_Attribute &src, GA_Offset srci) override final
    {
        if (!GA_ATIString::isType(&src))
            return false;
        fillData(destrange, UTverify_cast<const GA_ATIString *>(&src), srci);
        return true;
    }
    bool fill(const GA_Range &destrange, const GA_ATIString &src, GA_Offset srci)
    {
        fillData(destrange, &src, srci);
        return true;
    }
    /// @}

    /// @{ GA_AIFMerge
    /// Base class implementation of GA_AIFMerge::destroyDestination()
    void mergeDestroyDestination(const GA_MergeMap &map,
        GA_Attribute *dattrib) const;
    /// Base class implementation of GA_AIFMerge::addDestination()
    GA_Attribute *mergeAddDestination(const GA_MergeMap &map,
        GA_Attribute *dattrib) const;
    /// Base class implementation of GA_AIFMerge::growArray()
    void mergeGrowArray(const GA_MergeMap &map, const GA_ATIString &s);

    /// Base class implementation of GA_AIFMerge::copyArray()
    bool mergeAppendData(const GA_MergeMap &map,
        const GA_Attribute *sattrib);
    /// @}

    /// @{
    /// Interface used by GA_AIFCompare.
    bool isEqual(GA_Offset offset,
        const GA_ATIString &b, GA_Offset b_offset) const;
    bool isEqual(const GA_Range & range,
        const GA_ATIString &b, const GA_Range &b_range) const;
    /// @}

    /// Validates the internal structure for debugging purposes.
    bool validate() const;

    typedef GA_PageArray<int32> HandleArrayType;

    /// NOTE: This only provides read access, since for writing,
    ///       myHandles and myStrings need to be kept in sync.
    const HandleArrayType &getHandleData() const
    { return myHandles; }

    /// Returns true iff the specified page is constant-compressed,
    /// where a single string index is stored to represent GA_PAGE_SIZE
    /// values in the page, (or possibly fewer if only one page).
    SYS_FORCE_INLINE bool isPageConstant(GA_PageNum pagenum) const
    {
        return myHandles.isPageConstant(pagenum);
    }

protected:
    /// String attributes need each element to properly destruct for accurate
    /// reference counting.
    bool needDestruction() const override;

    /// Callback method to destruct an offset.
    void destructElement(GA_Offset offset) override;

    // Create a new ATIBlob
    GA_Attribute *doClone(const GA_IndexMap &index_map,
                          const UT_StringHolder &name) const override;

    /// Array of handles.  The default value is -1.
    HandleArrayType myHandles;

    /// String references.
    UT_IndexedHashSet<UT_StringHolder> myStrings;

private:
    /// @{
    /// Methods to implement copying of data for AIFCopyData
    bool copyData(GA_Offset di,
        const GA_ATIString *s,
        GA_Offset si);
    bool copyData(const GA_Range &di,
        const GA_ATIString *s,
        const GA_Range &si);
    bool fillData(const GA_Range &di,
        const GA_ATIString *s,
        GA_Offset si);
    /// @}

    /// @{ GA_AIFStringTuple
    /// @warning If you call addStringReference(), at some point, you must call
    /// delHandleReference() on the string you added.
    GA_StringIndexType addStringReference(const UT_StringHolder &str);
    void        delHandleReference(GA_StringIndexType handle);
    bool        tupleGet(GA_Offset di, GA_StringIndexType &v, int vi) const;
    bool        tupleSet(GA_Offset di, GA_StringIndexType v, int vi);
    /// @}

    static GA_AIFMerge      *myAIFMerge;
    static GA_AIFCopyData   *myAIFCopyData;
    static GA_AIFCompare    *myAIFCompare;
    static GA_AIFInterp     *myAIFInterp;
    static GA_AIFSharedStringTuple  *myAIFStringTuple;
    static GA_AIFJSON               *myAIFJSON;

    static const GA_AttributeType *theAttributeType;

    /// @cond INTERNAL_DOX
    friend class ga_StringCopyData;
    friend class ga_StringMerge;
    friend class ga_StringCompare;
    friend class ga_StringTuple;
    friend class ga_StringJSON;
    friend class GA_ATIStringDelayedWriter;
    /// @endcond
};

//
// Designed to delay all the reference count adjustments
// until this object is flushed.  Also maintains a local
// table for looking up the string indices with, thus avoiding
// concurrency issues.
//
class GA_API GA_ATIStringDelayedWriter
{
public:
    GA_ATIStringDelayedWriter();
    GA_ATIStringDelayedWriter(GA_ATIString *attrib);
    ~GA_ATIStringDelayedWriter();

    void                bind(GA_ATIString *attrib);

    // The holder version should be preferred as it can store the hash
    // and avoid hardening to the internal map.
    void                setString(GA_Offset offset, const char *str, int tuple=0);
    void                setString(GA_Offset offset, const UT_StringHolder &str, int tuple=0);
    void                setHolder(GA_Offset offset, const UT_StringHolder &str, int tuple=0)
    { setString(offset, str, tuple); }
    void                setString(const GA_Range &range, const char *str, int tuple=0);
    void                setString(const GA_Range &range, const UT_StringHolder &str, int tuple=0);
    void                setHolder(const GA_Range &range, const UT_StringHolder &str, int tuple=0)
    { setString(range, str, tuple); }

    // Directly set the index.
    void                setStringIndex(GA_Offset offset, GA_StringIndexType idx, int tuple=0);
    void                setHolderIndex(GA_Offset offset, GA_StringIndexType idx, int tuple = 0)
    { setStringIndex(offset, idx, tuple); }
    void                setStringIndex(const GA_Range &range, GA_StringIndexType idx, int tuple=0);
    void                setHolderIndex(const GA_Range &range, GA_StringIndexType idx, int tuple=0)
    { setStringIndex(range, idx, tuple); }

    void                setPageString(GA_PageNum pagenum, const UT_StringHolder &str, int tuple=0);
    void                setPageStringIndex(GA_PageNum pagenum, GA_StringIndexType str, int tuple=0);

    void                flush();

    SYS_FORCE_INLINE bool hasChanges() const
    {
        return myHasChanges;
    }

    // Returns the index to be used for the string, adding it to the string
    // table if necessary.
    GA_StringIndexType  addStringReference(const UT_StringHolder &str);

private:
    GA_ATIString *myAttribute;
    volatile bool myHasChanges;

    UT::ArrayMap<GA_StringIndexType, exint> myRefCountChanges;
    UT_ArrayStringMap<GA_StringIndexType>   myStringToIndex;
};

inline GA_StringIndexType
GA_ATIStringDelayedWriter::addStringReference(const UT_StringHolder &str)
{
    GA_StringIndexType index = GA_INVALID_STRING_INDEX;

    // See if already present...
    // We can't just test if it is already present, we must
    // ensure we have a copy being held onto by our table or
    // we could have it eaten by another thread!
    if (str.isstring())
    {
        index = myAttribute->addStringReference(str);

        // Add a reference.  This means we will *not* count
        // as a reference count!
        myRefCountChanges[index] += -1;
    }

    return index;
}

#endif