PDGE_Evaluator.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 __PDGE_EVALUATOR_H__
#define __PDGE_EVALUATOR_H__

#include "PDGE_API.h"

#include "PDGE_Dependency.h"
#include "PDGE_DependencyOwner.h"
#include "PDGE_EvaluationOptions.h"
#include "PDGE_Resolutions.h"

#include <UT/UT_ConcurrentQueue.h>
#include <UT/UT_ParallelUtil.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_TaskGroup.h>
#include <UT/UT_TaskScope.h>
#include <UT/UT_TBBSpinLock.h>
#include <UT/UT_UniquePtr.h>

#include <utility>

/*
 * Evaluates a dependency graph in parallel. The evaluator is provided with a
 * list of initial PDGE_Dependency objects that can be resolved immediately.
 * This kicks off recursive evaluation of the graph.
 *
 * Internally this class runs work in the background using a UT_TaskGroup.
 * It provides utility methods to cancel evaluation of the dependency graph,
 * and supports various configuration options thatcan be passed in via a
 * PDGE_EvaluationOption struct.
 *
 * There are three ways to submit PDGE_Resolution lists to the evaluator:
 *
 *  queueInitial will add initial evaluations that have no dependencies. It
 *  can only be called when evaluation has not yet begun, to add root nodes 
 *  in the dependency graph.
 *
 *  queueResolve will queue evaluations from a background thread and run them
 *  asynchronously. The caller does not block on the resolutions being
 *  processed. Internally, this will run a functor in the task group that runs
 *  the regular resolve method.
 *
 *  resolve will do a blocking parallelReduce over the supplied resolutions and
 *  iteratively evaluate them and any other dependencies that are able to run
 *  as a result.
 */
class PDGE_API PDGE_Evaluator : public PDGE_DependencyOwner
{
public:
    /// The state of the evaluator object
    enum State
    {
        /// The evaluator is uninitialize and evaluation has not yet begun
        eUninitialized,

        /// The evaluator is evaluating
        eEvaluating,

        /// The evaluator is canceling the current evaluation
        eCanceling,

        /// The evaluator has completed, either because it ran normally or 
        /// because it was canceled.
        eCompleted,

        /// This object is invalid because it was cleaned up during shutdown
        eInvalid,
    };

public:
                            PDGE_Evaluator();
                            ~PDGE_Evaluator() noexcept override;

    /// Returns the memory usage of this object
    int64                   getMemoryUsage(bool inclusive) const override;

    /// Returns the current state of the evaluator. This method is not thread-
    /// safe when called off the main thread if the main thread may be calling
    /// cancel().
    inline State            evaluationState() const
                                { return myState; }

    /// Returns the evaluation options used for the current cook
    inline const PDGE_EvaluationOptions&
                            evaluationOptions() const
                                { return myOptions; }

    /// Evaluates the dependency graph. If blocking is true, this method
    /// waits until the evaluation is completed. When blocking the functors
    /// created by the evaluator will be created in a task scope that is
    /// parented to the calling code's current task scope. Otherwise, if the
    /// cook is not blocking, an empty task scope will be used and evaluating
    /// dependencies will be unable to share task locks held by the calling
    /// code.
    void                    evaluate(const PDGE_EvaluationOptions& options);

    /// Cancels the current evaluation. If this object is not evaluating, this
    /// method does nothing.
    void                    cancelEvaluator();

    /// Resets the object back to its default state. This method cannot be
    /// called unless the evaluator is the Completed or Uninitialized state.
    void                    resetEvaluator();

    /// Sets this evaluator as invalid, which disables any additional work
    /// creation. It also waits for the contained task group to finish any
    /// pending work, so that it can be cleanly destroyed.
    void                    invalidateEvaluator();


    /// Adds a root dependency -- a dependency that must be completed before
    /// this evaluator can be marked as a Completed.
    void                    addRootDependency(PDGE_Dependency* dependency);

    /// Returns true if this evaluator depends on the specified dependency.
    inline bool             hasRootDependency(PDGE_Dependency* root) const
                                { return myRootDependency.hasDependency(root); }

    /// Adds an initial dependency resolution, which will be processed as
    /// soon as evaluation begins.
    void                    queueInitial(PDGE_Dependency* dependency);

    /// Queues a dependency resolution array, which will be processed in the
    /// background with the task group owned by this object.. This method
    /// should be used when queueing resolutions from a different TBB task or
    /// a thread that is NOT already being run through the task group
    /// associated with this evaluator object.
    void                    queueResolve(PDGE_Resolutions& resolutions);

    /// Immediately processes a dependency resolution array on the calling
    /// thread. This should only be called within the task hierarchy of the
    /// task group associated with the evaluator object. Otherwise, for
    /// external code that wishes to dynamically submit additional work, the
    /// queueResolve method should be used instead.
    void                    resolve(const PDGE_Resolutions& resolutions);

