1ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* 2ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh CObjects are marked Pending Deprecation as of Python 2.7. 3ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh The full schedule for 2.x is as follows: 4ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh - CObjects are marked Pending Deprecation in Python 2.7. 5ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh - CObjects will be marked Deprecated in Python 2.8 6ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh (if there is one). 7ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh - CObjects will be removed in Python 2.9 (if there is one). 8ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 9ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh Additionally, for the Python 3.x series: 10ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh - CObjects were marked Deprecated in Python 3.1. 11ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh - CObjects will be removed in Python 3.2. 12ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 13ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh You should switch all use of CObjects to capsules. Capsules 14ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh have a safer and more consistent API. For more information, 15ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh see Include/pycapsule.h, or read the "Capsules" topic in 16ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh the "Python/C API Reference Manual". 17ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 18ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh Python 2.7 no longer uses CObjects itself; all objects which 19ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh were formerly CObjects are now capsules. Note that this change 20ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh does not by itself break binary compatibility with extensions 21ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh built for previous versions of Python--PyCObject_AsVoidPtr() 22ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh has been changed to also understand capsules. 23ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 24ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh*/ 25ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 26ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* original file header comment follows: */ 27ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 28ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* C objects to be exported from one extension module to another. 29ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 30ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh C objects are used for communication between extension modules. 31ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh They provide a way for an extension module to export a C interface 32ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh to other extension modules, so that extension modules can use the 33ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh Python import mechanism to link to one another. 34ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 35ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh*/ 36ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 37ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh#ifndef Py_COBJECT_H 38ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh#define Py_COBJECT_H 39ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh#ifdef __cplusplus 40ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsiehextern "C" { 41ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh#endif 42ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 43ffab958fd8d42ed7227d83007350e61555a1fa36Andrew HsiehPyAPI_DATA(PyTypeObject) PyCObject_Type; 44ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 45ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh#define PyCObject_Check(op) (Py_TYPE(op) == &PyCObject_Type) 46ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 47ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* Create a PyCObject from a pointer to a C object and an optional 48ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh destructor function. If the second argument is non-null, then it 49ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh will be called with the first argument if and when the PyCObject is 50ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh destroyed. 51ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 52ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh*/ 53ffab958fd8d42ed7227d83007350e61555a1fa36Andrew HsiehPyAPI_FUNC(PyObject *) PyCObject_FromVoidPtr( 54ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh void *cobj, void (*destruct)(void*)); 55ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 56ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 57ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* Create a PyCObject from a pointer to a C object, a description object, 58ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh and an optional destructor function. If the third argument is non-null, 59ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh then it will be called with the first and second arguments if and when 60ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh the PyCObject is destroyed. 61ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh*/ 62ffab958fd8d42ed7227d83007350e61555a1fa36Andrew HsiehPyAPI_FUNC(PyObject *) PyCObject_FromVoidPtrAndDesc( 63ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh void *cobj, void *desc, void (*destruct)(void*,void*)); 64ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 65ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* Retrieve a pointer to a C object from a PyCObject. */ 66ffab958fd8d42ed7227d83007350e61555a1fa36Andrew HsiehPyAPI_FUNC(void *) PyCObject_AsVoidPtr(PyObject *); 67ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 68ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* Retrieve a pointer to a description object from a PyCObject. */ 69ffab958fd8d42ed7227d83007350e61555a1fa36Andrew HsiehPyAPI_FUNC(void *) PyCObject_GetDesc(PyObject *); 70ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 71ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* Import a pointer to a C object from a module using a PyCObject. */ 72ffab958fd8d42ed7227d83007350e61555a1fa36Andrew HsiehPyAPI_FUNC(void *) PyCObject_Import(char *module_name, char *cobject_name); 73ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 74ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh/* Modify a C object. Fails (==0) if object has a destructor. */ 75ffab958fd8d42ed7227d83007350e61555a1fa36Andrew HsiehPyAPI_FUNC(int) PyCObject_SetVoidPtr(PyObject *self, void *cobj); 76ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 77ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 78ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsiehtypedef struct { 79ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh PyObject_HEAD 80ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh void *cobject; 81ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh void *desc; 82ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh void (*destructor)(void *); 83ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh} PyCObject; 84ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 85ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh 86ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh#ifdef __cplusplus 87ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh} 88ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh#endif 89ffab958fd8d42ed7227d83007350e61555a1fa36Andrew Hsieh#endif /* !Py_COBJECT_H */ 90