stageCache.h

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache License.
//
#ifndef PXR_USD_USD_STAGE_CACHE_H
#define PXR_USD_USD_STAGE_CACHE_H

#include "pxr/pxr.h"
#include "pxr/usd/usd/api.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/base/tf/declarePtrs.h"

#include <boost/lexical_cast.hpp>
#include <boost/operators.hpp>

#include <string>
#include <memory>
#include <mutex>
#include <vector>

PXR_NAMESPACE_OPEN_SCOPE


SDF_DECLARE_HANDLES(SdfLayer);
TF_DECLARE_REF_PTRS(UsdStage);

class ArResolverContext;

class UsdStageCacheRequest;

class UsdStageCache
{
public:
    struct Id : private boost::totally_ordered<Id> {
        Id() : _value(-1) {}

        static Id FromLongInt(long int val) { return Id(val); }

        static Id FromString(const std::string &s) {
            return FromLongInt(boost::lexical_cast<long int>(s));
        }

        long int ToLongInt() const { return _value; }

        std::string ToString() const {
            return boost::lexical_cast<std::string>(ToLongInt());
        }

        bool IsValid() const { return _value != -1; }

        explicit operator bool() const { return IsValid(); }

    private:
        friend bool operator==(const Id &lhs, const Id &rhs) {
            return lhs.ToLongInt() == rhs.ToLongInt();
        }
        friend bool operator<(const Id &lhs, const Id &rhs) {
            return lhs.ToLongInt() < rhs.ToLongInt();
        }
        friend size_t hash_value(Id id) {
            return ~size_t(id.ToLongInt());
        }
        
        explicit Id(long int val) : _value(val) {}

        long int _value;
    };

    USD_API
    UsdStageCache();
    
    USD_API
    UsdStageCache(const UsdStageCache &other);

    USD_API
    ~UsdStageCache();

    USD_API
    UsdStageCache &operator=(const UsdStageCache &other);

    USD_API
    void swap(UsdStageCache &other);

    USD_API
    std::vector<UsdStageRefPtr> GetAllStages() const;

    USD_API
    size_t Size() const;

    bool IsEmpty() const { return Size() == 0; }

    USD_API
    std::pair<UsdStageRefPtr, bool>
    RequestStage(UsdStageCacheRequest &&request);

    USD_API
    UsdStageRefPtr Find(Id id) const;

    USD_API
    UsdStageRefPtr FindOneMatching(const SdfLayerHandle &rootLayer) const;

    USD_API
    UsdStageRefPtr FindOneMatching(const SdfLayerHandle &rootLayer,
                                   const SdfLayerHandle &sessionLayer) const;

    USD_API
    UsdStageRefPtr FindOneMatching(
        const SdfLayerHandle &rootLayer,
        const ArResolverContext &pathResolverContext) const;

    USD_API
    UsdStageRefPtr FindOneMatching(
        const SdfLayerHandle &rootLayer,
        const SdfLayerHandle &sessionLayer,
        const ArResolverContext &pathResolverContext) const;

    USD_API
    std::vector<UsdStageRefPtr>
    FindAllMatching(const SdfLayerHandle &rootLayer) const;

    USD_API
    std::vector<UsdStageRefPtr>
    FindAllMatching(const SdfLayerHandle &rootLayer,
                    const SdfLayerHandle &sessionLayer) const;

    USD_API
    std::vector<UsdStageRefPtr>
    FindAllMatching(const SdfLayerHandle &rootLayer,
                    const ArResolverContext &pathResolverContext) const;

    USD_API
    std::vector<UsdStageRefPtr>
    FindAllMatching(const SdfLayerHandle &rootLayer,
                    const SdfLayerHandle &sessionLayer,
                    const ArResolverContext &pathResolverContext) const;

    USD_API
    Id GetId(const UsdStageRefPtr &stage) const;

    bool Contains(const UsdStageRefPtr &stage) const {
        return static_cast<bool>(GetId(stage));
    }

    bool Contains(Id id) const { return Find(id); }

    USD_API
    Id Insert(const UsdStageRefPtr &stage);
    
    USD_API
    bool Erase(Id id);

    USD_API
    bool Erase(const UsdStageRefPtr &stage);

    USD_API
    size_t EraseAll(const SdfLayerHandle &rootLayer);

    USD_API
    size_t EraseAll(const SdfLayerHandle &rootLayer,
                    const SdfLayerHandle &sessionLayer);

    USD_API
    size_t EraseAll(const SdfLayerHandle &rootLayer,
                    const SdfLayerHandle &sessionLayer,
                    const ArResolverContext &pathResolverContext);
    
    USD_API
    void Clear();

    USD_API
    void SetDebugName(const std::string &debugName);

    USD_API
    std::string GetDebugName() const;

private:
    friend void swap(UsdStageCache &lhs, UsdStageCache &rhs) {
        lhs.swap(rhs);
    }

    typedef struct Usd_StageCacheImpl _Impl;
    std::unique_ptr<_Impl> _impl;
    mutable std::mutex _mutex;
};

class UsdStageCacheRequest
{
public:
    USD_API
    virtual ~UsdStageCacheRequest();

    // Return true if the stage satisfies this request.
    virtual bool IsSatisfiedBy(UsdStageRefPtr const &stage) const = 0;

    // Return true if the pending request will satisfy this request, once
    // complete.
    virtual bool IsSatisfiedBy(UsdStageCacheRequest const &pending) const = 0;

    // Invoked to manufacture a stage to insert in the cache.  Postcondition:
    // IsSatisfiedBy() must return true for the resulting stage.
    virtual UsdStageRefPtr Manufacture() = 0;

private:
    friend class UsdStageCache;

    struct _Mailbox;
    void _Subscribe(_Mailbox *);

    struct _Data;
    struct _DataDeleter { void operator()(_Data *); };
    std::unique_ptr<_Data, _DataDeleter> _data;
};


PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_USD_USD_STAGE_CACHE_H