pyuno/inc/pyuno.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_PYUNO_INC_PYUNO_HXX
  21 #define INCLUDED_PYUNO_INC_PYUNO_HXX
  22
  23 #ifndef Py_PYTHON_H
  24 #include <Python.h>
  25 #endif // #ifdef Py_PYTHON_H
  26 #include <com/sun/star/uno/XComponentContext.hpp>
  27 #include <com/sun/star/script/CannotConvertException.hpp>
  28 #include <com/sun/star/lang/IllegalArgumentException.hpp>
  29
  30 /**
  31    External interface of the Python UNO bridge.
  32
  33    This is a C++ interface, because the core UNO components
  34    invocation and proxyfactory are used to implement the bridge.
  35
  36    This interface is somewhat private and my change in future.
  37
  38    A scripting framework implementation may use this interface
  39    to do the necessary conversions.
  40 */
  41
  42 #if defined LO_DLLIMPLEMENTATION_PYUNO
  43 #define LO_DLLPUBLIC_PYUNO SAL_DLLPUBLIC_EXPORT
  44 #else
  45 #define LO_DLLPUBLIC_PYUNO SAL_DLLPUBLIC_IMPORT
  46 #endif
  47
  48 /** function called by the python runtime to initialize the
  49     pyuno module.
  50
  51     preconditions: python has been initialized before and
  52                    the global interpreter lock is held
  53 */
  54
  55 extern "C" LO_DLLPUBLIC_PYUNO
  56 #if PY_MAJOR_VERSION >= 3
  57     PyObject* PyInit_pyuno();
  58 #else
  59    void initpyuno();
  60 #endif
  61
  62 namespace pyuno
  63 {
  64
  65 enum NotNull
  66 {
  67     /** definition of a no acquire enum for ctors
  68      */
  69     NOT_NULL
  70 };
  71
  72 /** Helper class for keeping references to python objects.
  73     BEWARE: Look up every python function you use to check
  74     whether you get an acquired or not acquired object pointer
  75     (python terminus for a not acquired object pointer
  76     is 'borrowed reference'). Use in the acquired pointer cases the
  77     PyRef( pointer, SAL_NO_ACQUIRE) ctor.
  78
  79     precondition: python has been initialized before and
  80     the global interpreter lock is held
  81
  82 */
  83 class PyRef
  84 {
  85     PyObject *m;
  86 public:
  87     PyRef () : m(nullptr) {}
  88     PyRef( PyObject * p ) : m( p ) { Py_XINCREF( m ); }
  89
  90     PyRef( PyObject * p, __sal_NoAcquire ) : m( p ) {}
  91
  92     PyRef( PyObject * p, __sal_NoAcquire, NotNull ) : m( p )
  93     {
  94         if (!m)
  95             throw std::bad_alloc();
  96     }
  97
  98     PyRef(const PyRef &r) : m(r.get()) { Py_XINCREF(m); }
  99     PyRef(PyRef &&r) : m(r.get()) { r.scratch(); }
 100
 101     ~PyRef() { Py_XDECREF( m ); }
 102
 103     PyObject *get() const { return m; }
 104
 105     PyObject * getAcquired() const
 106     {
 107         Py_XINCREF( m );
 108         return m;
 109     }
 110
 111     PyRef& operator=(const PyRef& r)
 112     {
 113         PyObject *tmp = m;
 114         m = r.getAcquired();
 115         Py_XDECREF(tmp);
 116         return *this;
 117     }
 118
 119     PyRef& operator=(PyRef&& r)
 120     {
 121         PyObject *tmp = m;
 122         m = r.get();
 123         r.scratch();
 124         Py_XDECREF(tmp);
 125         return *this;
 126     }
 127
 128     bool operator == (  const PyRef & r ) const
 129     {
 130         return r.get() == m;
 131     }
 132
 133     /** clears the reference without decreasing the reference count
 134         only seldom needed ! */
 135     void scratch()
 136     {
 137         m = nullptr;
 138     }
 139
 140     /** returns 1 when the reference points to a python object python object,
 141         otherwise 0.
 142     */
 143     bool is() const
 144     {
 145         return m != nullptr;
 146     }
 147
 148     struct Hash
 149     {
 150         sal_IntPtr operator () ( const PyRef &r) const { return sal_IntPtr( r.get() ); }
 151     };
 152 };
 153
 154 struct stRuntimeImpl;
 155 typedef struct stRuntimeImpl RuntimeImpl;
 156
 157 enum ConversionMode { ACCEPT_UNO_ANY, REJECT_UNO_ANY };
 158
 159
 160 /** The pyuno::Runtime class keeps the internal state of the python UNO bridge
 161     for the currently in use python interpreter.
 162
 163     You may keep a Runtime instance, use it from a different thread, etc. But you must
 164     make sure to fulfill all preconditions mentioned for the specific methods.
 165 */
 166
 167 class LO_DLLPUBLIC_PYUNO Runtime
 168 {
 169     RuntimeImpl *impl;
 170
 171     /**
 172         Safely unpacks a Python iterator into a sequence, then
 173         stores it in an Any. Used internally by pyObject2Any
 174     */
 175     bool pyIterUnpack( PyObject *const, css::uno::Any & ) const;
 176 public:
 177     ~Runtime( );
 178
 179     /**
 180         preconditions: python has been initialized before,
 181         the global interpreter lock is held and pyuno
 182         has been initialized for the currently used interpreter.
 183
 184         Note: This method exists for efficiency reasons to save
 185         lookup costs for any2PyObject and pyObject2Any
 186
 187         @throw RuntimeException in case the runtime has not been
 188                initialized before
 189      */
 190     Runtime();
 191
 192     Runtime( const Runtime & );
 193     Runtime & operator = ( const Runtime & );
 194
 195     /** Initializes the python-UNO bridge. May be called only once per python interpreter.
 196
 197         @param ctx the component context is used to instantiate bridge services needed
 198         for bridging such as invocation, typeconverter, invocationadapterfactory, etc.
 199
 200         preconditions: python has been initialized before and
 201         the global interpreter lock is held and pyuno is not
 202         initialized (see isInitialized() ).
 203
 204         @throw RuntimeException in case the thread is not attached or the runtime
 205                                 has not been initialized.
 206     */
 207     static void initialize(
 208         const css::uno::Reference< css::uno::XComponentContext > & ctx );
 209
 210     /** Checks, whether the uno runtime is already initialized in the current python interpreter.
 211
 212         @throws css::uno::RuntimeException
 213      */
 214     static bool isInitialized();
 215
 216     /** converts something contained in an UNO Any to a Python object
 217
 218         preconditions: python has been initialized before,
 219         the global interpreter lock is held and pyuno::Runtime
 220         has been initialized.
 221
 222         @throws css::script::CannotConvertException
 223         @throws css::lang::IllegalArgumentException
 224         @throws css::uno::RuntimeException
 225     */
 226     PyRef any2PyObject (const css::uno::Any &source ) const;
 227
 228     /** converts a Python object to a UNO any
 229
 230         preconditions: python has been initialized before,
 231         the global interpreter lock is held and pyuno
 232         has been initialized
 233
 234         @throws css::uno::RuntimeException
 235     */
 236     css::uno::Any pyObject2Any (
 237         const PyRef & source , enum ConversionMode mode = REJECT_UNO_ANY ) const;
 238
 239     /** extracts a proper uno exception from a given python exception
 240      */
 241     css::uno::Any extractUnoException(
 242         const PyRef & excType, const PyRef & excValue, const PyRef & excTraceback) const;
 243
 244     /** Returns the internal handle. Should only be used by the module implementation
 245      */
 246     RuntimeImpl *getImpl() const { return impl; }
 247 };
 248
 249
 250 /** helper class for attaching the current thread to the python runtime.
 251
 252     Attaching is done creating a new threadstate for the given interpreter
 253     and acquiring the global interpreter lock.
 254
 255     Usage:
 256
 257     ... don't use python here
 258     {
 259         PyThreadAttach guard( PyInterpreterState_Head() );
 260         {
 261             ... do whatever python code you want
 262             {
 263                PyThreadDetach antiguard;
 264                ... don't use python here
 265             }
 266             ... do whatever python code you want
 267         }
 268     }
 269     ... don't use python here
 270
 271     Note: The additional scope brackets after the PyThreadAttach are needed,
 272           e.g. when you would leave them away, dtors of potential pyrefs
 273           may be called after the thread has detached again.
 274  */
 275 class LO_DLLPUBLIC_PYUNO PyThreadAttach
 276 {
 277     PyThreadState *tstate;
 278     PyThreadAttach ( const PyThreadAttach & ) = delete;
 279     PyThreadAttach & operator = ( const PyThreadAttach & ) = delete;
 280 public:
 281
 282     /** Creates a new python threadstate and acquires the global interpreter lock.
 283         precondition: The current thread MUST NOT hold the global interpreter lock.
 284         postcondition: The global interpreter lock is acquired
 285
 286         @throws css::uno::RuntimeException
 287              in case no pythread state could be created
 288      */
 289     PyThreadAttach( PyInterpreterState *interp);
 290
 291
 292     /** Releases the global interpreter lock and destroys the thread state.
 293      */
 294     ~PyThreadAttach();
 295 };
 296
 297 /** helper class for detaching the current thread from the python runtime
 298     to do some blocking, non-python related operation.
 299
 300     @see PyThreadAttach
 301 */
 302 class LO_DLLPUBLIC_PYUNO PyThreadDetach
 303 {
 304     PyThreadState *tstate;
 305     PyThreadDetach ( const PyThreadDetach & ) = delete;
 306     PyThreadDetach & operator = ( const PyThreadDetach & ) = delete;
 307
 308 public:
 309     /** Releases the global interpreter lock.
 310
 311        precondition: The current thread MUST hold the global interpreter lock.
 312        postcondition: The current thread does not hold the global interpreter lock anymore.
 313
 314        @throws css::uno::RuntimeException
 315     */
 316     PyThreadDetach();
 317     /** Acquires the global interpreter lock again
 318     */
 319     ~PyThreadDetach();
 320 };
 321
 322 }
 323 #endif
 324
 325 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */