4.6 C API の関数と型

C API が持つ全ての関数と型をここに辞書順に示します。

各関数には [-o, +p, x] という印が付いています。最初の o は関数がスタックからポップする要素の数を表し、二つ目の p は関数がスタックにプッシュする要素の数を表します (関数は必ず引数をポップしてから返り値をプッシュします)。x|y と書いてある場合には、状況に応じて x 個または y 個の要素をプッシュ/ポップする関数であることを示します。クエスチョンマーク ? は関数がプッシュ/ポップする要素の数が引数からは定まらないことを示します (個数がスタックの値に依存する場合など)。三つ目の x は関数がエラーを送出するかどうかを表します。x が - の関数はエラーを送出せず、m の関数はメモリ不足によるエラーのみを送出する可能性があり、v の関数は解説にあるエラーを送出する可能性があり、e の関数は任意の Lua コードを (直接あるいはメタメソッドを通して) 実行するので全てのエラーが送出される可能性があります。

lua_absindex

[-0, +0, -] 
int lua_absindex (lua_State *L, int idx);

処理可能なインデックス idx を同じ要素を指す絶対インデックス (スタックトップに依存しない値) に変換します。

lua_Alloc

typedef void * (*lua_Alloc) (void *ud,
                             void *ptr,
                             size_t osize,
                             size_t nsize);

Lua ステートが使うメモリアロケーション関数 (アロケータ) の型です。アロケータは realloc に似た機能を提供しなければなりませんが、二つは正確に同じではありません。引数 ud は不透明 (中身の指定されない) ポインタであり、lua_newstate に渡して設定します。ptr は確保/再確保/解放が行われるポインタ、osize は確保されるブロックの元のサイズまたは確保されるブロックに関する情報、nsize はブロックの新しいサイズをそれぞれ表します。

ptr が NULL でないとき、osize は ptr が指すブロックのサイズを表します。つまりそのブロックが最後に確保あるいは再確保されたときのサイズです。

ptr が NULL のとき、osize には Lua が確保しようとしているオブジェクトの種類がエンコードされます。このときの osize は LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA, LUA_TTHREAD のいずれかであり、値は作成されるオブジェクトの種類に応じて決まります。osize が他の値のときは Lua が何らかの用途のためにメモリを確保しています。

メモリのアロケータには次の振る舞いが要求されます:

アロケータの簡単な実装を示します。この関数は補助ライブラリの luaL_newstate によって使われます:

static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) {
  (void)ud;  (void)osize;  /* not used */
  if (nsize == 0) {
    free(ptr);
    return NULL;
  }
  else
    return realloc(ptr, nsize);
}

free(NULL) が何もしないこと、そして realloc(NULL,size) は malloc(size) と同じであることが C 規格によって定められている点に注意してください。

lua_arith

[-(2|1), +1, e] 
void lua_arith (lua_State *L, int op);

算術演算あるいはビットごとの演算をスタックトップに積まれた二つの値に対して行います (否定演算では使われる値は一つだけです)。一番上に積まれた値が二つ目のオペランドとなり、オペランドを全てポップした後に結果がプッシュされます。この関数の意味論は対応する Lua の演算子と同じです (つまり、メタメソッドが呼び出される可能性があります)。

op の値は次の定数のいずれかである必要があります:

lua_atpanic

[-0, +0, -] 
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);

新しくパニック関数を設定し、古いパニック関数を返します (参照: § 4.4)。

lua_call

[-(nargs+1), +nresults, e] 
void lua_call (lua_State *L, int nargs, int nresults);

関数を呼びます。Lua における通常の関数呼び出しと同じように、lua_call は __call メタメソッドを確認します。つまりここでの「関数」は「呼び出せる値」を指します。

呼び出しでは次のプロトコルを使う必要があります: まず呼び出す関数をスタックにプッシュし、それから引数をそのままの順番で (第一引数から順に) プッシュし、最後に lua_call を呼ぶというプロトコルです。そのとき nargs はスタックにプッシュした引数の数とします。関数の返り値はスタックにポップして返され、その個数は nresults が LUA_MULTRET でない限り nresults に調整されます。nresults が LUA_MULTRET である場合には、全ての返り値がプッシュされます。Lua は返り値がスタック空間に収まるよう必要に応じてメモリを確保しますが、元の空き空間を保持することはしません。関数の返り値はスタックにそのままの順番で (一つ目の返り値が最初に) プッシュされます。つまり関数が返ったときのスタックトップには最後の返り値があります。

関数の呼び出しおよび実行で起きたエラーは上流に (longjmp を使って) 伝播されます。

例を示します。Lua コード

a = f("how", t.x, 14)

は、次の C コードと等価です:

lua_getglobal(L, "f");     /* 呼ばれる関数 */
lua_pushliteral(L, "how"); /* 第一引数 */
lua_getglobal(L, "t");     /* アクセスするテーブル */
lua_getfield(L, -1, "x");  /* t.x (第二引数) をプッシュする */
lua_remove(L, -2);         /* スタックから t を取り除く */
lua_pushinteger(L, 14);    /* 第三引数 */
lua_call(L, 3, 1);         /* f を呼ぶ (引数は三つ、返り値は一つ) */
lua_setglobal(L, "a");     /* グローバル変数 a を設定する */

このコードは「バランスが取れている」ことに注意してください。つまり、最後まで実行するとスタックが最初の状態に戻ります。これは良いプログラミングの習慣とされます。

lua_callk

[-(nargs + 1), +nresults, e] 
void lua_callk (lua_State *L,
                int nargs,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

この関数の振る舞いは基本的に lua_call と同じですが、呼び出した先の関数で yield が許される点が異なります (参照: § 4.5)。

lua_CFunction

typedef int (*lua_CFunction) (lua_State *L);

Lua から呼び出せる C 関数の型です。

C 関数が Lua と適切なやり取りを行うには、パラメータと返り値に関する次のプロトコルを使わなければなりません。C 関数は Lua からの引数をスタックを通してそのままの順番 (第一引数を最初にプッシュする順番) で受け取ります。つまり関数の実行が始まった時点では lua_gettop(L) が「関数が受け取った引数の数」を返します。第一引数は (存在すれば) インデックス 1 の場所にあり、最後の引数はインデックスが lua_gettop(L) の場所にあります。C 関数から Lua に値を返すときは、返り値をそのままの順番で (最初の返り値を最初に) プッシュして、返り値の数を C 関数の返り値とします。Lua の関数と同様に、Lua が呼ぶ C 関数は複数の返り値を返すことができます。

例を示します。次の関数は可変個数の数値を引数として受け取り、その平均と和を返します:

static int foo (lua_State *L) {
  int n = lua_gettop(L);    /* 引数の数 */
  lua_Number sum = 0.0;
  int i;
  for (i = 1; i <= n; i++) {
    if (!lua_isnumber(L, i)) {
      lua_pushliteral(L, "incorrect argument");
      lua_error(L);
    }
    sum += lua_tonumber(L, i);
  }
  lua_pushnumber(L, sum/n);   /* 一つ目の返り値 */
  lua_pushnumber(L, sum);     /* 二つ目の返り値 */
  return 2;                   /* 返り値の数 */
}

lua_checkstack

[-0, +0, -] 
int lua_checkstack (lua_State *L, int n);

スタックに n スロット以上の空き容量があるかどうかを確認し、もしなければ容量を確保します。つまりこの関数を実行すると、スタックに n 個の値をプッシュできるようになります。要求に応えられない場合には false が返ります。false が返るのはスタックが固定された最大サイズ (通常は数千) を超えるとき、あるいはメモリの確保に失敗したときです。この関数はスタックを縮小しません: 最初から十分な空き容量がある場合には、スタックはそのままとなります。

lua_close

[-0, +0, -] 
void lua_close (lua_State *L);

メインスレッド内のアクティブなクローズ予約変数を全てクローズし、与えられた Lua ステートが持つオブジェクトを全て解放し (__gc メタメソッドがあればそれも呼び)、ステートが持つ動的メモリを全て解放します。

一部のプラットフォームではホストプログラムの終了によって全てのリソースが自然に解放されるので、この関数は必要になりません。一方で、デーモンやウェブサーバーのように長い間実行され複数のステートが作成されるプログラムでは、必要なくなったステートの解放が必要になる可能性があります。

lua_compare

[-0, +0, e] 
int lua_compare (lua_State *L, int index1, int index2, int op);

二つの Lua の値を比較します。インデックスが index1 の場所にある値と index2 の場所にある値が op を満たすなら 1 を返し、そうでないなら 0 を返します。比較演算の振る舞いは Lua と同様です (つまり、メタメソッドの呼び出される可能性があります)。インデックスのいずれかが有効でない場合にも 0 を返します。

op の値は次のいずれかです:

lua_concat

[-n, +1, e] 
void lua_concat (lua_State *L, int n);

スタックトップにある n 個の値を連結し、それらをポップし、結果をプッシュします。n が 1 のときはスタックにある一つの値が返り値となります (つまり、この関数は何もしません)。n が 0 のときは空文字列が返ります。連結演算は Lua における通常の連結 (§ 3.4.6) と同じように行われます。

lua_copy

[-0, +0, -] 
void lua_copy (lua_State *L, int fromidx, int toidx);

インデックス fromidx にある要素を処理可能なインデックス toidx にコピーします。toidx にある要素は上書きされます。toidx にある要素以外は影響を受けません。

lua_createtable

[-0, +1, m] 
void lua_createtable (lua_State *L, int narr, int nrec);

空のテーブルを新しく作り、スタックにプッシュします。narr はテーブルが今後シーケンスとして持つことになる要素の数に関するヒントであり、nrec はテーブルが今後持つことになるその他の要素の数に関するヒントです。Lua はこれらのヒントを使って新しいテーブル用のメモリを前持って確保する可能性があります。テーブルが持つ要素の数が最初から分かっている場合には、この前持って行われるメモリの確保によってパフォーマンスが改善されることがあります。要素の数が分かっていない場合には lua_newtable を使ってください。

lua_dump

[-0, +0, -] 
int lua_dump (lua_State *L, lua_Writer writer, void *data, int strip);

関数をバイナリチャンクとしてダンプします。スタックトップに Lua 関数を受け取り、ロードすると同じ関数が得られるようなバイナリチャンクを生成します。バイナリチャンクは少しずつ生成されるので、lua_dump は lua_Writer 型の関数 writer を data と共に何度も呼び出します。

strip を true とすると、バイナリ表現から関数のデバッグ情報を削除して空間を節約することが許可されます。

返り値は最後の writer の呼び出しのエラーコードです。エラーが無ければ 0 が返ります。

この関数は処理対象の Lua 関数をスタックからポップしません。

lua_error

[-1, +0, v] 
int lua_error (lua_State *L);

スタックトップにある値をエラーオブジェクトとして Lua エラーを送出します。この関数は longjmp を実行するので、返りません (参照: luaL_error)。

lua_gc

[-0, +0, -] 
int lua_gc (lua_State *L, int what, ...);

ガベージコレクタを制御します。

この関数は what パラメータの値に応じて次のタスクを実行します。追加の引数が必要な場合には what の後に続けて渡されます。

さらに詳しくは collectgarbage を参照してください。

lua_getallocf

[-0, +0, -] 
lua_Alloc lua_getallocf (lua_State *L, void **ud);

与えられたステートのメモリアロケーション関数を返します。ud が NULL でなければ、メモリアロケーション関数と一緒に設定されたユーザーデータを *ud に代入します。

lua_getfield

[-0, +1, e] 
int lua_getfield (lua_State *L, int index, const char *k);

スタックに値 t[k] をプッシュします。t はスタックの与えられたインデックスにある値です。Lua と同様に、この関数は index イベントに対するメタメソッドを呼び出す可能性があります (参照: § 2.4)。

返り値はプッシュされた値の型です。

lua_getextraspace

[-0, +0, -] 
void *lua_getextraspace (lua_State *L);

Lua ステートに結び付いた生のメモリ領域へのポインタを返します。アプリケーションはこの領域を任意の用途に利用でき、Lua はこの領域を全く利用しません。

新しいスレッドが作られるとき、この領域はメインスレッドのものがコピーされて初期化されます。

デフォルトではこの領域は void を指すポインタと同じサイズを持ちます。サイズは Lua を再コンパイルすれば変更できます (luaconf.h の LUA_EXTRASPACE を参照してください)。

lua_getglobal

[-0, +1, e] 
int lua_getglobal (lua_State *L, const char *name);

スタックにグローバル変数 name をプッシュし、その値の型を返します。

lua_geti

[-0, +1, e] 
int lua_geti (lua_State *L, int index, lua_Integer i);

スタックに値 t[i] をプッシュします。t はスタックの与えられたインデックスにある値です。Lua におけるアクセスと同様に、この関数は index イベントに対するメタメソッドを呼び出す可能性があります (参照: § 2.4)。

返り値はプッシュされた値の型です。

lua_getmetatable

[-0, +(0|1), -] 
int lua_getmetatable (lua_State *L, int index);

与えられたインデックスの値がメタテーブルを持つなら、そのメタテーブルをスタックにプッシュして 1 を返します。そうでなければ、何もプッシュせずに 0 を返します。

lua_gettable

[-1, +1, e] 
int lua_gettable (lua_State *L, int index);

スタックに値 t[k] をプッシュします。t は与えられたインデックスにある値であり、k はスタックトップにある値です。

この関数はキーをスタックからポップしてから t[k] をプッシュします。Lua におけるアクセスと同様に、この関数は index イベントに対するメタメソッドを呼び出す可能性があります (参照: § 2.4)。

返り値はプッシュされた値の型です。

lua_gettop

[-0, +0, -] 
int lua_gettop (lua_State *L);

スタックトップにある要素のインデックスを返します。インデックスは 1 から始まるので、この関数の返り値はスタックにある要素の数と一致します。特にスタックが空なら 0 が返ります。

lua_getiuservalue

[-0, +1, -] 
int lua_getiuservalue (lua_State *L, int index, int n);

スタックの与えられたインデックスにあるフルユーザーデータに関連付いた n 個目のユーザーバリューをスタックにプッシュし、プッシュした値の型を返します。

返すべき値がユーザーデータに存在しないときは、nil をプッシュして LUA_TNONE を返します。

lua_insert

[-1, +1, -] 
void lua_insert (lua_State *L, int index);

スタックトップにある要素を与えられた有効なインデックスに移動し、それよりも上の要素を全て一つ上に移動させます。この関数に疑似インデックスを渡すことはできません。疑似インデックスは本当のスタックの位置を表さないためです。

lua_Integer

typedef ... lua_Integer;

Lua の整数を表す型です。

デフォルトではこの型は long long (通常は 2 の補数を使う 64 ビット整数) です。しかし long や int (通常は 2 の補数を使う 32 ビットの整数) とすることもできます。luaconf.h の LUA_INT_TYPE を参照してください。

Lua は LUA_INT_TYPE の最小値と最大値を表す定数 LUA_MININTEGER と LUA_MAXINTEGER も定義します。

lua_isboolean

[-0, +0, -] 
int lua_isboolean (lua_State *L, int index);

スタックの与えられたインデックスにある値が真偽値型なら 1 を返し、そうでないなら 0 を返します。

lua_iscfunction

[-0, +0, -] 
int lua_iscfunction (lua_State *L, int index);

スタックの与えられたインデックスにある値が C 関数なら 1 を返し、そうでないなら 0 を返します。

lua_isfunction

[-0, +0, -] 
int lua_isfunction (lua_State *L, int index);

スタックの与えられたインデックスにある値が (C または Lua の) 関数なら 1 を返し、そうでないなら 0 を返します。

lua_isinteger

[-0, +0, -] 
int lua_isinteger (lua_State *L, int index);

スタックの与えられたインデックスにある値が整数 (整数で表せる数値) なら 1 を返し、そうでないなら 0 を返します。

lua_islightuserdata

[-0, +0, -] 
int lua_islightuserdata (lua_State *L, int index);

スタックの与えられたインデックスにある値がライトユーザーデータなら 1 を返し、そうでないなら 0 を返します。

lua_isnil

[-0, +0, -] 
int lua_isnil (lua_State *L, int index);

スタックの与えられたインデックスにある値が nil なら 1 を返し、そうでないなら 0 を返します。

lua_isnone

[-0, +0, -] 
int lua_isnone (lua_State *L, int index);

与えられたインデックスが有効でないなら 1 を返し、そうでないなら 0 を返します。

lua_isnoneornil

[-0, +0, -] 
int lua_isnoneornil (lua_State *L, int index);

与えられたインデックスが有効でないとき、あるいはそこにある値が nil のとき 1 を返し、そうでないなら 0 を返します。

lua_isnumber

[-0, +0, -] 
int lua_isnumber (lua_State *L, int index);

スタックの与えられたインデックスにある値が数値に変換可能な文字列または数値のとき 1 を返し、そうでなければ 0 を返します。

lua_isstring

[-0, +0, -] 
int lua_isstring (lua_State *L, int index);

スタックの与えられたインデックスにある値が文字列または数値のとき 1 を返し、そうでなければ 0 を返します (数値は常に文字列に変換できます)。

lua_istable

[-0, +0, -] 
int lua_istable (lua_State *L, int index);

スタックの与えられたインデックスにある値がテーブルのとき 1 を返し、そうでなければ 0 を返します。

lua_isthread

[-0, +0, -] 
int lua_isthread (lua_State *L, int index);

スタックの与えられたインデックスにある値がスレッドのとき 1 を返し、そうでなければ 0 を返します。

lua_isuserdata

[-0, +0, -] 
int lua_isuserdata (lua_State *L, int index);

スタックの与えられたインデックスにある値が (フルまたはライトの) ユーザーデータのとき 1 を返し、そうでなければ 0 を返します。

lua_isyieldable

[-0, +0, -] 
int lua_isyieldable (lua_State *L);

与えられたコルーチンが yield できるなら 1 を返し、そうでないなら 0 を返します。

lua_KContext

typedef ... lua_KContext;

継続関数のコンテキストの型であり、必ず数値型を表します。intptr_t が利用できるなら intptr_t と定義され、この型の値はポインタも保持できます。そうでないなら ptrdiff_t と定義されます。

lua_KFunction

typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);

