CFFI: Common LispからCの機能を利用する

## CFFIについて

ほとんどのCommon Lisp処理系はCの共有ライブラリにアクセスする何らかの方法を用意しているが、これらは独自拡張なので、各処理系間でAPIが統一されていない。この違いを吸収するためのCFFIというライブラリがあり、Cライブラリを呼ぶときはCFFIを使うのが常套手段となっている。
CFFIの情報源としては以下のようなものがある。

- [CFFI User Manual](https://common-lisp.net/project/cffi/manual/cffi-manual.html)
- [CFFI - Common LISP users jp](https://lisphub.jp/common-lisp/users/index.cgi?CFFI)
- [Common Lisp Recipes(19章)](https://www.apress.com/jp/book/9781484211779?gtmf=s)

## インストール
quicklispからインストールできる。

```common-lisp
(ql:quickload :cffi)
```

## 共有ライブラリを作成する
まず、Cでべき乗を計算する関数を書く。

```c
double power (double base, int exponent) {
  int i;
  double result = 1.0;
  for (i = 1; i <= exponent; i++)
    result *= base;
  return result;
}
```

これを`test.c`に保存してコンパイルし、共有ライブラリを作る。

```
gcc -fpic -shared test.c -o test.so
```

## ライブラリ読み込み

共有ライブラリは`load-foreign-library`関数によって読み込む。

直接絶対パスを指定してライブラリを読み込む場合はこう書く。

```common-lisp
(cffi:load-foreign-library "/path/to/test.so")
```

絶対パスではなく、ライブラリのファイル名だけ書く方法もある。その場合デフォルトのサーチパスから探される。例えばLinuxなら`/lib`と`/usr/lib`から、MacOSなら`~/lib`、`/usr/local/lib`、`/usr/lib`から探される。サーチパスに他のディレクトリを追加するには`cffi:*foreign-library-directories*`を変更する。

```common-lisp
(push #P"/path/to/" cffi:*foreign-library-directories*)
(cffi:load-foreign-library "test.so")
```

`:default`キーワードを付けると拡張子も環境から自動で決まる。`:or`キーワードを付けると存在しているいずれかのライブラリを使う。

```common-lisp
(cffi:load-foreign-library '(:default "test"))
(cffi:load-foreign-library '(:or "test.so.3" "test.so"))
```

より柔軟に環境に合わせた設定をするために、複数の環境ごとの設定をまとめて名前を付けることができる。

```common-lisp
(cffi:define-foreign-library test-lib
  (:darwin (:or "test.3.dylib" "test.dylib"))
  (:windows (:or "test.dll" "test.dll"))
  (t (:default "test")))

(cffi:load-foreign-library 'test-lib)
```

## LispからCの関数を呼び出す

```common-lisp
(cffi:foreign-funcall "power"     ; 関数名
                      :double 2d0 ; 引数1
                      :int 10     ; 引数2
                      :double)    ; 返り値の型
;; => 1024.0d0
```

`foreign-funcall`で呼び出す度に毎回型を指定するのは面倒だし、エディタによる補完も効かない。そこで`power`のラッパー関数を定義しておく。

```common-lisp

(cffi:defcfun "power" :double
  (base :double)
  (exponent :int))

(power 2d0 10)
;; => 1024.0d0
```

Cの関数名は自動的にLisp風に変換される。例えば`"c_power_num"`だったらラッパー関数の名前は`c-power-num`になる。明示的にラッパー関数に名前をつける場合は次のように書く。

```common-lisp
(cffi:defcfun ("c_power_num" power) :double
  (base :double)
  (exponent :int))
```

## Cのポインタの取扱い
ポインタの例として、K&Rとかにも出てくる2つの値を交換する関数`swap`を定義する。

```common-lisp

void swap (int *a, int *b) {
  int t = *b;
  *b = *a;
  *a = t;
}
```

次に、LispからCのswap関数を呼ぶためのラッパーを定義する。この際、引数の型に`:pointer`を指定する。

```common-lisp

(cffi:defcfun swap :void
  (a :pointer)
  (b :pointer))
```

この関数を呼び出すには、まずLisp側からCのメモリ領域を確保し、そのメモリ領域へのポインタを表すオブジェクトを作ってswap関数に渡す。
以下は実際に`foreign-alloc`関数でint型のCオブジェクトのメモリ領域を2つ生成し、swap関数を適用する例である。Cのメモリ領域はGCによって回収されないので、最後に`foreign-free`関数で開放してやる必要がある。

```common-lisp
(defparameter *a* (cffi:foreign-alloc :int))
;; => #.(SB-SYS:INT-SAP #X7FFFDC000F80) ; system-area-pointer

;; ポインタが差すデータを参照するにはmem-refを使う。setfで代入もできる
(cffi:mem-ref *a* :int)           ; =>  0
(setf (cffi:mem-ref *a* :int) 10) ; => 10
(cffi:mem-ref *a* :int)           ; => 10

;; :initial-elementで初期値を指定することもできる
(defparameter *b* (cffi:foreign-alloc :int :initial-element 20))

;; 外部関数のswapを呼び出す
(swap *a* *b*)
(cffi:mem-ref *a* :int) ; => 20
(cffi:mem-ref *b* :int) ; => 10

(defparameter result
  (list (cffi:mem-ref *a* :int) (cffi:mem-ref *b* :int)))

;; メモリ開放
(cffi:foreign-free *a*)
(cffi:foreign-free *b*)

result ; => (20 10)
```

外部オブジェクトのメモリ開放後も`result`が値を保持しているので、`mem-ref`する度にLispオブジェクトを生成していることが分かる。

`with-foreign-objects`マクロを使うと上の一連の流れをまとめてやることができる。

```common-lisp
(cffi:with-foreign-objects ((a :int) (b :int))
  (setf (cffi:mem-ref a :int) 10
        (cffi:mem-ref b :int) 20)
  (print (list (cffi:mem-ref a :int) (cffi:mem-ref b :int)))
  (swap a b)
  (list (cffi:mem-ref a :int) (cffi:mem-ref b :int)))
;; (10 20)
;; => (20 10)
```

特に何も指定しなくてもメモリ開放が保証されるのでこちらの方が安全といえる。

Cのポインタは型付きだが、Lispのポインタは何でも指せる。その代わりにmem-refに`(cffi:mem-ref :int)`のように呼び出し側で型情報を付けてやる必要がある。
ラッパー関数の引数のポインタに型を付けることもできるが、型チェックとかはしてくれない。試しにラッパー関数ではintへのポインタと宣言しているところにdoubleで確保した領域へのポインタを渡してみるとどうなるか。

```common-lisp

(cffi:defcfun swap :void
  (a (:pointer :int))
  (b (:pointer :int)))

;; bをdoubleにしてswapを呼んでみる
(cffi:with-foreign-objects ((a :int) (b :double))
  (setf (cffi:mem-ref a :int) 42
        (cffi:mem-ref b :double) 23d0)
  (print (list (cffi:mem-ref a :int)
               (cffi:mem-ref b :double)))
  (swap a b)
  (list (cffi:mem-ref a :double) (cffi:mem-ref b :int)))
;; (42 23.0d0) 
;; => (0.0d0 42)
```

エラーは起こらないがswapした結果がおかしなことになる。
ここで何が起こっているかを理解するためには、mem-refで指定する型によって参照する領域が決まることを理解しておく必要がある。
例として、short型の領域を2つ生成し、それらをまとめて4バイトのfloat型として参照してみる。Cオブジェクトの領域を生成するには`foreign-alloc`関数を使う。

```common-lisp
(defparameter *test* (cffi:foreign-alloc :short :initial-contents (list 42 23)))

;; 型のサイズ
(cffi:foreign-type-size :short) ; => 2
(cffi:foreign-type-size :float) ; => 4

(list (cffi:mem-ref *test* :short)
      (cffi:mem-ref *test* :short 2) ; 先頭から2バイト先をshort型と解釈して参照する
      (cffi:mem-ref *test* :float))  ; short型2個をfloat型1個と解釈して参照する
;; => (42 23 2.1122753e-39)
```

このように問題なく参照できてしまう。

## Cの配列の取り扱い
上の例で`foreign-alloc`でshort型が2つ並んだ領域を作ったが、配列も基本的にこれと同じになる。
例えば、C側で次のように配列の総和を取る関数を定義したとする。

```c

double sum (double *arr, int size) {
  int i;
  double result = 0.0;
  for (i = 0; i < size; i++) {
    result += arr[i];
  }
  return result;
}
```

これをLisp側から呼び出してみる。

```cl
(cffi:defcfun sum :double
  (arr :pointer)
  (size :int))

(defparameter *arr*
  (cffi:foreign-alloc :double
                      :initial-contents
                      (loop for x from 1d0 to 10d0 collect x)))

(loop for i from 0 below 10 collect
  (cffi:mem-aref *arr* :double i)) ; mem-refとは違うことに注意
;; => (1.0d0 2.0d0 3.0d0 4.0d0 5.0d0 6.0d0 7.0d0 8.0d0 9.0d0 10.0d0)

(sum *arr* 10) ; => 55.0d0
```

`foreign-alloc`は`make-array`と似たような感じで、`:initial-contents`でリストによって初期値を指定することができる。また`:count`キーワードで個数を指定して領域を取ってくることもできる。その際に`:initial-element`を指定しておくとその値で埋め尽くされる。

配列を参照するには`mem-aref`を使う。`mem-ref`では第3引数に先頭からのバイト数を指定していたが、`mem-aref`はインデックスになっているところが違う。

```cl
;; mem-refはバイト数
(cffi:mem-ref *arr* :double 0) ; => 1.0d0
(cffi:mem-ref *arr* :double 8) ; => 2.0d0
;; mem-arefはインデックス
(cffi:mem-aref *arr* :double 0) ; => 1.0d0
(cffi:mem-aref *arr* :double 1) ; => 2.0d0
```

`mem-aref`も`setf`が使えるので、`foreign-alloc`に`:count`キーワードを付けて長さで領域を取ってきてから値を代入して初期化するという方法もある。

```cl
(defparameter *arr2* (cffi:foreign-alloc :double :count 10))

(loop for i from 0 below 10 do
  (setf (cffi:mem-aref *arr2* :double i) (+ i 1d0)))

(sum *arr2* 10) ; => 55.0d0

;; 後始末
(cffi:foreign-free *arr*)
(cffi:foreign-free *arr2*)
```

`with-foreign-objects`のオプショナル引数に配列の長さを指定しても同じことができる。

```cl
(cffi:with-foreign-objects ((arr :double 10))
  (loop for i from 0 below 10 do
    (setf (cffi:mem-aref arr :double i) (+ i 1d0)))
  (sum arr 10))
```

C側からLispの配列にアクセスするにはLisp処理系が対応していなければならないらしく、Lispworksとかにはそのインターフェースがあるらしいが、CFFIではサポートされてない。

## Cの文字列の取り扱い

文字列も配列の場合と似ているが、いくつか便利なユーティリティが用意されている。
例として、文字列を大文字に破壊的に変更するCの関数を定義する。

```c

char *str_toupper(char *s)
{
    char *p;
    for (p = s; *p; p++)
        *p = toupper(*p);
    return (s);
}
```

これに対するラッパー関数`toupper`を定義する。

```cl
(cffi:defcfun ("str_toupper" toupper) (:pointer :char)
  (s (:pointer :char)))
```

数値の配列と同様に`foreign-alloc`でCの文字列オブジェクトを生成することもできるが、文字列用に`foreign-string-alloc`が用意されている。これはLispの文字列を受け取り、Cの文字列のための領域を確保し、初期化する。逆にCの文字列からLispの文字列に戻すには`foreign-string-to-lisp`が使える。

```cl

(defparameter *str* (cffi:foreign-string-alloc "hello"))

(toupper *str*)

(cffi:foreign-string-to-lisp *str*)
;; => "HELLO"

;; 後始末
(cffi:foreign-free *str*)
```

これまでと同様に、領域の確保と開放までを行う`with-foreign-strings`マクロもある。

```cl
(cffi:with-foreign-strings ((str "hello"))
  (toupper str)
  (cffi:foreign-string-to-lisp str))

;; => "HELLO"
```

## Cの構造体の取り扱い

構造体の場合も関数と同じで、Cの定義に対応するものをLisp側でも定義する。

```c
struct complex {
  double real;
  double imag;
};
double magnitude_squared (struct complex *c) {
  return c->real * c->real + c->imag * c->imag;
}
```

```cl
(cffi:defcstruct c-complex
  (real :double)
  (imag :double))

;; 構造体へのポインタを引数に取る関数
(cffi:defcfun "magnitude_squared" :double
  (c :pointer))
```

ここで定義した構造体のオブジェクトを生成するのにもこれまでと同様に`foreign-alloc`/`with-foreign-object`/`with-foreign-objects`が使える。型としては`'(:struct c-complex)`を指定する。構造体のスロットにアクセスするには`foreign-slot-value`を使う。

```cl
(cffi:with-foreign-object (c '(:struct c-complex))
  (setf (cffi:foreign-slot-value c '(:struct c-complex) 'real) 3d0
        (cffi:foreign-slot-value c '(:struct c-complex) 'imag) 4d0)
  ;; 初期化した構造体へのポインタをCの関数へ渡す
  (sqrt (magnitude-squared c)))
;; => 5.0d0
```