▼ |  | Inside: Racket C API

1 | Overview
2 | Embedding into a Program
3 | Writing Racket Extensions
4 | Values and Types
5 | Memory Allocation
6 | Namespaces and Modules
7 | Procedures
8 | Evaluation
9 | Exceptions and Escape Continuations
10 | Threads
11 | Parameterizations
12 | Continuation Marks
13 | String Encodings
14 | Bignums, Rationals, and Complex Numbers
15 | Ports and the Filesystem
16 | Structures
17 | Security Guards
18 | Custodians
19 | Subprocesses
20 | Miscellaneous Utilities
| Index

top ← prev up next →

### 6`` Namespaces and Modules

A Racket namespace (a top-level environment) is represented by a value of type Scheme_Env* — which is also a Racket value, castable to Scheme_Object*. Calling scheme_basic_env returns a namespace that includes all of Racket’s standard global procedures and syntax.

The scheme_basic_env function must be called once by an embedding program, before any other Racket function is called (except scheme_make_param), but scheme_main_setup automatically calls scheme_basic_env. The returned namespace is the initial current namespace for the main Racket thread. Racket extensions cannot call scheme_basic_env.

The current thread’s current namespace is available from scheme_get_env, given the current parameterization (see Parameterizations): scheme_get_env(scheme_config).

New values can be added as globals in a namespace using scheme_add_global. The scheme_lookup_global function takes a Racket symbol and returns the global value for that name, or NULL if the symbol is undefined.

A module’s set of top-level bindings is implemented using the same machinery as a namespace. Use scheme_primitive_module to create a new Scheme_Env* that represents a primitive module. The name provided to scheme_primitive_module is subject to change through the current-module-declare-name parameter (which is normally set by the module name resolver when auto-loading module files). After installing variables into the module with scheme_add_global, etc., call scheme_finish_primitive_module on the Scheme_Env* value to make the module declaration available. All defined variables are exported from the primitive module.

The Racket #%variable-reference form produces a value that is opaque to Racket code. Use SCHEME_PTR_VAL on the result of #%variable-reference to obtain the same kind of value as returned by scheme_global_bucket (i.e., a bucket containing the variable’s value, or NULL if the variable is not yet defined).

void |  | scheme_add_global | ( | char* name,
|  |  |  | Scheme_Object* val,
|  |  |  | Scheme_Env* env)

Adds a value to the table of globals for the namespace env, where name is a null-terminated string. (The string’s case will be normalized in the same way as for interning a symbol.)

void |  | scheme_add_global_symbol | ( | Scheme_Object* name,
|  |  |  | Scheme_Object* val,
|  |  |  | Scheme_Env* env)

Adds a value to the table of globals by symbol name instead of string name.

Scheme_Object* |  | scheme_lookup_global | ( | Scheme_Object* symbol,
|  |  |  | Scheme_Env* env)

Given a global variable name (as a symbol) in sym, returns the current value.

Scheme_Bucket* |  | scheme_global_bucket | ( | Scheme_Object* symbol,
|  |  |  | Scheme_Env* env)

Given a global variable name (as a symbol) in sym, returns the bucket where the value is stored. When the value in this bucket is NULL, then the global variable is undefined.

The Scheme_Bucket structure is defined as:

typedef struct Scheme_Bucket {
Scheme_Object so; /* so.type = scheme_variable_type */
void *key;
void *val;
} Scheme_Bucket;

Scheme_Bucket* |  | scheme_module_bucket | ( | Scheme_Object* mod,
|  |  |  | Scheme_Object* symbol,
|  |  |  | int pos,
|  |  |  | Scheme_Env* env)

Like scheme_global_bucket, but finds a variable in a module. The mod and symbol arguments are as for dynamic-require in Racket. The pos argument should be -1 always. The env argument represents the namespace in which the module is declared.

void |  | scheme_set_global_bucket | ( | char* procname,
|  |  |  | Scheme_Bucket* var,
|  |  |  | Scheme_Object* val,
|  |  |  | int set_undef)

Changes the value of a global variable. The procname argument is used to report errors (in case the global variable is constant, not yet bound, or bound as syntax). If set_undef is not 1, then the global variable must already have a binding. (For example, set! cannot set unbound variables, while define can.)

Scheme_Object* |  | scheme_builtin_value | ( | const char* name)

Gets the binding of a name as it would be defined in the initial namespace.

Scheme_Env* |  | scheme_get_env | ( | Scheme_Config* config)

Returns the current namespace for the given parameterization (see Parameterizations). The current thread’s current parameterization is available as scheme_config.

Scheme_Env* |  | scheme_primitive_module | ( | Scheme_Object* name,
|  |  |  | Scheme_Env* for_env)

Prepares a new primitive module whose name is the symbol name (or an alternative that is active via current-module-declare-name). The module will be declared within the namespace for_env. The result is a Scheme_Env * value that can be used with scheme_add_global, etc., but it represents a module instead of a namespace. The module is not fully declared until scheme_finish_primitive_module is called, at which point all variables defined in the module become exported.

void |  | scheme_finish_primitive_module | ( | Scheme_Env* env)

Finalizes a primitive module and makes it available for use within the module’s namespace.
top ← prev up next →