mapExpression.h

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_PCP_MAP_EXPRESSION_H
#define PXR_USD_PCP_MAP_EXPRESSION_H
 
#include "pxr/pxr.h"
#include "pxr/usd/pcp/api.h"
#include "pxr/usd/pcp/mapFunction.h"
 
#include "pxr/base/tf/delegatedCountPtr.h"
 
#include <tbb/spin_mutex.h>
 
#include <atomic>
#include <memory>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class PcpMapExpression
{
public:
    typedef PcpMapFunction Value;
 
    PCP_API
    const Value & Evaluate() const;
 
    PcpMapExpression() noexcept = default;
 
    ~PcpMapExpression() noexcept = default;
 
    void Swap(PcpMapExpression &other) noexcept {
        _node.swap(other._node);
    }
 
    bool IsNull() const noexcept {
        return !_node;
    }
 
 
    PCP_API
    static PcpMapExpression Identity();
 
    PCP_API
    static PcpMapExpression Constant( const Value & constValue );
 
    class Variable {
        Variable(Variable const &) = delete;
        Variable &operator=(Variable const &) = delete;
    public:
        Variable() = default;
        virtual ~Variable();
        virtual const Value & GetValue() const = 0;
        virtual void SetValue(Value && value) = 0;
        virtual PcpMapExpression GetExpression() const = 0;
    };
 
    typedef std::unique_ptr<Variable> VariableUniquePtr;
 
    PCP_API
    static VariableUniquePtr NewVariable(Value && initialValue);
 
    PCP_API
    static PcpMapExpression ImpliedClass(
        const PcpMapExpression& transferFunc,
        const PcpMapExpression& classArc);
 
    PCP_API
    PcpMapExpression Compose(const PcpMapExpression &f) const;
 
    PCP_API
    PcpMapExpression Inverse() const;
 
    PCP_API
    PcpMapExpression AddRootIdentity() const;
 
    bool IsConstantIdentity() const {
        return _node && _node->key.op == _OpConstant &&
            _node->key.valueForConstant.IsIdentity();
    }
 
 
 
    bool IsIdentity() const {
        return Evaluate().IsIdentity();
    }
 
    SdfPath MapSourceToTarget(const SdfPath &path) const {
        return Evaluate().MapSourceToTarget(path);
    }
 
    SdfPath MapTargetToSource(const SdfPath &path) const {
        return Evaluate().MapTargetToSource(path);
    }
 
    const SdfLayerOffset &GetTimeOffset() const {
        return Evaluate().GetTimeOffset();
    }
 
    std::string GetString() const {
        return Evaluate().GetString();
    }
 
 
private:
    // Allow Pcp_Statistics access to internal data for diagnostics.
    friend class Pcp_Statistics;
    friend struct Pcp_VariableImpl;
 
    class _Node;
    using _NodeRefPtr = TfDelegatedCountPtr<_Node>;
 
    explicit PcpMapExpression(const _NodeRefPtr & node) : _node(node) {}
 
private: // data
    enum _Op {
        _OpConstant,
        _OpVariable,
        _OpInverse,
        _OpCompose,
        _OpAddRootIdentity,
        _OpImpliedClass
    };
 
    class _Node {
        _Node(const _Node&) = delete;
        _Node& operator=(const _Node&) = delete;
 
        // Ref-counting ops manage _refCount.
        // Need to friend them here to have access to _refCount.
        friend PCP_API void TfDelegatedCountIncrement(_Node*);
        friend PCP_API void TfDelegatedCountDecrement(_Node*) noexcept;
    public:
        // The Key holds all the state needed to uniquely identify
        // this (sub-)expression.
        struct Key {
            const _Op op;
            const _NodeRefPtr arg1, arg2;
            const Value valueForConstant;
 
            Key( _Op op_,
                 const _NodeRefPtr & arg1_,
                 const _NodeRefPtr & arg2_,
                 const Value & valueForConstant_ )
                : op(op_)
                , arg1(arg1_)
                , arg2(arg2_)
                , valueForConstant(valueForConstant_)
            {}
            inline size_t GetHash() const;
            bool operator==(const Key &key) const;
        };
 
        // The Key of a node is const, and established when it is created.
        const Key key;
 
        // Whether or not the expression tree up to and including this node
        // will always include an identity mapping.
        const bool expressionTreeAlwaysHasIdentity;
 
        // Factory method to create new nodes.
        static _NodeRefPtr
        New( _Op op,
             const _NodeRefPtr & arg1 = _NodeRefPtr(),
             const _NodeRefPtr & arg2 = _NodeRefPtr(),
             const Value & valueForConstant = Value() );
        ~_Node();
 
        // Evaluate (and internally cache) the value of this node.
        const Value & EvaluateAndCache() const;
 
        // For _OpVariable nodes, sets the variable's value.
        void SetValueForVariable(Value &&newValue);
 
        // For _OpVariable nodes, returns the variable's value.
        const Value & GetValueForVariable() const {
            return _valueForVariable;
        }
 
    private:
        explicit _Node( const Key &key_ );
        void _Invalidate();
        Value _EvaluateUncached() const;
 
        // Helper to determine if the expression tree indicated by key
        // will always contains the root identity.
        static bool _ExpressionTreeAlwaysHasIdentity(const Key& key);
 
        // Registry of node instances, identified by Key.
        // Note: variable nodes are not tracked by the registry.
        struct _NodeMap;
        static TfStaticData<_NodeMap> _nodeRegistry;
 
        mutable std::atomic<int> _refCount;
        mutable Value _cachedValue;
        mutable std::set<_Node*> _dependentExpressions;
        Value _valueForVariable;
        mutable tbb::spin_mutex _mutex;
        mutable std::atomic<bool> _hasCachedValue;
    };
 
    // Need to friend them here to have visibility to private class _Node.
    friend PCP_API void TfDelegatedCountIncrement(_Node*);
    friend PCP_API void TfDelegatedCountDecrement(_Node*) noexcept;
 
    _NodeRefPtr _node;
};
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_USD_PCP_MAP_EXPRESSION_H