📄 embedding.html
字号:
<html><head><title>CHICKEN User's Manual - Embedding</title></head><body><p> </p><a name="embedding"></a><h1>Embedding</h1><p>Compiled Scheme files can be linked with C code, provided the Scheme code was compiled in <em>embedded</em> mode by passing <tt>-DC_EMBEDDED</tt> to the C compiler (this will disable generation of a <tt>main()</tt> function). <tt>csc</tt> will do this, when given the <tt>-embedded</tt> option. Alternatively pass <tt>-embedded</tt> to <tt>csc</tt>.</p><p>The following C API is available:</p><a name="chicken-parse-command-line"></a><h2>CHICKEN_parse_command_line</h2><pre>[C function] void CHICKEN_parse_command_line (int argc, char *argv[], int *heap, int *stack int *symbols)</pre><p>Parse the programs command-line contained in <tt>argc</tt> and <tt>argv</tt> and return the heap-, stack- and symbol table limits given by runtime options of the form <tt>-:...</tt>, or choose default limits. The library procedure <tt>argv</tt> can access the command-line only if this function has been called by the containing application.</p><a name="chicken-initialize"></a><h2>CHICKEN_initialize</h2><pre>[C function] int CHICKEN_initialize (int heap, int stack, int symbols, void *toplevel) </pre><p>Initializes the Scheme execution context and memory. <tt>heap</tt> holds the number of bytes that are to be allocated for the secondary heap. <tt>stack</tt> holds the number of bytes for the primary heap. <tt>symbols</tt> contains the size of the symbol table. Passing <tt>0</tt> to one or more of these parameters will select a default size. <tt>toplevel</tt> should be a pointer to the toplevel entry point procedure. You should pass <tt>C_toplevel</tt> here. In any subsequent call to <tt>CHICKEN_run</tt> you can simply pass <tt>NULL</tt>. Calling this function more than once has no effect. If enough memory is available and initialization was successful, then <tt>1</tt> is returned, otherwise this function returns <tt>0</tt>.</p><a name="chicken-run"></a><h2>CHICKEN_run</h2><pre>[C function] C_word CHICKEN_run (void *toplevel)</pre><p>Starts the Scheme program. Call this function once to execute all toplevel expressions in your compiled Scheme program. If the runtime system was not initialized before, then <tt>CHICKEN_initialize</tt> is called with default sizes. <tt>toplevel</tt> is the toplevel entry-point procedure, you usually pass <tt>C_toplevel</tt> here. The result value is the continuation that can be used to re-invoke the Scheme code from the point after it called <tt>return-to-host</tt> (see below).</p><p>If you just need a Scheme interpreter, you can also pass <tt>CHICKEN_default_toplevel</tt> as the toplevel procedure, which just uses the default library units.</p><p>Once <tt>CHICKEN_run</tt> has been called, Scheme code is executing until all toplevel expressions have been evaluated or until <tt>return-to-host</tt> is called inside the Scheme program.</p><a name="return-to-host"></a><h2>return-to-host</h2><pre>[procedure] (return-to-host)</pre><p>Exits the Scheme code and returns to the invoking context that called <tt>CHICKEN_run</tt> or <tt>CHICKEN_continue</tt>.</p><p>After <tt>return-to-host</tt> has been executed and once <tt>CHICKEN_run</tt> returns, you can invoke callbacks which have been defined with <tt>define-external</tt>. The <tt>eval</tt> library unit also provides <em>boilerplate</em> callbacks, that simplify invoking Scheme code embedded in a C or C++ application a lot.</p><a name="chicken-eval"></a><h2>CHICKEN_eval</h2><pre>[C macro] int CHICKEN_eval (C_word exp, C_word *result)</pre><p>Evaluates the Scheme object passed in <tt>exp</tt>, writing the result value to <tt>result</tt>. The return value is 1 if the operation succeeded, or 0 if an error occurred. Call <tt>CHICKEN_get_error_message</tt> to obtain a description of the error.</p><a name="chicken-eval-string"></a><h2>CHICKEN_eval_string</h2><pre>[C macro] int CHICKEN_eval_string (char *str, C_word *result)</pre><p>Evaluates the Scheme expression passed in the string <tt>str</tt>, writing the result value to <tt>result</tt>.</p><a name="chicken-eval-to-string"></a><h2>CHICKEN_eval_to_string</h2><pre>[C macro] int CHICKEN_eval_to_string (C_word exp, char *result, int size)</pre><p>Evaluates the Scheme expression passed in <tt>exp</tt>, writing a textual representation of the result into <tt>result</tt>. <tt>size</tt> should specify the maximal size of the result string.</p><a name="chicken-eval-string-to-string"></a><h2>CHICKEN_eval_string_to_string</h2><pre>[C macro] int CHICKEN_eval_string_to_string (char *str, char *result, int size)</pre><p>Evaluates the Scheme expression passed in the string <tt>str</tt>, writing a textual representation of the result into <tt>result</tt>. <tt>size</tt> should specify the maximal size of the result string.</p><a name="chicken-apply"></a><h2>CHICKEN_apply</h2><pre>[C macro] int CHICKEN_apply (C_word func, C_word args, C_word *result)</pre><p>Applies the procedure passed in <tt>func</tt> to the list of arguments <tt>args</tt>, writing the result value to <tt>result</tt>.</p><a name="chicken-apply-to-string"></a><h2>CHICKEN_apply_to_string</h2><pre>[C macro] int CHICKEN_apply_to_string (C_word func, C_word args, char *result, int size)</pre><p>Applies the procedure passed in <tt>func</tt> to the list of arguments <tt>args</tt>, writing a textual representation of the result into <tt>result</tt>.</p><a name="chicken-read"></a><h2>CHICKEN_read</h2><pre>[C macro] int CHICKEN_read (char *str, C_word *result)</pre><p>Reads a Scheme object from the string <tt>str</tt>, writing the result value to <tt>result</tt>.</p><a name="chicken-load"></a><h2>CHICKEN_load</h2><pre>[C macro] int CHICKEN_load (char *filename)</pre><p>Loads the Scheme file <tt>filename</tt> (either in source form or compiled).</p><a name="chicken-get-error-message"></a><h2>CHICKEN_get_error_message</h2><pre>[C macro] void CHICKEN_get_error_message (char *result, int size)</pre><p>Returns a textual description of the most recent error that occurred in executing embedded Scheme code.</p><a name="chicken-yield"></a><h2>CHICKEN_yield</h2><pre>[C macro] int CHICKEN_yield (int *status)</pre><p>If threads have been spawned during earlier invocations of embedded Scheme code, then this function will run the next scheduled thread for one complete time-slice. This is useful, for example, inside an <em>idle</em> handler in a GUI application with background Scheme threads. Note that the <tt>srfi-18</tt> library unit has to be linked in for this.</p><p>An example:</p><pre>% cat x.scm;;; x.scm(define (bar x) (gc) (* x x))(define-external (baz (int i)) double (sqrt i))(return-to-host)</pre><pre>% cat y.c/* y.c */#include <chicken.h>#include <assert.h>extern double baz(int);int main() { char buffer[ 256 ]; int status; C_word val = C_SCHEME_UNDEFINED; C_word *data[ 1 ]; data[ 0 ] = &val; CHICKEN_run(C_toplevel); status = CHICKEN_read("(bar 99)", &val); assert(status); C_gc_protect(data, 1); printf("data: %08x\n", val); status = CHICKEN_eval_string_to_string("(bar)", buffer, 255); assert(!status); CHICKEN_get_error_message(buffer, 255); printf("ouch: %s\n", buffer); status = CHICKEN_eval_string_to_string("(bar 23)", buffer, 255); assert(status); printf("-> %s\n", buffer); printf("data: %08x\n", val); status = CHICKEN_eval_to_string(val, buffer, 255); assert(status); printf("-> %s\n", buffer); printf("->` %g\n", baz(22)); return 0;}% csc x.scm y.c -embedded</pre><p>It is also possible to re-enter the computation following the call to <tt>return-to-host</tt> by calling <tt>CHICKEN_continue</tt>:</p><a name="chicken-continue"></a><h2>CHICKEN_continue</h2><pre>[C function] C_word CHICKEN_continue (C_word k)</pre><p>Re-enters Scheme execution. <tt>k</tt> is the continuation received from the previous invocation of <tt>CHICKEN_run</tt> or <tt>CHICKEN_continue</tt>. When <tt>return-to-host</tt> is called again, this function returns another continuation that can be used to restart again.</p><p>If you invoke callbacks prior to calling <tt>CHICKEN_continue</tt>, make sure that the continuation is not reclaimed by garbage collection. This can be avoided by using <tt>C_gc_protect</tt> or gc-roots.</p><p>Another example:</p><pre>% cat x.scm(require-extension srfi-18)(define m (make-mutex))(define (t) (mutex-lock! m) (thread-sleep! 1) (print (thread-name (current-thread))) (mutex-unlock! m) (t) )(thread-start! (make-thread t 'PING!))(thread-start! (make-thread t 'PONG!))(let loop () (return-to-host) (thread-yield!) (loop) )% cat y.c#include <chicken.h>int main(){ C_word k = CHICKEN_run(C_toplevel); for(;;) k = CHICKEN_continue(k); return 0;}% csc x.scm y.c -embedded</pre><p>It is advisable not to mix repeated uses of <tt>CHICKEN_continue</tt>/<tt>return-to-host</tt> (as in the example above) with callbacks. Once <tt>return-to-host</tt> is invoked, the runtime system and any Scheme code executed prior to the invocation is initialized and can be conveniently used via callbacks.</p><p>A simpler interface For handling GC-safe references to Scheme data are the so called <em>gc-roots</em>:</p><a name="chicken-new-gc-root"></a><h2>CHICKEN_new_gc_root</h2><pre>[C function] void* CHICKEN_new_gc_root ()</pre><p>Returns a pointer to a <em>GC root</em>, which is an object that holds a reference to a Scheme value that will always be valid, even after a garbage collection. The content of the gc root is initialized to an unspecified value.</p><a name="chicken-delete-gc-root"></a><h2>CHICKEN_delete_gc_root</h2><pre>[C function] void CHICKEN_delete_gc_root (void *root)</pre><p>Deletes the gc root.</p><a name="chicken-gc-root-ref"></a><h2>CHICKEN_gc_root_ref</h2><pre>[C macro] C_word CHICKEN_gc_root_ref (void *root)</pre><p>Returns the value stored in the gc root.</p><a name="chicken-gc-root-set"></a><h2>CHICKEN_gc_root_set</h2><pre>[C macro] void CHICKEN_gc_root_set (void *root, C_word value)</pre><p>Sets the content of the GC root to a new value.</p><p>Sometimes it is handy to access global variables from C code:</p><a name="chicken-global-lookup"></a><h2>CHICKEN_global_lookup</h2><pre>[C function] void* CHICKEN_global_lookup (char *name)</pre><p>Returns a GC root that holds the global variable with the name <tt>name</tt>. If no such variable exists, <tt>NULL</tt> is returned.</p><a name="chicken-global-ref"></a><h2>CHICKEN_global_ref</h2><pre>[C function] C_word CHICKEN_global_ref (void *global)</pre><p>Returns the value of the global variable referenced by the GC root <tt>global</tt>.</p><a name="chicken-global-set"></a><h2>CHICKEN_global_set</h2><pre>[C function] void CHICKEN_global_set (void *global, C_word value)</pre><p>Sets the value of the global variable referenced by the GC root <tt>global</tt> to <tt>value</tt>.</p><p>Previous: <a href="foreign-type-specifiers.html" class="internal">Foreign type specifiers</a></p><p>Next: <a href="callbacks.html" class="internal">Callbacks</a></p></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -