PDG_Partitioner.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_PARTITIONER_H__
#define __PDG_PARTITIONER_H__

#include "PDG_API.h"

#include "PDG_AttributeMerge.h"
#include "PDG_Node.h"
#include "PDG_WorkItemTypes.h"

#include <UT/UT_Array.h>
#include <UT/UT_ArrayMap.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_WorkBuffer.h>

class PDG_FeedbackBegin;
class PDG_PartitionHolder;

/**
 * PDG_Node subclass that partitions incoming work items, e.g. it groups
 * items together into a single unit that can be used for mapping or further
 * work item generation.
 */
class PDG_API PDG_Partitioner : public PDG_Node
{
public:
                                PDG_Partitioner(
                                    PDG_GraphContext* context,
                                    const UT_StringHolder& name,
                                    const PDG_NodeCallbackType* type_object,
                                    int custom_id = -1);

                                ~PDG_Partitioner() override {}

    /// Returns the total memory usage of the node, including any work items
    /// owned by it.
    void                        memoryInfo(
                                    PDG_MemoryInfo& memory_info,
                                    bool inclusive) const override;

    /// Deserialized the specified work item into this node. Most of the
    /// work is handled by the parent class, but partitioner nodes need to
    /// update the myPartitionMap
    bool                        deserializeWorkItem(
                                    PDG_WorkItem* work_item) override;

    /// Called after deserializing a work item and adding its dependencies
    void                        commitWorkItem(
                                    PDG_WorkItem* work_item) override;

    /// Adds special handling for feedback blocks, when a specific work item
    /// in a node is cooked with upstraem dependencies on an end block work
    /// item
    void                        queueWorkItemDeps(
                                    PDGE_Evaluator& evaluator,
                                    PDG_NodeSet& visited_nodes,
                                    PDG_WorkItemIDSet& visited_items,
                                    PDG_Filter& filter) override;

protected:
    /// Returns true if this partitioner generates when the target node is
    /// generated rather than the input nodes
    inline bool                 isTargetedPartitioner() const
                                    { return (myPartitionWhen > eAllInputsCooked); }

    /// Sets the loop depth and loop block reference on the node
    int                         preCookLoop(
                                    PDG_NodeSet& visited,
                                    const UT_Array<LoopInfo>& begin_info)
                                    override;

    /// Called when this node should clear all work items. Management of the
    /// main work item array is handled by the parent class, but partitioners
    /// need to clear their myPartitionMap contents.
    void                        clearAllWorkItems() override;

    /// Called when this node should clear a specific work item. Partitioner
    /// nodes need to update the myPartitionMap accordingly.
    void                        clearWorkItem(
                                    const PDG_WorkItem* work_item) override;

    /// Called when a work item in this node is building depenendcies
    bool                        queueWorkItem(
                                    PDG_WorkItem* work_item) override;

    /// Called when a work in this node cook. The partitioner uses this to
    /// control the data merging process
    bool                        cookWorkItem(
                                    PDGE_Resolutions& resolutions,
                                    PDG_WorkItem* work_item,
                                    bool did_cook) override;

    /// Resets any dependencies owned by this node
    void                        resetOwner() override;

    /// Called when a dependency on this node is resolved
    PDGE_Dependency::State
                                evalResolve(
                                    PDGE_Resolutions& resolutions,
                                    const PDGE_Evaluator& evaluator,
                                    PDGE_Dependency* dependency) override;

    /// Called when a dependency on this node is partially resolved
    PDGE_Dependency::State
                                evalPartial(
                                    PDGE_Resolutions& resolutions,
                                    const PDGE_Evaluator& evaluator,
                                    PDGE_Dependency* dependency,
                                    const PDGE_DependencyOwner::Array& owners)
                                    override;

    /// Caches any built in parm state for the current cook
    bool                        cacheBuiltinParms(
                                    PDG_NodeSet& dirty,
                                    int num_inputs,
                                    bool dynamic_inputs) override;

    /// Adds node dependencies based on the current partitioner settings
    void                        addInputDeps(PDG_Node* input_node) override;

    /// Adds depenencies are that not input specific
    void                        addCommonDeps() override;


    /// Returns true if this node needs to cook its inputs
    bool                        requiresCookedInputs(bool cook) const override;

private:
    /// Enumeration of conditions for partitioning work item with missing
    /// split attributes
    enum SplitMissing
    {
        /// Work items missing the split attribute are ignored
        eSplitIgnore,

        /// Work items missing the split attribute are added to the holder 
        /// and the node itself figures out what to do with them.
        eSplitDefer,

        /// Work items missing the attribute are added to all partitions.
        eSplitAll,

        /// Work items missing the attribute will use a default value
        eSplitDefault
    };

