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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
|
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>Chapter5.The Foreign Function Interface</title><meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /><link rel="home" href="index.html" title="SBCL User Manual" /><link rel="up" href="index.html" title="SBCL User Manual" /><link rel="previous" href="extensions.html" title="Extensions" /><link rel="next" href="foreign-types.html" title="Foreign Types" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter5.The Foreign Function Interface</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="extensions.html">Prev</a></td><th width="60%" align="center"></th><td width="20%" align="right"><a accesskey="n" href="foreign-types.html">Next</a></td></tr></table><hr /></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="ffi"></a>Chapter5.The Foreign Function Interface</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ffi.html#ffi-intro">Introduction to the Foreign Function Interface</a></span></dt><dt><span class="sect1"><a href="foreign-types.html">Foreign Types</a></span></dt><dd><dl><dt><span class="sect2"><a href="foreign-types.html#id2933778">Defining Foreign Types</a></span></dt><dt><span class="sect2"><a href="foreign-types.html#id2933813">Foreign Types and Lisp Types</a></span></dt><dt><span class="sect2"><a href="foreign-types.html#id2936865">Foreign Type Specifiers</a></span></dt></dl></dd><dt><span class="sect1"><a href="foreign-values.html">Operations On Foreign Values</a></span></dt><dd><dl><dt><span class="sect2"><a href="foreign-values.html#id2966578">Accessing Foreign Values</a></span></dt><dt><span class="sect2"><a href="foreign-values.html#id2966744">Coercing Foreign Values</a></span></dt><dt><span class="sect2"><a href="foreign-values.html#id2920625">Foreign Dynamic Allocation</a></span></dt></dl></dd><dt><span class="sect1"><a href="foreign-variables.html">Foreign Variables</a></span></dt><dd><dl><dt><span class="sect2"><a href="foreign-variables.html#id2920801">Local Foreign Variables</a></span></dt><dt><span class="sect2"><a href="foreign-variables.html#id2909835">External Foreign Variables</a></span></dt></dl></dd><dt><span class="sect1"><a href="foreign-data-structure.html">Foreign Data Structure Examples</a></span></dt><dt><span class="sect1"><a href="load-object.html">Loading Unix Object Files</a></span></dt><dt><span class="sect1"><a href="foreign-function-calls.html">Foreign Function Calls</a></span></dt><dd><dl><dt><span class="sect2"><a href="foreign-function-calls.html#id2928010">The alien-funcall Primitive</a></span></dt><dt><span class="sect2"><a href="foreign-function-calls.html#id2901125">The define-alien-routine Macro</a></span></dt><dt><span class="sect2"><a href="foreign-function-calls.html#id2956187">define-alien-routine Example</a></span></dt><dt><span class="sect2"><a href="foreign-function-calls.html#id2956237">Calling Lisp From C</a></span></dt></dl></dd><dt><span class="sect1"><a href="ffi-example.html">Step-By-Step Example of the Foreign Function Interface</a></span></dt></dl></div><p>This chapter describes <span class="application">SBCL</span>'s interface to C programs and
libraries (and, since C interfaces are a sort of <span class="foreignphrase"><i class="foreignphrase">lingua
franca</i></span> of the Unix world, to other programs and libraries in
general.)</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>In the modern Lisp world, the usual term for this
functionality is Foreign Function Interface, or <span class="acronym">FFI</span>, where
despite the mention of “<span class="quote">function</span>” in this term, <span class="acronym">FFI</span> also
refers to direct manipulation of C data structures as well as
functions. The traditional <span class="application">CMU CL</span> terminology is Alien Interface, and
while that older terminology is no longer used much in the system
documentation, it still reflected in names in the
implementation, notably in the name of the <tt class="literal">SB-ALIEN</tt>
package.</p></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ffi-intro"></a>Introduction to the Foreign Function Interface</h2></div></div><div></div></div><p>
Because of Lisp's emphasis on dynamic memory allocation and garbage
collection, Lisp implementations use non-C-like memory representations
for objects. This representation mismatch creates friction when a Lisp
program must share objects with programs which expect C data. There
are three common approaches to establishing communication:
</p><div class="itemizedlist"><ul type="disc"><li><p>The burden can be placed on the foreign program
(and programmer) by requiring the knowledge and use of the
representations used internally by the Lisp implementation.
This can require a considerable amount of “<span class="quote">glue</span>” code on the
C side, and that code tends to be sensitively dependent on the
internal implementation details of the Lisp system.</p></li><li><p>The Lisp system can automatically convert objects
back and forth between the Lisp and foreign representations.
This is convenient, but translation becomes prohibitively slow
when large or complex data structures must be shared. This approach
is supported by the <span class="application">SBCL</span> <span class="acronym">FFI</span>, and used automatically
by the when passing integers and strings.</p></li><li><p>The Lisp program can directly manipulate foreign
objects through the use of extensions to the Lisp language.
</p></li></ul></div><p>
</p><p><span class="application">SBCL</span>, like <span class="application">CMU CL</span> before it, relies primarily on the
automatic conversion and direct manipulation approaches. The SB-ALIEN
package provices a facility wherein foreign values of simple scalar
types are automatically converted and complex types are directly
manipulated in their foreign representation. Additionally the
lower-level System Area Pointers (or SAPs) can be used where
necessary to provide untyped access to foreign memory.</p><p>Any foreign objects that can't automatically be converted into
Lisp values are represented by objects of type <tt class="type">alien-value</tt>.
Since Lisp is a dynamically typed language, even foreign objects must
have a run-time type; this type information is provided by
encapsulating the raw pointer to the foreign data within an
<tt class="type">alien-value</tt> object.</p><p>The type language and operations on foreign types are
intentionally similar to those of the C language.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extensions.html">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"><a accesskey="n" href="foreign-types.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Extensions</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">Foreign Types</td></tr></table></div></body></html>
|
