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

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

  hs_init(&argc, &argv);

  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の間の引数)を抽出できるようにするためである。

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

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

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

hs_init()とともに+RTSフラグを使うには、例に多少の変更を加えなければならない。デフォルトでは、GHCのRTSは「安全な」+RTSフラグ(4.12.6. リンクに影響するオプションを見よ)のみを受け付け、これを変えるにはリンク時フラグ-rtsoptsを使う。しかし-rtsoptsは-no-hs-mainが使われているときには効果を持たない(-with-rtsoptsも同様)。これらのオプションを設定するには、hs_init()の代わりにGHC固有のAPIを呼ぶ必要がある。

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

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

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

#if __GLASGOW_HASKELL__ >= 703
  {
      RtsConfig conf = defaultRtsConfig;
      conf.rts_opts_enabled = RtsOptsAll;
      hs_init_ghc(&argc, &argv, conf);
  }
#else
  hs_init(&argc, &argv);
#endif

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

  hs_exit();
  return 0;
}

変更点が二つある。まずRts.hをインクルードした。これはGHC固有の外部RTSインタフェースを定義する。そしてhs_init_ghc()を呼ぶ代わりに、 RtsConfig型の引数を渡してhs_init_ghc()を呼んだ。RtsConfigは、ランタイムシステムの振る舞いに影響を与えるいろいろなフィールドを持つ構造体である。これの定義は以下。

typedef struct {
    RtsOptsEnabledEnum rts_opts_enabled;
    const char *rts_opts;
} RtsConfig;

extern const RtsConfig defaultRtsConfig;

typedef enum {
    RtsOptsNone,         // +RTSはエラーになる
    RtsOptsSafeOnly,     // 安全なRTSオプションが許される。それ以外はエラー
    RtsOptsAll           // 全てのRTSオプションが許される
  } RtsOptsEnabledEnum;

デフォルト値としてdefaultRtsConfigがあり、RtsConfig型の変数の初期化に用いられるべきである。将来、RtsConfigにもっと多くのフィールドが加えられることは間違いないので、コードを前方互換に保つためには、上のコード例のようにdefaultRtsConfigで初期化してから必要なフィールドを変更するのが良い。

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

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

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

HsBool mylib_init(void){
  int argc = 2;
  char *argv[] = { "+RTS", "-A32m", NULL };
  char **pargv = argv;

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

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

void mylib_end(void){
  hs_exit();
}

この初期化ルーチンmylib_initは、通常どおりhs_init()を呼んで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.15.2. SMP並列性のためのRTSオプション)を使っていない場合でもそうである。+RTS -NフラグはHaskellスレッドの並列実行を制御するが、ある時点での外部の呼び出しは、+RTS -Nの値に関係なく、いくらでも多くなり得る。

呼び出しがinterruptibleとされており、プログラムがマルチスレッドの場合、そのHaskellスレッドが例外を受けた場合に呼び出しが中断され得る。この中断が発生する機構はプラットフォームによって異なるが、ブロックしているシステムコールが「割り込み発生」のエラーコードで即座に返ることが意図されている。使われているOSスレッドを破壊するものではない。さらなる詳細は8.1.4. 割り込み可能な外部呼び出しを見よ。

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

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

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