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

#pragma once

#ifndef __GA_ATIDict__
#define __GA_ATIDict__

#include "GA_API.h"
#include "GA_AIFSharedDictTuple.h"      // For GA_DictIndexType type
#include "GA_ATIBlob.h"
#include "GA_Attribute.h"
#include "GA_AttributeType.h"
#include "GA_PageArray.h"
#include "GA_Types.h"

#include <UT/UT_ArrayMap.h>
#include <UT/UT_Options.h>
#include <UT/UT_StringHolder.h>

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


class GA_AIFJSON;
class GA_IndexMap;
class GA_Range;


class GA_API GA_ATIDict : public GA_ATIBlob
{
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_ATIDict *cast(GA_Attribute *attrib)
    {
        if (attrib && &attrib->getType() == theAttributeType)
            return static_cast<GA_ATIDict *>(attrib);
        return nullptr;
    }
    SYS_FORCE_INLINE
    static const GA_ATIDict *cast(const GA_Attribute *attrib)
    {
        if (attrib && &attrib->getType() == theAttributeType)
            return static_cast<const GA_ATIDict *>(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_ATIDict(const GA_AttributeType &type,
                        const GA_IndexMap &index_map,
                        GA_AttributeScope scope,
                        const UT_StringHolder &name,
                        int tuple_size);
    ~GA_ATIDict() override;

    // AIFCopyData is implemented in GA_ATIBlob.
    // AIFInterp is implemented in GA_ATIBlob.
    const GA_AIFSharedDictTuple     *getAIFSharedDictTuple() const override
                                        { return myAIFSharedDictTuple; }

    /// @section JSON-GA_ATIDict JSON Schema: GA_ATIDict
    /// @code
    /// {
    ///     "name"          : "GA_ATIDict",
    ///     "description"   : "An tuple array of indexed options",
    ///     "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" ],
    ///         },
    ///         "options": {
    ///             "type"  : { "$ref":"GA_BlobData", },
    ///             "description" : "Array of options 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 version to save writing marshalling code
    /// This lets you use this AIF in string-aware code and get sensible
    /// outputs.
    /// JSON normally has returns and tabs for formatting, compact will
    /// collapse these for a more compact output.
    UT_StringHolder      getString(GA_Offset offset, int component=0, bool compact=false) const;
    /// @}

    /// Get a string
    const UT_OptionsHolder &getDict(GA_Offset offset, int component=0) const;
    const UT_OptionsHolder &getHolder(GA_Offset offset, int component=0) const
    { return getDict(offset, component); }
    GA_DictIndexType     getDictIndex(GA_Offset offset, int component=0) const;
    GA_DictIndexType     getHolderIndex(GA_Offset offset, int component=0) const
    { return getDictIndex(offset, component); }
    /// @}
    /// @{
    /// Set a string
    void setDict(GA_Offset offset, const UT_OptionsHolder &opt, int component=0);
    void setHolder(GA_Offset offset, const UT_OptionsHolder &opt, int component=0)
    { return setDict(offset, opt, component); }
    void setDictIndex(GA_Offset offset, GA_DictIndexType i, int component=0)
    { tupleSet(offset, i, component); }
    void setHolderIndex(GA_Offset offset, GA_DictIndexType i, int component=0)
    { setDictIndex(offset, i, component); }
    /// @}

    UT_OptionsHolder     lookupDict(GA_DictIndexType handle) const;
    UT_OptionsHolder     lookupOrderedDict(exint handle) const;
    GA_DictIndexType     lookupHandle(const UT_OptionsRef &opt) const;
    GA_DictIndexType validateHandle(GA_DictIndexType h) const;
    bool                 replaceDict(GA_DictIndexType handle,
                                    const UT_OptionsHolder &opt);

    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:
    // Create a new ATIBlob
    GA_Attribute         *doClone(const GA_IndexMap &index_map,
                                  const UT_StringHolder &name) const override;

private:
    /// @{ GA_AIFDictTuple
    /// @warning If you call addDictReference(), at some point, you must call
    /// delHandleReference() on the string you added.
    GA_DictIndexType addDictReference(const UT_OptionsHolder &opt);
    void        delHandleReference(GA_DictIndexType handle);
    bool        tupleGet(GA_Offset di, GA_DictIndexType &v, int vi) const;
    bool        tupleSet(GA_Offset di, GA_DictIndexType v, int vi);
    /// @}

    static GA_AIFSharedDictTuple *myAIFSharedDictTuple;
    static GA_AIFJSON               *myAIFJSON;

    static const GA_AttributeType *theAttributeType;

    /// @cond INTERNAL_DOX
    friend class ga_DictCopyData;
    friend class ga_DictMerge;
    friend class ga_DictCompare;
    friend class ga_DictTuple;
    friend class ga_DictJSON;
    friend class GA_ATIDictDelayedWriter;
    /// @endcond
};

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

    void                bind(GA_ATIDict *attrib);

    // The holder version should be preferred as it can store the hash
    // and avoid hardening to the internal map.
    void                setDict(GA_Offset offset, const UT_OptionsHolder &opt, int tuple=0);
    void                setHolder(GA_Offset offset, const UT_OptionsHolder &opt, int tuple=0)
    { setDict(offset, opt, tuple); }
    void                setDict(const GA_Range &range, const UT_OptionsHolder &opt, int tuple=0);
    void                setHolder(const GA_Range &range, const UT_OptionsHolder &opt, int tuple=0)
    { setDict(range, opt, tuple); }
    // Directly set the index.
    void                setDictIndex(GA_Offset offset, GA_DictIndexType idx, int tuple=0);
    void                setHolderIndex(GA_Offset offset, GA_DictIndexType idx, int tuple=0)
    { setDictIndex(offset, idx, tuple); }
    void                setDictIndex(const GA_Range &range, GA_DictIndexType idx, int tuple=0);
    void                setHolderIndex(const GA_Range &range, GA_DictIndexType idx, int tuple=0)
    { setDictIndex(range, idx, tuple); }

    void                setPageDict(GA_PageNum pagenum, const UT_OptionsHolder &opt, int tuple=0);
    void                setPageDictIndex(GA_PageNum pagenum, GA_DictIndexType opt, int tuple=0);

    void                flush();

    SYS_FORCE_INLINE bool hasChanges() const
    {
        return myHasChanges;
    }

    // Returns the index to be used for the dictionary, adding it to the
    // dictionary table if necessary.
    GA_DictIndexType addDictReference(const UT_OptionsHolder &opt);

private:
    GA_ATIDict *myAttribute;
    volatile bool myHasChanges;

    UT_ArrayMap<GA_DictIndexType, exint> myRefCountChanges;
    UT_ArrayMap<UT_OptionsHolder, GA_DictIndexType> myDictToIndex;
};

inline GA_DictIndexType
GA_ATIDictDelayedWriter::addDictReference(const UT_OptionsHolder &opt)
{
    GA_DictIndexType index = GA_INVALID_DICT_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 (!opt.isEmpty())
    {
        index = myAttribute->addDictReference(opt);

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

    return index;
}

#endif