継続関数 (§ 4.5) の型です。

lua_len

[-0, +1, e] 
void lua_len (lua_State *L, int index);

スタックの与えられたインデックスにある値の長さを返します。Lua の # 演算子 (§ 3.4.7) と同じ処理が行われ、length イベントに対するメタメソッドが呼び出される可能性があります (参照: § 2.4)。結果はスタックにプッシュされます。

lua_load

[-0, +1, -] 
int lua_load (lua_State *L,
              lua_Reader reader,
              void *data,
              const char *chunkname,
              const char *mode);

Lua チャンクを実行せずに読み込みます。エラーが無ければコンパイルされたチャンクが Lua 関数としてスタックにプッシュされ、それ以外の場合にはエラーメッセージがプッシュされます。

lua_load 関数はユーザーによって指定される reader 関数を使ってチャンクを読み込みます (参照: lua_Reader)。data は reader 関数に渡される不透明な (中身の指定されない) 値です。

チャンクには chunkname という名前が付き、エラーメッセージやデバッグ情報 (§ 4.7) でこの名前が使われます。

lua_load はチャンクがテキストかバイナリかを自動的に検出し、読み込み処理を適切に切り替えます (luac プログラムを参照してください)。文字列 mode は load と同様の働きを持ちます。mode を NULL にすると "bt" が使われます。

lua_load はスタックを内部で使用するので、reader 関数はスタックを改変していない状態で返す必要があります。

lua_load の返り値は LUA_OK, LUA_ERRSYNTAX, LUA_ERRMEM のいずれかです。また reader 関数でエラーが起きた場合にはそれに応じた値が返ります (§ 4.4.1)。

読み込み結果の関数がアップバリューを持つ場合、最初のアップバリューがグローバル環境の値 (レジストリのインデックス LUA_RIDX_GLOBALS に保存される値) となります (参照: § 4.3)。メインチャンクを読み込みときこのアップバリューが _ENV 変数 (§ 2.2) となり、他のアップバリューは nil に初期化されます。

lua_newstate

[-0, +0, -] 
lua_State *lua_newstate (lua_Alloc f, void *ud);

新しい独立したステートを作成し、そのメインスレッドを返します。ステートの作成に (メモリ不足により) 失敗すると NULL を返します。第一引数の f はアロケータ関数であり、Lua はこのステートが使うメモリの確保をこの関数を通してのみ行います。第二引数の ud は不透明 (中身の指定されない) ポインタであり、Lua がアロケータ関数を呼び出すとき関数に毎回渡されます。

lua_newtable

[-0, +1, m] 
void lua_newtable (lua_State *L);

新しい空のテーブルを作成してスタックにプッシュします。lua_createtable(L, 0, 0) と等価です。

lua_newthread

[-0, +1, m] 
lua_State *lua_newthread (lua_State *L);

新しいスレッドを作り、スタックにプッシュし、そのスレッドを表す lua_State へのポインタを返します。この関数が返す新しいスレッドは元のスレッドとグローバル環境を共有しますが、独立した実行スタックを持ちます。

他の Lua オブジェクトと同様、スレッドも GC の対象です。

lua_newuserdatauv

[-0, +1, m] 
void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);

新しいフルユーザーデータを作成してスタックにプッシュします。このユーザーデータには nvalue 個の Lua の値と size バイトの生メモリ領域が関連付きます。フルユーザーデータに関連付く値をユーザーバリュー (user value) と呼びます。ユーザーバリューの読み書きには lua_setiuservalue と lua_getiuservalue を使用します。

この関数は作成されるメモリ領域のアドレスを返します。

lua_next

[-1, +(2|0), v] 
int lua_next (lua_State *L, int index);

スタックからキーをポップし、引数として与えられるインデックスに存在するテーブルが持つキーとバリューをこの順番でプッシュします。プッシュするのはスタックからポップされたキーの「次の」キーとバリューであり、次のペアが存在しなければ何もプッシュせずに 0 を返します。

典型的なテーブル操作の例を示します:

/* テーブルはスタックのインデックス "t" にある */
lua_pushnil(L);  /* 最初のキー */
while (lua_next(L, t) != 0) {
  /* インデックス -2 にはキーがあり、インデックス -1 にはバリューがある */
  printf("%s - %s\n",
         lua_typename(L, lua_type(L, -2)),
         lua_typename(L, lua_type(L, -1)));
  /* バリューを削除し、次の反復でキーを使えるようにする */
  lua_pop(L, 1);
}

テーブルの走査では、キーが文字列だと分かっていない限り lua_tolstring をキーに対して直接呼び出すのを避けるべきです。lua_tolstring は与えられたインデックスにある値を変更することがあるので、lua_next が意図した通りの動作をしなくなる可能性があります。

ポップしたキーが nil のとき、およびテーブルに存在しないときこの関数はエラーを送出します。走査中にテーブルを変更することに関する注意事項は next を参照してください。

lua_Number

typedef ... lua_Number;

Lua における浮動小数点数型の型です。

デフォルトでは double ですが、float や long double を使うように変更することもできます。luaconf.h の LUA_FLOAT_TYPE を参照してください。

lua_numbertointeger

int lua_numbertointeger (lua_Number n, lua_Integer *p);

Lua の浮動小数点数から Lua の整数への変換を試みます。浮動小数点数 n は整数値である必要があります。変換した値が Lua の整数の範囲に収まっている場合に限り *p に変換された値が代入されます。このマクロの返り値は変換が成功したかどうかを表す真偽値です (浮動小数点数には丸めがあるので、浮動小数点数が整数の範囲に収まっているかどうかの判定をこのマクロを使わずに自分で正確に行うのは難易度が高いことに注意してください)。

このマクロは引数を二度以上評価する可能性があります。

lua_pcall

[-(nargs + 1), +(nresults|1), -] 
int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);

関数 (または呼び出せるオブジェクト) を保護モードで呼び出します。

nargs と nresults の意味は lua_call と同じです。呼び出し中にエラーがなければ、lua_pcall の振る舞いは lua_call と全く同じになります。しかしエラーが発生すると lua_pcall はそれを捕捉し、スタックに値 (エラーオブジェクト) を一つプッシュしてからエラーコードを返します。lua_call と同様に、lua_pcall は必ず呼び出す関数とその引数をスタックから取り除きます。

msgh が 0 なら、スタックに返されるエラーオブジェクトは元のエラーオブジェクトと一致します。そうでなければ、msgh はメッセージハンドラ (message handler) のスタックにおけるインデックスとなります (このインデックスに疑似インデックスを使うことはできません)。実行時エラーが起きるとこのハンドラがエラーオブジェクトを引数として呼ばれ、ハンドラの返り値がスタックにプッシュされて返される lua_pcall の返り値となります。

通常メッセージハンドラが使われるのは、エラーオブジェクトにスタックのトレースバックなどのデバッグ情報を追加するためです。lua_pcall が返ってスタックが巻き戻った後ではこういった情報を集めることはできません。

lua_pcall が返すのは次のステータスコードのいずれかです:

lua_pcallk

[-(nargs + 1), +(nresults|1), -] 
int lua_pcallk (lua_State *L,
                int nargs,
                int nresults,
                int msgh,
                lua_KContext ctx,
                lua_KFunction k);

