Commit b0529043 authored by Armin Rigo's avatar Armin Rigo
Browse files

Drop the ".. versionchanged" and ".. versionadded", which was not very

essential and seems not to work on bitbucket's wiki
parent 2001880ed1c7
......@@ -180,8 +180,6 @@ can assume to exist are the standard types:
.. _`common Windows types`: http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751%28v=vs.85%29.aspx
.. "versionadded:: 0.9.3": intmax_t etc.
The declarations can also contain "``...``" at various places; these are
placeholders that will be completed by the compiler. More information
about it below in `Letting the C compiler fill the gaps`_.
......@@ -198,17 +196,16 @@ Multiple calls to ``ffi.cdef()`` are possible. Beware that it can be
slow to call ``ffi.cdef()`` a lot of times, a consideration that is
important mainly in in-line mode.
.. versionadded:: 0.8.2
The ``ffi.cdef()`` call takes an optional
argument ``packed``: if True, then all structs declared within
this cdef are "packed". If you need both packed and non-packed
structs, use several cdefs in sequence.) This
has a meaning similar to ``__attribute__((packed))`` in GCC. It
specifies that all structure fields should have an alignment of one
byte. (Note that the packed attribute has no effect on bit fields so
far, which mean that they may be packed differently than on GCC.
Also, this has no effect on structs declared with ``"...;"``---next
section.)
The ``ffi.cdef()`` call takes an optional
argument ``packed``: if True, then all structs declared within
this cdef are "packed". If you need both packed and non-packed
structs, use several cdefs in sequence.) This
has a meaning similar to ``__attribute__((packed))`` in GCC. It
specifies that all structure fields should have an alignment of one
byte. (Note that the packed attribute has no effect on bit fields so
far, which mean that they may be packed differently than on GCC.
Also, this has no effect on structs declared with ``"...;"``---next
section.)
.. _`ffi.set_unicode()`:
......@@ -233,8 +230,6 @@ strings as arguments instead of not byte strings. (Before cffi version 0.9,
``TCHAR`` and friends where hard-coded as unicode, but ``UNICODE`` was,
inconsistently, not defined by default.)
.. "versionadded:: 0.9" --- inlined in the previous paragraph
ffi.dlopen(): loading libraries in ABI mode
-------------------------------------------
......@@ -565,7 +560,7 @@ Known missing features that are GCC or MSVC extensions:
* Function pointers with non-default calling conventions (e.g. on
Windows, "stdcall").
Note that since version 0.8, declarations like ``int field[];`` in
Note that declarations like ``int field[];`` in
structures are interpreted as variable-length structures. Declarations
like ``int field[...];`` on the other hand are arrays whose length is
going to be completed by the compiler. You can use ``int field[];``
......@@ -575,10 +570,10 @@ believes it cannot ask the C compiler for the length of the array, you
get reduced safety checks: for example, you risk overwriting the
following fields by passing too many array items in the constructor.
.. versionadded:: 1.2
Thread-local variables (``__thread``) can be accessed, as well as
variables defined as dynamic macros (``#define myvar (*fetchme())``).
Before version 1.2, you need to write getter/setter functions.
*New in version 1.2:*
Thread-local variables (``__thread``) can be accessed, as well as
variables defined as dynamic macros (``#define myvar (*fetchme())``).
Before version 1.2, you need to write getter/setter functions.
Debugging dlopen'ed C libraries
......
......@@ -41,13 +41,16 @@ too, as described later.
Example::
>>> ffi.new("char *")
<cdata 'char *' owning 1 bytes>
>>> ffi.new("int *")
<cdata 'int *' owning 4 bytes>
>>> ffi.new("int[10]")
<cdata 'int[10]' owning 40 bytes>
>>> ffi.new("char *") # allocates only one char---not a C string!
<cdata 'char *' owning 1 bytes>
>>> ffi.new("char[]", "foobar") # this allocates a C string, ending in \0
<cdata 'char[]' owning 7 bytes>
Unlike C, the returned pointer object has *ownership* on the allocated
memory: when this exact object is garbage-collected, then the memory is
freed. If, at the level of C, you store a pointer to the memory
......@@ -514,34 +517,32 @@ directly as ``ffi.callback("int(int, int)", myfunc)``. This is
discouraged: using this a style, we are more likely to forget the
callback object too early, when it is still in use.
.. versionadded:: 1.2
If you want to be sure to catch all exceptions, use
``ffi.callback(..., onerror=func)``. If an exception occurs and
``onerror`` is specified, then ``onerror(exception, exc_value,
traceback)`` is called. This is useful in some situations where
you cannot simply write ``try: except:`` in the main callback
function, because it might not catch exceptions raised by signal
handlers: if a signal occurs while in C, it will be called after
entering the main callback function but before executing the
``try:``.
If ``onerror`` returns normally, then it is assumed that it handled
the exception on its own and nothing is printed to stderr. If
``onerror`` raises, then both tracebacks are printed. Finally,
``onerror`` can itself provide the result value of the callback in
C, but doesn't have to: if it simply returns None---or if
``onerror`` itself fails---then the value of ``error`` will be
used, if any.
Note the following hack: in ``onerror``, you can access the original
callback arguments as follows. First check if ``traceback`` is not
None (it is None e.g. if the whole function ran successfully but
there was an error converting the value returned: this occurs after
the call). If ``traceback`` is not None, then ``traceback.tb_frame``
is the frame of the outermost function, i.e. directly the one invoked
by the callback handler. So you can get the value of ``argname`` in
that frame by reading ``traceback.tb_frame.f_locals['argname']``.
*New in version 1.2:* If you want to be sure to catch all exceptions, use
``ffi.callback(..., onerror=func)``. If an exception occurs and
``onerror`` is specified, then ``onerror(exception, exc_value,
traceback)`` is called. This is useful in some situations where
you cannot simply write ``try: except:`` in the main callback
function, because it might not catch exceptions raised by signal
handlers: if a signal occurs while in C, it will be called after
entering the main callback function but before executing the
``try:``.
If ``onerror`` returns normally, then it is assumed that it handled
the exception on its own and nothing is printed to stderr. If
``onerror`` raises, then both tracebacks are printed. Finally,
``onerror`` can itself provide the result value of the callback in
C, but doesn't have to: if it simply returns None---or if
``onerror`` itself fails---then the value of ``error`` will be
used, if any.
Note the following hack: in ``onerror``, you can access the original
callback arguments as follows. First check if ``traceback`` is not
None (it is None e.g. if the whole function ran successfully but
there was an error converting the value returned: this occurs after
the call). If ``traceback`` is not None, then ``traceback.tb_frame``
is the frame of the outermost function, i.e. directly the one invoked
by the callback handler. So you can get the value of ``argname`` in
that frame by reading ``traceback.tb_frame.f_locals['argname']``.
FFI Interface
......@@ -580,12 +581,10 @@ also save and restore the ``GetLastError()`` value across function
calls. This function returns this error code as a tuple ``(code,
message)``, adding a readable message like Python does when raising
WindowsError. If the argument ``code`` is given, format that code into
a message instead of using ``GetLastError()``. *New in version 0.8.*
a message instead of using ``GetLastError()``.
(Note that it is also possible to declare and call the ``GetLastError()``
function as usual.)
.. "versionadded:: 0.8" --- inlined in the previous paragraph
**ffi.string(cdata, [maxlen])**: return a Python string (or unicode
string) from the 'cdata'.
......@@ -637,14 +636,10 @@ The buffer object returned by ``ffi.buffer(cdata)`` keeps alive the
``cdata`` object: if it was originally an owning cdata, then its
owned memory will not be freed as long as the buffer is alive.
.. versionchanged:: 0.8.2
Before version 0.8.2, ``bytes(buf)`` was supported in Python 3 to get
the content of the buffer, but on Python 2 it would return the repr
``<_cffi_backend.buffer object>``. This has been fixed. But you
should avoid using ``str(buf)``: it gives inconsistent results
between Python 2 and Python 3 (this is similar to how ``str()``
gives inconsistent results on regular byte strings). Use ``buf[:]``
instead.
Python 2/3 compatibility note: you should avoid using ``str(buf)``,
because it gives inconsistent results between Python 2 and Python 3.
This is similar to how ``str()`` gives inconsistent results on regular
byte strings). Use ``buf[:]`` instead.
**ffi.from_buffer(python_buffer)**: return a ``<cdata 'char[]'>`` that
points to the data of the given Python object, which must support the
......@@ -659,8 +654,6 @@ new memoryview API. The original object is kept alive (and, in case
of memoryview, locked) as long as the cdata object returned by
``ffi.from_buffer()`` is alive. *New in version 0.9.*
.. "versionadded:: 0.9" --- inlined in the previous paragraph
**ffi.typeof("C type" or cdata object)**: return an object of type
``<ctype>`` corresponding to the parsed string, or to the C type of the
......@@ -711,11 +704,11 @@ the argument. Corresponds to the ``__alignof__`` operator in GCC.
offset within the struct of the given field. Corresponds to ``offsetof()``
in C.
.. versionchanged:: 0.9
You can give several field names in case of nested structures. You
can also give numeric values which correspond to array items, in case
of a pointer or array type. For example, ``ffi.offsetof("int[5]", 2)``
is equal to the size of two integers, as is ``ffi.offsetof("int *", 2)``.
*New in version 0.9:*
You can give several field names in case of nested structures. You
can also give numeric values which correspond to array items, in case
of a pointer or array type. For example, ``ffi.offsetof("int[5]", 2)``
is equal to the size of two integers, as is ``ffi.offsetof("int *", 2)``.
**ffi.getctype("C type" or <ctype>, extra="")**: return the string
......@@ -828,8 +821,6 @@ returns a new allocator. An "allocator" is a callable that behaves like
``ffi.new()`` but uses the provided low-level ``alloc`` and ``free``
functions. *New in version 1.2.*
.. "versionadded:: 1.2" --- inlined in the previous paragraph
``alloc()`` is invoked with the size as sole argument. If it returns
NULL, a MemoryError is raised. Later, if ``free`` is not None, it will
be called with the result of ``alloc()`` as argument. Both can be either
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment