PDG_CustomHandlers.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_CUSTOM_HANDLERS_H
#define PDG_CUSTOM_HANDLERS_H

#include "PDG_API.h"

#include "PDG_File.h"
#include "PDG_Types.h"

#include <UT/UT_Array.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_StringSet.h>
#include <UT/UT_UniquePtr.h>

struct PDG_CookOptions;
class PDG_GraphContext;
class PDG_Node;
class PDG_Scheduler;
class PDG_WorkItem;

class UT_FileStat;

/*
 * Table of custom, user-authorable handlers for globally controlling the
 * behavior of file caching, dirtying and work item regeneration
 */
class PDG_API PDG_CustomHandlers : public UT_NonCopyable
{
public:
    /// Return result for custom cache handlers
    enum CacheResult
    {
        /// The custom handler has determined that the file was not cached
        eCacheMiss,

        /// The custom handler has determined that the file was found
        eCacheHit,

        /// The custom handler does not wish to handle the file
        eCacheSkip
    };

    /// Enunmerations of different work item regeneration levels that
    /// can returned by the correpsonding handler.
    enum RegenerateResult
    {
        /// Normal work item regeneration, including both attributes and
        /// cache file invalidation.
        eRegenerateAll,

        /// Regenerate attributes but leave cache files as-is
        eRegenerateAttributes,

        /// Do not regenerate work item attributes nor invalidate cache files
        eRegenerateNever,

        /// Ignore the handler
        eRegenerateSkip,
    };

    /// Enumeration of different file transfer handle results.
    enum TransferResult
    {
        /// The custom handler failed to transfer the file
        eTransferFailure,

        /// The custom handler successfully transfered the file
        eTransferSuccess,

        /// The custom handler chose not to transfer the file, and it should
        /// be handled by the next handler in the list or the default.
        eTransferSkip,

        /// The custom handler determined that the file was cached/already
        /// transfered, and no further attempts should be made to copy it
        eTransferCached
    };

    /// Enumeration of different levels of dirty handler
    enum DirtyHandlerType
    {
        /// The custom dirty handler runs for any dirtied work items
        eDirtyAny,

        /// The custom dirty handler runs only for work items that are
        /// being deleted
        eDirtyDelete,

        /// The custom dirty handler runs only for work itesm that are
        /// being deleted, and have their outputs removed from disk
        eDirtyDeleteFiles
    };

    /// Custom return type for a file transfer operation, which includes both
    /// a status enum and a mod time/cache id
    struct PDG_API TransferPair
    {
        /// The transfer result, e.g. failed or cached
        TransferResult  myResult;

        /// the user-defined cache id
        exint           myCacheID;
    };

    /// Custom return type a file stat operation, which includes both a
    /// hash-type value and a file size.
    struct PDG_API StatPair
    {
        /// The hash/mod time of the file
        PDG_File::Hash  myHash;

        /// The size of the file
        exint           mySize;
    };

public:

    /// Custom functor for checking if a file is cached. These are keyed
    /// on the tag associated with the file.
    class PDG_API CacheHandler
    {
    public:
                             CacheHandler() {}
        virtual             ~CacheHandler() {}
                             UT_NON_COPYABLE(CacheHandler)

        virtual CacheResult checkCached(
                                    const UT_StringHolder& local_path,
                                    const PDG_File& file,
                                    const PDG_WorkItem* work_item) const = 0;
    };

    /// Custom functor for stating a file and returning a size/hash
    class PDG_API StatHandler
    {
    public:
                                StatHandler() {}
        virtual                 ~StatHandler() {}
                                UT_NON_COPYABLE(StatHandler)

        virtual StatPair        statFile(
                                    const UT_StringHolder& local_path,
                                    const PDG_File& file,
                                    const PDG_WorkItem* work_item) const = 0;
    };

    /// Custom functor for handling dirtied work items, and possibly output
    class PDG_API DirtyHandler
    {
    public:
                                DirtyHandler(
                                            DirtyHandlerType type,
                                            const UT_ArrayStringSet& schedulers,
                                            const UT_ArrayStringSet& nodes,
                                            bool requires_outputs,
                                            bool global)
                                    : myType(type)
                                    , mySchedulerFilter(schedulers)
                                    , myNodeFilter(nodes)
                                    , myRequiresOutputs(requires_outputs)
                                    , myIsGlobal(global) {}
        virtual                 ~DirtyHandler() {}
                                UT_NON_COPYABLE(DirtyHandler)

        virtual bool            handleDirty(
                                    const PDG_WorkItem* work_item,
                                    const PDG_File::Set& files) const = 0;

        bool                    matchScheduler(const PDG_Scheduler* scheduler);
        bool                    matchNode(const PDG_Node* node);

        inline DirtyHandlerType type() const
                                    { return myType; }
        inline bool             requiresOutputs() const
                                    { return myRequiresOutputs; }
        inline bool             isGlobal() const
                                    { return myIsGlobal; }

    private:
        UT_ArrayStringSet   mySchedulerFilter;
        UT_ArrayStringSet   myNodeFilter;
        DirtyHandlerType    myType;
        bool                myRequiresOutputs;
        bool                myIsGlobal;
    };

    /// Custom functor for determining if a node should regenerate
    /// work items
    class PDG_API RegenerationHandler
    {
    public:
                                     RegenerationHandler() {}
        virtual                     ~RegenerationHandler() {}
                                    UT_NON_COPYABLE(RegenerationHandler)

        virtual RegenerateResult    shouldRegenerate(
                                        const PDG_Node*,
                                        const PDG_WorkItemArray&) const = 0;
    };

    /// Custom functor for transfering a file from the local machine to 
    /// remote directory associated with the scheduler
    class PDG_API TransferHandler
    {
    public:
                                    TransferHandler(bool use_mod_time)
                                        : myUseModTime(use_mod_time) {}
        virtual                     ~TransferHandler() {}
                                    UT_NON_COPYABLE(TransferHandler)

        virtual TransferPair        transferFile(
                                        const UT_StringHolder& local_path,
                                        const UT_StringHolder& remote_path,
                                        const PDG_File& file,
                                        const PDG_WorkItem* work_item,
                                        const PDG_Scheduler* scheduler,
                                        exint last_update) const = 0;
        inline bool                 useModTime() const 
                                        { return myUseModTime; } 

    private:
        bool                        myUseModTime;
    };

    /// Custom handler functor for running pre-flight logic before a cook
    class PDG_API PreflightHandler
    {
    public:
                        PreflightHandler(bool is_generate_graph)
                            : myIsGenerateGraph(is_generate_graph) {}
        virtual         ~PreflightHandler() {}
                        UT_NON_COPYABLE(PreflightHandler)

        virtual bool    preflight(
                            PDG_GraphContext* context,
                            const PDG_CookOptions& options,
                            UT_WorkBuffer& errors) const = 0;
        inline bool     isGenerateGraph() const
                            { return myIsGenerateGraph; }

    private:
        bool            myIsGenerateGraph;
    };

    /// Unique pointer to a custom cache handler
    using CacheHandlerPtr       = UT_UniquePtr<CacheHandler>;

    /// Cache handler map
    using CacheHandlerMap       = UT_SortedStringMap<CacheHandlerPtr>;


    /// Unique pointer to a custom stat handler
    using StatHandlerPtr        = UT_UniquePtr<StatHandler>;

    /// State handler map
    using StatHandlerMap        = UT_SortedStringMap<StatHandlerPtr>;


    /// Unique pointer to a custom delete handler
    using DirtyHandlerPtr       = UT_UniquePtr<DirtyHandler>;

    /// Delete handler map
    using DirtyHandlerArray     = UT_Array<DirtyHandlerPtr>;


    /// Unique pointer to a custom regeneration handler
    using RegenHandlerPtr       = UT_UniquePtr<RegenerationHandler>;

    /// Regeneration handler array
    using RegenHandlerArray     = UT_Array<RegenHandlerPtr>;


    /// Unique pointer to a custom transfer handler
    using TransferHandlerPtr    = UT_UniquePtr<TransferHandler>;

    /// Transfer handler array
    using TransferHandlerMap    = UT_SortedStringMap<TransferHandlerPtr>;


    /// Unique pointer to a custom preflight handler
    using PreflightHandlerPtr   = UT_UniquePtr<PreflightHandler>;

    /// Preflight handler array
    using PreflightHandlerArray = UT_Array<PreflightHandlerPtr>;

public:
    /// Returns the map of cache handlers, tag -> handler
    const CacheHandlerMap&          cacheHandlers() const
                                        { return myCacheHandlers; }

    /// Returns the map of stat handlers, tag -> handler
    const StatHandlerMap&           statHandlers() const
                                        { return myStatHandlers; }

    /// Returns the map of transfer handlers, tag -> handler
    const TransferHandlerMap&       transferHandlers() const
                                        { return myTransferHandlers; }

