Bump version to 24.04.3.4
[LibreOffice.git] / pyuno / inc / pyuno.hxx
blobf7cab36c7327076bc720c0b86b14cb909e2eac62
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
20 #pragma once
22 #ifndef Py_PYTHON_H
23 #include <Python.h>
24 #endif // #ifdef Py_PYTHON_H
26 #include <com/sun/star/uno/Any.hxx>
28 namespace com::sun::star::uno { class XComponentContext; }
29 namespace com::sun::star::uno { template <typename > class Reference; }
31 /**
32 External interface of the Python UNO bridge.
34 This is a C++ interface, because the core UNO components
35 invocation and proxyfactory are used to implement the bridge.
37 This interface is somewhat private and my change in future.
39 A scripting framework implementation may use this interface
40 to do the necessary conversions.
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
49 /** function called by the python runtime to initialize the
50 pyuno module.
52 preconditions: python has been initialized before and
53 the global interpreter lock is held
56 extern "C" LO_DLLPUBLIC_PYUNO PyObject* PyInit_pyuno();
58 namespace pyuno
61 enum NotNull
63 /** definition of a no acquire enum for ctors
65 NOT_NULL
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.
75 precondition: python has been initialized before and
76 the global interpreter lock is held
79 class PyRef
81 PyObject *m;
82 public:
83 PyRef () : m(nullptr) {}
84 PyRef( PyObject * p ) : m( p ) { Py_XINCREF( m ); }
86 PyRef( PyObject * p, __sal_NoAcquire ) : m( p ) {}
88 PyRef( PyObject * p, __sal_NoAcquire, NotNull ) : m( p )
90 if (!m)
91 throw std::bad_alloc();
94 PyRef(const PyRef &r) : m(r.get()) { Py_XINCREF(m); }
95 PyRef(PyRef &&r) noexcept : m(r.get()) { r.scratch(); }
97 ~PyRef() { Py_XDECREF( m ); }
99 PyObject *get() const noexcept { return m; }
101 PyObject * getAcquired() const
103 Py_XINCREF( m );
104 return m;
107 PyRef& operator=(const PyRef& r)
109 PyObject *tmp = m;
110 m = r.getAcquired();
111 Py_XDECREF(tmp);
112 return *this;
115 PyRef& operator=(PyRef&& r)
117 PyObject *tmp = m;
118 m = r.get();
119 r.scratch();
120 Py_XDECREF(tmp);
121 return *this;
124 bool operator == ( const PyRef & r ) const
126 return r.get() == m;
129 /** clears the reference without decreasing the reference count
130 only seldom needed ! */
131 void scratch() noexcept
133 m = nullptr;
136 /** returns 1 when the reference points to a python object python object,
137 otherwise 0.
139 bool is() const
141 return m != nullptr;
144 struct Hash
146 sal_IntPtr operator () ( const PyRef &r) const { return reinterpret_cast<sal_IntPtr>( r.get() ); }
150 //struct stRuntimeImpl;
151 typedef struct stRuntimeImpl RuntimeImpl;
153 enum ConversionMode { ACCEPT_UNO_ANY, REJECT_UNO_ANY };
156 /** The pyuno::Runtime class keeps the internal state of the python UNO bridge
157 for the currently in use python interpreter.
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.
163 class LO_DLLPUBLIC_PYUNO Runtime
165 RuntimeImpl *impl;
168 Safely unpacks a Python iterator into a sequence, then
169 stores it in an Any. Used internally by pyObject2Any
171 bool pyIterUnpack( PyObject *const, css::uno::Any & ) const;
172 public:
173 ~Runtime( );
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.
180 Note: This method exists for efficiency reasons to save
181 lookup costs for any2PyObject and pyObject2Any
183 @throw RuntimeException in case the runtime has not been
184 initialized before
186 Runtime();
188 Runtime( const Runtime & );
189 Runtime & operator = ( const Runtime & );
191 /** Initializes the python-UNO bridge. May be called only once per python interpreter.
193 @param ctx the component context is used to instantiate bridge services needed
194 for bridging such as invocation, typeconverter, invocationadapterfactory, etc.
196 preconditions: python has been initialized before and
197 the global interpreter lock is held and pyuno is not
198 initialized (see isInitialized() ).
200 @throw RuntimeException in case the thread is not attached or the runtime
201 has not been initialized.
203 static void initialize(
204 const css::uno::Reference< css::uno::XComponentContext > & ctx );
206 /** Checks, whether the uno runtime is already initialized in the current python interpreter.
208 @throws css::uno::RuntimeException
210 static bool isInitialized();
212 /** converts something contained in a UNO Any to a Python object
214 preconditions: python has been initialized before,
215 the global interpreter lock is held and pyuno::Runtime
216 has been initialized.
218 @throws css::script::CannotConvertException
219 @throws css::lang::IllegalArgumentException
220 @throws css::uno::RuntimeException
222 PyRef any2PyObject (const css::uno::Any &source ) const;
224 /** converts a Python object to a UNO any
226 preconditions: python has been initialized before,
227 the global interpreter lock is held and pyuno
228 has been initialized
230 @throws css::uno::RuntimeException
232 css::uno::Any pyObject2Any (
233 const PyRef & source , enum ConversionMode mode = REJECT_UNO_ANY ) const;
235 /** extracts a proper uno exception from a given python exception
237 css::uno::Any extractUnoException(
238 const PyRef & excType, const PyRef & excValue, const PyRef & excTraceback) const;
240 /** Returns the internal handle. Should only be used by the module implementation
242 RuntimeImpl *getImpl() const { return impl; }
246 /** helper class for attaching the current thread to the python runtime.
248 Attaching is done creating a new threadstate for the given interpreter
249 and acquiring the global interpreter lock.
251 Usage:
253 ... don't use python here
255 PyThreadAttach guard( PyInterpreterState_Head() );
257 ... do whatever python code you want
259 PyThreadDetach antiguard;
260 ... don't use python here
262 ... do whatever python code you want
265 ... don't use python here
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.
271 class LO_DLLPUBLIC_PYUNO PyThreadAttach
273 PyThreadState *tstate;
274 bool m_isNewState;
275 PyThreadAttach ( const PyThreadAttach & ) = delete;
276 PyThreadAttach & operator = ( const PyThreadAttach & ) = delete;
277 public:
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
283 @throws css::uno::RuntimeException
284 in case no pythread state could be created
286 PyThreadAttach( PyInterpreterState *interp);
289 /** Releases the global interpreter lock and destroys the thread state.
291 ~PyThreadAttach();
294 /** helper class for detaching the current thread from the python runtime
295 to do some blocking, non-python related operation.
297 @see PyThreadAttach
299 class PyThreadDetach
301 PyThreadState *tstate;
302 PyThreadDetach ( const PyThreadDetach & ) = delete;
303 PyThreadDetach & operator = ( const PyThreadDetach & ) = delete;
305 public:
306 /** Releases the global interpreter lock.
308 precondition: The current thread MUST hold the global interpreter lock.
309 postcondition: The current thread does not hold the global interpreter lock anymore.
311 @throws css::uno::RuntimeException
313 PyThreadDetach();
314 /** Acquires the global interpreter lock again
316 ~PyThreadDetach();
321 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */