PDG_Processor.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_PROCESSOR_H__
#define __PDG_PROCESSOR_H__

#include "PDG_API.h"

#include "PDG_EvaluationContext.h"
#include "PDG_Node.h"

#include <UT/UT_Lock.h>
#include <UT/UT_TBBSpinLock.h>
#include <UT/UT_UniquePtr.h>

class PDG_WorkItemHolder;

/**
 * Concrete node type that creates new work items from upstream items. This 
 * node can either create items each item an upstream item is cooked, or when
 * all upstream items are generated or cooked. Work items can also be injected
 * into the node.
 */
class PDG_API PDG_Processor : public PDG_Node
{
public:
    /// Prioritization schemes that node can use when generating work items.
    enum PriorityType
    {
        /// Inheirt the priority from the upstream work items, or 0 if there
        /// are no upstream items
        ePriorityInherit,

        /// Set the priority based on an expression
        ePriorityExpression,

        /// Set the priority using logic in the node. Only used by 
        /// ROP Fetch
        ePriorityNode
    };

    /// Labeling scheme that node can use when generating work item.
    enum LabelType
    {
        /// Use the default label field on the root graph, or no label
        /// if there is no default
        eLabelDefault,

        /// Inherit the label from the parent item
        eLabelInherit,

        /// Set the label based on an expression
        eLabelCustom,

        /// Set the label baed on custom node logic
        eLabelNode
    };

    /// The caching mode, used to control whether or not the node should 
    /// attempt to read existing files from disk prior to cooking
    enum CacheMode
    {
        /// Automatic - checks if the file exists and uses it if it does
        eCacheAutomatic,

        /// Always Read - always tries to read, and fails if the file does not
        /// exist
        eCacheAlwaysRead,

        /// Always Write - always writes, always spawns a job to do the cook
        /// and possibly overrwrites existing files
        eCacheAlwaysWrite,

        /// Same automatic, but the node will not invalidate work items due to
        /// upstream cache changes
        eCacheAutomaticIgnore,
    };

    /// Enumeration of generation conditions
    enum GenerateWhen
    {
        /// Generate work items each time an input work item cooks
        eEachInputCooked,

        /// Generate work items when all inputs work items are generated
        eAllInputsGenerated,

        /// Automatic generation mode
        eAutomaticGeneration,

        /// Generate work items when all inputs work items are cooked
        eAllInputsCooked,
    };

public:
    /// Constructs an new processor from graph context, name, callback type
    /// and custom id. Most of the initialization for this class is handled
    /// in the PDG_Node base.
                                PDG_Processor(
                                    PDG_GraphContext* context,
                                    const UT_StringHolder& name,
                                    const PDG_NodeCallbackType* type_object,
                                    int custom_id = -1);

                                ~PDG_Processor() 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;

    /// Returns the priority scheme used by this node. The default is to
    /// inherit from the upstream work item, if any.
    inline PriorityType         prioritizeBy() const
                                    { return myPriorityType; }

    /// Returns the cook type for work items created by this node.
    inline PDG_WorkItemCookType cookType() const
                                    { return myCookType; }

    /// Returns true if the processor has been configured to use services
    /// for the current cook.
    inline bool                 useServices() const
                                    {
                                        return (myServiceStatus ==
                                            eServiceStatusStarted);
                                    }

    /// Returns the condition when this node resets service clients
    inline PDG_ServiceResetWhen serviceResetWhen() const
                                    { return myServiceResetWhen; }

    /// Returns the reset type for service clients used by this node
    inline PDG_ServiceResetType serviceResetType() const
                                    { return myServiceResetType; }

    /// Constructs a new work item holder for this node, for work item
    /// injection. The caller takes ownership of the object.
    UT_UniquePtr<PDG_WorkItemHolder>
                                workItemHolder();

    /// Injects work items using a holder, which should be constructed with the
    /// this->workItemHolder() method. If compact_items is true, the node's
    /// work item array is compacted, prioritized and sorted after injecting
    /// items.
    void                        injectStaticItems(
                                        PDG_WorkItemHolder& holder,
                                        bool compact_items,
                                        bool sort_items);


    /// Resets this dependency owner
    void                        resetOwner() override;

    /// Returns the priority for the specified work item
    int                         itemPriority(const PDG_WorkItem* work_item,
                                             PriorityType priority_type) const;

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

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

