Armin Rigo avatar Armin Rigo committed 8e0915e

Reword this paragraph

Comments (0)

Files changed (1)

doc/source/index.rst

 ``void *`` that contains an opaque reference to ``python_object``.  You
 can pass it around to C functions or store it into C structures.  Later,
 you can use ``ffi.from_handle(p)`` to retrive the original
-``python_object`` from a value with the same ``void *`` pointer.  The
-cdata object returned by ``new_handle()`` must be kept alive (and, in
-turn, it keeps alive the ``python_object`` too).  In other words, the
-cdata object returned by ``new_handle()`` has *ownership*, in the same
-sense as ``ffi.new()`` or ``ffi.gc()``: the association ``void * ->
-python_object`` is only valid as long as *this* exact cdata returned by
-``new_handle()`` is alive.  *Calling ffi.from_handle(p) is invalid and
-will likely crash if the cdata object returned by new_handle() is not
-kept alive!* *New in version 0.7.*
+``python_object`` from a value with the same ``void *`` pointer.
+*New in version 0.7.*
+
+Note that ``from_handle()`` conceptually works like this: it searches in
+the list of cdata objects made by ``new_handle()`` the one which has got
+the same ``void *`` value, and then it fetches in that cdata object the
+corresponding Python object.  It will crash if the cdata object returned
+by ``new_handle()`` is not alive any more!  (Obviously, the real
+implementation is more efficient than suggested here.)  In other words,
+the result of ``new_handle()`` has *ownership* (similarly to
+``ffi.new()`` or ``ffi.gc()``) in the sense that the association ``void
+* -> python_object`` is only valid as long as *this* exact cdata
+returned by ``new_handle()`` is alive.  You must keep it alive (but the
+Python object itself is kept alive by it automatically).
 
 .. "versionadded:: 0.7" --- inlined in the previous paragraph
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.