1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
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 .
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
; }
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
46 #define LO_DLLPUBLIC_PYUNO SAL_DLLPUBLIC_IMPORT
49 /** function called by the python runtime to initialize the
52 preconditions: python has been initialized before and
53 the global interpreter lock is held
56 extern "C" LO_DLLPUBLIC_PYUNO PyObject
* PyInit_pyuno();
63 /** definition of a no acquire enum for ctors
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
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
)
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
107 PyRef
& operator=(const PyRef
& r
)
115 PyRef
& operator=(PyRef
&& r
)
124 bool operator == ( const PyRef
& r
) const
129 /** clears the reference without decreasing the reference count
130 only seldom needed ! */
131 void scratch() noexcept
136 /** returns 1 when the reference points to a python object python object,
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
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;
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
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
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.
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
;
275 PyThreadAttach ( const PyThreadAttach
& ) = delete;
276 PyThreadAttach
& operator = ( const PyThreadAttach
& ) = delete;
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.
294 /** helper class for detaching the current thread from the python runtime
295 to do some blocking, non-python related operation.
301 PyThreadState
*tstate
;
302 PyThreadDetach ( const PyThreadDetach
& ) = delete;
303 PyThreadDetach
& operator = ( const PyThreadDetach
& ) = delete;
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
314 /** Acquires the global interpreter lock again
321 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */