From 9b499dd69048a9d40afab0de3b155c6f29e3ae26 Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone Date: Sun, 2 Feb 2014 15:55:09 -0500 Subject: cffi callbacks are easy --- doc/internals.rst | 36 ++++-------------------------------- 1 file changed, 4 insertions(+), 32 deletions(-) diff --git a/doc/internals.rst b/doc/internals.rst index 839c446..a2a4cdc 100644 --- a/doc/internals.rst +++ b/doc/internals.rst @@ -27,38 +27,10 @@ For more information about this, see section :ref:`openssl-ssl`. Callbacks --------- -There are a number of problems with callbacks. First of all, OpenSSL is written -as a C library, it's not meant to have Python callbacks, so a way around that -is needed. Another problem is thread support. A lot of the OpenSSL I/O -functions can block if the socket is in blocking mode, and then you want other -Python threads to be able to do other things. The real trouble is if you've -released the global CPython interpreter lock to do a potentially blocking -operation, and the operation calls a callback. Then we must take the GIL back, -since calling Python APIs without holding it is not allowed. - -There are two solutions to the first problem, both of which are necessary. The -first solution to use is if the C callback allows ''userdata'' to be passed to -it (an arbitrary pointer normally). This is great! We can set our Python -function object as the real userdata and emulate userdata for the Python -function in another way. The other solution can be used if an object with an -''app_data'' system always is passed to the callback. For example, the SSL -object in OpenSSL has app_data functions and in e.g. the verification -callbacks, you can retrieve the related SSL object. What we do is to set our -wrapper :py:class:`.Connection` object as app_data for the SSL object, and we can -easily find the Python callback. - -The other problem is solved using thread local variables. Whenever the GIL is -released before calling into an OpenSSL API, the PyThreadState pointer returned -by :c:func:`PyEval_SaveState` is stored in a global thread local variable -(using Python's own TLS API, :c:func:`PyThread_set_key_value`). When it is -necessary to re-acquire the GIL, either after the OpenSSL API returns or in a C -callback invoked by that OpenSSL API, the value of the thread local variable is -retrieved (:c:func:`PyThread_get_key_value`) and used to re-acquire the GIL. -This allows Python threads to execute while OpenSSL APIs are running and allows -use of any particular pyOpenSSL object from any Python thread, since there is -no per-thread state associated with any of these objects and since OpenSSL is -threadsafe (as long as properly initialized, as pyOpenSSL initializes it). - +Callbacks were more of a problem when pyOpenSSL was written in C. +Having switched to being written in Python using cffi, callbacks are now straightforward. +The problems that originally existed no longer do +(if you are interested in the details you can find descriptions of those problems in the version control history for this document). .. _socket-methods: -- cgit v1.2.1 From eeb4bb12feb95985e691ea0967ef9e90fba80ead Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone Date: Sun, 2 Feb 2014 15:57:55 -0500 Subject: There is a top-level INSTALL document now. Let's not be redundant. --- doc/index.rst | 1 - doc/install.rst | 69 --------------------------------------------------------- 2 files changed, 70 deletions(-) delete mode 100644 doc/install.rst diff --git a/doc/index.rst b/doc/index.rst index a63df87..e4a5a23 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -14,7 +14,6 @@ Contents: :maxdepth: 3 introduction - install api internals diff --git a/doc/install.rst b/doc/install.rst deleted file mode 100644 index f525726..0000000 --- a/doc/install.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _building: - -Building and Installing -======================= - -These instructions can also be found in the file ``INSTALL``. - -I have tested this on Debian Linux systems (woody and sid), Solaris 2.6 and -2.7. Others have successfully compiled it on Windows and NT. - -.. _building-unix: - -Building the Module on a Unix System ------------------------------------- - -pyOpenSSL uses distutils, so there really shouldn't be any problems. To build -the library:: - - python setup.py build - -If your OpenSSL header files aren't in ``/usr/include``, you may need to supply -the ``-I`` flag to let the setup script know where to look. The same goes for -the libraries of course, use the ``-L`` flag. Note that ``build`` won't accept -these flags, so you have to run first ``build_ext`` and then ``build``! -Example:: - - python setup.py build_ext -I/usr/local/ssl/include -L/usr/local/ssl/lib - python setup.py build - -Now you should have a directory called ``OpenSSL`` that contains e.g. -``SSL.so`` and ``__init__.py`` somewhere in the build dicrectory, -so just:: - - python setup.py install - -If you, for some arcane reason, don't want the module to appear in the -``site-packages`` directory, use the ``--prefix`` option. - -You can, of course, do:: - - python setup.py --help - -to find out more about how to use the script. - -.. _building-windows: - -Building the Module on a Windows System ---------------------------------------- - -Big thanks to Itamar Shtull-Trauring and Oleg Orlov for their help with -Windows build instructions. Same as for Unix systems, we have to separate -the ``build_ext`` and the ``build``. - -Building the library:: - - setup.py build_ext -I ...\openssl\inc32 -L ...\openssl\out32dll - setup.py build - -Where ``...\openssl`` is of course the location of your OpenSSL installation. - -Installation is the same as for Unix systems:: - - setup.py install - -And similarily, you can do:: - - setup.py --help - -to get more information. -- cgit v1.2.1 From 269184974da23fe17c6cc911cb1aac7171ef66f4 Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone Date: Sun, 2 Feb 2014 15:59:19 -0500 Subject: github! python.org! --- README | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README b/README index afe4ddc..1b2a093 100644 --- a/README +++ b/README @@ -3,3 +3,7 @@ pyOpenSSL - A Python wrapper around the OpenSSL library ------------------------------------------------------------------------------ See the file INSTALL for installation instructions. + +See http://github.com/pyca/pyopenssl for development. + +See https://mail.python.org/mailman/listinfo/pyopenssl-users for the discussion mailing list. -- cgit v1.2.1