この関数は lua_pcall と全く同じように振る舞いますが、呼び出される関数が yield できる点が唯一異なります (参照: § 4.5)。

lua_pop

[-n, +0, -] 
void lua_pop (lua_State *L, int n);

スタックから n 要素をポップします。

lua_pushboolean

[-0, +1, -] 
void lua_pushboolean (lua_State *L, int b);

値が b の真偽値をスタックにプッシュします。

lua_pushcclosure

[-n, +1, m] 
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);

C クロージャをスタックにプッシュします。この関数は C 関数へのポインタを受け取り、関数型の Lua の値をスタックにプッシュします。プッシュされた値を呼ぶと引数として渡された C 関数が実行されます。パラメータ n は関数が持つアップバリューの数を表します (参照: § 4.2)。

Lua から呼び出す C 関数はパラメータの受け取りと返り値の返却において決まったプロトコルを使わなければなりません (参照: lua_CFunction)。

作成される C 関数には Lua の値を関連付けることができます。こういった値はアップバリューと呼ばれ、関数が呼ばれたときいつでもアクセス可能となります。アップバリューが関連付いた C 関数は C クロージャ (§ 4.2) と呼ばれます。C クロージャを作成するには、まずアップバリューに対する初期値をスタックにプッシュします (アップバリューが複数ある場合には、最初のアップバリューを最初にプッシュします)。その上で lua_pushcclosure を呼ぶと、引数 n を関数に関連付けられるアップバリューの数として C 関数の作成とスタックへのプッシュが行われます。そのとき lua_pushcclosure はスタックからアップバリューの初期値をポップします。

n の最大値は 255 です。

n が 0 だと、この関数はライト C 関数 (light C function) を作成します。これは C 関数へのただのポインタであり、この場合にはメモリエラーは起こりません。

lua_pushcfunction

[-0, +1, -] 
void lua_pushcfunction (lua_State *L, lua_CFunction f);

C 関数をスタックへプッシュします。アップバリューを使わない lua_pushcclosure と等価です。

lua_pushfstring

[-0, +1, v] 
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);

完成した文字列をスタックにプッシュし、その文字列を指すポインタを返します。処理は C の sprintf 関数と同様ですが、重要な違いが二つあります。第一に、結果のための空間を確保する必要はありません: 結果は Lua 文字列であり、Lua がメモリの確保 (と GC を通した解放) を行います。第二に、利用できる変換指定子は非常に限られています。フラグ・幅・精度の指定はできず、使える変換指定子は次に示すものだけです:

この関数はメモリがオーバーフローしたときおよび無効な変換指定子があるときにエラーを送出します。

lua_pushglobaltable

[-0, +1, -] 
void lua_pushglobaltable (lua_State *L);

グローバル環境をスタックにプッシュします。

lua_pushinteger

[-0, +1, -] 
void lua_pushinteger (lua_State *L, lua_Integer n);

値 n の整数値をスタックにプッシュします。

lua_pushlightuserdata

[-0, +1, -] 
void lua_pushlightuserdata (lua_State *L, void *p);

ライトユーザーデータをスタックにプッシュします。

Lua におけるユーザーデータが表すのは C の値であり、ライトユーザーデータが表すのはポインタ void* です。ライトユーザーデータは Lua において数値と同様に値として扱われます。つまりライトユーザーデータを作る処理は存在せず、メタテーブルは存在せず、構築処理が存在しないので GC の対象にもなりません。同じ C アドレスを指す全てのライトユーザーデータは等しいとみなされます。

lua_pushliteral

[-0, +1, m] 
const char *lua_pushliteral (lua_State *L, const char *s);

このマクロは lua_pushstring と等価ですが、s が文字列リテラルである場合にはこちらを使うべきです (Lua が最適化できる場合があります)。

lua_pushlstring

[-0, +1, m] 
const char *lua_pushlstring (lua_State *L, const char *s, size_t len);

s が指す長さ len の文字列をスタックにプッシュします。Lua は与えられた文字列のコピーを内部に作成するので、この関数が返った後にメモリ s の解放や再利用を行って構いません。文字列は任意のバイナリデータを含むことができ、途中にゼロ文字があっても構いません。

内部にコピーした文字列を指すポインタを返します。

lua_pushnil

[-0, +1, -] 
void lua_pushnil (lua_State *L);

nil 値をスタックにプッシュします。

lua_pushnumber

[-0, +1, -] 
void lua_pushnumber (lua_State *L, lua_Number n);

値 n を持つ浮動小数点数をスタックにプッシュします。

lua_pushstring

[-0, +1, m] 
const char *lua_pushstring (lua_State *L, const char *s);

s が指すゼロ終端文字列をスタックにプッシュします。Lua は与えられた文字列のコピーを内部に作成するので、この関数が返った後にメモリ s の解放や再利用を行って構いません。

内部にコピーした文字列を指すポインタを返します。

s が NULL の場合には nil をプッシュして NULL を返します。

lua_pushthread

[-0, +1, -] 
int lua_pushthread (lua_State *L);

L が表すスレッドをスタックにプッシュします。プッシュされたスレッドがステートのメインスレッドなら 1 を返します。

lua_pushvalue

[-0, +1, -] 
void lua_pushvalue (lua_State *L, int index);

スタックの与えられたインデックスにある要素のコピーをスタックにプッシュします。

lua_pushvfstring

[-0, +1, v] 
const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp);

lua_pushfstring と同様の処理を行いますが、可変個の引数の代わりに va_list を受け取ります。

lua_rawequal

[-0, +0, -] 
int lua_rawequal (lua_State *L, int index1, int index2);

スタックのインデックス index1 と index2 にある値が原始的に等しい (つまり、__eq メタメソッドを呼び出さない比較で等しい) とき 1 を返し、それ以外のとき 0 を返します。インデックスのいずれかが有効でない場合にも 0 を返します。

lua_rawget

[-1, +1, -] 
int lua_rawget (lua_State *L, int index);

lua_gettable と同様ですが、生の (メタメソッドを使わない) アクセスを行います。

lua_rawgeti

[-0, +1, -] 
int lua_rawgeti (lua_State *L, int index, lua_Integer n);

値 t[n] をスタックにプッシュします。t はスタックの与えられたインデックスにあるテーブルです。アクセスは生であり、メタバリュー __index を使いません。

プッシュされた値の型を返します。

