PY/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.
 *
 * Produced by:
 *      Side Effects Software Inc
 *      123 Front Street West, Suite 1401
 *      Toronto, Ontario
 *      Canada   M5J 2M2
 *      416-504-9876
 *
 * 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_Result.h"

class PY_API PY_Callback
{
public:
    // Construct instances of this class with an abstract PY_PyObject
    // containing a callable Python object.  The constructor assumes that
    // someone else has already incremented the reference count, and the
    // destructor will decrement the count.
    PY_Callback(void *python_callable_object);
    ~PY_Callback();

    PY_Callback(const PY_Callback &callback);
    PY_Callback &operator=(const PY_Callback &callback);

    bool operator==(const PY_Callback &callback) const;
    bool operator!=(const PY_Callback &callback) const
    { return !operator==(callback); }

    // Given an opaque PyObject *, return whether or not our callback is the
    // same as it.
    bool equalsOpaqueCallback(void *opaque_callback) const;

    // Return a borrowed reference to the opaque PyObject * containing the
    // callback.  If the caller will hold a reference to this object after
    // the PY_Callback has been deleted, it is up to the caller to increment
    // the reference count.
    void *opaqueCallback() const
    { return myOpaqueCallback; }

    // 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;
    }

private:
    void *myOpaqueCallback;
};

#endif

---