document Windows embedding requirement when parallelism is enabled

merge to v5.0

collects/scribblings/inside/memory.scrbl

@@ -653,6 +653,12 @@ Like @cpp{scheme_malloc}, but in 3m, the type tag determines how the
 Like @cpp{scheme_malloc}, but in 3m, pointers are allowed to
  reference the middle of the object; see @secref["im:memoryalloc"].}
 
+@function[(void* scheme_malloc_atomic_allow_interior
+           [size_t n])]{
+
+Like @cpp{scheme_malloc_atomic}, but in 3m, pointers are allowed to
+ reference the middle of the object; see @secref["im:memoryalloc"].}
+
 @function[(char* scheme_strdup
            [char* str])]{
 
@@ -807,6 +813,21 @@ difference between the actual stack start and the reported stack base,
 in addition to the margin needed for detecting and handling stack
 overflow.}
 
+@function[(void scheme_register_tls_space
+           [void* ptr]
+           [int   tls_index])]{
+
+Only available under Windows; registers @var{ptr} as the address of a
+ thread-local pointer variable that is declared in the main
+ executable. The variable's storage will be used to implement
+ thread-local storage within the Racket run-time. See
+ @secref["embedding"].
+
+The @var{tls_index} argument must be @cpp{0}. It is currently
+ ignored, but a future version may use the argument to allow
+ declaration of the thread-local variable in a dynamically linked
+ DLL.}
+
 @function[(void scheme_register_static
            [void* ptr]
            [long size])]{

collects/scribblings/inside/overview.scrbl

@@ -359,7 +359,23 @@ To embed Racket CGC in a program, follow these steps:
   @cppi{scheme_basic_env} and passing the result to the function
   provided to @cpp{scheme_main_setup}. (The
   @cpp{scheme_main_stack_setup} trampoline registers the C stack with
-  the memory manager without creating a namespace.)}
+  the memory manager without creating a namespace.)
+
+  Under Windows, when support for parallelism is enabled in the Racket
+  build (as is the default), then before calling
+  @cpp{scheme_main_setup}, your embedding application must first call
+  @cppi{scheme_register_tls_space}:
+
+  @verbatim[#:indent 2]{
+   scheme_register_tls_space(&tls_space, 0);
+  }
+
+  where @cpp{tls_space} is declared as a thread-local pointer variable
+  in the main executable (i.e., not in a dynamically linked DLL):
+
+  @verbatim[#:indent 2]{
+   static __declspec(thread) void *tls_space;
+  }}
 
  @item{Configure the namespace by adding module declarations. The
   initial namespace contains declarations only for a few primitive