境界を越えると何を共有できなくなるか
ある言語から別の言語やネイティブライブラリの関数を呼ぶ仕組みをFFIと呼びます。同じプロセス内で呼び出していても、型、メモリ管理、例外の規則まで自動的に共有されるわけではありません。Python側で整数として扱っている値が、C側のどの幅の整数へ入るか、配列がどの長さで存在するかは、境界の契約として決める必要があります。
この教材ではLinux、Python 3.12、C11の小例を使います。Cが配列の合計を計算し、Pythonが入力と結果の領域を持ちます。まず所有権と借用の教材を読み、誰が領域を持ち、いつまで参照できるかを説明できるようにしてください。実行例は別プロセスの使い捨てディレクトリで検証しています。異なるOSの共有ライブラリ形式や呼出し規約まで同じコマンドで再現できるとはしていません。対象のABIとライブラリの版も、実際の統合では確認が必要です。
契約を型名だけで終わらせない
入力は最大四つのuint32_t、出力はuint64_t、個数はsize_tと定めます。C関数は呼出し中だけ入力を読み、ポインタを保存せず、領域を解放しません。結果の置き場所も呼出し側が用意します。正常時は0を返し、無効なポインタ条件では1、上限を超える個数では2を返します。失敗時に出力値を変更しないことも契約に含めます。
四つに制限した理由は、小例の境界を明確にし、uint32_t四つの和がuint64_tへ収まることを容易に確認するためです。任意長の集計APIを作ったわけではありません。また、ポインタと個数を渡しても、C側は実際に確保された領域の容量を一般には知りません。個数が上限内なら常に安全という意味でもありません。呼出し側が、その個数以上の要素を持つ有効な領域を維持する必要があります。型、容量、期間の三つを別々に記しておくと、隠れた前提が見つかります。
| 領域 | 所有・解放担当 | C側の利用期間 |
|---|---|---|
| 入力配列 | Python側 | 呼出し中だけ読取り |
| 出力値 | Python側 | 正常時に呼出し中だけ書込み |
| 保存したポインタ | このAPIでは禁止 | 呼出し後の利用はなし |
C側は状態を返して失敗を伝える
次のコードをsum_u32.cとして保存します。gcc -std=c11 -O2 -Wall -Wextra -Werror -shared -fPIC sum_u32.c -o libsum_u32.soで共有ライブラリを作ります。出力ポインタと上限を先に検査し、countが正のときだけ入力ポインタを必要とします。読み終わるまで*outへ書かないため、この関数内の拒否では結果を変更しません。
ここでの検査は、任意の不正ポインタを安全に見分ける仕組みではありません。NULL以外のポインタでも、解放済みや短すぎる領域なら安全に読めるとは限りません。そのような未定義動作を起こす入力は実行しません。C++などの例外を使う実装なら、例外を境界の内側で捕捉して状態値へ変換する契約も必要になります。このCの小例は例外の伝播を実装せず、戻り値で失敗を伝える方式を採用しています。
#include <stdint.h>
#include <stddef.h>
int sum_u32(const uint32_t *values, size_t count, uint64_t *out) {
if (out == NULL) return 1;
if (count > 4) return 2;
if (count > 0 && values == NULL) return 1;
uint64_t total = 0;
for (size_t i = 0; i < count; i++) total += values[i];
*out = total;
return 0;
}Python側で幅と事前条件を明示する
次のコードを同じディレクトリのffi_check.pyへ保存し、python3.12 ffi_check.pyで実行します。argtypesとrestypeを指定して、入力ポインタ、個数、出力ポインタ、状態値の型を対応させます。未指定の戻り値の扱いに頼ると、実際のCの宣言と一致しない解釈をしてしまう可能性があります。固定幅の整数とsize_tを区別している点を確認してください。
ラッパーはPython整数の範囲を先に検査します。整数から固定幅型への変換が、期待する範囲検査を自動的に行うとは考えません。boolもこのAPIでは入力として受け入れないため、type(v) is intを使っています。配列とresultは呼出しが終わるまでPythonの変数から保持され、Cはその範囲だけ借用します。正常値、32ビットを超える合計、空配列、拒否すべき値の全assertが成功したことを、Python 3.12.14とGCC 13.3.0で確認しています。
import ctypes as C
from pathlib import Path
lib = C.CDLL(str(Path('libsum_u32.so').resolve()))
lib.sum_u32.argtypes = [C.POINTER(C.c_uint32), C.c_size_t, C.POINTER(C.c_uint64)]
lib.sum_u32.restype = C.c_int
def checked_sum(values):
if len(values) > 4:
raise ValueError('at most four values')
if any(type(v) is not int or not 0 <= v <= 0xffffffff for v in values):
raise ValueError('uint32 values required')
array = (C.c_uint32 * len(values))(*values)
result = C.c_uint64(0)
status = lib.sum_u32(array, len(values), C.byref(result))
if status != 0:
raise RuntimeError('native status ' + str(status))
return result.value
assert checked_sum([1, 2, 3]) == 6
assert checked_sum([0xffffffff, 1]) == 4294967296
assert checked_sum([]) == 0
for bad in [[-1], [0x100000000], [True], [1, 2, 3, 4, 5]]:
try:
checked_sum(bad)
except ValueError:
pass
else:
raise AssertionError('invalid input accepted')
result = C.c_uint64(99)
assert lib.sum_u32(None, 1, C.byref(result)) == 1
assert result.value == 99
assert lib.sum_u32(None, 5, C.byref(result)) == 2
assert result.value == 99
print('FFI values, widths, and error contracts passed')解放担当とポインタを保持する期間を決める
この例では、入力と出力をPython側が管理し、C側でmallocやfreeを呼びません。したがって、解放関数の組合せをまたぐ問題を小例から外しています。実際のAPIがC側で確保した領域を返す場合は、どの関数で、いつ、何回だけ解放するかを契約へ追加します。返されたポインタへ、名前の似た任意の解放関数を当てればよいわけではありません。
非同期にポインタを保存するAPIでは、呼出しが戻った時点で借用が終わるという前提が使えません。終了通知まで元の領域やコールバックを保持する仕組みが必要です。GCが領域を動かす処理系なら、固定やハンドルの扱いも確認します。C側が保存していることをGCが自動的に理解するとは限りません。所有者、借用者、最後の利用時点、解放する関数を表にすると、同期の小例から非同期の統合へ移る際の不足がはっきりします。
文字列とエラーには別の変換規則がある
配列を文字列へ変える場合は、バイト列か文字列か、文字コードは何か、長さの単位は何かを決めます。Cの終端付き文字列は途中のゼロで終わる場合がありますが、長さ付きのバイト列はゼロを内容として持てます。Pythonで見える文字数を、そのままCへ渡すバイト長に使うと、UTF-8などの可変長表現で食い違います。型名にcharがあるだけでは契約を確定できません。
エラーも同様です。errnoを読むなら、対象APIがそれを設定する条件と、呼出し直後に正しく取得する方法を確認します。すべての非ゼロ値を同じ例外へ変えるだけでは、再試行できる失敗と入力の誤りを区別できなくなる場合があります。この小例では状態1と2を使い、Python側では通常それらへ到達しない事前検査を置きました。境界の検査が両側にあっても、それぞれが何を保証しているかは別に説明します。
関数のABIと保存形式を同じものにしない
固定幅のuint32_tを使ったことから、そのメモリ表現をそのままネットワークやファイルへ保存して互換になるとは限りません。バイト順、構造体の詰め方、アラインメントは、関数を呼び出すABIと、長期保存や通信の形式とで別に決めます。この例は同じプロセスの配列を関数へ渡しており、通信形式を定義していません。
実際に外へ保存する要件があるなら、フィールドの幅、バイト順、長さ、版を定めた表現へ変換します。sizeofが同じであることだけを、異なる環境の互換性の根拠にはしません。C側とPython側が同じABIへ対応している確認と、保存データが将来も読める確認には、別々の試験が必要です。関数の境界を越えた値を、今度は時間やマシンの境界へ渡す問題として考えます。
課題は境界の契約を一箇所変える
課題として、[4294967295, 1]の結果がなぜ0ではないか説明します。解答では、入力要素は32ビットですが、集計と出力は64ビットなので4294967296を保持できるためです。次に、負数を入力した際に、PythonからCを呼ぶ前に拒否される箇所を示します。変換後の値を見て推測するのではなく、事前条件の検査を根拠にしてください。
最後に、Cが入力ポインタを保存する仕様へ変わったと仮定します。現在のchecked_sumの局所変数だけで期間を保証できるか考えてください。答えはできません。呼出し終了後も保持する所有者と、Cが利用を終えたことを知らせる規則が必要です。修正するなら、単にPythonの変数名を変えるのではなく、保持と終了のAPIを設計します。型宣言、長さ、所有権、終了、エラーを合わせて初めて、境界の契約を説明したことになります。