/usr/share/doc/chicken-bin/manual-html/Callbacks.html is in chicken-bin 4.9.0.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | <!doctype html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rel="stylesheet" href="manual.css" type="text/css" /></head>
<title>Chicken » Callbacks</title>
<meta name="viewport" content="initial-scale=1" /></html>
<body>
<div id="body">
<div id="main">
<div id="toc">
<h2 class="toc">TOC »</h2>
<ul class="toc">
<li><a href="#sec:Callbacks">Callbacks</a>
<ul>
<li><a href="#sec:define-external">define-external</a></li>
<li><a href="#sec:C_callback">C_callback</a></li>
<li><a href="#sec:C_callback_adjust_stack">C_callback_adjust_stack</a></li></ul></li></ul></div><h2 id="sec:Callbacks"><a href="#sec:Callbacks">Callbacks</a></h2><p>To enable an external C function to call back to Scheme, the form <tt>foreign-safe-lambda</tt> (or <tt>foreign-safe-lambda*</tt>) has to be used. This generates special code to save and restore important state information during execution of C code. There are two ways of calling Scheme procedures from C: the first is to invoke the runtime function <tt>C_callback</tt> with the closure to be called and the number of arguments. The second is to define an externally visible wrapper function around a Scheme procedure with the <tt>define-external</tt> form.</p><p>Note: the names of all functions, variables and macros exported by the CHICKEN runtime system start with <tt>C_</tt>. It is advisable to use a different naming scheme for your own code to avoid name clashes. Callbacks (defined by <tt>define-external</tt>) do not capture the lexical environment.</p><p>Non-local exits leaving the scope of the invocation of a callback from Scheme into C will not remove the C call-frame from the stack (and will result in a memory leak). <b>Note:</b> The same applies to SRFI-18 threading, which is implemented with <tt>call/cc</tt>; additionally, if you enter one callback, switch threads and then exit a different callback, your program is likely to crash.</p><h3 id="sec:define-external"><a href="#sec:define-external">define-external</a></h3><dl class="defsig"><dt class="defsig" id="def:define-external"><span class="sig"><tt>(define-external [QUALIFIERS] (NAME (ARGUMENTTYPE1 VARIABLE1) ...) RETURNTYPE BODY ...)</tt></span> <span class="type">syntax</span></dt>
<dt class="defsig" id="def:define-external"><span class="sig"><tt>(define-external NAME TYPE [INIT])</tt></span> <span class="type">syntax</span></dt>
<dd class="defsig"><p>The first form defines an externally callable Scheme procedure. <tt>NAME</tt> should be a symbol, which, when converted to a string, represents a legal C identifier. <tt>ARGUMENTTYPE1 ...</tt> and <tt>RETURNTYPE</tt> are foreign type specifiers for the argument variables <tt>VAR1 ...</tt> and the result, respectively. <tt>QUALIFIERS</tt> is an optional qualifier for the foreign procedure definition, like <tt>__stdcall</tt>.</p>
<pre class="highlight colorize"><span class="paren1">(<span class="default"><i><span class="symbol">define-external</span></i> <span class="paren2">(<span class="default">foo <span class="paren3">(<span class="default">c-string x</span>)</span></span>)</span> int <span class="paren2">(<span class="default">string-length x</span>)</span></span>)</span></pre><p>The second form of <tt>define-external</tt> can be used to define variables that are accessible from foreign code. It declares a global variable named by the symbol <tt>NAME</tt> that has the type <tt>TYPE</tt>. <tt>INIT</tt> can be an arbitrary expression that is used to initialize the variable. <tt>NAME</tt> is accessible from Scheme just like any other foreign variable defined by <tt>define-foreign-variable</tt>.</p>
<pre class="highlight colorize"><span class="paren1">(<span class="default"><i><span class="symbol">define-external</span></i> foo int 42</span>)</span>
<span class="paren1">(<span class="default"><span class="paren2">(<span class="default">foreign-lambda* int <span class="paren3">(<span class="default"></span>)</span>
<span class="string">"C_return(foo);"</span></span>)</span></span>)</span> ==> 42</pre><p><b>Note:</b> don't be tempted to assign strings or bytevectors to external variables. Garbage collection moves those objects around, so it is a very bad idea to assign pointers to heap-data. If you have to do so, then copy the data object into statically allocated memory (for example by using <tt>object-evict</tt>).</p><p>Results of type <tt>scheme-object</tt> returned by <tt>define-external</tt> are always allocated in the secondary heap, that is, not in the stack.</p></dd>
</dl>
<h3 id="sec:C_callback"><a href="#sec:C_callback">C_callback</a></h3><pre>[C function] C_word C_callback (C_word closure, int argc)</pre><p>This function can be used to invoke the Scheme procedure <tt>closure</tt>. <tt>argc</tt> should contain the number of arguments that are passed to the procedure on the temporary stack. Values are put onto the temporary stack with the <tt>C_save</tt> macro.</p><h3 id="sec:C_callback_adjust_stack"><a href="#sec:C_callback_adjust_stack">C_callback_adjust_stack</a></h3><pre>[C function] void C_callback_adjust_stack (C_word *ptr, int size)</pre><p>The runtime-system uses the stack as a special allocation area and internally holds pointers to estimated limits to distinguish between Scheme data objects inside the stack from objects outside of it. If you invoke callbacks at wildly differing stack-levels, these limits may shift from invocation to invocation. Callbacks defined with <tt>define-external</tt> will perform appropriate adjustments automatically, but if you invoke <tt>C_callback</tt> manually, you should perform a <tt>C_callback_adjust_stack</tt> to make sure the internal limits are set properly. <tt>ptr</tt> should point to some data object on the stack and <tt>size</tt> is the number of words contained in the data object (or some estimate). The call will make sure the limits are adjusted so that the value pointed to by <tt>ptr</tt> is located in the stack.</p><hr /><p>Previous: <a href="Embedding.html">Embedding</a></p><p>Next: <a href="Locations.html">Locations</a></p></div></div></body>
|