APEX_Registry.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.
 *
 * NAME:        APEX_Registry.h (APEX Library, C++)
 *
 * COMMENTS:
 */

#ifndef __APEX_REGISTRY_H__
#define __APEX_REGISTRY_H__

#include "APEX_API.h"
#include "APEX_Callback.h"
#include "APEX_CompatibilityMap.h"
#include "APEX_COW.h"
#include "APEX_Include.h"

#include <GA/GA_Types.h>

#include <UT/UT_Array.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_ArrayStringSet.h>
#include <UT/UT_Function.h>
#include <UT/UT_Lock.h>
#include <UT/UT_Map.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Notifier.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_UniquePtr.h>
#include <SYS/SYS_Types.h>

#include <initializer_list>
#include <map>
#include <string>
#include <utility>

class GU_DetailHandle;
class UN_UniCategory;
class UT_DSOHandle;

namespace apex
{

class APEX_Graph;
class APEX_Registry;
class APEX_OverloadSet;

using addApexFunctionPtr = void (*)(APEX_Registry &);

enum APEX_RegistryType
{
    APEX_REGISTRY_INVALID = -1,  // Invalid registry
    APEX_REGISTRY_CALLBACK,      // The callback registry
    APEX_REGISTRY_COMPONENT,     // The component registry
    APEX_REGISTRY_CONSTRAINT,    // The constraint registry
    APEX_REGISTRY_CONTROL,       // The control registry
    APEX_REGISTRY_N
};

class APEX_RegistryEvent
{
public:
    /// Enumeration of event types.
    enum Type
    {
        CallbacksAdded,  // Callback added; names are in the list.
        SubgraphsUpdated // Subgraphs reloaded.
    };

    APEX_RegistryEvent(Type type, const UT_StringArray &names = UT_StringArray());
    Type getType() const;
    const UT_StringArray &getNames() const;

private:
    Type myType;
    const UT_StringArray &myNames;
};


using APEX_RegistryPtr = UT_SharedPtr<APEX_Registry>;
using APEX_RegistryPtrList = UT_Array<APEX_RegistryPtr>;
using APEX_OverloadSetPtr = UT_SharedPtr<APEX_OverloadSet>;


/// Registries track callback nodes and subgraph nodes.
/// Registries are created in a hierarchy. The "callback" registry holds the
/// essential nodes used by descendent registries. For instance, the "callback"
/// registry is the parent of the "component" registry (which tracks rig
/// component subgraphs). So, each rig component subgraph in the "component"
/// registry can make use of the callback nodes and subgraph nodes available
/// in its parent registry.
class APEX_API APEX_Registry : public UTenable_shared_from_this<APEX_Registry>
{
public:
    ~APEX_Registry();

    UT_NON_COPYABLE(APEX_Registry);

    static constexpr UT_StringLit theUniCategoryName = "Apex";
    static constexpr UT_StringLit theUniCategoryLabel = "APEX";
    static constexpr UT_StringLit theDSOFolder = "apexdso";
    static constexpr UT_StringLit theBrushRegistryName = "brush";
    static constexpr UT_StringLit theBrushRegistryGraphFolder = "apexbrush";
    static constexpr UT_StringLit theCallbackRegistryName = "callback";
    static constexpr UT_StringLit theCallbackRegistryGraphFolder = "apexgraph";
    static constexpr UT_StringLit theComponentRegistryName = "component";
    static constexpr UT_StringLit theComponentRegistryGraphFolder = "apexcomponent";
    static constexpr UT_StringLit theConstraintRegistryName = "constraint";
    static constexpr UT_StringLit theConstraintRegistryGraphFolder = "apexconstraint";
    static constexpr UT_StringLit theControlRegistryName = "control";
    static constexpr UT_StringLit theControlRegistryGraphFolder = "apexcontrol";

    /// Returns the global registry map. Registries are looked up by their name.
    static UT_ArrayStringMap<UT_SharedPtr<APEX_Registry>> &allRegistries();

    /// Returns the APEX registry using its registry type.
    static UT_SharedPtr<APEX_Registry> findOrCreateRegistry(APEX_RegistryType reg_type);

    /// @{ Returns the APEX registries.
    static UT_SharedPtr<APEX_Registry> findOrCreateBrushRegistry(bool load_subgraphs = true);
    static UT_SharedPtr<APEX_Registry> findOrCreateCallbackRegistry(bool load_subgraphs = true);
    static UT_SharedPtr<APEX_Registry> findOrCreateComponentRegistry(bool load_subgraphs = true);
    static UT_SharedPtr<APEX_Registry> findOrCreateConstraintRegistry(bool load_subgraphs = true);
    static UT_SharedPtr<APEX_Registry> findOrCreateControlRegistry(bool load_subgraphs = true);
    /// @}

    /// Find a registry by its name.
    static APEX_RegistryPtr findRegistry(const UT_StringRef &reg_name);

    /// Creates a named registry.
    /// @param reg_name The name of the new registry.
    /// @param reg_graph_folder The name of the folder on the HOUDINI_PATH
    ///            holding subgraphs which should be loaded by the new registry.
    /// @param parent_registries A list of parent registries whose contents
    ///            are accessible by the new registry.
    /// @param add_to_registry_map When true, the registry is added to the
    ///            global registry map. If a registry with the same name
    ///            already exists in the global map, it is replaced with the
    ///            new registry.
    static APEX_RegistryPtr createRegistry(
            const UT_StringRef &reg_name,
            const UT_StringHolder &reg_graph_folder = "",
            const APEX_RegistryPtrList &parent_registries = APEX_RegistryPtrList(),
            bool add_to_registry_map = true);

    /// @{ Adds a new callback node to the registry. The registry holds a
    /// pointer to the callback function and does not participate in lifetime
    /// management of the callback. Therefore, the callback object must exist
    /// for the lifetime of the registry.
    void addCallback(const APEX_FunctionBase *f);
    void addCallbacks(std::initializer_list<const APEX_FunctionBase *> funcs);
    /// @}

    /// Returns the number of callback nodes in the registry.
    exint numCallbacks(bool include_ancestors = false) const;

    /// Finds the named callback node in the registry.
    const APEX_FunctionBase *getCallback(
            const UT_StringRef &callback_name,
            bool include_ancestors = false) const;

