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