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