PDGT_RegisteredType.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 __PDGT_REGISTERED_TYPE_H__
#define __PDGT_REGISTERED_TYPE_H__

#include "PDGT_API.h"
#include "PDGT_BaseType.h"

#include <UT/UT_ConcurrentVector.h>
#include <UT/UT_Function.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_WeakPtr.h>
#include <UT/UT_WorkBuffer.h>

class PDGT_ValueArgs;

/**
 * This class represents a concrete type in a type system. It subclasses from
 * PDGT_BaseType, and defines a number of new template arguments that describe
 * the type. These include:
 *
 *      The Class, which is the backing C++ class that this type will produce.
 *      For example, the PDG_NodeCallbackType produces instances of the
 *      PDG_NodeCallback class.
 *
 *      The pointer type. If the pointer type is a shared pointer, this object
 *      will be able to safely tracking the list of instances created.
 *      Otherwise, instance tracking will be disabled and attempts to use the
 *      reload functionality will error out.
 *
 *      The specfic entry in the EnumType that's associated with this type,
 *      for example PDG_RegistrationType::eNode.
 *
 *      The variadic argument pack of constructor arguments that are needed to
 *      create instances of Class using type object.
 *
 * By default, a registered type expects to be given a functor to use to 
 * construct Class instances. A default functor which simply calls `new Class`
 * with the appropriate args is already included. It is also possible to 
 * completely override the functor-based constructor and instead redefine the
 * `instantiate` function to perform construction logic. This is done for
 * Python-backed node/scheduler types in PDG, which implement part their
 * construction logic in the PYPDG module using pybind11.
 *
 * An instance of this class provides three main pieces of functionality:
 *
 *      The ability to construct new instances of Class, using logic defined
 *      by the type object and the input Args...
 *
 *      Optional thread safe tracking of all instances of the type that have
 *      been created.
 *
 *      And, assuming the tracking is enabled, the ability to run some sort of
 *      reloading logic. For example, for PDG nodes defined in Python, this
 *      functionality can be used to reload the Python module and recreate
 *      any underlying PyObjects used by the node callback type.
 */
template <typename Class, typename Pointer, typename EnumType, EnumType Type, typename... Args>
class PDGT_API_TMPL PDGT_RegisteredType : public PDGT_BaseType<EnumType>
{
public:
    /// The factory function type, which returns a new instance of Class as a
    /// Pointer.
    using Function  = UT_Function<Pointer (
                            const PDGT_BaseType<EnumType>*,
                            UT_WorkBuffer&,
                            const PDGT_ValueArgs& extra_args,
                            Args...)>;

    /// Array of instances that refer to Class objects created using this type.
    /// The array contains weak references, which is why instance tracking can
    /// only be enabled when Pointer is some sort of shared_ptr type.
    using Instances = UT_ConcurrentVector<UT_WeakPtr<Class>>;

    /// The enum entry this registered type is associated with, from the
    /// EnumType declared as a template argument.
    static constexpr EnumType Enum = Type;


    PDGT_RegisteredType(const UT_StringHolder& name,
                        const UT_StringHolder& label,
                        typename PDGT_BaseType<EnumType>::Language lang,
                        bool track_instances)
        : PDGT_BaseType<EnumType>(name, label, lang, Type)
        , myTrackInstances(track_instances)
        , myIsPrivate(false)
    {
    }

    ~PDGT_RegisteredType() override {}

    /// Constructs a new instance of Class using this registered type. If the
    /// Pointer type is a raw pointer, the caller takes owernship of the object.
    /// Otherwise, if Pointer is a shared pointer type, the ownership is of
    /// course bound to the lifetime of that shared pointer. The caller is 
    /// responsible for making sure that they keep it alive for as long as
    /// they need it.
    Pointer             instance(UT_WorkBuffer& errors,
                                 const PDGT_ValueArgs& extra_args,
                                 Args... args) const
                            { 
                                Pointer instance =
                                    instantiate(errors, extra_args, args...);
                                addInstance(instance);
                                return instance;
                            }

    /// Reloads a particular instance of Class, using this type object. This
    /// is a "re-initialize" call, to reset whatever state in the Class*
    /// instance is dependent on this type object.
    bool                reloadInstance(UT_WorkBuffer& errors,
                                       const PDGT_ValueArgs& extra_args,
                                       Class* instance,
                                       Args... args) const
                            {
                                return reload(errors, extra_args, instance,
                                    args...);
                            }

    /// Reloads this type object itself, and requests that each existing
    /// instance of Class also resets itself. If Pointer is not a shared pointer
    /// type, there will be no instances to reset.
    bool                reloadType(UT_WorkBuffer& errors)
                            {
                                bool result = reload(errors);
                                for (auto&& instance : myInstances)
                                {
                                    if (auto p = instance.lock())
                                    {
                                        p->setReloading(true);
                                        result &= p->reloadInstance(errors);
                                        p->setReloading(false);
                                    }
                                }
                                return result;
                            }

    /// Returns the combined memory usage of all instances of this type
    int64               instanceMemoryUsage() const override
                            {
                                int64 mem = 0;
                                for (auto&& instance : myInstances)
                                {
                                    if (auto p = instance.lock())
                                        mem += p->getMemoryUsage(true);
                                }

                                return mem;
                            }

    /// Sets the factory function to use when contructing Class instances.
    void                setFunction(const Function& function)
                            { myFunction = function; }

    /// Sets the isPrivate flag
    void                setIsPrivate(bool is_private)
                            { myIsPrivate = is_private; }

    /// Returns true if the type is private
    bool                isPrivate() const
                            { return myIsPrivate; }

    /// Default factory method, which simple allocates a new instance of
    /// ConcreteType, which much be Class or some subclass of it. The object
    /// is returned as Pointer.
    template <typename ConcreteType>
    static Pointer      typeInit(const PDGT_BaseType<EnumType>* type,
                                 UT_WorkBuffer& errors,
                                 const PDGT_ValueArgs& extra_args,
                                 Args... args)
                            {
                                return Pointer(
                                    new ConcreteType(type, extra_args, args...));
                            }

protected:
    /// These methods conditionally enable instance tracking. We can only safely
    /// keep weak-refs to the instances if our Pointer type is a shared ptr, so
    /// an overload to addInstance that's conditional on that being the case
    /// is required. It's also possible to disable instance tracking with a 
    /// member variable, so that gets checked in the codepath that may actually
    /// append an instance to our tracking vector.
    template <typename P = Pointer>
    typename std::enable_if<std::is_same<P, UT_SharedPtr<Class>>::value>::type
                        addInstance(P instance) const
                            {
                                if (myTrackInstances)
                                    myInstances.push_back(instance);
                            }
    template <typename P = Pointer>
    typename std::enable_if<!std::is_same<P, UT_SharedPtr<Class>>::value>::type
                        addInstance(P instance) const
                            {
                            }

    UT_SharedPtr<Class> lockInstance(UT_WeakPtr<Class> instance) const
                            {
                                return instance.lock();
                            }


    /// This function is responsible for constructing an instance of Class. It
    /// uses the functor by default, but subclasses are permitted to redefine
    /// it to construct objects in a different way.
    virtual Pointer     instantiate(UT_WorkBuffer& errors,
                                    const PDGT_ValueArgs& extra_args,
                                    Args... variadic_args) const
                            {
                                if (!myFunction)
                                {
                                    errors.appendFormat(
                                        "Incomplete or invalid type '{}'",
                                        PDGT_BaseType<EnumType>::typeName());
                                }

                                return myFunction(this, errors, extra_args,
                                    variadic_args...);
                            }

    /// This function is responsible for reloading this type object itself.
    /// For example, for a Python-backed node as defined in the PYPDG module,
    /// this function will reload the underlying Python module.
    virtual bool        reload(UT_WorkBuffer& errors)
                            {
                                errors.format(
                                    "Type '{}' does not support reloading",
                                    PDGT_BaseType<EnumType>::typeName());
                                return false;
                            }

    /// This function is responsible for reloading a particular instance of
    /// Class created using this type object. By default, it does nothing, but 
    /// subclasses that wish to support reloading should customize it. For 
    /// example, the PYPDG subclass will use this hook to reconstruct the Py
    /// Object inside of a PDG_NodeCallback, when reloading that instance.
    virtual bool        reload(UT_WorkBuffer& errors,
                               const PDGT_ValueArgs& extra_args,
                               Class* instance,
                               Args... variadic_args) const
                            {
                                errors.format(
                                    "Instances of type '{}' cannot be reloaded",
                                    PDGT_BaseType<EnumType>::typeName());
                                return false;
                            }

private:
    Function            myFunction;
    mutable Instances   myInstances;
    bool                myTrackInstances;
    bool                myIsPrivate;
};

#endif