モジュール java.base
パッケージ java.lang.foreign

インタフェースVaList

すべてのスーパー・インタフェース:
AddressablePREVIEW
public sealed interface VaList extends AddressablePREVIEW
VaListは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでVaListを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
変数引数リスト。C va_listと機能的に似ています。

変数引数リストは、一連の引数を反復するために使用されるステートフル・カーソルです。 変数引数リストは、参照、例えば、によって「ダウンコール・メソッド・ハンドル」PREVIEWに渡すことができます。

C仕様 (C99標準6.5.2.2関数コール - アイテム6を参照) に従って、可変個呼び出しへの引数は、整数昇格 (C99標準6.3.1.1 - アイテム2を参照)によって整数型を消去し、doubleのすべてのfloat引数を消去する'デフォルトの引数プロモーション'によって消去されます。

そのため、このインタフェースでは、int、doubleおよびlongに適合するその他のタイプの読取りのみがサポートされます。

安全に関する考慮事項

クライアントは、変数引数リストの空間境界外の要素にアクセスできます。 可変引数リストの実装では、範囲外の読み取りをベスト・エフォートで検出しようとします。

この検出が成功するかどうかは、変数引数リストの作成に使用されるファクトリ・メソッドによって異なります:

このクラスはスレッド・セーフではなく、すべてのアクセスは単一のスレッド (変数arityリストに関連付けられたメモリー・セッションに関係なく)内で行う必要があります。

導入されたバージョン:
19

  • メソッドの詳細

    • session

      MemorySessionPREVIEW session()
      この変数引数リストに関連付けられたメモリー・セッションを返します。
      戻り値:
      この変数引数リストに関連付けられたメモリー・セッション

    • nextVarg

      int nextVarg(ValueLayout.OfIntPREVIEW layout)
      次の値をintとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。
      パラメータ:
      layout - 読み取る値のレイアウト。
      戻り値:
      この変数引数リストから読み取られるint値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられている「セッション」がalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、この変数引数リストに関連付けられた「セッション」を所有するスレッド以外のスレッドからコールされる場合。
      NoSuchElementException - out-of-bounds読取りが検出された場合。

    • nextVarg

      long nextVarg(ValueLayout.OfLongPREVIEW layout)
      次の値をlongとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。
      パラメータ:
      layout - 読み取る値のレイアウト。
      戻り値:
      この変数引数リストから読み取られるlong値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられている「セッション」がalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、この変数引数リストに関連付けられた「セッション」を所有するスレッド以外のスレッドからコールされる場合。
      NoSuchElementException - out-of-bounds読取りが検出された場合。

    • nextVarg

      double nextVarg(ValueLayout.OfDoublePREVIEW layout)
      次の値をdoubleとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。
      パラメータ:
      layout - 値のレイアウト
      戻り値:
      この変数引数リストから読み取られるdouble値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられている「セッション」がalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、この変数引数リストに関連付けられた「セッション」を所有するスレッド以外のスレッドからコールされる場合。
      NoSuchElementException - out-of-bounds読取りが検出された場合。

    • nextVarg

      MemoryAddressPREVIEW nextVarg(ValueLayout.OfAddressPREVIEW layout)
      次の値をMemoryAddressとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。
      パラメータ:
      layout - 読み取る値のレイアウト。
      戻り値:
      この変数引数リストから読み取られるMemoryAddress値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられている「セッション」がalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、この変数引数リストに関連付けられた「セッション」を所有するスレッド以外のスレッドからコールされる場合。
      NoSuchElementException - out-of-bounds読取りが検出された場合。

    • nextVarg

      MemorySegmentPREVIEW nextVarg(GroupLayoutPREVIEW layout, SegmentAllocatorPREVIEW allocator)
      次の値をMemorySegmentとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。 指定されたグループ・レイアウトは、C構造体または共用体タイプに対応している必要があります。

      返されるセグメントでの値の読取り方法は、ABIに依存: メンバー・レイアウトL_1, L_2, ... L_nを持つグループ・レイアウトでこのメソッドを呼び出すことは、L_1, L_2, ... L_nの各レイアウトに対してnextVargへの個別のコールを実行する意味的に等しくなるとはかぎりません。

      このメソッドによって返されるメモリー・セグメントは、指定されたSegmentAllocatorPREVIEWを使用して割り当てられます。

      パラメータ:
      layout - 読み取る値のレイアウト。
      allocator - 変数引数リストの内容がコピーされるセグメントの作成に使用するロケータ。
      戻り値:
      この変数引数リストから読み取られるMemorySegment値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられている「セッション」がalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、この変数引数リストに関連付けられた「セッション」を所有するスレッド以外のスレッドからコールされる場合。
      NoSuchElementException - out-of-bounds読取りが検出された場合。

    • skip

      void skip(MemoryLayoutPREVIEW... layouts)
      指定されたメモリー・レイアウトを持つ多数の要素をスキップし、この変数引数リストの位置を先に進めます。
      パラメータ:
      layouts - スキップする値のレイアウト。
      例外:
      IllegalStateException - この変数引数リストに関連付けられている「セッション」がalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、この変数引数リストに関連付けられた「セッション」を所有するスレッド以外のスレッドからコールされる場合。
      NoSuchElementException - out-of-bounds読取りが検出された場合。

    • copy

      VaListPREVIEW copy()
      この変数引数リストを現在の位置にコピーして、この変数引数リストと同じメモリー・セッションに関連付けられた新しい変数引数リストを作成します。 このメソッドの動作は、Cのva_copy関数と同じです。

      コピーは、元の変数引数リストの状態に影響を与えずに、変数引数リスト要素を現在の位置から移動する場合に役立ちます。基本的に、要素を複数回移動できます。

      戻り値:
      この変数引数リストのコピー。
      例外:
      IllegalStateException - この変数引数リストに関連付けられている「セッション」がalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、この変数引数リストに関連付けられた「セッション」を所有するスレッド以外のスレッドからコールされる場合。

    • address

      MemoryAddressPREVIEW address()
      この変数引数リストに関連付けられている「メモリー・アドレス」PREVIEWを返します。
      定義:
      インタフェースAddressablePREVIEW内のaddress
      戻り値:
      この変数引数リストに関連付けられた「メモリー・アドレス」PREVIEW
      例外:
      IllegalStateException - この変数引数リストに関連付けられている「セッション」がalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、この変数引数リストに関連付けられた「セッション」を所有するスレッド以外のスレッドからコールされる場合。

    • ofAddress

      static VaListPREVIEW ofAddress(MemoryAddressPREVIEW address, MemorySessionPREVIEW session)
      指定されたメモリー・セッションを使用して、既存の変数引数リストを指すメモリー・アドレスから変数引数リストを作成します。

      このメソッドは「制限付き」です。 制限されたメソッドは安全ではなく、誤って使用するとJVMがクラッシュしたり、悪化したりするとメモリーが破損する可能性があります。 したがって、クライアントは制限付きメソッドに応じて屈折し、可能な場合は安全でサポートされている機能を使用する必要があります。

      実装上のノート:
      このメソッドを使用して作成された変数引数リストは、out-of-bounds読取りを検出できません。
      パラメータ:
      address - 既存の変数引数リストを指すメモリー・アドレス。
      session - 返された変数引数リストに関連付けられるメモリー・セッション。
      戻り値:
      addressのメモリー・リージョンによってバックアップされる新しい変数引数リスト。
      例外:
      IllegalStateException - sessionがalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、sessionを「所有している」PREVIEWスレッド以外のスレッドからコールされる場合。
      UnsupportedOperationException - 基盤となるネイティブ・プラットフォームがサポートされていない場合。
      IllegalCallerException - このメソッドへのアクセスがモジュールMから発生し、コマンドライン・オプション--enable-native-accessが指定されているが、モジュール名M、またはMが無名モジュールの場合はALL-UNNAMEDが指定されていない場合。

    • make

      static VaListPREVIEW make(Consumer<VaList.BuilderPREVIEW> actions, MemorySessionPREVIEW session)
      指定されたメモリー・セッションを持つビルダー(VaList.BuilderPREVIEWを参照してください)を使用して、変数引数リストを作成します。

      このメソッドでメモリーを割り当てる必要がある場合、このようなメモリーは指定されたメモリー・セッションによって管理され、メモリー・セッションがclosedPREVIEWのときに解放されます。

      作成されたvaリストに要素が追加されていない場合、このメソッドはempty()と同じものを返します。

      実装上のノート:
      このメソッドを使用して作成された変数引数リストは、out-of-bounds読取りを検出できます。
      パラメータ:
      actions - 基礎となる変数引数リストの要素を指定するために使用できるビルダー(VaList.BuilderPREVIEWを参照してください)のコンシューマ。
      session - 新しい変数arityリストに関連付けるメモリー・セッション。
      戻り値:
      新しい変数引数リスト。
      例外:
      UnsupportedOperationException - 基盤となるネイティブ・プラットフォームがサポートされていない場合。
      IllegalStateException - sessionがalivePREVIEWでない場合。
      WrongThreadException - このメソッドが、sessionを「所有している」PREVIEWスレッド以外のスレッドからコールされる場合。

    • empty

      static VaListPREVIEW empty()
      globalPREVIEWメモリー・セッションに関連付けられた空の変数引数リストを返します。 結果の変数引数リストには引数が含まれず、address()、copy()およびsession()を除くすべての演算でUnsupportedOperationExceptionがスローされます。
      戻り値:
      空の変数引数リスト。
      例外:
      UnsupportedOperationException - 基盤となるネイティブ・プラットフォームがサポートされていない場合。