10a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* 20a8c90248264a8b26970b4473770bcc3df8515fJosh Gao CObjects are marked Pending Deprecation as of Python 2.7. 30a8c90248264a8b26970b4473770bcc3df8515fJosh Gao The full schedule for 2.x is as follows: 40a8c90248264a8b26970b4473770bcc3df8515fJosh Gao - CObjects are marked Pending Deprecation in Python 2.7. 50a8c90248264a8b26970b4473770bcc3df8515fJosh Gao - CObjects will be marked Deprecated in Python 2.8 60a8c90248264a8b26970b4473770bcc3df8515fJosh Gao (if there is one). 70a8c90248264a8b26970b4473770bcc3df8515fJosh Gao - CObjects will be removed in Python 2.9 (if there is one). 80a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 90a8c90248264a8b26970b4473770bcc3df8515fJosh Gao Additionally, for the Python 3.x series: 100a8c90248264a8b26970b4473770bcc3df8515fJosh Gao - CObjects were marked Deprecated in Python 3.1. 110a8c90248264a8b26970b4473770bcc3df8515fJosh Gao - CObjects will be removed in Python 3.2. 120a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 130a8c90248264a8b26970b4473770bcc3df8515fJosh Gao You should switch all use of CObjects to capsules. Capsules 140a8c90248264a8b26970b4473770bcc3df8515fJosh Gao have a safer and more consistent API. For more information, 150a8c90248264a8b26970b4473770bcc3df8515fJosh Gao see Include/pycapsule.h, or read the "Capsules" topic in 160a8c90248264a8b26970b4473770bcc3df8515fJosh Gao the "Python/C API Reference Manual". 170a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 180a8c90248264a8b26970b4473770bcc3df8515fJosh Gao Python 2.7 no longer uses CObjects itself; all objects which 190a8c90248264a8b26970b4473770bcc3df8515fJosh Gao were formerly CObjects are now capsules. Note that this change 200a8c90248264a8b26970b4473770bcc3df8515fJosh Gao does not by itself break binary compatibility with extensions 210a8c90248264a8b26970b4473770bcc3df8515fJosh Gao built for previous versions of Python--PyCObject_AsVoidPtr() 220a8c90248264a8b26970b4473770bcc3df8515fJosh Gao has been changed to also understand capsules. 230a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 240a8c90248264a8b26970b4473770bcc3df8515fJosh Gao*/ 250a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 260a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* original file header comment follows: */ 270a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 280a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* C objects to be exported from one extension module to another. 290a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 300a8c90248264a8b26970b4473770bcc3df8515fJosh Gao C objects are used for communication between extension modules. 310a8c90248264a8b26970b4473770bcc3df8515fJosh Gao They provide a way for an extension module to export a C interface 320a8c90248264a8b26970b4473770bcc3df8515fJosh Gao to other extension modules, so that extension modules can use the 330a8c90248264a8b26970b4473770bcc3df8515fJosh Gao Python import mechanism to link to one another. 340a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 350a8c90248264a8b26970b4473770bcc3df8515fJosh Gao*/ 360a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 370a8c90248264a8b26970b4473770bcc3df8515fJosh Gao#ifndef Py_COBJECT_H 380a8c90248264a8b26970b4473770bcc3df8515fJosh Gao#define Py_COBJECT_H 390a8c90248264a8b26970b4473770bcc3df8515fJosh Gao#ifdef __cplusplus 400a8c90248264a8b26970b4473770bcc3df8515fJosh Gaoextern "C" { 410a8c90248264a8b26970b4473770bcc3df8515fJosh Gao#endif 420a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 430a8c90248264a8b26970b4473770bcc3df8515fJosh GaoPyAPI_DATA(PyTypeObject) PyCObject_Type; 440a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 450a8c90248264a8b26970b4473770bcc3df8515fJosh Gao#define PyCObject_Check(op) (Py_TYPE(op) == &PyCObject_Type) 460a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 470a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* Create a PyCObject from a pointer to a C object and an optional 480a8c90248264a8b26970b4473770bcc3df8515fJosh Gao destructor function. If the second argument is non-null, then it 490a8c90248264a8b26970b4473770bcc3df8515fJosh Gao will be called with the first argument if and when the PyCObject is 500a8c90248264a8b26970b4473770bcc3df8515fJosh Gao destroyed. 510a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 520a8c90248264a8b26970b4473770bcc3df8515fJosh Gao*/ 530a8c90248264a8b26970b4473770bcc3df8515fJosh GaoPyAPI_FUNC(PyObject *) PyCObject_FromVoidPtr( 540a8c90248264a8b26970b4473770bcc3df8515fJosh Gao void *cobj, void (*destruct)(void*)); 550a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 560a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 570a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* Create a PyCObject from a pointer to a C object, a description object, 580a8c90248264a8b26970b4473770bcc3df8515fJosh Gao and an optional destructor function. If the third argument is non-null, 590a8c90248264a8b26970b4473770bcc3df8515fJosh Gao then it will be called with the first and second arguments if and when 600a8c90248264a8b26970b4473770bcc3df8515fJosh Gao the PyCObject is destroyed. 610a8c90248264a8b26970b4473770bcc3df8515fJosh Gao*/ 620a8c90248264a8b26970b4473770bcc3df8515fJosh GaoPyAPI_FUNC(PyObject *) PyCObject_FromVoidPtrAndDesc( 630a8c90248264a8b26970b4473770bcc3df8515fJosh Gao void *cobj, void *desc, void (*destruct)(void*,void*)); 640a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 650a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* Retrieve a pointer to a C object from a PyCObject. */ 660a8c90248264a8b26970b4473770bcc3df8515fJosh GaoPyAPI_FUNC(void *) PyCObject_AsVoidPtr(PyObject *); 670a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 680a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* Retrieve a pointer to a description object from a PyCObject. */ 690a8c90248264a8b26970b4473770bcc3df8515fJosh GaoPyAPI_FUNC(void *) PyCObject_GetDesc(PyObject *); 700a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 710a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* Import a pointer to a C object from a module using a PyCObject. */ 720a8c90248264a8b26970b4473770bcc3df8515fJosh GaoPyAPI_FUNC(void *) PyCObject_Import(char *module_name, char *cobject_name); 730a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 740a8c90248264a8b26970b4473770bcc3df8515fJosh Gao/* Modify a C object. Fails (==0) if object has a destructor. */ 750a8c90248264a8b26970b4473770bcc3df8515fJosh GaoPyAPI_FUNC(int) PyCObject_SetVoidPtr(PyObject *self, void *cobj); 760a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 770a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 780a8c90248264a8b26970b4473770bcc3df8515fJosh Gaotypedef struct { 790a8c90248264a8b26970b4473770bcc3df8515fJosh Gao PyObject_HEAD 800a8c90248264a8b26970b4473770bcc3df8515fJosh Gao void *cobject; 810a8c90248264a8b26970b4473770bcc3df8515fJosh Gao void *desc; 820a8c90248264a8b26970b4473770bcc3df8515fJosh Gao void (*destructor)(void *); 830a8c90248264a8b26970b4473770bcc3df8515fJosh Gao} PyCObject; 840a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 850a8c90248264a8b26970b4473770bcc3df8515fJosh Gao 860a8c90248264a8b26970b4473770bcc3df8515fJosh Gao#ifdef __cplusplus 870a8c90248264a8b26970b4473770bcc3df8515fJosh Gao} 880a8c90248264a8b26970b4473770bcc3df8515fJosh Gao#endif 890a8c90248264a8b26970b4473770bcc3df8515fJosh Gao#endif /* !Py_COBJECT_H */ 90