From 6e0a38238c45d74a1ce3e66619f180af47b5ce4f Mon Sep 17 00:00:00 2001 From: Robert Bradshaw Date: Wed, 11 Nov 2009 21:46:46 -0800 Subject: [PATCH] Consolidate typing sections. --- src/quickstart/cdef_functions.rst | 41 ----------------- src/quickstart/cythonize.rst | 74 ++++++++++++++++++++++++++++++- src/quickstart/datatypes.rst | 24 ---------- src/quickstart/overview.rst | 2 +- 4 files changed, 73 insertions(+), 68 deletions(-) delete mode 100644 src/quickstart/cdef_functions.rst delete mode 100644 src/quickstart/datatypes.rst diff --git a/src/quickstart/cdef_functions.rst b/src/quickstart/cdef_functions.rst deleted file mode 100644 index 41b0bea3..00000000 --- a/src/quickstart/cdef_functions.rst +++ /dev/null @@ -1,41 +0,0 @@ -cdef functions -============== - -Python function calls can be expensive--in Cython doubly so because -one might need to convert to and from Python objects to do the call. -In our example above, the argument is assumed to be a C double both inside f() -and in the call to it, yet a Python ``float`` object must be constructed around the -argument in order to pass it. - -Therefore Cython provides a syntax for declaring a C-style function, -the cdef keyword:: - - cdef double f(double) except *: - return sin(x**2) - -Some form of except-modifier should usually be added, otherwise Cython -will not be able to propagate exceptions raised in the function (or a -function it calls). Above ``except *`` is used which is always -safe. An except clause can be left out if the function returns a Python -object or if it is guaranteed that an exception will not be raised -within the function call. - -A side-effect of cdef is that the function is no longer available from -Python-space, as Python wouldn't know how to call it. Using the -``cpdef`` keyword instead of cdef, a Python wrapper is also created, -so that the function is available both from Cython (fast, passing -typed values directly) and from Python (wrapping values in Python -objects). - -Note also that it is no longer possible to change ``f`` at runtime. - -Speedup: 45 times over pure Python. - -.. figure:: htmlreport.png - - Using the ``-a`` switch to the ``cython`` command line program (or - following a link from the Sage notebook) results in an HTML report - of Cython code interleaved with the generated C code. Lines are - colored according to the level of "typedness" -- white lines - translates to pure C without any Python API calls. This report - is invaluable when optimizing a function for speed. diff --git a/src/quickstart/cythonize.rst b/src/quickstart/cythonize.rst index f77abddf..efc708b6 100644 --- a/src/quickstart/cythonize.rst +++ b/src/quickstart/cythonize.rst @@ -1,5 +1,33 @@ -Faster code by adding types -=========================== +Faster code via static typing +============================= + +Cython is a Python compiler. This means that it can compile normal +Python code without changes (with a few obvious exceptions of some as-yet +unsupported language features). However, for performance critical +code, it is often helpful to add static type declarations, as they +will allow Cython to step out of the dynamic nature of the Python code +and generate simpler and faster C code - sometimes faster by orders of +magnitude. + +It must be noted, however, that type declarations can make the source +code more verbose and thus less readable. It is therefore discouraged +to use them without good reason, such as where benchmarks prove +that they really make the code substantially faster in a performance +critical section. Typically a few types in the right spots go a long way. + +All C types are available for type declarations: integer and floating +point types, complex numbers, structs, unions and pointer types. +Cython can automatically and correctly convert between the types on +assignment. This also includes Python's arbitrary size integer types, +where value overflows on conversion to a C type will raise a Python +``OverflowError`` at runtime. The generated C code will handle the +platform dependent sizes of C types correctly and safely in this case. + +Types are declared via the cdef keyword. + + +Typing Variables +---------------- Consider the following pure Python code:: @@ -42,3 +70,45 @@ difference, but in this case it is not much extra work to be consistent and type the entire function. This results in a 24 times speedup over the pure Python version. + +Typing Functions +---------------- + +Python function calls can be expensive--in Cython doubly so because +one might need to convert to and from Python objects to do the call. +In our example above, the argument is assumed to be a C double both inside f() +and in the call to it, yet a Python ``float`` object must be constructed around the +argument in order to pass it. + +Therefore Cython provides a syntax for declaring a C-style function, +the cdef keyword:: + + cdef double f(double) except *: + return sin(x**2) + +Some form of except-modifier should usually be added, otherwise Cython +will not be able to propagate exceptions raised in the function (or a +function it calls). Above ``except *`` is used which is always +safe. An except clause can be left out if the function returns a Python +object or if it is guaranteed that an exception will not be raised +within the function call. + +A side-effect of cdef is that the function is no longer available from +Python-space, as Python wouldn't know how to call it. Using the +``cpdef`` keyword instead of cdef, a Python wrapper is also created, +so that the function is available both from Cython (fast, passing +typed values directly) and from Python (wrapping values in Python +objects). + +Note also that it is no longer possible to change ``f`` at runtime. + +Speedup: 45 times over pure Python. + +.. figure:: htmlreport.png + + Using the ``-a`` switch to the ``cython`` command line program (or + following a link from the Sage notebook) results in an HTML report + of Cython code interleaved with the generated C code. Lines are + colored according to the level of "typedness" -- white lines + translates to pure C without any Python API calls. This report + is invaluable when optimizing a function for speed. diff --git a/src/quickstart/datatypes.rst b/src/quickstart/datatypes.rst deleted file mode 100644 index b94206a3..00000000 --- a/src/quickstart/datatypes.rst +++ /dev/null @@ -1,24 +0,0 @@ -Data types in Cython -==================== - -Cython is a Python compiler. This means that it can compile normal -Python code without changes (with a few obvious exceptions of some as-yet -unsupported language features). However, for performance critical -code, it is often helpful to add static type declarations, as they -will allow Cython to step out of the dynamic nature of the Python code -and generate simpler and faster C code - sometimes faster by orders of -magnitude. - -It must be noted, however, that type declarations can make the source -code more verbose and thus less readable. It is therefore discouraged -to use them without good reason, such as where benchmarks prove -that they really make the code substantially faster in a performance -critical section. Typically a few types in the right spots go a long way. - -All C types are available for type declarations: integer and floating -point types, complex numbers, structs, unions and pointer types. -Cython can automatically and correctly convert between the types on -assignment. This also includes Python's arbitrary size integer types, -where value overflows on conversion to a C type will raise a Python -``OverflowError`` at runtime. The generated C code will handle the -platform dependent sizes of C types correctly and safely in this case. diff --git a/src/quickstart/overview.rst b/src/quickstart/overview.rst index c0807759..f3566882 100644 --- a/src/quickstart/overview.rst +++ b/src/quickstart/overview.rst @@ -17,7 +17,7 @@ CPython, as it is written in C. Other major implementations use Java many external libraries that interface through the C language. It has, however, remained non trivial to write the necessary glue code in C, especially for programmers who are more fluent in a high-level -language like Python than in a do-it-yourself language like C. +language like Python than in a close-to-the-metal language like C. Originally based on the well-known Pyrex [Pyrex]_, the Cython project has approached this problem by means of a source code compiler that -- 2.26.2