PY_Callback.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:
 *      Instances of this class hold a Python callback (any callable Python
 *      object).  You can invoke this callback with the call() method, passing
 *      it optional arguments.  When this object is destroyed, the reference
 *      count on the Python callback will be decremented.
 */

#ifndef __PY_Callback_h__
#define __PY_Callback_h__

#include "PY_API.h"
#include "PY_CompiledCode.h"
#include "PY_InterpreterAutoLock.h"
#include "PY_EvaluationContext.h"
#include "PY_OpaqueObject.h"
#include "PY_Result.h"
#include "PY_Kwargs.h"

#include <UT/UT_Function.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_UniquePtr.h>

class PY_PyObject;
class BM_View;
class FUSE_Office;
class OP_Node;

// A cache to avoid recompiling PY_CompiledCode.
class PY_API PY_CallbackCompiledCodeCache
{
public:
    PY_CallbackCompiledCodeCache(exint cache_size=100);
    virtual ~PY_CallbackCompiledCodeCache();

    PY_CompiledCode *compile(const UT_StringHolder &code);

    PY_EvaluationContext myContext;
    UT_StringMap<PY_CompiledCode*> myExpressionCache;

    exint myCacheSize;
};

// Interface class implemented in HOMUI/HOMF which allows allows code in low 
// level libraries such as PY and BM to create HOM wrapper instances.
// This can be used to avoid generating code that has a pointer as an int64 in
// its python code string.
class PY_API PY_CallbackHOM
{
public:
    PY_CallbackHOM() = default;
    virtual ~PY_CallbackHOM(){}

    UT_NON_COPYABLE(PY_CallbackHOM)

    virtual bool getDesktopOffice(const BM_View& v, int &desktop_id, int &office_id) = 0;
    virtual FUSE_Office *getOffice(const BM_View& v) = 0;

    // Returns True if the viewer office is usable
    virtual bool isValidViewerOffice(const BM_View& v) const = 0;
    
    virtual PY_PyObject *newNode(OP_Node &node) = 0;
    virtual PY_PyObject *newSceneViewer(FUSE_Office &office, bool convert_context_viewer=false) = 0;
    virtual PY_PyObject *newViewerStateContext(int64 val) = 0;
    virtual PY_PyObject *newUIEvent(int64 val, int64 val2) = 0;
    virtual PY_PyObject *newViewerEvent(int desktop, int office, int64 val, int64 val2) = 0;
    virtual PY_PyObject *newCompositorViewerEvent(int desktop, int office, int64 val, int64 val2) = 0;
    virtual PY_PyObject *newCompositorViewer(FUSE_Office &office) = 0;
};

class PY_API PY_Callback : public PY_OpaqueObject
{
public:
    using ArgHandler = UT_Function<void (PY_PyObject* args, PY_PyObject* kwargs)>;

    PY_Callback() noexcept : PY_OpaqueObject()
    {};
    PY_Callback(std::nullptr_t n) noexcept : PY_OpaqueObject(n)
    {};

    // Construct instances of this class with an opaque PY_PyObject
    // containing a callable Python object.
    explicit
    PY_Callback(void *python_callable_object, bool new_ref = false) noexcept
    : PY_OpaqueObject(python_callable_object, new_ref)
    , myExpressionCache(nullptr)
    {}

    /// Copy construct/assign
    /// @{
    PY_Callback(const PY_Callback &callback) noexcept
    : PY_OpaqueObject(callback)
    , myExpressionCache(nullptr)
    {}
    PY_Callback &operator=(const PY_Callback &callback) noexcept
    { return (PY_Callback &)PY_OpaqueObject::operator=(callback); }
    /// @}

    /// Move construct/assign
    /// @{
    PY_Callback(PY_Callback &&callback) noexcept
    : PY_OpaqueObject(std::forward<PY_Callback>(callback))
    , myExpressionCache(nullptr)
    {
    }
    PY_Callback &operator=(PY_Callback &&callback) noexcept
    {
        return (PY_Callback &)PY_OpaqueObject::operator=(
                                    std::forward<PY_Callback>(callback));
    }
    /// @}

