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 0 : PyRef () : m(0) {}
87 0 : PyRef( PyObject * p ) : m( p ) { Py_XINCREF( m ); }
88 :
89 0 : PyRef( PyObject * p, __sal_NoAcquire ) : m( p ) {}
90 :
91 0 : PyRef( const PyRef &r ) : m( r.get() ) { Py_XINCREF( m ); }
92 :
93 0 : ~PyRef() { Py_XDECREF( m ); }
94 :
95 0 : PyObject *get() const { return m; }
96 :
97 0 : PyObject * getAcquired() const
98 : {
99 0 : Py_XINCREF( const_cast< PyObject*> (m) );
100 0 : return m;
101 : }
102 :
103 0 : PyRef & operator = ( const PyRef & r )
104 : {
105 0 : PyObject *tmp = m;
106 0 : m = r.getAcquired();
107 0 : Py_XDECREF( tmp );
108 0 : return *this;
109 : }
110 :
111 0 : bool operator == ( const PyRef & r ) const
112 : {
113 0 : return r.get() == m;
114 : }
115 :
116 : /** clears the reference without decreasing the reference count
117 : only seldomly needed ! */
118 0 : void scratch()
119 : {
120 0 : m = 0;
121 0 : }
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 0 : sal_Bool is() const
135 : {
136 0 : return m != 0;
137 : }
138 :
139 : struct Hash
140 : {
141 0 : 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 0 : 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: */
|
