module Foo where

foreign export ccall foo :: Int -> IO Int

foo :: Int -> IO Int
foo n = return (length (f n))

f :: Int -> [Int]
f 0 = []
f n = n:(f (n-1))

#include "HsFFI.h"
extern HsInt foo(HsInt a0);

通常、GHCのランタイムシステムがmain()を提供する。このmain()はHaskellプログラムのMain.mainを起動するように手配する。しかし、main関数を別の言語(例えばC)で書いて、そこにHaskellコードをリンクしなければならないこともあるだろう。これをするためには、明示的にHaskellランタイムシステムを初期化しなければならない。

上の例を使って、これをスタンドアローンのCプログラムから呼び出してみよう。以下がCコードである。

#include <stdio.h>
#include "HsFFI.h"

#ifdef __GLASGOW_HASKELL__
#include "foo_stub.h"
#endif

#ifdef __GLASGOW_HASKELL__
extern void __stginit_Foo ( void );
#endif

int main(int argc, char *argv[])
{
  int i;

  hs_init(&argc, &argv);
#ifdef __GLASGOW_HASKELL__
  hs_add_root(__stginit_Foo);
#endif

  for (i = 0; i < 5; i++) {
    printf("%d\n", foo(2500));
  }

  hs_exit();
  return 0;
}

GHC特有の部分は#ifdef __GLASGOW_HASKELL__で囲った。それ以外のコードは、FFI標準に対応したHaskell実装の間で可搬であるはずだ。

hs_init()の呼び出しでGHCのランタイムシステムが初期化される。hs_init()を呼ぶ前にはいかなるHaskell関数も起動しようと*しない*ように。疑いの余地なく、悪いことが起こるだろう。

hs_init()にargcとargvへの参照を渡している。これは、RTSへの引数(つまり、+RTS...-RTSの間の引数)を抽出できるようにするためである。

次に、hs_add_rootを呼ぶ。これは、プログラム中のHaskellモジュールを初期化するのに必要なGHC固有のインタフェースである。hs_add_rootの引数としては、プログラムの「ルート」モジュールの初期化関数の名前を与えるべきである。ルートモジュールとは、プログラム中の全てのモジュールを直接・間接にインポートするモジュールのことである。スタンドアローンのHaskellプログラムではこれは通常Mainであるが、ライブラリからHaskellコードを使っているならそうとは限らない。(訳注: ライブラリ由来のHaskellコードを使っているならそうとは限らない、と訳すべき？原文は、..., but when you are using Haskell code from a library it may not be.)。プログラムに複数のルートモジュールがあるときは、それぞれについて一回ずつhs_add_rootを呼べば良い。モジュールMの初期化関数の名前は__stginit_Mであり、上記のコードのように外部関数シンボルとして宣言することができる。シンボル名は以下に示すZ符号化に従って変換せねばならないことに注意。

Haskellの関数を呼び出し終えた後、hs_exit()を呼んでRTSを終了させることができる。

hs_init()を複数回呼んでも良いが、毎回それに対応して一回(だけ)hs_exit()^[11]を呼ぶ必要がある。

参考: 最終的なプログラムをリンクする際、通常最も簡単なのは、GHCを使ってリンクすることである。(絶対に必要な訳ではないが)。GHCを使うなら、フラグ-no-hs-mainを使うことを忘れないように。さもないと、GHCはMainというHaskellモジュールをリンクしようとする。

8.2.1.1. 自分で用意したmain()を使うとよく似た状況だが、完全なプログラムをリンクするのが目的ではなく、Haskellコードからライブラリを作って、Cのコードでできたライブラリと同じように使えるようにしたいという場合である。

この場合、まず、Haskellコードが最初に呼ばれる前にランタイムが初期化される必要がある。このため、初期化と脱初期化のためのエントリポイントをCかC++で実装し、ライブラリ内に用意するべきである。例えば以下のように。

 HsBool mylib_init(void){
   int argc = ...
   char *argv[] = ...

   // Haskellのラインタイムを初期化する
   hs_init(&argc, &argv);

   // 全てのルートモジュールをHaskellに通知する
   hs_add_root(__stginit_Foo);

   // その他の初期化があればここで行ない、
   // 問題があればfalseを返す
   return HS_BOOL_TRUE;
 }

 void mylib_end(void){
   hs_exit();
 }

この初期化ルーチンmylib_initは、通常どおりhs_init()とhs_add_root()を呼んでHaskellランタイムを初期化する。これに対応する脱初期化関数mylib_end()はhs_exit()を呼んでランタイムを終了させる。

safe注釈(デフォルトである)付きでforeign importされた関数を呼ぶ場合、プログラムが-threadedを使ってリンクされているなら、その呼び出しは他のHaskellスレッドと並行に走る。プログラムが-threadedなしでリンクされている時は、その呼び出しが返るまで他のHaskellスレッドはブロックされる。

つまり、長い時間が掛かったり、いつまでブロックするか分からない関数を他言語呼び出しする必要があるなら、それをsafeにして、-threadedを使うべきである。ライブラリ関数の中には、内部的にこの種の呼び出しを行うものもある。その場合は説明文書にその旨記載があるべきである。

複数のHaskellスレッドから他言語呼び出しを行い、しかも-threadedを使っている場合、呼んでいる外部コードがスレッドセーフでなければならないことに注意すること。特に、ある種のGUIライブラリはスレッドセーフでなく、GUIメソッドを一つのスレッドからのみ呼ぶことを要求する。この場合、GUI操作は一つのHaskellスレッドからのみ行い、さらに結合スレッド(8.2.4.2. HaskellスレッドとOSスレッドの関係を見よ)を使う必要があるかもしれない。

複数のHaskellスレッドでなされた他言語呼び出しは並列に実行され得るのに注意。これは+RTS -Nフラグ(4.14.2. SMP並列性のためのRTSオプション)を使っていない場合でもそうである。+RTS -NフラグはHaskellスレッドの並列実行を制御するが、ある時点での他言語の呼び出しは、+RTS -Nの値に関係なく、いくらでも多くなり得る。

通常、HaskellスレッドとOSスレッドの間に固定された関係はない。つまり、他言語呼び出しを行った時、それがどのOSスレッドで起こるのかは規定されない。さらに、一つのHaskellスレッドが複数回の呼び出しを行ったとしても、それが同じOSスレッド上で実行される保証はない。

このことは普通問題にならないし、このおかげでGHCのランタイムシステムがOSのスレッド資源を効率的に利用することが可能になっている。しかし、例えばスレッドローカルな状態を使う外部コードを呼ぶ場合など、どのOSスレッドを使うかをもっと制御できた方が便利なことがある。このような場合のために、結合スレッド(bound thread)を用意している。これは、特定のOSスレッドに結び付けられたHaskellスレッドである。結合スレッドについての情報は、Control.Concurrentモジュールの説明を見よ。

プログラムが-threaded付きでリンクされているなら、foreign exportされた関数を複数のOSスレッドから並行に呼び出してよい。通常通り、ランタイムシステムはhs_init()とhs_add_rootを呼んで初期化せねばならない。また、これらの呼び出しはforeign exportされたいかなる関数をも呼び出す前に完了していなければならない。

通常、hs_exit()によって、そのシステムで実行中のすべてのHaskellスレッドは終了し、hs_exit()が返る時点では、もはやHaskellスレッドは一つも走っていない。この後、ランタイムは、必要ならプロファイル出力や統計情報を生成したり、持っているメモリをすべて開放したりして、システムを規則正しく終了させる。

Haskellスレッドを強制的に終了させることができない場合もある。例えば、スレッドが他言語呼び出しを実行中かもしれないが、他言語の呼び出しを終了させる方法はない。さらに、ランタイムは、Haskellコードとランタイムがメモリから削除予定であるという最悪の場合を想定しなければならない。(例えば、WindowsのDLLでは、hs_exit()が呼ばれるのは、通常そのDLLをアンロードする前である)。そのため、hs_exit()は、実行中のすべての他言語呼び出しが返るまで待ってからでないと、自分自身返ることができない。

要するに、他言語呼び出しでブロックしているHaskellスレッドがあるなら、その呼び出しが返るまでhs_exit()はハングする(場合によってはビジーウェイト)ということだ。よって、hs_exit()を呼び出すときにそのようなスレッドがシステム中にないようにするのが良い。これには、I/Oをしているあらゆるスレッドも含まれる。I/Oはブロックする他言語呼び出しを使って実装されているかもしれない(プラットフォームとI/Oの種類によってはそうでないかもしれない)からである。

GHCのランタイムは、プログラムが終了する場合を特別扱いして、スタンドアローンの実行ファイルが終了するときにブロックしているスレッドを待つ必要がないようにしている。コードがメモリから取り除かれるのと同時にプログラムとそのすべてのスレッドが終了するのだから、スレッドが先に終了するように保証する必要がない。(非公式だが、この、早くていい加減なhs_exit()が欲しいなら、代わりにshutdownHaskellAndExit()を呼ぶと良い)