    // Given two strings containing Python expressions (one that evaluates to
    // a tuple of arguments and another that evaluates to a dictionary of
    // keyword arguments), call the callback.  Either or both of the argument
    // tuple and keyword argument dictionary may be null.  The result is
    // returned in the PY_Result object.
    void call(PY_Result &result, const char *args_expression=NULL,
        const char *kwargs_expression=NULL) const;

    // This convenience version of call() returns the PY_Result by value,
    // instead of passing it in by reference.  This versions can be used by
    // code that isn't performance-critical.
    PY_Result call(const char *args_expression=NULL,
        const char *kwargs_expression=NULL) const
    {
        PY_Result result;
        call(result, args_expression, kwargs_expression);
        return result;
    }

    // For callbacks returning values
    PY_Result call( 
        const char *args_expression,
        const char *kwargs_expression,
        PY_Result::Type desired_result_type ) const;

    // Similar to the above methods but take a lambda function to add elements to
    // the evaluated expressions before firing the callback. Also takes a module name
    // to evaluate the expressions, the module is optional and can be set to nullptr if
    // not required.
    // 
    PY_Result call(
        const char*     args_expression,
        const char*     kwargs_expression,
        const char*     module_name,
        PY_Result::Type desired_result_type,
        PY_OpaqueObject& out_args,
        PY_OpaqueObject& out_kwargs,
        ArgHandler      arg_handler ) const
    {
        PY_InterpreterAutoLock auto_lock;

        PY_Result result = evaluateArgs(
            args_expression, kwargs_expression, module_name, out_args, out_kwargs, arg_handler);
        if (result.myResultType == PY_Result::ERR)
        {
            return result;
        }

        return call(out_args.pyObject(), out_kwargs.pyObject(),
                    desired_result_type);
    }

    // Evaluates argument expressions and use a lambda function for 
    // adding extra elements to the arg and kwarg objects.
    PY_Result evaluateArgs(
        const char*     args_expression,
        const char*     kwargs_expression,
        const char*     module_name,
        PY_OpaqueObject& out_args,
        PY_OpaqueObject& out_kwargs,
        ArgHandler      arg_handler ) const
    {
        PY_InterpreterAutoLock auto_lock;

        PY_Result result = evaluate(
            args_expression, kwargs_expression, module_name, out_args, out_kwargs);
        if (result.myResultType == PY_Result::ERR)
        {
            return result;
        }

        arg_handler(out_args.pyObject(), out_kwargs.pyObject());

        return result;
    }

    void setExpressionCache(PY_CallbackCompiledCodeCache *c)
        { myExpressionCache = c; }

    static void setHOM(PY_CallbackHOM *hom)
        { theHOM = hom; }

    static PY_CallbackHOM* getHOM()
        { return theHOM; }

private:
    // Performs a call with pre-evaluated args and kwargs
    PY_Result call( 
        PY_PyObject * args, 
        PY_PyObject * kwargs,
        PY_Result::Type desired_result_type=PY_Result::NONE ) const;

    // Evaluates positional and keyworded arguments. The returned arguments can 
    // be expanded with other values before performing a call.
    PY_Result evaluate(
        const char *args_expression,
        const char *kwargs_expression,
        const char *module_name,
        PY_OpaqueObject& out_args,
        PY_OpaqueObject& out_kwargs ) const;

    PY_OpaqueObject evaluateExpression(const char *expression, PY_Result &result) const;
    // This version use an input module to evaluate the expression
    PY_OpaqueObject evaluateExpression(
        const char *expression, const char* module_name, PY_Result &result) const;

    PY_CallbackCompiledCodeCache *myExpressionCache;

    static PY_CallbackHOM *theHOM;
};

#endif