txlyre
/
avram


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on November 8, 2012 by texi2html 1.82
texi2html was written by: 
            Lionel Cons <[email protected]> (original author)
            Karl Berry  <[email protected]>
            Olaf Bachmann <[email protected]>
            and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <[email protected]>
-->
<head>
<title>avram - a virtual machine code interpreter: 2.7.16.1 Library combinator</title>

<meta name="description" content="avram - a virtual machine code interpreter: 2.7.16.1 Library combinator">
<meta name="keywords" content="avram - a virtual machine code interpreter: 2.7.16.1 Library combinator">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<a name="Library-combinator"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Interfaces-to-External-Code.html#Interfaces-to-External-Code" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Have-combinator.html#Have-combinator" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="Virtual-Machine-Specification.html#Virtual-Machine-Specification" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="Interfaces-to-External-Code.html#Interfaces-to-External-Code" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<hr size="1">
<a name="Library-combinator-1"></a>
<h4 class="subsubsection">2.7.16.1 Library combinator</h4>

<p>The simplest and fastest method of interfacing to an external library
is by way of a virtual machine combinator called <code>library</code>. It
takes two non-empty character strings as arguments to a virtual code
program of the form implied by the following property.
</p><dl compact="compact">
<dt> <em>T33</em></dt>
<dd><p>[[<code>library</code>]] (<code><var>x</var></code>,<code><var>y</var></code>) = <code>((nil,nil),((<var>x</var>,<var>y</var>),(nil,nil)))</code>
</p></dd>
</dl>

<p>Intuitively, <var>x</var> is the name of a library and <var>y</var> is the name
of a function within the library. For example, if <var>x</var> is
<code>'math'</code> and <var>y</var> is <code>'sqrt'</code>, then
<code>library</code>(<var>x</var>,<var>y</var>) represents the function that computes
the square root of a floating point number as defined by the host
machine&rsquo;s native C implementation, normally in IEEE double precision
format.  Different functions and libraries may involve other argument
and result types, such as complex numbers, arrays, sparse matrices, or
arbitrary precision numbers. A list of currently supported external
library names with their functions and calling conventions is given in
<a href="External-Libraries.html#External-Libraries">External Libraries</a>.
</p>
<p>On the virtual code side, all function arguments and results
regardless of their types are encoded as nested pairs of <code>nil</code>,
as always, and may be manipulated or stored as any other data,
including storage and retrieval from files in &lsquo;<tt>.avm</tt>&rsquo; virtual
code format (<a href="File-Format.html#File-Format">File Format</a>). However, on the C side,
various memory management and caching techniques are employed to
maintain this facade while allowing the libraries to operate on data
in their native format. The details are given more fully in the API
documentation, particularly in <a href="Type-Conversions.html#Type-Conversions">Type Conversions</a> and
<a href="External-Library-Maintenance.html#External-Library-Maintenance">External Library Maintenance</a>.
</p>
<p>While this style is fast and convenient, it is limited either to
libraries that have already been built into the virtual machine, or to
those for which the user is prepared to implement a new interface
module in C as described in <a href="Implementing-new-library-functions.html#Implementing-new-library-functions">Implementing new library functions</a>.
</p>
<hr size="1">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Interfaces-to-External-Code.html#Interfaces-to-External-Code" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Have-combinator.html#Have-combinator" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="Virtual-Machine-Specification.html#Virtual-Machine-Specification" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="Interfaces-to-External-Code.html#Interfaces-to-External-Code" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
 <font size="-1">
  This document was generated on <i>November 8, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
 </font>
 <br>

</p>
</body>
</html>