common.h 14.8 KB
Newer Older
Wenzel Jakob's avatar
Wenzel Jakob committed
1
/*
2
    pybind11/common.h -- Basic macros
Wenzel Jakob's avatar
Wenzel Jakob committed
3

4
    Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
Wenzel Jakob's avatar
Wenzel Jakob committed
5
6
7
8
9

    All rights reserved. Use of this source code is governed by a
    BSD-style license that can be found in the LICENSE file.
*/

10
#pragma once
Wenzel Jakob's avatar
Wenzel Jakob committed
11
12

#if !defined(NAMESPACE_BEGIN)
13
#  define NAMESPACE_BEGIN(name) namespace name {
Wenzel Jakob's avatar
Wenzel Jakob committed
14
15
#endif
#if !defined(NAMESPACE_END)
16
#  define NAMESPACE_END(name) }
Wenzel Jakob's avatar
Wenzel Jakob committed
17
18
#endif

19
#if !defined(PYBIND11_EXPORT)
20
21
22
23
24
#  if defined(WIN32) || defined(_WIN32)
#    define PYBIND11_EXPORT __declspec(dllexport)
#  else
#    define PYBIND11_EXPORT __attribute__ ((visibility("default")))
#  endif
Wenzel Jakob's avatar
Wenzel Jakob committed
25
#endif
26

27
#if defined(_MSC_VER)
28
#  define PYBIND11_NOINLINE __declspec(noinline)
29
#else
30
#  define PYBIND11_NOINLINE __attribute__ ((noinline))
31
32
#endif

33
#define PYBIND11_VERSION_MAJOR 1
34
#define PYBIND11_VERSION_MINOR 9
35
#define PYBIND11_VERSION_PATCH dev0
36

Wenzel Jakob's avatar
Wenzel Jakob committed
37
38
/// Include Python header, disable linking to pythonX_d.lib on Windows in debug mode
#if defined(_MSC_VER)
39
40
41
42
#  define HAVE_ROUND
#  pragma warning(push)
#  pragma warning(disable: 4510 4610 4512 4005)
#  if _DEBUG
43
#    define PYBIND11_DEBUG_MARKER
44
45
#    undef _DEBUG
#  endif
Wenzel Jakob's avatar
Wenzel Jakob committed
46
#endif
47

Wenzel Jakob's avatar
Wenzel Jakob committed
48
#include <Python.h>
49
#include <frameobject.h>
50
#include <pythread.h>
51

52
53
54
55
56
#if defined(_WIN32) && (defined(min) || defined(max))
#  error Macro clash with min and max -- define NOMINMAX when compiling your program on Windows
#endif

#if defined(isalnum)
57
58
59
60
61
62
63
#  undef isalnum
#  undef isalpha
#  undef islower
#  undef isspace
#  undef isupper
#  undef tolower
#  undef toupper
64
#endif
65

Wenzel Jakob's avatar
Wenzel Jakob committed
66
#if defined(_MSC_VER)
67
#  if defined(PYBIND11_DEBUG_MARKER)
68
#    define _DEBUG
69
70
#    undef PYBIND11_DEBUG_MARKER
#  endif
71
#  pragma warning(pop)
Wenzel Jakob's avatar
Wenzel Jakob committed
72
73
#endif

74
#include <forward_list>
75
76
77
78
79
80
#include <vector>
#include <string>
#include <stdexcept>
#include <unordered_set>
#include <unordered_map>
#include <memory>
81
#include <typeindex>
82

83
#if PY_MAJOR_VERSION >= 3 /// Compatibility macros for various Python versions
Wenzel Jakob's avatar
Wenzel Jakob committed
84
#define PYBIND11_INSTANCE_METHOD_NEW(ptr, class_) PyInstanceMethod_New(ptr)
85
86
87
88
89
#define PYBIND11_BYTES_CHECK PyBytes_Check
#define PYBIND11_BYTES_FROM_STRING PyBytes_FromString
#define PYBIND11_BYTES_FROM_STRING_AND_SIZE PyBytes_FromStringAndSize
#define PYBIND11_BYTES_AS_STRING_AND_SIZE PyBytes_AsStringAndSize
#define PYBIND11_BYTES_AS_STRING PyBytes_AsString
90
#define PYBIND11_BYTES_CHECK PyBytes_Check
91
92
93
#define PYBIND11_LONG_CHECK(o) PyLong_Check(o)
#define PYBIND11_LONG_AS_LONGLONG(o) PyLong_AsLongLong(o)
#define PYBIND11_LONG_AS_UNSIGNED_LONGLONG(o) PyLong_AsUnsignedLongLong(o)
94
#define PYBIND11_BYTES_NAME "bytes"
95
96
#define PYBIND11_STRING_NAME "str"
#define PYBIND11_SLICE_OBJECT PyObject
97
98
99
100
#define PYBIND11_FROM_STRING PyUnicode_FromString
#define PYBIND11_OB_TYPE(ht_type) (ht_type).ob_base.ob_base.ob_type
#define PYBIND11_PLUGIN_IMPL(name) \
    extern "C" PYBIND11_EXPORT PyObject *PyInit_##name()
101
#else
Wenzel Jakob's avatar
Wenzel Jakob committed
102
#define PYBIND11_INSTANCE_METHOD_NEW(ptr, class_) PyMethod_New(ptr, nullptr, class_)
103
104
105
106
107
#define PYBIND11_BYTES_CHECK PyString_Check
#define PYBIND11_BYTES_FROM_STRING PyString_FromString
#define PYBIND11_BYTES_FROM_STRING_AND_SIZE PyString_FromStringAndSize
#define PYBIND11_BYTES_AS_STRING_AND_SIZE PyString_AsStringAndSize
#define PYBIND11_BYTES_AS_STRING PyString_AsString
108
#define PYBIND11_BYTES_CHECK PyString_Check
109
110
111
#define PYBIND11_LONG_CHECK(o) (PyInt_Check(o) || PyLong_Check(o))
#define PYBIND11_LONG_AS_LONGLONG(o) (PyInt_Check(o) ? (long long) PyLong_AsLong(o) : PyLong_AsLongLong(o))
#define PYBIND11_LONG_AS_UNSIGNED_LONGLONG(o) (PyInt_Check(o) ? (unsigned long long) PyLong_AsUnsignedLong(o) : PyLong_AsUnsignedLongLong(o))
112
#define PYBIND11_BYTES_NAME "str"
113
114
#define PYBIND11_STRING_NAME "unicode"
#define PYBIND11_SLICE_OBJECT PySliceObject
115
116
117
118
#define PYBIND11_FROM_STRING PyString_FromString
#define PYBIND11_OB_TYPE(ht_type) (ht_type).ob_type
#define PYBIND11_PLUGIN_IMPL(name) \
    extern "C" PYBIND11_EXPORT PyObject *init##name()
119
#endif
120

121
122
123
124
#if PY_VERSION_HEX >= 0x03050000 && PY_VERSION_HEX < 0x03050200
extern "C" {
    struct _Py_atomic_address { void *value; };
    PyAPI_DATA(_Py_atomic_address) _PyThreadState_Current;
125
}
126
127
#endif

128
#define PYBIND11_TRY_NEXT_OVERLOAD ((PyObject *) 1) // special failure return code
129
130
131
132
#define PYBIND11_STRINGIFY(x) #x
#define PYBIND11_TOSTRING(x) PYBIND11_STRINGIFY(x)
#define PYBIND11_INTERNALS_ID "__pybind11_" \
    PYBIND11_TOSTRING(PYBIND11_VERSION_MAJOR) "_" PYBIND11_TOSTRING(PYBIND11_VERSION_MINOR) "__"
133
134
135
136
137
138
139
140
141
142
143
144
145

#define PYBIND11_PLUGIN(name) \
    static PyObject *pybind11_init(); \
    PYBIND11_PLUGIN_IMPL(name) { \
        try { \
            return pybind11_init(); \
        } catch (const std::exception &e) { \
            PyErr_SetString(PyExc_ImportError, e.what()); \
            return nullptr; \
        } \
    } \
    PyObject *pybind11_init()

146
NAMESPACE_BEGIN(pybind11)
Wenzel Jakob's avatar
Wenzel Jakob committed
147
148
149
150

typedef Py_ssize_t ssize_t;