    /// Enumeration of partitioning conditions
    enum PartitionWhen
    {
        /// Partition when all input work items are generated
        eAllInputsGenerated,

        /// Partition when all input work items are cooked
        eAllInputsCooked,

        /// Partition when all target items are generated
        eAllTargetsGenerated,

        /// Partition when each target item group is generated
        eEachTargetGenerated,
    };

    /// Enumeration of frame configuration options
    enum PartitionFrame
    {
        /// The partition will not have its frame set
        eFrameNone,

        /// The partition will set its frame from the first work item with
        /// a frame value
        eFrameFirst,

        /// The partition will set its frame from the last work item with 
        /// a frame value
        eFrameLast,

        /// The partition will set its frame to the largest frame value 
        /// from all work items
        eFrameLargest,

        /// The partition will set its frame to the smallest frame value
        /// from all work items
        eFrameSmallest
    };

    /// Result of syncing partition attribute data
    enum SyncResult
    {
        /// Sync failed
        eSyncFail,

        /// Synced successfully without any user-defined changes
        eSyncSuccess,
    };

private:

    /// Validates and configures targeted nodes
    bool                        cacheTargets();

    /// Loads merge options from pattern parms into our merge pattern object.
    /// Returns true if the pattern has changed.
    bool                        cacheMergePatterns();

    /// Merges partition data on a specified work item
    SyncResult                  syncPartitionAttributes(
                                        PDG_WorkItem* work_item,
                                        bool update);

    /// Constructs a new partition work item
    PDG_WorkItem*               createPartition(
                                        int index,
                                        int priority,
                                        PDG_OptionalFrame frame);

    /// Partitions a list of work items that came from a target node
    bool                        partitionFromTarget(
                                        PDG_WorkItemArray& partitions,
                                        PDG_WorkItemArray& new_partitions,
                                        PDGE_Resolutions& resolutions,
                                        const PDG_WorkItemArray& work_items);

    /// Constructs partitions from the input work items and target item, and
    /// returns them back in the output array
    bool                        partitionWorkItems(
                                        PDG_WorkItemArray& partitions,
                                        PDG_WorkItemArray& new_partitions,
                                        const PDG_WorkItemArray& work_items,
                                        const PDG_WorkItem* target);

    /// Standard parh for creating partitions
    bool                        partitionStandard(
                                        PDG_WorkItemArray& partitions,
                                        PDG_WorkItemArray& new_partitions,
                                        const PDG_WorkItemArray& work_items,
                                        const PDG_WorkItem* target,
                                        const PDG_PartitionHolder& holder);

    /// Optimized path for creating a single partition with all work items.
    bool                        partitionAll(
                                        PDG_WorkItemArray& partitions,
                                        PDG_WorkItemArray& new_partitions,
                                        const PDG_WorkItemArray& work_items,
                                        const PDG_WorkItem* target,
                                        const PDG_PartitionHolder& holder,
                                        bool add_all);

    /// Adds a loop dependency for a specified work item
    void                        addLoopDependency(
                                        PDG_WorkItem* work_item,
                                        bool full_cook);

    /// Adds loop dependencies for the specified partitions and input work
    /// items
    void                        addLoopDependencies(
                                        const PDG_WorkItemArray& work_items,
                                        bool full_cook);

    /// Removes stale partitions from the node.
    void                        removeStalePartitions();


private:
    using PartitionMap      = UT_ArrayMap<int, PDG_WorkItem*>;
    using LoopDependencies  = UT_Array<UT_UniquePtr<PDGE_Dependency>>;

    using TargetMap         = UT_ArrayMap<PDG_WorkItemID, PDG_WorkItemArray>;
    using TargetMapInv      = UT_ArrayMap<PDG_WorkItemID, PDG_WorkItemIDSet>;
    
    PartitionMap                myPartitionMap;
    PDG_NodeSet                 myPartitionTargets;
    PDG_FeedbackBegin*          myFeedbackBegin;

    LoopDependencies            myLoopDependencies;
    TargetMap                   myTargetPartitions;
    TargetMapInv                myTargetPartitionsInv;
    PDG_AttributeMerge::Pattern myMergePattern;
    PDG_AttributeMergeOp        myOutputMergeOp;

    UT_StringHolder             myWorkItemIDAttribute;

    UT_StringHolder             mySplitAttribute;
    UT_StringHolder             mySplitDefault;
    SplitMissing                mySplitMissing;

    PartitionWhen               myPartitionWhen;
    PartitionFrame              myPartitionFrame;

    bool                        mySplitEnabled;
    bool                        mySplitPartial;
    bool                        myHasCustomFrame;
    bool                        myMergeAttributes;
    bool                        myStoreWorkItemIDs;
    bool                        myIgnoreFailedItems;
};

#endif /* __PDG_PARTITIONER_H__ */