lua_rawgetp

[-0, +1, -] 
int lua_rawgetp (lua_State *L, int index, const void *p);

スタックに値 t[k] をプッシュします。t はスタックの与えられたインデックスにある値であり、k はライトユーザーデータとして表されたポインタ p です。アクセスは生であり、メタバリュー __index を使いません。

プッシュされた値の型を返します。

lua_rawlen

[-0, +0, -] 
lua_Unsigned lua_rawlen (lua_State *L, int index);

スタックの与えられたインデックスにある値の「長さ」を返します。文字列型の値では文字列の長さ、テーブルではメタメソッドを使わない長さ演算子 (#) の結果、ユーザーデータでは確保されているメモリ領域のサイズが返ります。その他の値に対しては 0 を返します。

lua_rawset

[-2, +0, m] 
void lua_rawset (lua_State *L, int index);

基本的に lua_settable と同様ですが、生の (メタメソッドを使わない) 代入を行います。

lua_rawseti

[-1, +0, m] 
void lua_rawseti (lua_State *L, int index, lua_Integer i);

t[i] = v と同じ処理を実行します。t はスタックの与えられたインデックスにある値であり、v はスタックトップにある値です。

この関数はスタックから値をポップします。代入は生であり、__newindex メタバリューを使いません。

lua_rawsetp

[-1, +0, m] 
void lua_rawsetp (lua_State *L, int index, const void *p);

t[p] = v と同じ処理を実行します。t はスタックの与えられたインデックスにある値であり、p は引数 p をライトユーザーデータとしてエンコードした値で、v はスタックトップにある値です。

この関数はスタックから値をポップします。代入は生であり、__newindex メタバリューを使いません。

lua_Reader

typedef const char * (*lua_Reader) (lua_State *L,
                                    void *data,
                                    size_t *size);

lua_load の reader 関数の型です。reader は lua_load がチャンクの次の部分を必要とするたびに呼ばれ、data がパラメータとして渡されます。reader はチャンクの次の部分が入ったメモリ領域のポインタを返り値として、size をそのサイズに設定します。新しいブロックは reader がもう一度呼び出されるまで存在している必要があります。reader 関数は 0 より大きい任意のサイズのメモリ領域を返却できます。

lua_register

[-0, +0, e] 
void lua_register (lua_State *L, const char *name, lua_CFunction f);

C 関数 f を新しいグローバル変数 name の値として設定します。これはマクロとして次のように定義されます:

#define lua_register(L,n,f) \
       (lua_pushcfunction(L, f), lua_setglobal(L, n))

lua_remove

[-1, +0, -] 
void lua_remove (lua_State *L, int index);

与えられた有効なインデックスにある要素を削除し、それより上にある要素を一つずつ下に下げて隙間を埋めます。この関数は疑似インデックスで呼び出すことができません。疑似インデックスは本当のスタック位置ではないからです。

lua_replace

[-1, +0, -] 
void lua_replace (lua_State *L, int index);

スタックトップにある要素を与えられた有効なインデックスに移動させます。指定されたインデックスにある値が置き換わり、他の要素は移動しません。この関数はその後スタックトップにある要素をポップします。

lua_resetthread

[-0, +?, -] 
int lua_resetthread (lua_State *L);

スレッドをリセットします。つまりスタックを掃除し、残っているクローズ予約変数を全てクローズします。返り値は状態コードであり、クローズメソッドでエラーがなければ LUA_OK が、エラーが起きればそのエラーコードが返ります。エラーが起きたときは、エラーオブジェクトがスタックトップに置かれたまま返ります。

lua_resume

[-?, +?, -] 
int lua_resume (lua_State *L, lua_State *from, int nargs, int *nresults);

与えられたスレッド L のコルーチンを開始/再開します。

コルーチンを開始するには、メイン関数と引数をスレッドの空スタックにプッシュし、nargs を引数の数として lua_resume を呼びます。この呼び出しはコルーチンの実行が停止あるいは完了したときに返ります。関数が返るとき *nresults は更新され、スタックトップには関数本体の return あるいは lua_yield に渡された *results 個の値が存在します。この関数はコルーチンが yield すると LUA_YIELD を返し、コルーチンが実行をエラーを出さずに終了すると LUA_OK を返します。エラーが起こるとエラーコード (§ 4.4.1) を返し、そのときエラーオブジェクトがスタックトップに存在します。

コルーチンを再開するには、yield された *nresults 個の値をスタックから取り除き、yield の返り値となる値をプッシュし、それから lua_resume を呼びます。

パラメータ from は L を再開させるコルーチンを表します。そのようなコルーチンが存在しない場合1には from を NULL にできます。

lua_rotate

[-0, +0, -] 
void lua_rotate (lua_State *L, int idx, int n);

有効なインデックス idx からスタックトップの間にある要素を回転させます。n が正なら要素がスタックトップに向かって n 要素分回転させ、n が負ならスタックボトムに向かって -n 要素分回転させます。n の絶対値を回転される部分のサイズより大きくすることはできません。また、この関数は疑似インデックスを使って呼び出すことができません。疑似インデックスは本当のスタック位置ではないためです。

lua_setallocf

[-0, +0, -] 
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);

与えられたステートのアロケータ関数とそのユーザーデータを f と ud に変更します。

lua_setfield

[-1, +0, e] 
void lua_setfield (lua_State *L, int index, const char *k);

t[k] = v と同じ処理を実行します。t はスタックの与えられたインデックスにある値であり、v はスタックトップにある値です。

この関数はスタックから v の値をポップします。Lua と同様に、この関数は newindex イベントに対するメタメソッドを起動する可能性があります (参照: § 2.4)。

lua_setglobal

[-1, +0, e] 
void lua_setglobal (lua_State *L, const char *name);

スタックから値をポップし、それをグローバル変数 name の値に設定します。

lua_seti

[-1, +0, e] 
void lua_seti (lua_State *L, int index, lua_Integer n);

t[n] = v と同じ処理を実行します。t はスタックの与えられたインデックスにある値であり、v はスタックトップにある値です。

この関数はスタックから v の値をポップします。Lua と同様に、この関数は newindex イベントに対するメタメソッドを呼び出す可能性があります (参照: § 2.4)。

lua_setiuservalue

[-1, +0, -] 
int lua_setiuservalue (lua_State *L, int index, int n);

スタックから値をポップし、それを与えられたインデックスにあるフルユーザーデータの n 個目のユーザーバリューとして設定します。指定されたユーザーデータに n 個目の値が無い場合には 0 を返します。