    /// Returns the overload set which contains all versions of a generic
    /// callback node. The name of the overload set must contain "<>".
    // For example, "Add<>" returns an overload set containing all generic
    // "Add" callback nodes.
    APEX_OverloadSetPtr getOverloadSet(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// Visits all callback nodes and executes the provided function object.
    void iterCallbacks(
            const UT_Function<void(const APEX_FunctionBase &)> &f,
            bool include_ancestors = false) const;

    /// Visits all subgraph nodes and executes the provided function object.
    void iterSubGraphs(
            const UT_Function<void(const APEX_GraphHandle &)> &f,
            bool include_ancestors = false) const;

    /// Loads callback nodes from the dynamic library.
    /// The dynamic library should define the entry point "addApexFunction"
    /// with the signature given by @ref addApexFunctionPtr. To register
    /// callback nodes, use the registry passed to the entry point function to
    /// call @ref addCallback or @ref addCallbacks.
    void loadCallbackLibrary(const char *dllpath);

    /// Loads the subgraph node library (saved as a .bgeo) at the filepath.
    bool loadSubGraphLibrary(const char *filepath);

    /// Loads the subgraph node library from an in memory geometry.
    bool loadSubGraphLibrary(const GU_DetailHandle &gdh, const char *filepath = "",
                             bool replace = false);

    /// Loads the compatibility file at the filepath.
    void loadCompatibilityFile(const char *filepath);

    /// Clears all subgraph nodes loaded by the registry.
    /// @param except_geo_loaded When true, do not clear subgraphs loaded from
    ///        in memory geometries.
    void clearSubGraphs(bool except_geo_loaded = false);

    /// Reload the subgraph node libraries from the registry's graph folder
    /// (which was specified when creating the registry).
    void reloadSubGraphLibraries();

    /// Returns the number of subgraph nodes tracked by the registry.
    exint numSubGraphs(bool include_ancestors = false) const;

    /// Returns an array of subgraph node names.
    UT_StringArray getSubGraphNames(
            const char *version = nullptr,
            bool include_ancestors = false) const;

    /// Returns the path of the subgraph library from which a named subgraph
    /// node was loaded. If the subgraph node was loaded from a geometry,
    /// returns "<subgraph>".
    const UT_StringHolder &getSubGraphPath(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// Returns the subgraph node's geometry representation.
    const ApexGeometry &getSubGraphGeo(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// Returns the named subgraph node as an @ref APEX_Graph.
    const APEX_GraphHandle &getSubGraph(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// @name GenericFunctions
    /// Generic Functions (functions agnostic to being a callback or subgraph).
    /// @{

    /// Checks if the @a name (as well as any remapping of the name)
    /// corresponds to a callback or subgraph tracked by the registry.
    bool containsName(
        const UT_StringRef &name,
        bool include_ancestors = false) const;

    /// Finds the names of node types matching the @a pattern.
    /// The default @a version "" matches against the current set of names in
    /// the registry. When @a version is nullptr, then all names (including the
    /// names found in the compatibility files) are candidates for matching.
    /// Otherwise, when a specific @a version is given, the names are matched
    /// against the names available in that product version.
    UT_StringArray findMatchingNames(
            const char *pattern = "*",
            const char *version = "",
            bool include_ancestors = false) const;

    /// A convenience function which checks the compatibility map for @a name
    /// and returns its latest name in the registry. If @a name is not in the
    /// compatibility map, it is assumed to already be up to date.
    UT_StringHolder getLatestName(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// Gets a list of available node names that have the same base (core) name
    /// as the given name. The list is sorted in descending precedence order.
    void getNamesInPrecedenceOrder(
            UT_StringArray &precedence_order,
            const char *fullname,
            bool include_ancestors = false) const;

    /// Get the icon name for given callback
    ///
    /// This is first done by mapping it through getLatestName().
    UT_StringHolder getIconName(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// Returns true if the node should be hidden from the UI.
    bool getIsHidden(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// Returns the version number in which the node was introduced.
    UT_StringHolder getMinProductVersion(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// Returns the node's default parameters.
    const Dict &getParmDefaults(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// Returns the signature of the node.
    APEX_Signature getSignature(
            const UT_StringRef &name,
            bool include_ancestors = false) const;

    /// @}

    // Maps from old callback names to new callback names
    const APEX_CompatibilityMap &getCompatibilityMap() const;

    /// Gets a CompatibilityResolver which builds a mapping from the type
    /// definition of @a name at @a version to its current type definition. If
    /// @a version is an empty string, then it is assumed to be the original
    /// version of the node type and all compatibility entries are used.
    UT_UniquePtr<APEX_CompatibilityMap::CompatibilityResolver>
    getCompatibilityResolver(
            const UT_StringRef &name,
            const char *version = "",
            bool include_ancestors = false) const;

    // Additional legal characters that APEX uses the node type names, 
    // (to match callback names, which use them to indicate parm types).
    static constexpr auto theNodeTypeSafeChars = UT_StringLit("<,>");

    /// Returns the UNI category used for the APEX graphs.
    static const UN_UniCategory *uniCategory();

    /// Returns an object used for notifying interested parties about
    /// new callbacks and subgraphs being added.
    UT_NotifierImpl<const APEX_RegistryEvent &> &getEventNotifier();

    /// Returns the registry's DataID. The DataID is updated each time the
    /// registry is modified.
    GA_DataId getDataId() const;

private:
    struct PassKey {};
public:
    /// Use the @ref createRegistry factory method to create a new registry.
    APEX_Registry(
            const UT_StringHolder &registry_graph_folder,
            const APEX_RegistryPtrList &parent_registries,
            const PassKey &);

private:
    const UT_Array<APEX_Registry *> &registryList(bool include_ancestors) const;

    void loadCallbackLibrariesFromPath(const UT_StringRef &dirname);
    void loadCompatibilityFilesFromPath(const UT_StringRef &dirname);

    void addCallbackImpl(const UT_StringHolder &name, const APEX_FunctionBase *f);

    void bumpDataId();

    /// Sets the registry type.
    void setRegistryType(APEX_RegistryType reg_type);

    class SubGraphData;

    const SubGraphData *getSubGraphData(
        const UT_StringRef &name,
        bool include_ancestors = false) const;

    // Callbacks
    UT_ArrayStringMap<UT_DSOHandle *> myCallbackLibraries;
    UT_SortedMap<UT_StringHolder, const APEX_FunctionBase *> myCallbacks;

    // SubGraphs
    UT_StringHolder mySubGraphFolder; // Optional HOUDINI_PATH subdir in which to find subgraphs
    UT_StringArray mySubGraphLibraries; // Holds all subgraph library filepaths
    UT_ArrayStringSet mySubGraphLibrariesFromPath; // Tracks subgraph libraries from HOUDINI_PATH
    mutable UT_SortedMap<UT_StringHolder, SubGraphData> mySubGraphs;

    // Overload sets
    // The first set represents overloads using only this registry.
    // The second set represents overloads of this registry in addition to all
    // ancestor registries. Since they can be requested independently, they must
    // also be cached independently.
    mutable UT_ArrayStringMap<std::pair<APEX_OverloadSetPtr, APEX_OverloadSetPtr>> myOverloadSets;

    // Compatibility
    APEX_CompatibilityMap myCompatibilityMap;

    // Communication
    // Object that sends notifications about registry changes.
    UT_NotifierImpl<const APEX_RegistryEvent &> myEventNotifier;
    GA_DataId myDataId = 0;

    // Concurrency
    mutable UT_Lock myLock;

    // Dependencies
    APEX_RegistryPtrList myParentRegistries;
    UT_Array<APEX_Registry *> myRegistryList;
    UT_Array<APEX_Registry *> myAncestorRegistryList;

    // Registry type
    APEX_RegistryType myRegistryType = APEX_REGISTRY_INVALID;
};

//
// APEX_Registry
//
inline UT_ArrayStringMap<UT_SharedPtr<APEX_Registry>> &
APEX_Registry::allRegistries()
{
    // Currently leaked on purpose due to destruction order problems with
    // referenced types.
    static auto the_registries = new UT_ArrayStringMap<UT_SharedPtr<APEX_Registry>>();
    return *the_registries;
}

inline UT_SharedPtr<APEX_Registry>
APEX_Registry::findOrCreateRegistry(APEX_RegistryType reg_type)
{
    if (reg_type == APEX_REGISTRY_CALLBACK)
        return findOrCreateCallbackRegistry();
    if (reg_type == APEX_REGISTRY_COMPONENT)
        return findOrCreateComponentRegistry();
    if (reg_type == APEX_REGISTRY_CONSTRAINT)
        return findOrCreateConstraintRegistry();
    if (reg_type == APEX_REGISTRY_CONTROL)
        return findOrCreateControlRegistry();
    return nullptr;
}

inline const UT_Array<APEX_Registry *> &
APEX_Registry::registryList(bool include_ancestors) const
{
    return include_ancestors ? myAncestorRegistryList : myRegistryList;
}

inline exint
APEX_Registry::numSubGraphs(bool include_ancestors) const
{
    exint count = 0;
    const UT_Array<APEX_Registry *> &reg_list = registryList(include_ancestors);
    for (const APEX_Registry *reg : reg_list)
    {
        count += reg->mySubGraphs.size();
    }
    return count;
}

inline exint
APEX_Registry::numCallbacks(bool include_ancestors) const
{
    exint count = 0;
    const UT_Array<APEX_Registry *> &reg_list = registryList(include_ancestors);
    for (const APEX_Registry *reg : reg_list)
    {
        count += reg->myCallbacks.size();
    }
    return count;
}

inline const APEX_CompatibilityMap &
APEX_Registry::getCompatibilityMap() const
{
    return myCompatibilityMap;
}

inline
GA_DataId
APEX_Registry::getDataId() const
{
    return myDataId;
}

inline void
APEX_Registry::bumpDataId()
{
    ++myDataId;
}

inline void
APEX_Registry::setRegistryType(APEX_RegistryType reg_type)
{
    myRegistryType = reg_type; 
}

//
// APEX_RegistryEvent
//
inline
APEX_RegistryEvent::APEX_RegistryEvent(APEX_RegistryEvent::Type type, const UT_StringArray &names)
    : myType(type), myNames(names)
{
}

inline APEX_RegistryEvent::Type
APEX_RegistryEvent::getType() const
{
    return myType;
}

inline const UT_StringArray &
APEX_RegistryEvent::getNames() const
{
    return myNames;
}

inline UT_NotifierImpl<const APEX_RegistryEvent &> &
APEX_Registry::getEventNotifier()
{
    return myEventNotifier;
}

}; // namespace apex

#endif // __APEX_REGISTRY_H__