/// Approach used to cast a previously unknown C++ instance into a Python object
151
enum class return_value_policy : uint8_t {
Wenzel Jakob's avatar
Wenzel Jakob committed
152
153
154
155
156
    /** This is the default return value policy, which falls back to the policy
        return_value_policy::take_ownership when the return value is a pointer.
        Otherwise, it uses return_value::move or return_value::copy for rvalue
        and lvalue references, respectively. See below for a description of what
        all of these different policies do. */
Wenzel Jakob's avatar
Wenzel Jakob committed
157
    automatic = 0,
Wenzel Jakob's avatar
Wenzel Jakob committed
158

Wenzel Jakob's avatar
Wenzel Jakob committed
159
    /** As above, but use policy return_value_policy::reference when the return
160
161
162
        value is a pointer. This is the default conversion policy for function
        arguments when calling Python functions manually from C++ code (i.e. via
        handle::operator()). You probably won't need to use this. */
163
    automatic_reference,
Wenzel Jakob's avatar
Wenzel Jakob committed
164

Wenzel Jakob's avatar
Wenzel Jakob committed
165
166
167
168
    /** Reference an existing object (i.e. do not create a new copy) and take
        ownership. Python will call the destructor and delete operator when the
        object’s reference count reaches zero. Undefined behavior ensues when
        the C++ side does the same.. */
Wenzel Jakob's avatar
Wenzel Jakob committed
169
    take_ownership,
Wenzel Jakob's avatar
Wenzel Jakob committed
170

Wenzel Jakob's avatar
Wenzel Jakob committed
171
172
173
174
175
176
177
178
179
180
181
182
183
184
    /** Create a new copy of the returned object, which will be owned by
        Python. This policy is comparably safe because the lifetimes of the two
        instances are decoupled. */
    copy,

    /** Use std::move to move the return value contents into a new instance
        that will be owned by Python. This policy is comparably safe because the
        lifetimes of the two instances (move source and destination) are
        decoupled. */
    move,

    /** Reference an existing object, but do not take ownership. The C++ side
        is responsible for managing the object’s lifetime and deallocating it
        when it is no longer used. Warning: undefined behavior will ensue when
Wenzel Jakob's avatar
Wenzel Jakob committed
185
186
        the C++ side deletes an object that is still referenced and used by
        Python. */
Wenzel Jakob's avatar
Wenzel Jakob committed
187
    reference,
Wenzel Jakob's avatar
Wenzel Jakob committed
188

Wenzel Jakob's avatar
Wenzel Jakob committed
189
190
191
192
193
194
195
196
197
198
    /** This policy only applies to methods and properties. It references the
        object without taking ownership similar to the above
        return_value_policy::reference policy. In contrast to that policy, the
        function or property’s implicit this argument (called the parent) is
        considered to be the the owner of the return value (the child).
        pybind11 then couples the lifetime of the parent to the child via a
        reference relationship that ensures that the parent cannot be garbage
        collected while Python is still using the child. More advanced
        variations of this scheme are also possible using combinations of
        return_value_policy::reference and the keep_alive call policy */
Wenzel Jakob's avatar
Wenzel Jakob committed
199
    reference_internal
Wenzel Jakob's avatar
Wenzel Jakob committed
200
201
202
203
};

/// Information record describing a Python buffer object
struct buffer_info {
204
205
206
207
    void *ptr;                   // Pointer to the underlying storage
    size_t itemsize;             // Size of individual items in bytes
    size_t size;                 // Total number of entries
    std::string format;          // For homogeneous buffers, this should be set to format_descriptor<T>::value
208
    size_t ndim;                 // Number of dimensions
209
210
    std::vector<size_t> shape;   // Shape of the tensor (1 entry per dimension)
    std::vector<size_t> strides; // Number of entries between adjacent entries (for each per dimension)
Wenzel Jakob's avatar
Wenzel Jakob committed
211

Johan Mabille's avatar
Johan Mabille committed
212
    buffer_info() : ptr(nullptr), view(nullptr) {}
213
    buffer_info(void *ptr, size_t itemsize, const std::string &format, size_t ndim,
Wenzel Jakob's avatar
Wenzel Jakob committed
214
                const std::vector<size_t> &shape, const std::vector<size_t> &strides)
215
216
        : ptr(ptr), itemsize(itemsize), size(1), format(format),
          ndim(ndim), shape(shape), strides(strides) {
217
218
        for (size_t i = 0; i < ndim; ++i)
            size *= shape[i];
Wenzel Jakob's avatar
Wenzel Jakob committed
219
    }
220
221

    buffer_info(Py_buffer *view)
222
223
224
        : ptr(view->buf), itemsize((size_t) view->itemsize), size(1), format(view->format),
          ndim((size_t) view->ndim), shape((size_t) view->ndim), strides((size_t) view->ndim), view(view) {
        for (size_t i = 0; i < (size_t) view->ndim; ++i) {
225
226
227
228
229
230
231
232
233
            shape[i] = (size_t) view->shape[i];
            strides[i] = (size_t) view->strides[i];
            size *= shape[i];
        }
    }

    ~buffer_info() {
        if (view) { PyBuffer_Release(view); delete view; }
    }
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258

    Py_buffer& as_pybuffer() const {
        static Py_buffer buf { };
        // Py_buffer uses signed sizes, strides and shape!..
        static std::vector<Py_ssize_t> py_strides { };
        static std::vector<Py_ssize_t> py_shape { };
        buf.buf = ptr;
        buf.itemsize = (Py_ssize_t) itemsize;
        buf.format = const_cast<char *>(format.c_str());
        buf.ndim = (int) ndim;
        buf.len = (Py_ssize_t) size;
        py_strides.clear();
        py_shape.clear();
        for (size_t i = 0; i < ndim; ++i) {
            py_strides.push_back((Py_ssize_t) strides[i]);
            py_shape.push_back((Py_ssize_t) shape[i]);
        }
        buf.strides = py_strides.data();
        buf.shape = py_shape.data();
        buf.suboffsets = nullptr;
        buf.readonly = false;
        buf.internal = nullptr;
        return buf;
    }

259
260
private:
    Py_buffer *view = nullptr;
Wenzel Jakob's avatar
Wenzel Jakob committed
261
262
263
264
};

NAMESPACE_BEGIN(detail)

Wenzel Jakob's avatar
Wenzel Jakob committed
265
inline static constexpr int log2(size_t n, int k = 0) { return (n <= 1) ? k : log2(n >> 1, k + 1); }
266

267
268
inline std::string error_string();

269
270
/// Core part of the 'instance' type which POD (needed to be able to use 'offsetof')
template <typename type> struct instance_essentials {
Wenzel Jakob's avatar
Wenzel Jakob committed
271
272
    PyObject_HEAD
    type *value;
273
    PyObject *weakrefs;
Wenzel Jakob's avatar
Wenzel Jakob committed
274
275
    bool owned : 1;
    bool constructed : 1;
276
277
278
279
};

/// PyObject wrapper around generic types, includes a special holder type that is responsible for lifetime management
template <typename type, typename holder_type = std::unique_ptr<type>> struct instance : instance_essentials<type> {
Wenzel Jakob's avatar
Wenzel Jakob committed
280
281
282
    holder_type holder;
};

283
284
285
286
287
288
289
290
struct overload_hash {
    inline std::size_t operator()(const std::pair<const PyObject *, const char *>& v) const {
        size_t value = std::hash<const void *>()(v.first);
        value ^= std::hash<const void *>()(v.second)  + 0x9e3779b9 + (value<<6) + (value>>2);
        return value;
    }
};

Wenzel Jakob's avatar
Wenzel Jakob committed
291
/// Internal data struture used to track registered instances and types
Wenzel Jakob's avatar
Wenzel Jakob committed
292
struct internals {
293
294
295
    std::unordered_map<std::type_index, void*> registered_types_cpp;   // std::type_index -> type_info
    std::unordered_map<const void *, void*> registered_types_py;       // PyTypeObject* -> type_info
    std::unordered_multimap<const void *, void*> registered_instances; // void * -> PyObject*
296
    std::unordered_set<std::pair<const PyObject *, const char *>, overload_hash> inactive_overload_cache;
297
    std::forward_list<void (*) (std::exception_ptr)> registered_exception_translators;
298
#if defined(WITH_THREAD)
299
    decltype(PyThread_create_key()) tstate = 0; // Usually an int but a long on Cygwin64 with Python 3.x
300
301
    PyInterpreterState *istate = nullptr;
#endif
Wenzel Jakob's avatar
Wenzel Jakob committed
302
303
};

Wenzel Jakob's avatar
Wenzel Jakob committed
304
/// Return a reference to the current 'internals' information
Wenzel Jakob's avatar
Wenzel Jakob committed
305
306
inline internals &get_internals();

Wenzel Jakob's avatar
Wenzel Jakob committed
307
308
309
310
311
312
/// Index sequence for convenient template metaprogramming involving tuples
template<size_t ...> struct index_sequence  { };
template<size_t N, size_t ...S> struct make_index_sequence : make_index_sequence <N - 1, N - 1, S...> { };
template<size_t ...S> struct make_index_sequence <0, S...> { typedef index_sequence<S...> type; };

/// Strip the class from a method type
Wenzel Jakob's avatar
Wenzel Jakob committed
313
template <typename T> struct remove_class { };
Wenzel Jakob's avatar
Wenzel Jakob committed
314
315
316
317
template <typename C, typename R, typename... A> struct remove_class<R (C::*)(A...)> { typedef R type(A...); };
template <typename C, typename R, typename... A> struct remove_class<R (C::*)(A...) const> { typedef R type(A...); };

/// Helper template to strip away type modifiers
318
319
320
321
322
323
324
template <typename T> struct intrinsic_type                       { typedef T type; };
template <typename T> struct intrinsic_type<const T>              { typedef typename intrinsic_type<T>::type type; };
template <typename T> struct intrinsic_type<T*>                   { typedef typename intrinsic_type<T>::type type; };
template <typename T> struct intrinsic_type<T&>                   { typedef typename intrinsic_type<T>::type type; };
template <typename T> struct intrinsic_type<T&&>                  { typedef typename intrinsic_type<T>::type type; };
template <typename T, size_t N> struct intrinsic_type<const T[N]> { typedef typename intrinsic_type<T>::type type; };
template <typename T, size_t N> struct intrinsic_type<T[N]>       { typedef typename intrinsic_type<T>::type type; };
Wenzel Jakob's avatar
Wenzel Jakob committed
325
326
327

/// Helper type to replace 'void' in some expressions
struct void_type { };
328

Wenzel Jakob's avatar
Wenzel Jakob committed
329
NAMESPACE_END(detail)
330

Wenzel Jakob's avatar
Wenzel Jakob committed
331
332
333
334
335
336
337
#define PYBIND11_RUNTIME_EXCEPTION(name) \
    class name : public std::runtime_error { public: \
        name(const std::string &w) : std::runtime_error(w) { }; \
        name(const char *s) : std::runtime_error(s) { }; \
        name() : std::runtime_error("") { } \
    };

338
// C++ bindings of core Python exceptions
Wenzel Jakob's avatar
Wenzel Jakob committed
339
340
341
class error_already_set : public std::runtime_error { public: error_already_set() : std::runtime_error(detail::error_string())  {} };
PYBIND11_RUNTIME_EXCEPTION(stop_iteration)
PYBIND11_RUNTIME_EXCEPTION(index_error)
342
PYBIND11_RUNTIME_EXCEPTION(key_error)
343
PYBIND11_RUNTIME_EXCEPTION(value_error)
Wenzel Jakob's avatar
Wenzel Jakob committed
344
PYBIND11_RUNTIME_EXCEPTION(cast_error) /// Thrown when pybind11::cast or handle::call fail due to a type casting error
345
PYBIND11_RUNTIME_EXCEPTION(reference_cast_error) /// Used internally
346

347
348
[[noreturn]] PYBIND11_NOINLINE inline void pybind11_fail(const char *reason) { throw std::runtime_error(reason); }
[[noreturn]] PYBIND11_NOINLINE inline void pybind11_fail(const std::string &reason) { throw std::runtime_error(reason); }
349

350
351
352
353
354
355
356
357
358
359
360
/// Format strings for basic number types
#define PYBIND11_DECL_FMT(t, v) template<> struct format_descriptor<t> { static constexpr const char *value = v; }
template <typename T, typename SFINAE = void> struct format_descriptor { };
template <typename T> struct format_descriptor<T, typename std::enable_if<std::is_integral<T>::value>::type> {
    static constexpr const char value[2] =
        { "bBhHiIqQ"[detail::log2(sizeof(T))*2 + (std::is_unsigned<T>::value ? 1 : 0)], '\0' };
};
template <typename T> constexpr const char format_descriptor<
    T, typename std::enable_if<std::is_integral<T>::value>::type>::value[2];
PYBIND11_DECL_FMT(float, "f"); PYBIND11_DECL_FMT(double, "d"); PYBIND11_DECL_FMT(bool, "?");

361
NAMESPACE_END(pybind11)