lua_setmetatable

[-1, +0, -] 
int lua_setmetatable (lua_State *L, int index);

テーブルあるいは nil をスタックからポップし、それをスタックの与えられたインデックスにある値の新しいメタテーブルとして設定します (メタテーブルが nil とは存在しないことを意味します)。

(歴史的な理由によりこの関数の返り値の型は int で、現在その値は常に 1 です)

lua_settable

[-2, +0, e] 
void lua_settable (lua_State *L, int index);

t[k] = v と同じ処理を実行します。t はスタックの与えられたインデックスにある値、v はスタックトップにある値、k はスタックトップの一つ下にある値です。

この関数はキーとバリューの両方をスタックからポップします。Lua と同様に、この関数は newindex イベントに対するメタメソッドを呼び出す可能性があります (参照: § 2.4)。

lua_settop

[-?, +?, -] 
void lua_settop (lua_State *L, int index);

任意のインデックスあるいは 0 を受け取り、スタックトップをその値に変更します。新しいトップが古いトップより大きい場合には、新しい部分の要素は nil となります。index が 0 なら全ての要素が削除されます。

lua_setwarnf

[-0, +0, -] 
void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);

Lua が警告を発するときに使う警告関数 (lua_WarnFunction) を設定します。パラメータ ud は警告関数へ渡される値 ud となります。

lua_State

typedef struct lua_State lua_State;

スレッドを表す不透明な (中身が明かされない) データ構造の型です。このデータ構造からはスレッド通して間接的に Lua インタープリタの状態全体にもアクセスでき、ステートに関する全ての情報にこのデータ構造からアクセスできます。Lua ライブラリは完全に再入可能です: グローバル変数は存在しません。

このデータ構造を指すポインタは Lua ライブラリの全ての関数の第一引数として渡されます。唯一の例外は Lua ステートを新しく作成する lua_newstate です。

lua_status

[-0, +0, -] 
int lua_status (lua_State *L);

スレッド L の状態を返します。

通常のスレッドの状態は LUA_OK ですが、lua_resume の実行をエラーと共に終えたスレッドではエラーコードが返り、yield で停止されたスレッドでは LUA_YIELD が返ります。

関数を呼び出せるのは状態が LUA_OK であるスレッドだけです。スレッドを開始できるのは状態が LUA_OK または LUA_YIELD であるスレッドだけであり、前者の場合にはコルーチンが新しく開始され、後者の場合にはコルーチンが再開します。

lua_stringtonumber

[-0, +1, -] 
size_t lua_stringtonumber (lua_State *L, const char *s);

ゼロ終端文字列 s を数値に変換し、それをスタックにプッシュし、文字列のサイズ (長さ + 1) を返します。変換結果は整数または浮動小数点数であり、Lua の字句変換規則 (§ 3.1) に従います。文字列には符号および (前後に) 空白が付いていても構いません。文字列が数値を表していない場合には何もプッシュせず 0 を返します。変換が成功したかどうかを表す真偽値として関数の返り値が利用できることに注意してください。

lua_toboolean

[-0, +0, -] 
int lua_toboolean (lua_State *L, int index);

スタックの与えられたインデックスにある Lua の値を C の真偽値 (0 または 1) に変換します。Lua における判定と同じように、lua_toboolean は false と nil に対して false を返し、それ以外の全ての値に対して true を返します。Lua における真偽値型の値だけを受け付けたい場合には、lua_isboolean を使って値の型を確認してください。

lua_tocfunction

[-0, +0, -] 
lua_CFunction lua_tocfunction (lua_State *L, int index);

スタックの与えられたインデックスにある値を C 関数に変換します。変換される値は C 関数である必要があり、そうでなければ NULL が返ります。

lua_toclose

[-0, +0, v] 
void lua_toclose (lua_State *L, int index);

スタックの与えられたインデックスをクローズ予約「変数」 (§ 3.3.8) として印を付けます。Lua におけるクローズ予約変数と同様に、スタックにあるこの値がスコープを外れるとクローズ処理が実行されるようになります。ここで C 関数を考えているときの「スコープを外れる」とは、関数が Lua に返ったとき、エラーが起きたとき、そして指定されたインデックスが lua_settop や lua_pop でスタックから削除されたときを意味します。クローズ予約の印が付いたスタックのインデックスを lua_settop と lua_pop 以外の API で削除してはいけません。

クローズが既に予約されているインデックスに対してこの関数を呼んではいけません。

この関数はメモリ不足エラーを送出する可能性があります。その場合には指定されたインデックスは既にクローズが予約されているように扱われ、その場でクローズされます。

lua_tointeger

[-0, +0, -] 
lua_Integer lua_tointeger (lua_State *L, int index);

isnum を NULL とした lua_tointegerx と等価です。

lua_tointegerx

[-0, +0, -] 
lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);

スタックの与えられたインデックスにある Lua の値を lua_Integer 型の符号付き整数に変換します。変換される値は整数に変換できる文字列または数値 (§ 3.4.3)、もしくは整数である必要があり、そうでなければ lua_tointegerx は 0 を返します。

isnum が NULL でない場合、*isnum に変換が成功したかどうかを表す真偽値が代入されます。

lua_tolstring

[-0, +0, m] 
const char *lua_tolstring (lua_State *L, int index, size_t *len);

スタックの与えられたインデックスにある Lua の値を C 文字列に変換します。len が NULL でなければ、*len に変換後の文字列の長さが代入されます。変換される値は文字列または数値でなければならず、そうでない場合この関数は NULL を返します。変換される値が数値のとき、lua_tolstring はスタックにある値を直接文字列に変換します。この動作のために、テーブルの走査中にキーに対して lua_tostring を使うと走査が上手く行かなくなります。

lua_tolstring は Lua ステート内部に存在する文字列へのポインタを返します。この文字列は C の文字列と同様に最後の文字の後ろにゼロ文字 ('\0') を持ちますが、本体にゼロ文字を持つことは可能です。

Lua には GC があるので、lua_tolstring が返すポインタに対応する Lua の値がスタックから取り除かれた時点で返り値のポインタが有効である保証は無くなります。

lua_tonumber

[-0, +0, -] 
lua_Number lua_tonumber (lua_State *L, int index);

isnum を NULL として呼び出す lua_tonumberx と等価です。

lua_tonumberx

[-0, +0, -] 
lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);

