Hide Login/Register to vote and to have access to more features

You are here: Root > By Topic > FFI

View the dependency graph for this library

Foreign Structures By Value
Created by liam on: Mon, 04 May 2009 04:22:09 GMT, Last modification: Mon, 04 May 2009 04:22:09 GMT

Call foreign functions when one or more arguments and/or the return value are structures. In CFFI and most Lisp foreign interfaces, structures must be passed by reference, that is, as pointers. FSBV permits calling them by value.

eMail	lhealy@common-lisp.net
Web site	http://repo.or.cz/w/fsbv.git
Mailing list
Version	0.1 - Sunday, 03 May 2009
Maturity	Alpha
OS compatibility	N/A
ASDF installable	No
Official Download	git://repo.or.cz/fsbv.git
Mirrored Download
Source code repository	git

Description

Call foreign functions when one or more arguments and/or the return value are structures. In CFFI and most Lisp foreign interfaces, structures must be passed by reference, that is, as pointers. FSBV permits calling them by value. It requires CFFI and libffi.

Example

For example, the complex type is defined in the GNU Scientific Library (GSL) as

typedef struct
  {
    double dat[2];
  }
gsl_complex;

The function gsl_complex_conjugate takes and returns a structure of this type by value,

gsl_complex gsl_complex_conjugate (gsl_complex z);

If we define

(defcstruct (complex :constructor complex :deconstructor (realpart imagpart))
  (dat :double :count 2))
(defcfun (complex-conjugate "gsl_complex_conjugate") complex
  (c complex))

then we can call this function from Lisp:

(complex-conjugate #c(3.0d0 4.0d0))
#C(3.0 -4.0)

Definitions

The following definitions provide the call by value capability, and provide a convenient way of making equivalent Lisp and foreign objects:

• Macro: fsbv:defcstruct name-and-options &body doc-and-slots ⇒ name

  name-and-options ::= structure-name | (structure-name &key constructor deconstructor)

  doc-and-slots ::= [docstring] { (slot-name slot-type &key count offset) }*

  Define the foreign structure to Lisp. The constructor is a symbol that when called on the components in order creates a Lisp object with the same contents as the foreign object; default is list. The deconstructor is a symbol that when called on the Lisp object and a sequence number n selects the n-th component of that object, or it is a list of symbols that select the parts of the object in order; default is elt.

• Macro: fsbv:defcfun name-and-options return-type &body [docstring] arguments [&rest] ⇒ lisp-name

  name-and-options ::= name | (name) name ::= lisp-name [foreign-name] | foreign-name [lisp-name] arguments ::= { (arg-name arg-type) }*

  This is used the same as cffi:defcfun, except that options are not supported in name-and-options.

• Macro: fsbv:foreign-funcall name-and-options &rest arguments ⇒ return-value

  This is called the same as cffi:foreign-funcall, except that if the name is a symbol (as opposed to a string), the preparation defined by a previous fsbv:defcfun for that function name will be used. If foreign-funcall specifies no structures by value in its list of arguments or return type, it expands as cffi:foreign-funcall.

• Macro: fsbv:defcenum-aux (name) &optional (base-type :int)

  For the C enumeration name which has been defined using cffi:defcenum, make auxiliary definitions for FSBV.

• Macro: fsbv:with-foreign-objects (bindings) &body body

  bindings ::= {(var type &optional initial-value)}*

  Bind var to a pointer of a foreign object of type type which has optionally been initialized to the initial-value.

There are also functions fsbv:object and (setf fsbv:object) that create the Lisp object from the foreign pointer and type, and vice versa. They are used internally but are exported for the convenience of users. When FSBV is loaded, it will put :fsbv in *features*.

Note: all arguments to the function, and the return value, will gain an additional layer of indirection. This means that arguments normally sent by reference (as a pointer) will require a pointer to the pointer.

Copying

Copyright © 2009 Liam Healy <lhealy at common-lisp.net>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

---

Time-stamp: <2009-05-03 12:12:50EDT readme.html>

Required Libraries  View graph

ASDF | CFFI - the Common Foreign Function Interface

Authors and Maintainers

Liam Healy

Tags

FFI | Compatibility layers

See Also

GNU Scientific Library for Lisp

0 Notes and 0 comments