doc corrections and completions
This commit is contained in:
Matthew Flatt
parent
b26bf5e225
commit
1a5e662433
|
|
@ -2,7 +2,8 @@
|
|||
@(require scribble/manual
|
||||
scribble/bnf
|
||||
(for-label openssl
|
||||
scheme))
|
||||
scheme
|
||||
openssl/sha1))
|
||||
|
||||
@title{@bold{OpenSSL}}
|
||||
|
||||
|
|
@ -339,6 +340,35 @@ collection for testing purposes where the peer identifies itself using
|
|||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{SHA-1 Hashing}
|
||||
|
||||
@defmodule[openssl/sha1]{The @schememodname[openssl/sha1] library
|
||||
provides a Racket wrapper for the OpenSSL library's SHA-1 hashing
|
||||
functions.}
|
||||
|
||||
@defproc[(sha1 [in input-port]) string?]{
|
||||
|
||||
Returns a 40-character string that represents the SHA-1 hash (in
|
||||
hexadecimal notation) of the content from @scheme[in], consuming all
|
||||
of the input from @scheme[in] until an end-of-file.
|
||||
|
||||
The @scheme[sha1] function composes @scheme[bytes->hex-string] with
|
||||
@racket[sha1-bytes].}
|
||||
|
||||
@defproc[(sha1-bytes [in input-port]) bytes?]{
|
||||
|
||||
Returns a 20-byte byte string that represents the SHA-1 hash of the
|
||||
content from @scheme[in], consuming all of the input from @scheme[in]
|
||||
until an end-of-file.}
|
||||
|
||||
@defproc[(bytes->hex-string [bstr bytes?]) string?]{
|
||||
|
||||
Converts the given byte string to a string representation, where each
|
||||
byte in @scheme[bstr] is converted to its two-digit hexadecimal
|
||||
representation in the resulting string.}
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{Implementation Notes}
|
||||
|
||||
For Windows, @schememodname[openssl] relies on @filepath{libeay32.dll}
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
@defproc[(end-atomic) void?]
|
||||
)]{
|
||||
|
||||
Disables and enables context switches at the level of Scheme
|
||||
Disables and enables context switches at the level of Racket
|
||||
threads. Calls to @scheme[start-atomic] and @scheme[end-atomic] can be
|
||||
nested.
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ operations manage tags to distinguish pointer types.
|
|||
ctype])]{
|
||||
|
||||
Construct a kind of a pointer that gets a specific tag when converted
|
||||
to Scheme, and accept only such tagged pointers when going to C. An
|
||||
to Racket, and accept only such tagged pointers when going to C. An
|
||||
optional @scheme[ptr-type] can be given to be used as the base pointer
|
||||
type, instead of @scheme[_pointer].
|
||||
|
||||
|
|
@ -37,7 +37,7 @@ an interface can hide its value from users (e.g., not provide the
|
|||
|
||||
@scheme[_cpointer/null] is similar to @scheme[_cpointer] except that
|
||||
it tolerates @cpp{NULL} pointers both going to C and back. Note that
|
||||
@cpp{NULL} pointers are represented as @scheme[#f] in Scheme, so they
|
||||
@cpp{NULL} pointers are represented as @scheme[#f] in Racket, so they
|
||||
are not tagged.}
|
||||
|
||||
|
||||
|
|
@ -63,7 +63,7 @@ obtain a tag. The tag is the string form of @schemevarfont{id}.}
|
|||
|
||||
These two functions treat pointer tags as lists of tags. As described
|
||||
in @secref["foreign:pointer-funcs"], a pointer tag does not have any
|
||||
role, except for Scheme code that uses it to distinguish pointers;
|
||||
role, except for Racket code that uses it to distinguish pointers;
|
||||
these functions treat the tag value as a list of tags, which makes it
|
||||
possible to construct pointer types that can be treated as other
|
||||
pointer types, mainly for implementing inheritance via upcasts (when a
|
||||
|
|
|
|||
|
|
@ -17,9 +17,9 @@ pointer to a memory block).
|
|||
|
||||
Like @scheme[_bytes], @scheme[_cvector] can be used as a simple type
|
||||
that corresponds to a pointer that is managed as a safe C vector on
|
||||
the Scheme side. The longer form behaves similarly to the
|
||||
the Racket side. The longer form behaves similarly to the
|
||||
@scheme[_list] and @scheme[_vector] custom types, except that
|
||||
@scheme[_cvector] is more efficient; no Scheme list or vector is
|
||||
@scheme[_cvector] is more efficient; no Racket list or vector is
|
||||
needed.}
|
||||
|
||||
@defproc[(make-cvector [type ctype?][length exact-nonnegative-integer?]) cvector?]{
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ Looks for the given object name @scheme[objname] in the given
|
|||
@scheme[lib] library. If @scheme[lib] is not a foreign-library value
|
||||
produced by @scheme[ffi-lib], it is converted to one by calling
|
||||
@scheme[ffi-lib]. If @scheme[objname] is found in @scheme[lib], it is
|
||||
converted to Scheme using the given @scheme[type]. Types are described
|
||||
converted to Racket using the given @scheme[type]. Types are described
|
||||
in @secref["types"]; in particular the @scheme[get-ffi-obj] procedure
|
||||
is most often used with function types created with @scheme[_fun].
|
||||
|
||||
|
|
@ -101,7 +101,7 @@ Looks for @scheme[objname] in @scheme[lib] similarly to
|
|||
@scheme[get-ffi-obj], but then it stores the given @scheme[new] value
|
||||
into the library, converting it to a C value. This can be used for
|
||||
setting library customization variables that are part of its
|
||||
interface, including Scheme callbacks.}
|
||||
interface, including Racket callbacks.}
|
||||
|
||||
|
||||
@defproc[(make-c-parameter [objname (or/c string? bytes? symbol?)]
|
||||
|
|
@ -114,7 +114,7 @@ Returns a parameter-like procedure that can either references the
|
|||
specified foreign value, or set it. The arguments are handled as in
|
||||
@scheme[get-ffi-obj].
|
||||
|
||||
A parameter-like function is useful in case Scheme code and library
|
||||
A parameter-like function is useful in case Racket code and library
|
||||
code interact through a library value. Although
|
||||
@scheme[make-c-parameter] can be used with any time, it is not
|
||||
recommended to use this for foreign functions, since each reference
|
||||
|
|
@ -124,9 +124,9 @@ actual call.}
|
|||
|
||||
@defform[(define-c id lib-expr type-expr)]{
|
||||
|
||||
Defines @scheme[id] behave like a Scheme binding, but @scheme[id] is
|
||||
Defines @scheme[id] behave like a Racket binding, but @scheme[id] is
|
||||
actually redirected through a parameter-like procedure created by
|
||||
@scheme[make-c-parameter]. The @scheme[id] is used both for the Scheme
|
||||
@scheme[make-c-parameter]. The @scheme[id] is used both for the Racket
|
||||
binding and for the foreign object's name.}
|
||||
|
||||
@defproc[(ffi-obj-ref [objname (or/c string? bytes? symbol?)]
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ for cases where the regular expression begins with a @litchar{^} or
|
|||
ends with a @litchar{$}, in which case @scheme[regexp-replace] is
|
||||
used.
|
||||
|
||||
For example, the following makes it convenient to define Scheme
|
||||
For example, the following makes it convenient to define Racket
|
||||
bindings such as @scheme[foo-bar] for foreign names like
|
||||
@scheme[MyLib_foo_bar]:
|
||||
|
||||
|
|
@ -48,7 +48,7 @@ according to the given @scheme[type].}
|
|||
|
||||
@defproc[(vector->cblock [vec vector?][type type?]) any]{
|
||||
|
||||
Like @scheme[list->cblock], but for Scheme vectors.}
|
||||
Like @scheme[list->cblock], but for Racket vectors.}
|
||||
|
||||
|
||||
@defproc[(vector->cpointer [vec vector?]) cpointer?]{
|
||||
|
|
@ -93,7 +93,7 @@ The conversion is equivalent to
|
|||
list?]{
|
||||
|
||||
Converts C @scheme[cblock], which is a vector of @scheme[type]s, to a
|
||||
Scheme list. The arguments are the same as in the
|
||||
Racket list. The arguments are the same as in the
|
||||
@scheme[list->cblock]. The @scheme[length] must be specified because
|
||||
there is no way to know where the block ends.}
|
||||
|
||||
|
|
@ -101,4 +101,4 @@ there is no way to know where the block ends.}
|
|||
@defproc[(cblock->vector [cblock any/c][type ctype?][length exact-nonnegative-integer?])
|
||||
vector?]{
|
||||
|
||||
Like @scheme[cblock->vector], but for Scheme vectors.}
|
||||
Like @scheme[cblock->vector], but for Racket vectors.}
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Returns @scheme[#f] for other values.}
|
|||
|
||||
@defproc[(ptr-equal? [cptr1 cpointer?][cptr2 cpointer?]) boolean?]{
|
||||
|
||||
Compares the values of the two pointers. Two different Scheme
|
||||
Compares the values of the two pointers. Two different Racket
|
||||
pointer objects can contain the same pointer.}
|
||||
|
||||
|
||||
|
|
@ -189,7 +189,7 @@ inclusive).}
|
|||
|
||||
@defproc[(cpointer-tag [cptr cpointer?]) any]{
|
||||
|
||||
Returns the Scheme object that is the tag of the given @scheme[cptr]
|
||||
Returns the Racket object that is the tag of the given @scheme[cptr]
|
||||
pointer.}
|
||||
|
||||
|
||||
|
|
@ -207,7 +207,7 @@ can contain other information).}
|
|||
|
||||
@section{Memory Management}
|
||||
|
||||
For general information on C-level memory management with PLT Scheme,
|
||||
For general information on C-level memory management with Racket,
|
||||
see @|InsideMzScheme|.
|
||||
|
||||
@defproc[(malloc [bytes-or-type (or/c exact-nonnegative-integer? ctype?)]
|
||||
|
|
@ -223,7 +223,7 @@ see @|InsideMzScheme|.
|
|||
Allocates a memory block of a specified size using a specified
|
||||
allocation. The result is a @scheme[cpointer] to the allocated
|
||||
memory. Although not reflected above, the four arguments can appear in
|
||||
any order since they are all different types of Scheme objects; a size
|
||||
any order since they are all different types of Racket objects; a size
|
||||
specification is required at minimum:
|
||||
|
||||
@itemize[
|
||||
|
|
@ -243,8 +243,8 @@ specification is required at minimum:
|
|||
|
||||
@item{A symbol @scheme[mode] argument can be given, which specifies
|
||||
what allocation function to use. It should be one of
|
||||
@indexed-scheme['nonatomic] (uses @cpp{scheme_malloc} from PLT
|
||||
Scheme's C API), @indexed-scheme['atomic]
|
||||
@indexed-scheme['nonatomic] (uses @cpp{scheme_malloc} from
|
||||
Racket's C API), @indexed-scheme['atomic]
|
||||
(@cpp{scheme_malloc_atomic}), @indexed-scheme['stubborn]
|
||||
(@cpp{scheme_malloc_stubborn}), @indexed-scheme['uncollectable]
|
||||
(@cpp{scheme_malloc_uncollectable}), @indexed-scheme['eternal]
|
||||
|
|
@ -269,7 +269,7 @@ type, and @scheme['atomic] allocation is used otherwise.}
|
|||
Uses the operating system's @cpp{free} function for
|
||||
@scheme['raw]-allocated pointers, and for pointers that a foreign
|
||||
library allocated and we should free. Note that this is useful as
|
||||
part of a finalizer (see below) procedure hook (e.g., on the Scheme
|
||||
part of a finalizer (see below) procedure hook (e.g., on the Racket
|
||||
pointer object, freeing the memory when the pointer object is
|
||||
collected, but beware of aliasing).}
|
||||
|
||||
|
|
@ -283,7 +283,7 @@ pointer.}
|
|||
@defproc[(malloc-immobile-cell [v any/c]) cpointer?]{
|
||||
|
||||
Allocates memory large enough to hold one arbitrary (collectable)
|
||||
Scheme value, but that is not itself collectable or moved by the
|
||||
Racket value, but that is not itself collectable or moved by the
|
||||
memory manager. The cell is initialized with @scheme[v]; use the type
|
||||
@scheme[_scheme] with @scheme[ptr-ref] and @scheme[ptr-set!] to get
|
||||
or set the cell's value. The cell must be explicitly freed with
|
||||
|
|
@ -298,7 +298,7 @@ Frees an immobile cell created by @scheme[malloc-immobile-cell].}
|
|||
@defproc[(register-finalizer [obj any/c][finalizer (any/c . -> . any)]) void?]{
|
||||
|
||||
Registers a finalizer procedure @scheme[finalizer-proc] with the given
|
||||
@scheme[obj], which can be any Scheme (GC-able) object. The finalizer
|
||||
@scheme[obj], which can be any Racket (GC-able) object. The finalizer
|
||||
is registered with a will executor; see
|
||||
@scheme[make-will-executor]. The finalizer is invoked when
|
||||
@scheme[obj] is about to be collected. (This is done by a thread that
|
||||
|
|
@ -306,9 +306,9 @@ is in charge of triggering these will executors.)
|
|||
|
||||
Finalizers are mostly intended to be used with cpointer objects (for
|
||||
freeing unused memory that is not under GC control), but it can be
|
||||
used with any Scheme object---even ones that have nothing to do with
|
||||
used with any Racket object---even ones that have nothing to do with
|
||||
foreign code. Note, however, that the finalizer is registered for the
|
||||
@italic{Scheme} object. If you intend to free a pointer object, then
|
||||
@italic{Racket} object. If you intend to free a pointer object, then
|
||||
you must be careful to not register finalizers for two cpointers that
|
||||
point to the same address. Also, be careful to not make the finalizer
|
||||
a closure that holds on to the object.
|
||||
|
|
@ -319,7 +319,7 @@ string that you should free. Here is an attempt at creating a suitable type:
|
|||
@schemeblock[
|
||||
(define bytes/free
|
||||
(make-ctype _pointer
|
||||
#f (code:comment @#,t{a Scheme bytes can be used as a pointer})
|
||||
#f (code:comment @#,t{a Racket bytes can be used as a pointer})
|
||||
(lambda (x)
|
||||
(let ([b (make-byte-string x)])
|
||||
(register-finalizer x free)
|
||||
|
|
@ -336,7 +336,7 @@ for debugging:
|
|||
@schemeblock[
|
||||
(define bytes/free
|
||||
(make-ctype _pointer
|
||||
#f (code:comment @#,t{a Scheme bytes can be used as a pointer})
|
||||
#f (code:comment @#,t{a Racket bytes can be used as a pointer})
|
||||
(lambda (x)
|
||||
(let ([b (make-byte-string x)])
|
||||
(register-finalizer b
|
||||
|
|
@ -359,10 +359,10 @@ procedure would then not close over @scheme[b].)}
|
|||
|
||||
Returns a byte string made of the given pointer and the given length.
|
||||
No copying is done. This can be used as an alternative to make
|
||||
pointer values accessible in Scheme when the size is known.
|
||||
pointer values accessible in Racket when the size is known.
|
||||
|
||||
If @scheme[cptr] is an offset pointer created by @scheme[ptr-add], the
|
||||
offset is immediately added to the pointer. Thus, this function cannot
|
||||
be used with @scheme[ptr-add] to create a substring of a Scheme byte
|
||||
be used with @scheme[ptr-add] to create a substring of a Racket byte
|
||||
string, because the offset pointer would be to the middle of a
|
||||
collectable object (which is not allowed).}
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ along with conversion functions to and from the existing types.
|
|||
|
||||
Creates a new @tech{C type} value whose representation for foreign
|
||||
code is the same as @scheme[type]'s. The given conversions functions
|
||||
convert to and from the Scheme representation of @scheme[type]. Either
|
||||
convert to and from the Racket representation of @scheme[type]. Either
|
||||
conversion function can be @scheme[#f], meaning that the conversion
|
||||
for the corresponding direction is the identity function. If both
|
||||
functions are @scheme[#f], @scheme[type] is returned.}
|
||||
|
|
@ -119,7 +119,7 @@ correspond to @scheme[_int16]. The @scheme[_int] aliases correspond to
|
|||
For cases where speed matters and where you know that the integer is
|
||||
small enough, the types @scheme[_fixnum] and @scheme[_ufixnum] are
|
||||
similar to @scheme[_long] and @scheme[_ulong] but assume that the
|
||||
quantities fit in PLT Scheme's immediate integers (i.e., not bignums).}
|
||||
quantities fit in Racket's immediate integers (i.e., not bignums).}
|
||||
|
||||
@defthing*[([_fixint ctype?]
|
||||
[_ufixint ctype?])]{
|
||||
|
|
@ -146,7 +146,7 @@ value to @scheme[1].}
|
|||
|
||||
@defthing[_void ctype?]{
|
||||
|
||||
Indicates a Scheme @|void-const| return value, and it cannot be used
|
||||
Indicates a Racket @|void-const| return value, and it cannot be used
|
||||
to translate values to C. This type cannot be used for function
|
||||
inputs.}
|
||||
|
||||
|
|
@ -157,9 +157,9 @@ inputs.}
|
|||
@subsection{Primitive String Types}
|
||||
|
||||
The five primitive string types correspond to cases where a C
|
||||
representation matches MzScheme's representation without encodings.
|
||||
representation matches Racket's representation without encodings.
|
||||
|
||||
The form @scheme[_bytes] form can be used type for Scheme byte
|
||||
The form @scheme[_bytes] form can be used type for Racket byte
|
||||
strings, which corresponds to C's @cpp{char*} type. In addition to
|
||||
translating byte strings, @scheme[#f] corresponds to the @cpp{NULL}
|
||||
pointer.
|
||||
|
|
@ -168,8 +168,8 @@ pointer.
|
|||
@defthing[_string/ucs-4 ctype?]
|
||||
)]{
|
||||
|
||||
A type for Scheme's native Unicode strings, which are in UCS-4 format.
|
||||
These correspond to the C @cpp{mzchar*} type used by PLT Scheme. As usual, the types
|
||||
A type for Racket's native Unicode strings, which are in UCS-4 format.
|
||||
These correspond to the C @cpp{mzchar*} type used by Racket. As usual, the types
|
||||
treat @scheme[#f] as @cpp{NULL} and vice-versa.}
|
||||
|
||||
|
||||
|
|
@ -183,7 +183,7 @@ Unicode strings in UTF-16 format. As usual, the types treat
|
|||
|
||||
@defthing[_path ctype?]{
|
||||
|
||||
Simple @cpp{char*} strings, corresponding to Scheme's paths. As usual,
|
||||
Simple @cpp{char*} strings, corresponding to Racket's paths. As usual,
|
||||
the types treat @scheme[#f] as @cpp{NULL} and vice-versa.
|
||||
|
||||
Beware that changing the current directory via
|
||||
|
|
@ -196,7 +196,7 @@ them to a foreign function.}
|
|||
|
||||
@defthing[_symbol ctype?]{
|
||||
|
||||
Simple @cpp{char*} strings as Scheme symbols (encoded in UTF-8).
|
||||
Simple @cpp{char*} strings as Racket symbols (encoded in UTF-8).
|
||||
Return values using this type are interned as symbols.}
|
||||
|
||||
|
||||
|
|
@ -206,7 +206,7 @@ Return values using this type are interned as symbols.}
|
|||
[_string/latin-1 ctype?]
|
||||
[_string/locale ctype?])]{
|
||||
|
||||
Types that correspond to (character) strings on the Scheme side and
|
||||
Types that correspond to (character) strings on the Racket side and
|
||||
@cpp{char*} strings on the C side. The bridge between the two requires
|
||||
a transformation on the content of the string. As usual, the types
|
||||
treat @scheme[#f] as @cpp{NULL} and vice-versa.}
|
||||
|
|
@ -216,18 +216,18 @@ treat @scheme[#f] as @cpp{NULL} and vice-versa.}
|
|||
[_string*/locale ctype?])]{
|
||||
|
||||
Similar to @scheme[_string/utf-8], etc., but accepting a wider range
|
||||
of values: Scheme byte strings are allowed and passed as is, and
|
||||
Scheme paths are converted using @scheme[path->bytes].}
|
||||
of values: Racket byte strings are allowed and passed as is, and
|
||||
Racket paths are converted using @scheme[path->bytes].}
|
||||
|
||||
|
||||
@subsection{Variable Auto-Converting String Type}
|
||||
|
||||
The @scheme[_string/ucs-4] type is rarely useful when interacting with
|
||||
foreign code, while using @scheme[_bytes] is somewhat unnatural, since
|
||||
it forces Scheme programmers to use byte strings. Using
|
||||
it forces Racket programmers to use byte strings. Using
|
||||
@scheme[_string/utf-8], etc., meanwhile, may prematurely commit to a
|
||||
particular encoding of strings as bytes. The @scheme[_string] type
|
||||
supports conversion between Scheme strings and @cpp{char*} strings
|
||||
supports conversion between Racket strings and @cpp{char*} strings
|
||||
using a parameter-determined conversion.
|
||||
|
||||
@defthing[_string ctype?]{
|
||||
|
|
@ -248,19 +248,19 @@ so @italic{before} interfaces are defined.}
|
|||
|
||||
@defthing[_file ctype?]{
|
||||
|
||||
Like @scheme[_path], but when values go from Scheme to C,
|
||||
Like @scheme[_path], but when values go from Racket to C,
|
||||
@scheme[cleanse-path] is used on the given value. As an output value,
|
||||
it is identical to @scheme[_path].}
|
||||
|
||||
@defthing[_bytes/eof ctype?]{
|
||||
|
||||
Similar to the @scheme[_bytes] type, except that a foreign return
|
||||
value of @cpp{NULL} is translated to a Scheme @scheme[eof] value.}
|
||||
value of @cpp{NULL} is translated to a Racket @scheme[eof] value.}
|
||||
|
||||
@defthing[_string/eof ctype?]{
|
||||
|
||||
Similar to the @scheme[_string] type, except that a foreign return
|
||||
value of @cpp{NULL} is translated to a Scheme @scheme[eof] value.}
|
||||
value of @cpp{NULL} is translated to a Racket @scheme[eof] value.}
|
||||
|
||||
@; ------------------------------------------------------------
|
||||
|
||||
|
|
@ -268,8 +268,8 @@ value of @cpp{NULL} is translated to a Scheme @scheme[eof] value.}
|
|||
|
||||
@defthing[_pointer ctype?]{
|
||||
|
||||
Corresponds to Scheme ``C pointer'' objects. These pointers can have
|
||||
an arbitrary Scheme object attached as a type tag. The tag is ignored
|
||||
Corresponds to Racket ``C pointer'' objects. These pointers can have
|
||||
an arbitrary Racket object attached as a type tag. The tag is ignored
|
||||
by built-in functionality; it is intended to be used by interfaces.
|
||||
See @secref["foreign:tagged-pointers"] for creating pointer types that
|
||||
use these tags for safety. A @scheme[#f] value is converted to
|
||||
|
|
@ -296,12 +296,15 @@ formerly occupied by the reference to be used later by the garbage
|
|||
collector.}
|
||||
|
||||
|
||||
@defthing[_scheme ctype?]{
|
||||
@deftogether[(
|
||||
@defthing[_racket ctype?]
|
||||
@defthing[_scheme ctype?]
|
||||
)]{
|
||||
|
||||
This type can be used with any Scheme object; it corresponds to the
|
||||
@cpp{Scheme_Object*} type of PLT Scheme's C API (see
|
||||
A type that can be used with any Racket object; it corresponds to the
|
||||
@cpp{Scheme_Object*} type of Racket's C API (see
|
||||
@|InsideMzScheme|). It is useful only for libraries that are aware of
|
||||
PLT Scheme's C API.}
|
||||
Racket's C API.}
|
||||
|
||||
|
||||
@defthing[_fpointer ctype?]{
|
||||
|
|
@ -358,14 +361,14 @@ instead, since it manages a wide range of complicated cases.
|
|||
The resulting type can be used to reference foreign functions (usually
|
||||
@scheme[ffi-obj]s, but any pointer object can be referenced with this type),
|
||||
generating a matching foreign callout object. Such objects are new primitive
|
||||
procedure objects that can be used like any other Scheme procedure.
|
||||
procedure objects that can be used like any other Racket procedure.
|
||||
As with other pointer types, @scheme[#f] is treated as a @cpp{NULL}
|
||||
function pointer and vice-versa.
|
||||
|
||||
A type created with @scheme[_cprocedure] can also be used for passing
|
||||
Scheme procedures to foreign functions, which will generate a foreign
|
||||
function pointer that calls the given Scheme procedure when it is
|
||||
used. There are no restrictions on the Scheme procedure; in
|
||||
Racket procedures to foreign functions, which will generate a foreign
|
||||
function pointer that calls the given Racket procedure when it is
|
||||
used. There are no restrictions on the Racket procedure; in
|
||||
particular, its lexical context is properly preserved.
|
||||
|
||||
The optional @scheme[abi] keyword argument determines the foreign ABI
|
||||
|
|
@ -375,12 +378,12 @@ platform-dependent default; other possible values are
|
|||
``cdecl''). This is especially important on Windows, where most
|
||||
system functions are @scheme['stdcall], which is not the default.
|
||||
|
||||
If @scheme[atomic?] is true, then when a Scheme procedure is given
|
||||
this procedure type and called from foreign code, then the PLT Scheme
|
||||
process is put into atomic mode while evaluating the Scheme procedure
|
||||
body. In atomic mode, other Scheme threads do not run, so the Scheme
|
||||
If @scheme[atomic?] is true, then when a Racket procedure is given
|
||||
this procedure type and called from foreign code, then the Racket
|
||||
process is put into atomic mode while evaluating the Racket procedure
|
||||
body. In atomic mode, other Racket threads do not run, so the Racket
|
||||
code must not call any function that potentially synchronizes with
|
||||
other threads, or else it may deadlock. In addition, the Scheme code
|
||||
other threads, or else it may deadlock. In addition, the Racket code
|
||||
must not perform any potentially blocking operation (such as I/O), it
|
||||
must not raise an uncaught exception, it must not perform any escaping
|
||||
continuation jumps, and its non-tail recursion must be minimal to
|
||||
|
|
@ -397,8 +400,8 @@ accessible through @scheme[saved-errno]. If @scheme[save-errno] is
|
|||
under Windows (on other platforms @scheme[saved-errno] will return
|
||||
0). If @scheme[save-errno] is @scheme[#f], no error value is saved
|
||||
automatically. The error-recording support provided by
|
||||
@scheme[save-errno] is needed because the PLT Scheme runtime system
|
||||
may otherwise preempt the current Scheme thread and itself call
|
||||
@scheme[save-errno] is needed because the Racket runtime system
|
||||
may otherwise preempt the current Racket thread and itself call
|
||||
functions that set error values.
|
||||
|
||||
The optional @scheme[wrapper], if provided, is expected to be a
|
||||
|
|
@ -410,10 +413,10 @@ manipulations before the foreign function is invoked, and return
|
|||
different results (for example, grabbing a value stored in an
|
||||
``output'' pointer and returning multiple values). It can also be
|
||||
used for callbacks, as an additional layer that tweaks arguments from
|
||||
the foreign code before they reach the Scheme procedure, and possibly
|
||||
the foreign code before they reach the Racket procedure, and possibly
|
||||
changes the result values too.
|
||||
|
||||
Sending Scheme functions as callbacks to foreign code is achieved by
|
||||
Sending Racket functions as callbacks to foreign code is achieved by
|
||||
translating them to a foreign ``closure,'' which foreign code can call
|
||||
as plain C functions. Additional care must be taken in case the
|
||||
foreign code might hold on to the callback function. In these cases
|
||||
|
|
@ -446,14 +449,14 @@ values: @itemize[
|
|||
allowing the box itself to be garbage-collected. This is can be
|
||||
useful if the box is held for a dynamic extent that corresponds to
|
||||
when the callback is needed; for example, you might encapsulate some
|
||||
foreign functionality in a Scheme class or a unit, and keep the
|
||||
foreign functionality in a Racket class or a unit, and keep the
|
||||
callback box as a field in new instances or instantiations of the
|
||||
unit.}
|
||||
|
||||
@item{A box holding @scheme[null] (or any list) -- this is similar to
|
||||
the previous case, except that new callback values are consed onto
|
||||
the contents of the box. It is therefore useful in (rare) cases
|
||||
when a Scheme function is used in multiple callbacks (that is, sent
|
||||
when a Racket function is used in multiple callbacks (that is, sent
|
||||
to foreign code to hold onto multiple times).}
|
||||
|
||||
@item{Finally, if a one-argument function is provided as
|
||||
|
|
@ -643,7 +646,7 @@ following:
|
|||
one will be freshly allocated before the call.}
|
||||
|
||||
@item{@scheme[io] --- combines the above into an
|
||||
@italic{input/output} pointer argument: the wrapper gets the Scheme
|
||||
@italic{input/output} pointer argument: the wrapper gets the Racket
|
||||
value, allocates and set a pointer using this value, and then
|
||||
references the value after the call. The ``@scheme[_ptr]'' name can
|
||||
be confusing here: it means that the foreign function expects a
|
||||
|
|
@ -691,7 +694,7 @@ length of the list which the C function will most likely require.}
|
|||
@defform[(_vector mode type maybe-len)]{
|
||||
|
||||
A @tech{custom function type} like @scheme[_list], except that it uses
|
||||
Scheme vectors instead of lists.}
|
||||
Racket vectors instead of lists.}
|
||||
|
||||
|
||||
@defform*[#:literals (o)
|
||||
|
|
@ -717,7 +720,7 @@ is present for consistency with the above macros).}
|
|||
|
||||
The primitive type constructor for creating new C struct types. These
|
||||
types are actually new primitive types; they have no conversion
|
||||
functions associated. The corresponding Scheme objects that are used
|
||||
functions associated. The corresponding Racket objects that are used
|
||||
for structs are pointers, but when these types are used, the value
|
||||
that the pointer @italic{refers to} is used, rather than the pointer
|
||||
itself. This value is basically made of a number of bytes that is
|
||||
|
|
@ -741,7 +744,7 @@ below for a more efficient approach.}
|
|||
|
||||
Defines a new C struct type, but unlike @scheme[_list-struct], the
|
||||
resulting type deals with C structs in binary form, rather than
|
||||
marshaling them to Scheme values. The syntax is similar to
|
||||
marshaling them to Racket values. The syntax is similar to
|
||||
@scheme[define-struct], providing accessor functions for raw struct
|
||||
values (which are pointer objects). The new type uses pointer tags to
|
||||
guarantee that only proper struct objects are used. The @scheme[_id]
|
||||
|
|
@ -793,7 +796,7 @@ inheritance, where a sub-struct is made by having a first field that
|
|||
is its super-struct. Instances of the sub-struct can be considered as
|
||||
instances of the super-struct, since they share the same initial
|
||||
layout. Using the tag of an initial cstruct field means that the same
|
||||
behavior is implemented in Scheme; for example, accessors and mutators
|
||||
behavior is implemented in Racket; for example, accessors and mutators
|
||||
of the super-cstruct can be used with the new sub-cstruct. See the
|
||||
example below.
|
||||
|
||||
|
|
@ -914,7 +917,7 @@ take an @cpp{A} pointer:
|
|||
(gety b)
|
||||
]
|
||||
|
||||
Constructing a @cpp{B} instance in Scheme requires allocating a
|
||||
Constructing a @cpp{B} instance in Racket requires allocating a
|
||||
temporary @cpp{A} struct:
|
||||
|
||||
@schemeblock[
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ please let us know.
|
|||
[lib (or/c ffi-lib? path-string? #f)])
|
||||
any]{
|
||||
|
||||
Pulls out a foreign object from a library, returning a Scheme value
|
||||
Pulls out a foreign object from a library, returning a Racket value
|
||||
that can be used as a pointer. If a name is provided instead of a
|
||||
foreign-library value, @scheme[ffi-lib] is used to create a library
|
||||
object.}
|
||||
|
|
@ -48,9 +48,9 @@ cstructs, and another ctype for user-defined ctypes.}
|
|||
[abi (or/c symbol/c #f) #f])
|
||||
any]{
|
||||
|
||||
The primitive mechanism that creates Scheme ``callout'' values. The
|
||||
The primitive mechanism that creates Racket ``callout'' values. The
|
||||
given @scheme[ptr] (any pointer value, including @scheme[ffi-obj]
|
||||
values) is wrapped in a Scheme-callable primitive function that uses
|
||||
values) is wrapped in a Racket-callable primitive function that uses
|
||||
the types to specify how values are marshaled.
|
||||
|
||||
The optional @scheme[abi] argument determines the foreign ABI that is
|
||||
|
|
@ -66,7 +66,7 @@ especially important on Windows, where most system functions are
|
|||
[atomic? any/c #f])
|
||||
ffi-callback?]{
|
||||
|
||||
The symmetric counterpart of @scheme[ffi-call]. It receives a Scheme
|
||||
The symmetric counterpart of @scheme[ffi-call]. It receives a Racket
|
||||
procedure and creates a callback object, which can also be used as a
|
||||
pointer. This object can be used as a C-callable function, which
|
||||
invokes @scheme[proc] using the types to specify how values are
|
||||
|
|
|
|||
|
|
@ -16,3 +16,27 @@ the @racketmodname[racket], @racketmodname[racket/enter] and
|
|||
library for GRacket. It re-exports the @racketmodname[racket/init] and
|
||||
@racketmodname[racket/gui/base] libraries, and it sets
|
||||
@racket[current-load] to use @racket[text-editor-load-handler].}
|
||||
|
||||
@defmodule*/no-declare[(racket/language-info)]{The
|
||||
@racketmodname[racket/language-info] library provides a
|
||||
@schemeidfont{get-info} function that takes any value and returns
|
||||
another function; the returned function takes a key value and a
|
||||
default value, and it returns @scheme['(#(racket/runtime-config
|
||||
configure #f))] if the key is @scheme['configure-runtime] or the
|
||||
default value otherwise.}
|
||||
|
||||
The vector @scheme['#(racket/language-info get-info #f)] is suitable
|
||||
for attaching to a module as its language info to get the same
|
||||
language information as the @scheme[racket/base] language.
|
||||
|
||||
@defmodule*/no-declare[(racket/runtime-config)]{The
|
||||
@racketmodname[racket/runtime-config] library provides a
|
||||
@racketidfont{configure} function that returns another function; the
|
||||
returned function takes an value ans set @racket[print-as-expression]
|
||||
to @scheme[#t].}
|
||||
|
||||
The vector @scheme[#(racket/runtime-config configure #f)] is suitable
|
||||
as a member of a list of runtime-configuration specification (as
|
||||
returned by a module's language-information function for the key
|
||||
@racket['configure-runtime]) to obtain the same runtime configuration as
|
||||
for the @schememodname[racket/base] language.
|
||||
|
|
|
|||
|
|
@ -323,7 +323,8 @@ the interpretation of results is up to external tools, such as
|
|||
DrRacket. If no information is available for a given key, the result
|
||||
should be the given default value.
|
||||
|
||||
See also @racket[module->language-info].}
|
||||
See also @racket[module->language-info] and
|
||||
@racketmodname[racket/language-info].}
|
||||
|
||||
|
||||
@;------------------------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -183,7 +183,11 @@ mode but with a @litchar{'} prefix; the pair's content is printed with
|
|||
(when the pair is a list), or @litchar{list*} (otherwise) after the
|
||||
openining @litchar{(}, any @litchar{.} that would otherwise be printed
|
||||
is suppressed, and the pair content is printed at @tech{quoting depth}
|
||||
@scheme[0].
|
||||
@scheme[0]. In all cases, when @scheme[print-as-expression] is
|
||||
@scheme[#t] for @scheme[print] mode, then the value of
|
||||
@scheme[print-reader-abbreviations] is ignored and reader
|
||||
abbreviations are always used for lists printed at @tech{quoting
|
||||
depth} @scheme[1].
|
||||
|
||||
By default, mutable pairs (as created with @scheme[mcons]) print the
|
||||
same as pairs for @scheme[write] and @scheme[display], except that
|
||||
|
|
|
|||
|
|
@ -134,7 +134,9 @@ flags:
|
|||
the evaluation are printed via @racket[current-print].}
|
||||
|
||||
@item{@FlagFirst{f} @nonterm{file} or @DFlagFirst{load}
|
||||
@nonterm{file} : @racket[load]s @nonterm{file}.}
|
||||
@nonterm{file} : @racket[load]s @nonterm{file}; if
|
||||
@nonterm{file} is @filepath{-}, then expressions are read and
|
||||
evaluated from standard input.}
|
||||
|
||||
@item{@FlagFirst{t} @nonterm{file} or @DFlagFirst{require}
|
||||
@nonterm{file} : @racket[require]s @nonterm{file}.}
|
||||
|
|
|
|||
|
|
@ -202,9 +202,12 @@ is a module path (in the sense of @racket[module-path?]) and the
|
|||
second is a symbol, then the property value is preserved in the
|
||||
corresponding compiled and/or declared module. The third component of
|
||||
the vector should be printable and @racket[read]able, so that it can
|
||||
be preserved in marshaled bytecode. See also
|
||||
@racket[module-compiled-language-info] and
|
||||
@racket[module->language-info].}
|
||||
be preserved in marshaled bytecode. The @racketmodname[racket/base]
|
||||
and @racketmodname[racket] languages attach
|
||||
@scheme['#(racket/language-info get-info #f)] to a @racket[module]
|
||||
form. See also @racket[module-compiled-language-info],
|
||||
@racket[module->language-info], and
|
||||
@racketmodname[racket/language-info].}
|
||||
|
||||
See also @secref["module-eval-model"] and @secref["mod-parse"].
|
||||
|
||||
|
|
|
|||
|
|
@ -212,7 +212,7 @@ with @racket[quote], @racket['quasiquote], @racket['unquote],
|
|||
@defboolparam[print-as-expression on?]{
|
||||
|
||||
A parameter that controls printing in @racket[print] mode (as opposed
|
||||
to @racket[write] or @racket[display]); defaults to @racket[#f]. See
|
||||
to @racket[write] or @racket[display]); defaults to @racket[#t]. See
|
||||
@secref["printing"] for more information.}
|
||||
|
||||
@defboolparam[print-honu on?]{
|
||||
|
|
|
|||
|
|
@ -148,6 +148,21 @@ must occur after all the @scheme[provide*] forms to which it refers.}
|
|||
@compat[scheme/help racket/help]
|
||||
@compat[scheme/include racket/include]
|
||||
@compat[scheme/init racket/init]
|
||||
|
||||
@;------------------------------------------------------------------------
|
||||
|
||||
@section[#:tag "scheme/language-info"]{@schememodname[scheme/language-info]}
|
||||
|
||||
@defmodule[scheme/language-info]{
|
||||
The @schememodname[scheme/language-info] library is like
|
||||
@schememodname[racket/language-info], except that it produces
|
||||
@scheme['(#(scheme/runtime-config configure #f))] for the
|
||||
@scheme['configure-runtime] information key.}
|
||||
|
||||
See also @racketmodname[scheme/runtime-config].
|
||||
|
||||
@;------------------------------------------------------------------------
|
||||
|
||||
@compat[scheme/list racket/list]
|
||||
@compat[scheme/load racket/load]
|
||||
@compat[scheme/local racket/local]
|
||||
|
|
@ -230,6 +245,19 @@ An alias for @racket[pretty-write].}
|
|||
@compat[scheme/require racket/require]
|
||||
@compat[scheme/require-syntax racket/require-syntax]
|
||||
@compat[scheme/require-transform racket/require-transform]
|
||||
|
||||
@;------------------------------------------------------------------------
|
||||
|
||||
@section[#:tag "scheme/runtime-config"]{@schememodname[scheme/runtime-config]}
|
||||
|
||||
@defmodule[scheme/runtime-config]{
|
||||
The @schememodname[scheme/runtime-config] library is like
|
||||
@schememodname[racket/runtime-config], except that the result of its
|
||||
@schemeidfont{configure} function is a procedure that sets
|
||||
@racket[print-as-expression] to @scheme[#f].}
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@compat[scheme/runtime-path racket/runtime-path]
|
||||
|
||||
@; ----------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user