PDG_AttributeMerge.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.
 *
 * COMMENTS:
 */

#ifndef __PDG_ATTRIBUTE_MERGE_H__
#define __PDG_ATTRIBUTE_MERGE_H__

#include "PDG_API.h"

#include "PDG_AttributeMap.h"
#include "PDG_AttributePattern.h"
#include "PDG_AttributeTypes.h"

#include <UT/UT_Array.h>
#include <UT/UT_ArrayStringSet.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_VectorTypes.h>

#include <utility>

class PDG_Node;

/**
 * Utility class for merging work item attributes. Stores a list of patterns
 * and operations that determine how attributes should be merged. The array
 * order determines the order the patterns are applied.
 */
class PDG_API PDG_AttributeMerge : UT_NonCopyable
{
public:
    /// Enumeration of types of data types to merge
    enum AttribType
    {
        /// Merge operation should include regular attributes, which are all
        /// attributes except for inputs and outputs.
        eAttribRegular  = 0x01,

        /// Merge operation should copy incoming output files to the dest
        /// map's input file attrib
        eAttribInput    = 0x02,

        /// Merge operation should copy incoming output files to the dest
        /// map's output file attrib
        eAttribOutput   = 0x04,

        /// Convenience value for merging all attribute types
        eAttribAll      = 0x07
    };

    /// Enumeration of different flatten operations, which determines if the
    /// dynamic and static attribute maps of the source should be combined.
    enum AttribFlatten
    {
        /// Never flatten the attribute maps
        eAttribFlattenNever,

        /// Always flatten the attribute maps
        eAttribFlattenAlways,

        /// Use the context runtime state to determine if the maps should be
        /// flattened
        eAttribFlattenContext
    };

    /// Merge pattern entry consisting of a pattern and merge operation, used
    /// for filtering attributes
    struct PDG_API MergeData
    {
        explicit MergeData(PDG_AttributeMergeOp merge_op)
            : myMergeOp(merge_op)
            , myPreserveArray(false)
        {
        }

        MergeData(const UT_StringHolder& pattern,
                  PDG_AttributeMergeOp merge_op,
                  bool preserve_array)
            : myPattern(pattern)
            , myMergeOp(merge_op)
            , myPreserveArray(preserve_array)
        {
        }

        PDG_AttributePattern        myPattern;
        PDG_AttributeMergeOp        myMergeOp;
        bool                        myPreserveArray;
    };

    /// A collection of merge patterns
    using Pattern = UT_Array<UT_UniquePtr<MergeData>>;
    
    /// The default, empty merge pattern
    static const Pattern            theEmptyPattern;

public:
    /// Constructs a new attribute merge operation from the specified
    /// merge types, operation and is_deep flag
                                    PDG_AttributeMerge(
                                        int attribute_types,
                                        const Pattern& pattern=theEmptyPattern,
                                        bool is_deep=false);

    /// Returns the attribute type filter
    inline int                      attribTypes() const
                                        { return myAttributeTypes; }

    /// Returns true if merging should always do a deep copy of attribs
    inline bool                     isDeep() const
                                        { return myIsDeep; }

    /// Returns true if the merge operation is between dependents within the
    /// same node
    bool                            isInternalDependent() const
                                        { return myIsInternalDependent; }
    
    /// Returns the attribute collision strategy
    PDG_AttributeCollision          attribCollision() const
                                        { return myCollisionStrategy; }

    /// Sets the attribute flatten mode
    void                            setAttribFlatten(AttribFlatten flatten)
                                        { myAttribFlatten = flatten; }

    /// Sets the default merge operation
    void                            setDefaultMerge(
                                            PDG_AttributeMergeOp merge_op)
                                        { myDefaultOp.myMergeOp = merge_op; }

    /// Adds a merge type for input files
    void                            setInputMerge(
                                            PDG_AttributeMergeOp merge_op)
                                        { myInputOp.myMergeOp = merge_op; }

    /// Adds  a merge type for output files
    void                            setOutputMerge(
                                            PDG_AttributeMergeOp merge_op)
                                        { myOutputOp.myMergeOp = merge_op; }

    /// Sets the is merge added flag
    void                            setIsMergeAdded(bool merge_added)
                                        { myIsMergeAdded = merge_added; }

    /// Sets the collision strategy, used when an existing attribute is found
    /// and a decision needs to be made about overwrting it.
    void                            setAttribCollision(
                                            PDG_AttributeCollision strategy)
                                        { myCollisionStrategy = strategy; }

    /// Adds an attibute name to the list of forced ignore attributes
    void                            addForceIgnore(const UT_StringHolder& name)
                                        { myForceIgnore.insert(name); }

    /// Sets a flag that indicates this merge is being applied to work items
    /// from the same node
    void                            setIsInternalDependent(bool dependent)
                                        { myIsInternalDependent = dependent; }

    /// Returns true if the merge should flatten the dynamic and static
    /// attribute maps into a single table
    bool                            isMergeFlatten() const;

    /// Returns true if the merge should also included added files when
    /// merging outputs, which is typically only used during deseralization
    bool                            isMergeAdded() const;

    /// Reports warnings on the specified node from the merge errors recorded
    /// in the map
    void                            reportErrors(PDG_Node* node) const;

    /// Compares two patterns for equality
    static bool                     arePatternsEqual(const Pattern& left,
                                                     const Pattern& right);

private:
    /// Struct for holding details about a merge error
    struct MergeError
    {
        int                             myLeftStride;
        int                             myRightStride;
        PDG_AttributeType               myLeftType;
        PDG_AttributeType               myRightType;
        PDG_AttributeMergeOp            myMergeOp;
        PDG_AttributeMergeError         myError;
    };

    /// Struct for holding pending merge operations
    struct MergePending
    {
        PDG_AttributeMergeOp            myMergeOp;
        PDG_AttributeMap::AttribTable   myTable;
        int                             myStride;
    };

    /// String map of attrib name -> merge error. We only store one error
    /// per attribute to avoid too much noise.
    using MergeErrors = UT_StringMap<MergeError>;

    /// All collection of pending operations that need to be applied
    using Pending = UT_StringMap<MergePending>;

private:
    friend class PDG_AttributeMap;

    /// Adds a merge error
    void                            addMergeError(
                                            const UT_StringHolder& name,
                                            int left_stride,
                                            int right_stride,
                                            PDG_AttributeType left,
                                            PDG_AttributeType right,
                                            PDG_AttributeMergeOp merge_op,
                                            PDG_AttributeMergeError error);

    /// Adds a collision error
    void                            addCollisionError(
                                            const UT_StringHolder& name);

    /// Adds a pending operation that needs to be applied after merging is
    /// completed
    int                             addPendingOp(
                                            const UT_StringHolder& name,
                                            const MergeData* merge_data,
                                            PDG_AttributeMap::AttribTable,
                                            int current_length,
                                            int new_length);

    /// Returns pending operations stored in this object
    const Pending&                  pendingOps() const
                                        { return myPendingOps; }

    /// Returns true if the specified merge op requires post processing
    static bool                     requiresPending(
                                            PDG_AttributeMergeOp merge_op);

    /// Returns the merge type for the specified attribute name by matching
    /// it against the patterns.
    const MergeData*                matchAttrib(
                                            const UT_StringHolder& name,
                                            PDG_AttributeType type) const;

private:
    MergeErrors                     myMergeErrors;
    UT_ArrayStringSet               myCollisionErrors;

    Pending                         myPendingOps;
    const Pattern&                  myMergePattern;

    UT_ArrayStringSet               myForceIgnore;

    int                             myAttributeTypes;
    AttribFlatten                   myAttribFlatten;

    MergeData                       myDefaultOp;
    MergeData                       myInputOp;
    MergeData                       myOutputOp;

    PDG_AttributeCollision          myCollisionStrategy;

    bool                            myIsDeep;
    bool                            myIsMergeAdded;
    bool                            myIsInternalDependent;
};

#endif