diff options
| author | Kaz Kylheku <kaz@kylheku.com> | 2017-12-15 06:29:44 -0800 |
|---|---|---|
| committer | Kaz Kylheku <kaz@kylheku.com> | 2017-12-15 06:29:44 -0800 |
| commit | b745923e691192ebede5ca63aaa1ecfdcf4d7a31 (patch) | |
| tree | 54c7803ba9312914452823a6c182c49e133f3d16 /txr.1 | |
| parent | 10600bbfbbc0a427369c8ea02eca9ac00f6019ac (diff) | |
| download | txr-b745923e691192ebede5ca63aaa1ecfdcf4d7a31.tar.gz txr-b745923e691192ebede5ca63aaa1ecfdcf4d7a31.tar.bz2 txr-b745923e691192ebede5ca63aaa1ecfdcf4d7a31.zip | |
doc: ffi: clarify in and out nuances.
* txr.1: Fix wrong wording about the by-value nuance of the
in operation. What is specifically doesn't do, in contrast
to the by-pointer nuance, is propagate the foreign
representation back to Lisp. Not Lisp to foreign, which is
opposite to the in operation. Also clarifying some wording
in the description of the out operation: that the by-value
nuance doesn't reconstruct from the updated Lisp structure,
to help the reader keep in mind the data direction.
Diffstat (limited to 'txr.1')
| -rw-r--r-- | txr.1 | 13 |
1 files changed, 7 insertions, 6 deletions
@@ -56519,10 +56519,10 @@ The in operation has two nuances: the by-value nuance and the by-pointer nuance. Data passed into a function by value such as function arguments or via .code ptr-in -are subject to the by-value nuance. Updates to these objects themselves -do not propagate from the Lisp representation to the external representation; -however, those objects may contain pointers requiring the by-pointer -nuance of the in operation to be invoked. +are subject to the by-value nuance. Updates to the foreign representation +of these objects does not propagate back to the Lisp representation to the +external representation; however, those objects may contain pointers requiring +the by-pointer nuance of the in operation of those pointers to be invoked. .NP* The \fIget\fP operation @@ -56548,8 +56548,9 @@ operation. This operation is like the reverse of the in operation. Like that operation, it has a by-value and by-pointer nuance. For instance, if a callback receives a structure by value, upon return, there -is no use in reconstructing a new version of the structure; the caller will not -receive the change. However, if the structure contains pointers to data that +is no use in reconstructing a new version of the structure from the updated +Lisp structure; the caller will not receive the change. However, if the +structure contains pointers to data that was updated, by the callback, those changes must materialize. This is achieved by triggering the by-value nuance of the structure type's out operation, which will recursively invoke the out operation of embedded pointers, which will |