suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Chez Scheme: update docs on ftype pointer types in foreign-procedure

Browse Source 
Now specifies that the ftype pointer parameter types - `(* ftype)` and
`(& ftype)` - actually require an `ftype-name` (i.e., the syntax
requires an identifier in that position). This clarifies the problem
encountered in issue cisco/ChezScheme#557 (although further examples
would be helpful, of course).
This commit is contained in:
Jamie Taylor 2021-04-01 20:33:55 -04:00 committed by Matthew Flatt
parent e97ae6522c
commit b090edbe9d
1 changed files with 17 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
racket/src/ChezScheme/csug/foreign.stex
View File

@ -600,26 +600,27 @@ the endianness of the target machine.
For example, \scheme{wstring} is equivalent to \scheme{utf-16le} For example, \scheme{wstring} is equivalent to \scheme{utf-16le}
under Windows running on Intel hardware. under Windows running on Intel hardware.
\foreigntype{\scheme{(* \var{ftype})}} \foreigntype{\scheme{(* \var{ftype-name})}}
\index{ftype}This type allows a pointer to a foreign \index{ftype}This type allows a pointer to a foreign
type (ftype) to be passed. type (ftype) to be passed.
The argument must be an ftype pointer of type \var{ftype}, The argument must be an ftype pointer of the type identified by
\var{ftype-name},
and the actual argument is the address encapsulated in the and the actual argument is the address encapsulated in the
ftype pointer. ftype pointer.
See Section~\ref{SECTFOREIGNDATA} for a description of See Section~\ref{SECTFOREIGNDATA} for a description of
foreign types. foreign types.
\foreigntype{\scheme{(& \var{ftype})}} \foreigntype{\scheme{(& \var{ftype-name})}}
\index{ftype}This type allows a foreign \index{ftype}This type allows a foreign
type (ftype) to be passed as a value, but represented type (ftype) to be passed as a value, but represented
on the Scheme side as a pointer to the foreign-type data. on the Scheme side as a pointer to the foreign-type data.
That is, a \scheme{(& \var{ftype})} argument is represented on That is, a \scheme{(& \var{ftype-name})} argument is represented on
the Scheme side the same as a \scheme{(* \var{ftype})} argument, the Scheme side the same as a \scheme{(* \var{ftype-name})} argument,
but a \scheme{(& \var{ftype})} argument is passed to the foreign procedure as the but a \scheme{(& \var{ftype-name})} argument is passed to the foreign procedure as the
content at the foreign pointer's address instead of as the content at the foreign pointer's address instead of as the
address. For example, if \var{ftype} is a \scheme{struct} type, address. For example, if \var{ftype-name} identifies a \scheme{struct} type,
then \scheme{(& \var{ftype})} passes a struct argument instead of then \scheme{(& \var{ftype-name})} passes a struct argument instead of
a struct-pointer argument. The \var{ftype} cannot refer to an array type. a struct-pointer argument. The \var{ftype-name} cannot refer to an array type.
\medskip\noindent \medskip\noindent
The result types are similar to the parameter types with the addition of a The result types are similar to the parameter types with the addition of a
@ -872,22 +873,22 @@ the endianness of the target machine.
For example, \scheme{wstring} is equivalent to \scheme{utf-16le} For example, \scheme{wstring} is equivalent to \scheme{utf-16le}
under Windows running on Intel hardware. under Windows running on Intel hardware.
\foreigntype{\scheme{(* \var{ftype})}} \foreigntype{\scheme{(* \var{ftype-name})}}
\index{ftype}The result is interpreted as the address of a foreign object \index{ftype}The result is interpreted as the address of a foreign object
whose structure is described by \var{ftype}, and a freshly allocated whose structure is described by the ftype identified by \var{ftype-name}, and a freshly allocated
ftype pointer encapsulating the address is returned. ftype pointer encapsulating the address is returned.
See Section~\ref{SECTFOREIGNDATA} for a description of See Section~\ref{SECTFOREIGNDATA} for a description of
foreign types. foreign types.
\foreigntype{\scheme{(& \var{ftype})}} \foreigntype{\scheme{(& \var{ftype-name})}}
\index{ftype}The result is interpreted as a foreign object \index{ftype}The result is interpreted as a foreign object
whose structure is described by \var{ftype}, where the foreign whose structure is described by the ftype identified by \var{ftype-name}, where the foreign
procedure returns a \var{ftype} result, but the caller procedure returns a \var{ftype-name} result, but the caller
must provide an extra \scheme{(* \var{ftype})} argument before must provide an extra \scheme{(* \var{ftype-name})} argument before
all other arguments to receive the result. An unspecified Scheme object all other arguments to receive the result. An unspecified Scheme object
is returned when the foreign procedure is called, since the result is returned when the foreign procedure is called, since the result
is instead written into storage referenced by the extra argument. is instead written into storage referenced by the extra argument.
The \var{ftype} cannot refer to an array type. The \var{ftype-name} cannot refer to an array type.
\medskip\noindent \medskip\noindent
Consider a C identity procedure: Consider a C identity procedure: