From 71ffa2bcb6d259f40fdea918d7ce2c17c16a76bf Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 23 Nov 2020 11:47:32 -0700 Subject: [PATCH] doc: clarify intent of CS C-to-Racket calling API --- .../scribblings/inside/cs-eval.scrbl | 8 +++++-- .../scribblings/inside/cs-procs.scrbl | 22 +++++++++++++------ .../scribblings/inside/cs-start.scrbl | 6 ++++- 3 files changed, 26 insertions(+), 10 deletions(-) diff --git a/pkgs/racket-doc/scribblings/inside/cs-eval.scrbl b/pkgs/racket-doc/scribblings/inside/cs-eval.scrbl index 11833fe3ed..3e82b7e552 100644 --- a/pkgs/racket-doc/scribblings/inside/cs-eval.scrbl +++ b/pkgs/racket-doc/scribblings/inside/cs-eval.scrbl @@ -7,7 +7,7 @@ The @cppi{racket_apply} function provides basic evaluation support, but @cppi{racket_eval}, @cppi{racket_dynamic_require}, and @cppi{racket_namespace_require} provide higher-level support for the -most common evaluation tasks. +most common evaluation tasks to initialize a Racket instance. @function[(ptr racket_eval [ptr s_expr])]{ @@ -21,7 +21,11 @@ Use @cppi{racket_namespace_require} to initialize a namespace, or use @cppi{racket_dynamic_require} to access functionality without going through a top-level namespace. Although those functions are the same as using @racket[namespace-require] and @racket[dynamic-require], they -work without having those identifiers bound in a namespace already.} +work without having those identifiers bound in a namespace already. + +This function and others in this section are not meant to be called +in C code that was called from Racket. See also @secref["cs-procs"] +for a discussion of @emph{entry} points versus @emph{re-entry} points.} @function[(ptr racket_dynamic_require [ptr module_path] [ptr sym_or_false])]{ diff --git a/pkgs/racket-doc/scribblings/inside/cs-procs.scrbl b/pkgs/racket-doc/scribblings/inside/cs-procs.scrbl index c5c3f56c9c..5d8561a70d 100644 --- a/pkgs/racket-doc/scribblings/inside/cs-procs.scrbl +++ b/pkgs/racket-doc/scribblings/inside/cs-procs.scrbl @@ -3,13 +3,21 @@ @title[#:tag "cs-procs"]{Calling Procedures} -Normally, C programs should call Racket procedures by using -@cppi{racket_apply}, which calls the procedure in the initial Racket -thread of the main Racket place. Chez Scheme entry points such as -@cppi{Scall0} and @cppi{Scall} directly call a procedure outside of -any Racket thread, which will not work correctly with Racket -facilities such as threads, parameters, continuations, or continuation -marks. +As an entry point into Racket, C programs should normally call Racket +procedures by using @cppi{racket_apply}, which calls the procedure in +the initial Racket thread of the main Racket place. Chez Scheme entry +points such as @cppi{Scall0} and @cppi{Scall} directly call a +procedure outside of any Racket thread, which will not work correctly +with Racket facilities such as threads, parameters, continuations, or +continuation marks. + +The functions in this section are meant to be used as an entry point +to Racket, but not as a @emph{re-entry} point. When Racket calls a C +function that in turn calls back into Racket, the best approach is to +use the FFI (see @other-doc['(lib +"scribblings/foreign/foreign.scrbl")]) so that the C call recieves a +Racket callback that is wrapped as a plain C callback. That way, the +FFI can handle the details of boundary crossings between Racket and C. @; ---------------------------------------------------------------------- diff --git a/pkgs/racket-doc/scribblings/inside/cs-start.scrbl b/pkgs/racket-doc/scribblings/inside/cs-start.scrbl index 6ade3777f1..f240580456 100644 --- a/pkgs/racket-doc/scribblings/inside/cs-start.scrbl +++ b/pkgs/racket-doc/scribblings/inside/cs-start.scrbl @@ -125,4 +125,8 @@ functions, and @DFlag{c-mods} mode generates C code that calls If @var{as_predefined} is true, then the code is loaded during the creation of any new Racket @tech[#:doc reference-doc]{place} in the new place, so that modules declared by the code are loaded in the new -place, too.} +place, too. + +These functions are not meant to be called in C code that was called +from Racket. See also @secref["cs-procs"] for a discussion of +@emph{entry} points versus @emph{re-entry} points.}