duk_push_heapptr()

1.1.0 stack object heap ptr borrowed

プロトタイプ

duk_idx_t duk_push_heapptr(duk_context *ctx, void *ptr);

スタック

| ... | -> | ... | obj | (if ptr != NULL) | ... | -> | ... | undefined | (if ptr == NULL)

要約

Duk_get_heapptr() またはその亜種から借用したポインタ参照を使って、 Duktape ヒープオブジェクトをバリュースタックにプッシュします。ptr が NULL の場合、undefined がプッシュされます。

呼び出し側は、引数 ptr がプッシュされたときにまだ有効である (Duktape ガベージコレクションによって解放されていない) ことを確認する責任があります。これを怠ると、予測不可能でメモリが安全でない動作になります。

これを確実にするために、2つの基本的な方法があります。

強力な後方参照：関連するヒープ・オブジェクトが、duk_get_heapptr() と duk_push_heapptr() の間で Duktape ガベージコレクションのために常に到達可能であることを保証します。例えば、借用した void ポインタが使用されている間に、関連するオブジェクトがスタッ シュに書き込まれたことを確認します。要するに、アプリケーションは、強く参照される値によってバックされる借用された参照を保持しているのです。これは、Duktape 2.1以前でサポートされていた唯一の方法です。 弱い参照＋ファイナライザー：関連するヒープ・オブジェクトのために（できればネイティブの）ファイナライザーを追加し、遅くともファイナライザーが呼ばれた時点で（オブジェクトがファイナライザーによって救出されないと仮定して）voidポインターの使用を停止します。Duktape 2.1以降では、到達不可能なオブジェクトに対して、ファイナライザーを呼び出すまで、duk_push_heapptr()が許可されるようになりました。この方法によって、アプリケーションは関連するオブジェクトへの弱い参照を保持することができます。ただし、以下の制限事項を参照してください。 ファイナライザーの呼び出しは、メモリ不足などで静かに失敗することがあります。ポインタの有効期間の終了を示すためにファイナライザコールに依存している場合、 ファイナライザコールを逃すと duk_push_heapptr() にぶら下がったポインタが与えられる可能性があります。この状況に対する回避策は今のところありません。したがって、もしメモリ不足の状態が予想されるなら、ファイナライザに基づくアプローチは確実に機能しないかもしれません。今後の課題は、少なくともネイティブファイナライザ関数へのエントリーが成功しないとオブジェクトが解放されないようにすることです。https://github.com/svaarala/duktape/issues/1456 を参照してください。

例

void *ptr;
duk_idx_t idx;

/* 'ptr' originally obtained using duk_get_heapptr() earlier: */

idx = duk_push_heapptr(ctx, ptr);

参照

duk_get_heapptr duk_require_heapptr