スタックの与えられたインデックスにある Lua の値を C の lua_Number 型の値に変換します。変換される値は数値または数値に変換可能な文字列である必要があり、それ以外のときこの関数は 0 を返します。

isnum が NULL でない場合、変換が成功したかどうかを表す真偽値が *isnum に代入されます。

lua_topointer

[-0, +0, -] 
const void *lua_topointer (lua_State *L, int index);

スタックの与えられたインデックスにある値を void* 型の C ポインタに変換します。変換される値はユーザーデータ・テーブル・スレッド・文字列・関数のいずれかである必要があり、それ以外のときこの関数は NULL を返します。異なるオブジェクトからは異なるポインタが返ります。変換されたポインタから元の値を取得する方法はありません。

通常この関数はデバッグ情報の収集とハッシュの計算だけに使われます。

lua_tostring

[-0, +0, m] 
const char *lua_tostring (lua_State *L, int index);

len を NULL とした lua_tolstring と等価です。

lua_tothread

[-0, +0, -] 
lua_State *lua_tothread (lua_State *L, int index);

スタックの与えられたインデックスにある値を lua_State* 型の Lua スレッドに変換します。変換される値はスレッドである必要があり、それ以外のときこの関数は NULL を返します。

lua_touserdata

[-0, +0, -] 
void *lua_touserdata (lua_State *L, int index);

スタックの与えられたインデックスにある値がフルユーザーデータなら、そのメモリ領域を指すポインタを返します。もし値がライトユーザーデータなら、その値 (ポインタ) を返します。それ以外のとき NULL を返します。

lua_type

[-0, +0, -] 
int lua_type (lua_State *L, int index);

与えられたインデックスが有効ならそれが指す値の型を返し、有効でない処理可能なインデックスなら LUA_TNONE を返します。lua_type が返す型は lua.h で定義される次の定数のいずれかです:

lua_typename

[-0, +0, -] 
const char *lua_typename (lua_State *L, int tp);

tp がエンコードする型の名前を返します。tp は lua_type が返す値のいずれかである必要があります。

lua_Unsigned

typedef ... lua_Unsigned;

符号無しの lua_Integer です。

lua_upvalueindex

[-0, +0, -] 
int lua_upvalueindex (int i);

実行中の関数の i 番目のアップバリュー (§ 4.2) を表す疑似インデックスを返します。i は [1, 256] の範囲にある必要があります。

lua_version

[-0, +0, -] 
lua_Number lua_version (lua_State *L);

このコアのバージョン番号を返します。

lua_WarnFunction

typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);

Lua が警告を発するときに呼ぶ警告関数の型です。一つ目のパラメータは lua_setwarnf で設定される不透明ポインタであり、二つ目のパラメータは警告メッセージです。三つ目のパラメータはこのメッセージの後に別のメッセージが続くかどうかを表す真偽値です。

警告について詳しくは warn を参照してください。

lua_warning

[-0, +0, -] 
void lua_warning (lua_State *L, const char *msg, int tocont);

与えられたメッセージを持つ警告を発生させます。tocont を true にしてこの関数を呼び出した場合には、その後にこの関数をもう一度呼び出すべきです。

警告について詳しくは warn を参照してください。

lua_Writer

typedef int (*lua_Writer) (lua_State *L,
                           const void* p,
                           size_t sz,
                           void* ud);

lua_dump が使う writer 関数の型です。lua_dump がチャンクの一部を生成するたびに writer 関数が呼ばれ、そのとき書き込むデータのあるバッファ (p) とバッファのサイズ (sz) そして lua_dump に渡された ud が writer 関数に渡されます。

writer 関数が返すのはエラーコードであり、エラーが起きなければ 0 です。エラーを表す他の値が返ると、lua_dump はそれ以上 writer 関数を呼び出さなくなります。

lua_xmove

[-?, +?, -] 
void lua_xmove (lua_State *from, lua_State *to, int n);

同じステート内の異なるスレッドの間で値を交換します。

この関数は from のスタックから n 個の値をポップし、それらを to のスタックにプッシュします。

lua_yield

[-?, +?, v] 
int lua_yield (lua_State *L, int nresults);

この関数は基本的に lua_yieldk と同じですが、継続 (§ 4.5) を持ちません。そのためスレッドを resume すると、lua_yield を呼んだ関数を呼んだ関数2が再開されます。コードを理解しやすくするために、この関数は末尾呼び出しとしてのみ使われるべきです。

lua_yieldk

[-?, +?, v] 
int lua_yieldk (lua_State *L,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

コルーチン (スレッド) を yield します。

C 関数が lua_yieldk を呼ぶと実行中のスレッドが停止し、そのコルーチンを開始した lua_resume の呼び出しが返ります。パラメータ nresults は lua_resume の返り値としてスタックに積まれている値の数です。

yield したコルーチンをもう一度 resume すると、Lua は lua_yieldk に渡された継続関数 k を実行して yield した C 関数の実行を「再開」します (参照: § 4.5)。この継続関数は元の関数と同じスタックを受け取り、そのときスタックにある nresults 個の値は取り除かれて lua_resume に渡された引数に置き換えられます。さらに継続関数は lua_yieldk に渡された ctx も受け取ります。

通常この関数は返りません: コルーチンが resume すると継続関数で実行が受け継がれるからです。しかし例外が一つだけあります。それはラインフックまたはカウントフック (§ 4.7) の内側で呼ばれるときで、このときは lua_yieldk に継続関数を渡すべきではありません (あるいは最初から lua_yield を使うべきです)。この二つのフックでは lua_yieldk が値を返すことは許されず、lua_yield[k] の呼び出しの後すぐにフックが返ることが求められます。フックの関数が yield しその後コルーチンが resume されると、フックを呼び出した (Lua) 関数の通常の実行が再開されます。

スレッドが継続関数を持たない実行途中の C 呼び出し (いわゆる C 呼び出し境界 (C-call boundary) ) を持つ場合、およびスレッドが resume を実行していない場合 (よくあるのがメインスレッドから lua_yieldk を呼んだとき) には、lua_yieldk はエラーを送出する場合があります。

  1. 訳注: 例えばメインスレッドから lua_resume を呼ぶときなど。なおソースコードによると、from はスタックオーバーフローを検出するためだけに使われる。[return]

  2. 訳注: 「Lua が実行を追えている最後の関数」と表現した方が正確だと思われる。[return]

広告
このページの文章はテキストゆれないくんを使って校正されました。