    /// Immediately processes partial evaluations in a dependency resolution
    /// array on the calling thread. Adds additional non-partial resolutions
    /// that become unblocked to the array.
    void                    partial(PDGE_Resolutions& resolutions);


    /// Returns the debug name for this evaluator object
    UT_StringHolder         debugName() const override;

    /// Called when all dependencies on this object's root dependency have
    /// resolved. This indicates that the cook is complete.
    PDGE_Dependency::State  evalResolve(PDGE_Resolutions& resolutions,
                                        const PDGE_Evaluator& evaluator,
                                        PDGE_Dependency* dependency) override;

    /// Runs a functor with the evaluator's task group and returns
    /// immediately. The functor will eventually run in the background.
    template <typename WrappedFunction, typename... Args>
    inline void             runFunctor(Args&&... args)
                                {
                                    if (myOptions.mySerial)
                                    {
                                        WrappedFunction functor(
                                            std::forward<Args>(args)...);
                                        functor();
                                    }
                                    else
                                    {
                                        ScopedFunctor<WrappedFunction> functor(
                                            false,
                                            std::forward<Args>(args)...);
                                        functor.setTaskScope(myTaskScope);
                                        myTaskGroup->run(std::move(functor));
                                    }
                                }

protected:
    bool                    preEvaluate();
    void                    postEvaluate();

    virtual bool            preEvaluation()
                                { return true; }
    virtual bool            tickEvaluation()
                                { return false; }
    virtual void            postEvaluation(State state, bool canceled)
                                { }

private:
    /*
     * Helper class that wraps a callable object in a UT_TaskScope. When the
     * functor is invoked a task scope is constructed around the call to the
     * wrapped functor. If this object has a task scope set, the scope is
     * created with myScope as a its parent, otherwise it's created with the
     * current scope as the parent. This ensures correct behavior if the
     * functor is created on one thread, but invoked on a different one --
     * for example, if it's queued for execution with UT_TaskGroup::run or if
     * it's passed to a UTparallelFor.
     *
     * This class provies both a const and non-const operator() implemenation
     * that create a task scope, and call WrappedFunctor::operator() with
     * forwarded arguments.
     *
     * The ScopedFunctor subclasses from WrappedFunctor so that any other
     * members from WrappedFunctor are transparently available via this object.
     */
    template <typename WrappedFunctor>
    class ScopedFunctor : public WrappedFunctor
    {
    public:
        template <typename... Args>
                                ScopedFunctor(bool blocking, Args&&... args)
                                    : WrappedFunctor(std::forward<Args>(args)...)
                                    , myScope(nullptr)
                                {
                                    if (blocking)
                                        myScope = UT_TaskScope::getCurrent();
                                }

        template <typename... Args>
        inline void             operator()(Args&&... args)
                                    {
                                        UT_TaskScope task_scope(taskScope());
                                        return WrappedFunctor::operator()(
                                            std::forward<Args>(args)...);
                                    }

        template <typename... Args>
        inline void             operator()(Args&&... args) const
                                    {
                                        UT_TaskScope task_scope(taskScope());
                                        return WrappedFunctor::operator()(
                                            std::forward<Args>(args)...);
                                    }

        inline void             setTaskScope(const UT_TaskScope* parent_scope)
                                    { myScope = parent_scope; }

    protected:
        const UT_TaskScope*     taskScope() const
                                    {
                                        if (myScope)
                                            return myScope;
                                        return UT_TaskScope::getCurrent();
                                    }
    protected:
        const UT_TaskScope*     myScope;
    };

    /*
     * Specialized version of ScopedFunctor<T> that is suitable for use with
     * a UTparallelReduce. We need a special splitting constructor to satisify
     * the requirements of the parallel reduce, which also needs to copy our
     * task scope pointer to the new functor instance.
     */
    template <typename WrappedFunctor>
    class ScopedReduce : public ScopedFunctor<WrappedFunctor>
    {
    public:
        using Base = ScopedFunctor<WrappedFunctor>;
        using Base::Base;

        ScopedReduce(const ScopedReduce<WrappedFunctor>& other, UT_Split split)
            : Base(false, other, split)
        {
            Base::setTaskScope(other.myScope);
        }
    };
    
    using TaskGroupPtr  = UT_UniquePtr<UT_TaskGroup>;
    using ResolveQueue  = UT_ConcurrentQueue<PDGE_Resolutions>;

private:
    PDGE_Dependency         myRootDependency;
    PDGE_Resolutions        myInitialResolves;

    ResolveQueue            myResolveQueue;

    TaskGroupPtr            myTaskGroup;
    const UT_TaskScope*     myTaskScope;

    PDGE_EvaluationOptions  myOptions;
    State                   myState;
    UT_TBBSpinLock          myCancelLock;
};

#endif