    /// Returns the array of dirty handlers
    const DirtyHandlerArray&        dirtyHandlers() const
                                        { return myDirtyHandlers; }

    // Returns the array of regeneration handlers
    const RegenHandlerArray&        regenerationHandlers() const
                                        { return myRegenHandlers; }

    // Returns the array of preflight handlers
    const PreflightHandlerArray&    preflightHandlers() const
                                        { return myPreflightHandlers; }


    /// Adds a custom tag prefix -> cache handler mapping. Returns true if an
    /// existing entry was replaced.
    bool                            addCacheHandler(
                                        const UT_StringHolder& tag,
                                        CacheHandler* handler);

    /// Adds a custom tag prefix -> hash handler mapping. Returns true if an
    /// existing entry was replaced.
    bool                            addStatHandler(
                                        const UT_StringHolder& tag,
                                        StatHandler* handler);

    /// Adds a custom delete handler.
    void                            addDirtyHandler(DirtyHandler* handler);

    /// Adds a custom regeneration handler.
    void                            addRegenerationHandler(
                                        RegenerationHandler* handler);

    /// Adds a custom transfer handler.
    bool                            addTransferHandler(
                                        const UT_StringHolder& tag,
                                        TransferHandler* handler);

    /// Adds a custom preflight handler.
    void                            addPreflightHandler(
                                        PreflightHandler* handler);

    /// Returns true if there are any custom dirty handlers registered
    bool                            hasDirtyHandlers(
                                        DirtyHandlerType type) const;

    /// Clears all cache and delete handlers
    void                            clearHandlers();

    /// Checks if a given file path is cached
    CacheResult                     handleCache(
                                        const UT_StringHolder& local_path,
                                        const PDG_File& file,
                                        const PDG_WorkItem* work_item) const;

    /// Returns the hash/mod time of the file
    StatPair                        handleStat(
                                        const UT_StringHolder& local_path,
                                        const PDG_File& file,
                                        const PDG_WorkItem* work_item) const;

    /// Called before a dirty w/ deleted outputs, in order to run global delete
    /// handlers
    void                            handleDirtyGlobal(
                                        bool delete_items,
                                        bool remove_outputs) const;

    /// Called when a work item should delete files, and runs any custom
    /// handlers that match the item
    bool                            handleDirty(
                                        const PDG_WorkItem* work_item,
                                        const PDG_File::Set& files,
                                        bool delete_items,
                                        bool remove_outputs) const;

    /// Called when a node is going to regenerate work items, to see if it
    /// should.
    RegenerateResult                handleRegenerate(
                                        PDG_Node* node,
                                        const PDG_WorkItemArray& items);

    /// Called when a file needs to be transfered to the working directory
    /// of a scheduler
    TransferPair                    handleTransfer(
                                        const UT_FileStat& local_stat,
                                        const UT_StringHolder& local_path,
                                        const UT_StringHolder& remote_path,
                                        const PDG_File& file,
                                        const PDG_WorkItem* work_item,
                                        const PDG_Scheduler* scheduler,
                                        exint last_update) const;

    /// Called when the graph run preflight logic, and returns false if any
    /// of the handlers fail.
    bool                            handlePreflight(
                                        const PDG_CookOptions& options,
                                        PDG_GraphContext* context,
                                        UT_WorkBuffer& errors);

protected:
    friend class PDG_TypeRegistry;

    /// Constructs a new instance of the table
                                    PDG_CustomHandlers();
private:
    bool                            matchDirtyHandler(
                                        const DirtyHandlerPtr& handler,
                                        const PDG_File::Set& files,
                                        bool global,
                                        bool delete_items,
                                        bool remove_outputs) const;

private:
    // Map of tag prefix -> custom cache handler
    CacheHandlerMap                 myCacheHandlers;

    // Map of tag prefix -> custom hash handler
    StatHandlerMap                  myStatHandlers;

    // Map of tag prefix -> custom transfer handler
    TransferHandlerMap              myTransferHandlers;

    // Array of delete handlers
    DirtyHandlerArray               myDirtyHandlers;

    // Array of regeneration handlers
    RegenHandlerArray               myRegenHandlers;

    // Array of preflight handlers
    PreflightHandlerArray           myPreflightHandlers;

    // Set to true when preflight handlers begin evaluating, to avoid
    // recursive cooks triggering handlers again.
    bool                            myIsHandlingPreflight;
};

#endif