    /// Syncs data for the work item, using node-specific logic
    void                        syncWorkItem(
                                    PDG_WorkItem* work_item,
                                    const PDG_WorkItem* clone_target) override;

    /// Checks if a work item is cached based on its expected outputs and the
    /// current output cache state
    PDG_WorkItemState           isOutputCached(
                                    PDG_WorkItem* work_item) const override;

protected:
    /// Runs node-specific pre cook logic. Called before anything in the graph
    /// evaluates.
    bool                        preCook(bool is_dirty,
                                        bool has_filter) override;

    /// Runs node-specific post cook logic. Called after all work items have
    /// finished cooking.
    void                        postCook() override;


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

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

    /// Called when this node should add a work item. Processor nodes need to
    /// update the myParentMap accordingly.
    void                        addWorkItem(PDG_WorkItem* work_item) override;

    /// Called when a dependency owned by this node is resolved. This method
    /// will generate work items when the generation mode is set to either
    /// AllInputsCooked or AllInputsGenerated.
    PDGE_Dependency::State      evalResolve(
                                    PDGE_Resolutions& resolutions,
                                    const PDGE_Evaluator& evaluator,
                                    PDGE_Dependency* dependency) override;

    /// Called when a dependency owned by thhis node receives a partial
    /// resolution. This method will generate work items when the generation
    /// mode is set to EachInputCooked.
    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,
                                                  bool dynamic_inputs) override;

    /// Adds dependencies on input nodes based on the current generation
    /// settings
    void                        addInputDeps(PDG_Node* input_node) override;

    /// Returns true if the work item should be scheduled, or false if it
    /// should be immediately marked as cooked.
    bool                        shouldSchedule(
                                    const PDG_WorkItem* work_item) const override;

private:
    /// Enumeration of service status
    enum ServiceStatus
    {
        /// Services have not yet been checked/started
        eServiceStatusUnstarted,

        /// Services have been successfully started
        eServiceStatusStarted,

        /// Services failed to start
        eServiceStatusFailed,

        /// Services are not used/disabled
        eServiceStatusUnused,
    };

    /// Queries for existing work items generate in this node for the
    /// specified upstream item.
    bool                        workItemsForParent(
                                                PDG_WorkItemArray& work_items,
                                                PDG_BatchWorkItemSet& batches,
                                                PDG_WorkItem* upstream_item);

    /// Generates work items from an upstream work item
    bool                        generateFromUpstream(
                                                PDGE_Resolutions& resolutions,
                                                PDG_WorkItem* upstream_item);

    /// Adds internal dependencies between the specified work items, i.e. 
    /// dependencies between sibling work items.
    void                        addInternalDependencies(
                                    const PDG_WorkItemArray& work_items);

    /// Adds the specified work items to this node.
    void                        addWorkItems(
                                    const PDG_WorkItemArray& all_items,
                                    const PDG_WorkItemArray& work_items,
                                    const PDG_WorkItemPairArray& pairs,
                                    PDG_EvaluationContext::State state,
                                    bool compact_items,
                                    bool sort_items);

    /// Sets the label for a specific work item
    void                        setWorkItemLabel(
                                    PDG_WorkItem* work_item,
                                    int thread) const;

    /// Sets the label and command for the specified work items
    void                        configureWorkItems(
                                    const PDG_WorkItemArray& work_items,
                                    PDG_EvaluationContext::State state) const;

    /// Configures services for this node
    void                        configureServices();

    /// Checks if any of the expected output files in the node have
    /// duplicate paths, and emits a warning if they do
    void                        checkDuplicateOutputs() const;

private:
    PDG_WorkItemConstMap        myParentMap;
    PDG_WorkItemArray           myPendingInjections;

    PriorityType                myPriorityType;
    LabelType                   myLabelType;
    GenerateWhen                myGenerateWhen;
    CacheMode                   myCacheMode;
    PDG_WorkItemCookType        myCookType;

    ServiceStatus               myServiceStatus;
    PDG_ServiceResetWhen        myServiceResetWhen;
    PDG_ServiceResetType        myServiceResetType;

    mutable UT_Lock             myServiceStatusLock;
    mutable UT_TBBSpinLock      myPendingLock;
    bool                        myHadInjection;
    bool                        myUseScheduleCondition;
};

#endif /* __PDG_PROCESSOR_H__ */