210 lines
8.3 KiB
Racket
210 lines
8.3 KiB
Racket
#lang scribble/doc
|
|
@(require "utils.ss")
|
|
|
|
@title[#:tag "config"]{Parameterizations}
|
|
|
|
A @defterm{parameterization} is a set of parameter values. Each thread
|
|
has its own initial parameterization, which is extended functionally
|
|
and superseded by parameterizations that are attached to a particular
|
|
continuation mark.
|
|
|
|
Parameterization information is stored in a @cppi{Scheme_Config}
|
|
record. For the currently executing thread,
|
|
@cppi{scheme_current_config} returns the current parameterization.
|
|
|
|
To obtain parameter values, a @cpp{Scheme_Config} is combined with the
|
|
current threads @cpp{Scheme_Thread_Cell_Table}, as stored in the
|
|
thread record's @cpp{cell_values} field.
|
|
|
|
Parameter values for built-in parameters are obtained and modified
|
|
(for the current thread) using @cppi{scheme_get_param} and
|
|
@cppi{scheme_set_param}. Each parameter is stored as a
|
|
@cpp{Scheme_Object *} value, and the built-in parameters are accessed
|
|
through the following indices:
|
|
|
|
@itemize{
|
|
@item{@cppdef{MZCONFIG_ENV} --- @scheme[current-namespace] (use @cpp{scheme_get_env})}
|
|
@item{@cppdef{MZCONFIG_INPUT_PORT} --- @scheme[current-input-port]}
|
|
@item{@cppdef{MZCONFIG_OUTPUT_PORT} --- @scheme[current-output-port]}
|
|
@item{@cppdef{MZCONFIG_ERROR_PORT} --- @scheme[current-error-port]}
|
|
|
|
@item{@cppdef{MZCONFIG_ERROR_DISPLAY_HANDLER} --- @scheme[error-display-handler]}
|
|
@item{@cppdef{MZCONFIG_ERROR_PRINT_VALUE_HANDLER} --- @scheme[error-value->string-handler]}
|
|
|
|
@item{@cppdef{MZCONFIG_EXIT_HANDLER} --- @scheme[exit-handler]}
|
|
|
|
@item{@cppdef{MZCONFIG_INIT_EXN_HANDLER} --- @scheme[uncaught-exception-handler]}
|
|
|
|
@item{@cppdef{MZCONFIG_EVAL_HANDLER} --- @scheme[current-eval]}
|
|
@item{@cppdef{MZCONFIG_LOAD_HANDLER} --- @scheme[current-load]}
|
|
|
|
@item{@cppdef{MZCONFIG_PRINT_HANDLER} --- @scheme[current-print]}
|
|
@item{@cppdef{MZCONFIG_PROMPT_READ_HANDLER} --- @scheme[current-prompt-read]}
|
|
|
|
@item{@cppdef{MZCONFIG_CAN_READ_GRAPH} --- @scheme[read-accept-graph]}
|
|
@item{@cppdef{MZCONFIG_CAN_READ_COMPILED} --- @scheme[read-accept-compiled]}
|
|
@item{@cppdef{MZCONFIG_CAN_READ_BOX} --- @scheme[read-accept-box]}
|
|
@item{@cppdef{MZCONFIG_CAN_READ_PIPE_QUOTE} --- @scheme[read-accept-bar-quote]}
|
|
|
|
@item{@cppdef{MZCONFIG_PRINT_GRAPH} --- @scheme[print-graph]}
|
|
@item{@cppdef{MZCONFIG_PRINT_STRUCT} --- @scheme[print-struct]}
|
|
@item{@cppdef{MZCONFIG_PRINT_BOX} --- @scheme[print-box]}
|
|
|
|
@item{@cppdef{MZCONFIG_CASE_SENS} --- @scheme[read-case-sensitive]}
|
|
@item{@cppdef{MZCONFIG_SQUARE_BRACKETS_ARE_PARENS} --- @scheme[read-square-brackets-as-parens]}
|
|
@item{@cppdef{MZCONFIG_CURLY_BRACES_ARE_PARENS} --- @scheme[read-curly-braces-as-parens]}
|
|
|
|
@item{@cppdef{MZCONFIG_ERROR_PRINT_WIDTH} --- @scheme[error-print-width]}
|
|
|
|
@item{@cppdef{MZCONFIG_ALLOW_SET_UNDEFINED} --- @scheme[allow-compile-set!-undefined]}
|
|
|
|
@item{@cppdef{MZCONFIG_CUSTODIAN} --- @scheme[current-custodian]}
|
|
|
|
@item{@cppdef{MZCONFIG_USE_COMPILED_KIND} --- @scheme[use-compiled-file-paths]}
|
|
|
|
@item{@cppdef{MZCONFIG_LOAD_DIRECTORY} --- @scheme[current-load-relative-directory]}
|
|
|
|
@item{@cppdef{MZCONFIG_COLLECTION_PATHS} --- @scheme[current-library-collection-paths]}
|
|
|
|
@item{@cppdef{MZCONFIG_PORT_PRINT_HANDLER} --- @scheme[global-port-print-handler]}
|
|
|
|
@item{@cppdef{MZCONFIG_LOAD_EXTENSION_HANDLER} --- @scheme[current-load-extension]}
|
|
|
|
}
|
|
|
|
To get or set a parameter value for a thread other than the current
|
|
one, use @cppi{scheme_get_thread_param} and
|
|
@cppi{scheme_set_thread_param}, each of which takes a
|
|
@cpp{Scheme_Thread_Cell_Table} to use in resolving or setting a
|
|
parameter value.
|
|
|
|
When installing a new parameter with @cpp{scheme_set_param}, no check
|
|
is performed on the supplied value to ensure that it is a legal value
|
|
for the parameter; this is the responsibility of the caller of
|
|
@cpp{scheme_set_param}. Note that Boolean parameters should only be
|
|
set to the values @scheme[#t] and @scheme[#f].
|
|
|
|
New primitive parameter indices are created with
|
|
@cppi{scheme_new_param} and implemented with
|
|
@cppi{scheme_make_parameter} and @cppi{scheme_param_config}.
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@function[(Scheme_Object* scheme_get_param
|
|
[Scheme_Config* config]
|
|
[int param_id])]{
|
|
|
|
Gets the current value (for the current thread) of the parameter
|
|
specified by @var{param_id}.}
|
|
|
|
@function[(Scheme_Object* scheme_set_param
|
|
[Scheme_Config* config]
|
|
[int param_id]
|
|
[Scheme_Object* v])]{
|
|
|
|
Sets the current value (for the current thread) of the parameter
|
|
specified by @var{param_id}.}
|
|
|
|
@function[(Scheme_Object* scheme_get_thread_param
|
|
[Scheme_Config* config]
|
|
[Scheme_Thread_Cell_Table* cells]
|
|
[int param_id])]{
|
|
|
|
Like @cpp{scheme_get_param}, but using an arbitrary thread's
|
|
cell-value table.}
|
|
|
|
@function[(Scheme_Object* scheme_set_thread_param
|
|
[Scheme_Config* config]
|
|
[Scheme_Thread_Cell_Table* cells]
|
|
[int param_id]
|
|
[Scheme_Object* v])]{
|
|
|
|
Like @cpp{scheme_set_param}, but using an arbitrary thread's
|
|
cell-value table.}
|
|
|
|
@function[(Scheme_Object* scheme_extend_config
|
|
[Scheme_Config* base]
|
|
[int param_id]
|
|
[Scheme_Object* v])]{
|
|
|
|
Creates and returns a parameterization that extends @var{base} with a
|
|
new value @var{v} (in all threads) for the parameter
|
|
@var{param_id}. Use @cpp{scheme_install_config} to make this
|
|
configuration active in the current thread.}
|
|
|
|
@function[(void scheme_install_config
|
|
[Scheme_Config* config])]{
|
|
|
|
Adjusts the current thread's continuation marks to make @var{config}
|
|
the current parameterization. Typically, this function is called
|
|
after @cpp{scheme_push_continuation_frame} to establish a new
|
|
continuation frame, and then @cpp{scheme_pop_continuation_frame}
|
|
is called later to remove the frame (and thus the parameterization).}
|
|
|
|
@function[(Scheme_Thread_Cell_Table* scheme_inherit_cells
|
|
[Scheme_Thread_Cell_Table* cells])]{
|
|
|
|
Creates a new thread-cell-value table, copying values for preserved
|
|
thread cells from @var{cells}.}
|
|
|
|
@function[(int scheme_new_param)]{
|
|
|
|
Allocates a new primitive parameter index. This function must be
|
|
called @italic{before} @cppi{scheme_basic_env}, so it is only
|
|
available to embedding applications (i.e., not extensions).}
|
|
|
|
@function[(Scheme_Object* scheme_register_parameter
|
|
[Scheme_Prim* function]
|
|
[char* name]
|
|
[int exnid])]{
|
|
|
|
Use this function instead of the other primitive-constructing
|
|
functions, like @cpp{scheme_make_prim}, to create a primitive
|
|
parameter procedure. See also @cpp{scheme_param_config}, below.
|
|
This function is only available to embedding applications (i.e., not
|
|
extensions).}
|
|
|
|
@function[(Scheme_Object* scheme_param_config
|
|
[char* name]
|
|
[Scheme_Object* param]
|
|
[int argc]
|
|
[Scheme_Object** argv]
|
|
[int arity]
|
|
[Scheme_Prim* check]
|
|
[char* expected]
|
|
[int isbool])]{
|
|
|
|
Call this procedure in a primitive parameter procedure to implement
|
|
the work of getting or setting the parameter. The @var{name} argument
|
|
should be the parameter procedure name; it is used to report
|
|
errors. The @var{param} argument is a fixnum corresponding to the
|
|
primitive parameter index returned by @cpp{scheme_new_param}. The
|
|
@var{argc} and @var{argv} arguments should be the un-touched and
|
|
un-tested arguments that were passed to the primitive parameter.
|
|
Argument-checking is performed within @cpp{scheme_param_config}
|
|
using @var{arity}, @var{check}, @var{expected}, and @var{isbool}:
|
|
|
|
@itemize{
|
|
|
|
@item{If @var{arity} is non-negative, potential parameter values must
|
|
be able to accept the specified number of arguments. The @var{check}
|
|
and @var{expected} arguments should be @cpp{NULL}.}
|
|
|
|
@item{If @var{check} is not @cpp{NULL}, it is called to check a
|
|
potential parameter value. The arguments passed to @var{check} are
|
|
always @cpp{1} and an array that contains the potential parameter
|
|
value. If @var{isbool} is @cpp{0} and @var{check} returns
|
|
@cpp{scheme_false}, then a type error is reported using @var{name}
|
|
and @var{expected}. If @var{isbool} is @cpp{1}, then a type error is
|
|
reported only when @var{check} returns @cpp{NULL} and any
|
|
non-@cpp{NULL} return value is used as the actual value to be stored
|
|
for the parameter.}
|
|
|
|
@item{Otherwise, @var{isbool} should be 1. A potential procedure
|
|
argument is then treated as a Boolean value.}
|
|
|
|
}
|
|
|
|
This function is only available to embedding applications (i.e., not
|
|
extensions).}
|