モジュール jdk.incubator.foreign
パッケージ jdk.incubator.foreign

インタフェースVaList

すべてのスーパー・インタフェース:
Addressable
public sealed interface VaList extends Addressable
C va_listと同様に、変数引数リストをモデル化するインタフェース。

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

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

そのため、このインタフェースでは、int、doubleおよびlongに適合するその他のタイプの読取りのみがサポートされます。 このクラスはスレッド安全ではないため、すべてのアクセスは単一のスレッド (変数アリティ・リストに関連付けられたスコープに関係なく)内で発生する必要があります。

特に指定がないかぎり、null引数、またはこのクラスのメソッドに1つ以上のnull要素を含む配列引数を渡すと、NullPointerExceptionがスローされます。

  • ネストされたクラスのサマリー

    ネストされたクラス
    修飾子と型
    インタフェース
    説明
    static interface 
    VaList.Builder
    変数引数リストの作成に使用されるビルダー・インタフェース。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    MemoryAddress
    address()
    この変数引数リストに関連付けられた「メモリー・アドレス」を返します。
    VaList
    copy()
    この変数引数リストを現在の位置にコピーし、この変数引数リストと同じスコープに関連付けられた新しい変数引数リストにコピーします。
    static VaList
    empty()
    「グローバル」スコープに関連付けられた空の変数引数リストを返します。
    static VaList
    make(Consumer<VaList.Builder> actions, ResourceScope scope)
    特定のリソース・スコープを使用して、ビルダー(VaList.Builderを参照してください)を使用して新しい変数引数リストを構成します。
    MemorySegment
    nextVarg(GroupLayout layout, SegmentAllocator allocator)
    次の値をMemorySegmentとして読み取って、この変数引数リストの位置を進めます。
    MemoryAddress
    nextVarg(ValueLayout.OfAddress layout)
    次の値をMemoryAddressとして読み取って、この変数引数リストの位置を進めます。
    double
    nextVarg(ValueLayout.OfDouble layout)
    次の値をdoubleとして読み取って、この変数引数リストの位置を進めます。
    int
    nextVarg(ValueLayout.OfInt layout)
    次の値をintとして読み取って、この変数引数リストの位置を進めます。
    long
    nextVarg(ValueLayout.OfLong layout)
    次の値をlongとして読み取って、この変数引数リストの位置を進めます。
    static VaList
    ofAddress(MemoryAddress address, ResourceScope scope)
    指定されたリソース・スコープで、既存の変数引数リストを指すメモリー・アドレスから新しい変数引数リストを構成します。
    ResourceScope
    scope()
    この変数引数リストに関連付けられたリソース・スコープを返します。
    void
    skip(MemoryLayout... layouts)
    指定されたメモリー・レイアウトを持つ多数の要素をスキップし、この変数引数リストの位置を先に進めます。

  • メソッドの詳細

    • nextVarg

      int nextVarg(ValueLayout.OfInt layout)
      次の値をintとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。
      パラメータ:
      layout - 読み取る値のレイアウト。
      戻り値:
      この変数引数リストから読み取られるint値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられたスコープが閉じられている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • nextVarg

      long nextVarg(ValueLayout.OfLong layout)
      次の値をlongとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。
      パラメータ:
      layout - 読み取る値のレイアウト。
      戻り値:
      この変数引数リストから読み取られるlong値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられたスコープが閉じられている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • nextVarg

      double nextVarg(ValueLayout.OfDouble layout)
      次の値をdoubleとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。
      パラメータ:
      layout - 値のレイアウト
      戻り値:
      この変数引数リストから読み取られるdouble値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられたスコープが閉じられている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • nextVarg

      MemoryAddress nextVarg(ValueLayout.OfAddress layout)
      次の値をMemoryAddressとして読み取って、この変数引数リストの位置を進めます。 このメソッドの動作は、Cのva_arg関数と同じです。
      パラメータ:
      layout - 読み取る値のレイアウト。
      戻り値:
      この変数引数リストから読み取られるMemoryAddress値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられたスコープが閉じられている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • nextVarg

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

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

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

      パラメータ:
      layout - 読み取る値のレイアウト。
      allocator - 変数引数リストの内容がコピーされるセグメントの作成に使用するロケータ。
      戻り値:
      この変数引数リストから読み取られるMemorySegment値。
      例外:
      IllegalStateException - この変数引数リストに関連付けられたスコープが閉じられている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • skip

      void skip(MemoryLayout... layouts)
      指定されたメモリー・レイアウトを持つ多数の要素をスキップし、この変数引数リストの位置を先に進めます。
      パラメータ:
      layouts - スキップする値のレイアウト。
      例外:
      IllegalStateException - この変数引数リストに関連付けられたスコープが閉じられている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • scope

      ResourceScope scope()
      この変数引数リストに関連付けられたリソース・スコープを返します。
      戻り値:
      この変数引数リストに関連付けられたリソース・スコープ

    • copy

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

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

      戻り値:
      この変数引数リストのコピー。
      例外:
      IllegalStateException - この変数引数リストに関連付けられたスコープが閉じられている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • address

      MemoryAddress address()
      この変数引数リストに関連付けられた「メモリー・アドレス」を返します。
      定義:
      インタフェースAddressable内のaddress
      戻り値:
      この変数引数リストに関連付けられた「メモリー・アドレス」
      例外:
      IllegalStateException - この変数引数リストに関連付けられたスコープが閉じられている場合、またはそのスコープを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • ofAddress

      static VaList ofAddress(MemoryAddress address, ResourceScope scope)
      指定されたリソース・スコープで、既存の変数引数リストを指すメモリー・アドレスから新しい変数引数リストを構成します。

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

      パラメータ:
      address - 既存の変数引数リストを指すメモリー・アドレス。
      scope - 返される変数引数リストに関連付けるリソース・スコープ。
      戻り値:
      addressのメモリー・リージョンによってバックアップされる新しい変数引数リスト。
      例外:
      IllegalStateException - scopeがすでにクローズされている場合、またはscopeを所有するスレッド以外のスレッドからアクセスが発生した場合。
      IllegalCallerException - このメソッドへのアクセスがモジュールMから発生し、コマンドライン・オプション--enable-native-accessがない場合、またはモジュール名Mが名前なしモジュールの場合はALL-UNNAMEDは説明しません。

    • make

      static VaList make(Consumer<VaList.Builder> actions, ResourceScope scope)
      特定のリソース・スコープを使用して、ビルダー(VaList.Builderを参照してください)を使用して新しい変数引数リストを構成します。

      このメソッドがネイティブ・メモリーを割り当てる必要がある場合、このようなメモリーは指定された「リソース・スコープ」によって管理され、リソース・スコープがclosedのときに解放されます。

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

      パラメータ:
      actions - 基礎となる変数引数リストの要素を指定するために使用できる、ビルダー(VaList.Builderを参照してください)のコンシューマ。
      scope - 新しい変数アリティ・リストに関連付けるスコープをスコープにします。
      戻り値:
      新しい変数引数リスト。
      例外:
      IllegalStateException - scopeがすでにクローズされている場合、またはscopeを所有するスレッド以外のスレッドからアクセスが発生した場合。

    • empty

      static VaList empty()
      「グローバル」スコープに関連付けられた空の変数引数リストを返します。 結果の変数引数リストには引数が含まれず、scope()、copy()およびaddress()を除くすべての操作でUnsupportedOperationExceptionをスローします。
      戻り値:
      空の変数引数リスト。