2.7.16.1 Library combinator

The simplest and fastest method of interfacing to an external library is by way of a virtual machine combinator called library. It takes two non-empty character strings as arguments to a virtual code program of the form implied by the following property.

T33

[[library]] (x,y) = ((nil,nil),((x,y),(nil,nil)))

Intuitively, x is the name of a library and y is the name of a function within the library. For example, if x is 'math' and y is 'sqrt', then library(x,y) represents the function that computes the square root of a floating point number as defined by the host machine’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 External Libraries.

On the virtual code side, all function arguments and results regardless of their types are encoded as nested pairs of nil, as always, and may be manipulated or stored as any other data, including storage and retrieval from files in ‘.avm’ virtual code format (File Format). 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 Type Conversions and External Library Maintenance.

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 Implementing new library functions.

This document was generated on December 10, 2012 using texi2html 1.82.