Module jdk.incubator.foreign
Package jdk.incubator.foreign

Interface VaList

All Superinterfaces:
Addressable
public sealed interface VaList extends Addressable
An interface that models a variable argument list, similar in functionality to a C va_list.

A variable argument list is a stateful cursor used to iterate over a set of arguments. A variable argument list can be passed by reference e.g. to a downcall method handle.

Per the C specification (see C standard 6.5.2.2 Function calls - item 6), arguments to variadic calls are erased by way of 'default argument promotions', which erases integral types by way of integer promotion (see C standard 6.3.1.1 - item 2), and which erases all float arguments to double.

As such, this interface only supports reading int, double, and any other type that fits into a long. This class is not thread safe, and all accesses should occur within a single thread (regardless of the scope associated with the variable arity list).

Unless otherwise specified, passing a null argument, or an array argument containing one or more null elements to a method in this class causes a NullPointerException to be thrown.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    VaList.Builder
    A builder interface used to construct a variable argument list.

  • Method Summary

    Modifier and Type
    Method
    Description
    MemoryAddress
    address()
    Returns the memory address associated with this variable argument list.
    VaList
    copy()
    Copies this variable argument list at its current position into a new variable argument list associated with the same scope as this variable argument list.
    static VaList
    empty()
    Returns an empty variable argument list, associated with the global scope.
    static VaList
    make(Consumer<VaList.Builder> actions, ResourceScope scope)
    Constructs a new variable argument list using a builder (see VaList.Builder), with a given resource scope.
    MemorySegment
    nextVarg(GroupLayout layout, SegmentAllocator allocator)
    Reads the next value as a MemorySegment, and advances this variable argument list's position.
    MemoryAddress
    nextVarg(ValueLayout.OfAddress layout)
    Reads the next value as a MemoryAddress and advances this variable argument list's position.
    double
    nextVarg(ValueLayout.OfDouble layout)
    Reads the next value as a double and advances this variable argument list's position.
    int
    nextVarg(ValueLayout.OfInt layout)
    Reads the next value as an int and advances this variable argument list's position.
    long
    nextVarg(ValueLayout.OfLong layout)
    Reads the next value as a long and advances this variable argument list's position.
    static VaList
    ofAddress(MemoryAddress address, ResourceScope scope)
    Constructs a new variable argument list from a memory address pointing to an existing variable argument list, with given resource scope.
    ResourceScope
    scope()
    Returns the resource scope associated with this variable argument list.
    void
    skip(MemoryLayout... layouts)
    Skips a number of elements with the given memory layouts, and advances this variable argument list's position.

  • Method Details

    • nextVarg

      int nextVarg(ValueLayout.OfInt layout)
      Reads the next value as an int and advances this variable argument list's position. The behavior of this method is equivalent to the C va_arg function.
      Parameters:
      layout - the layout of the value to be read.
      Returns:
      the int value read from this variable argument list.
      Throws:
      IllegalStateException - if the scope associated with this variable argument list has been closed, or if access occurs from a thread other than the thread owning that scope.

    • nextVarg

      long nextVarg(ValueLayout.OfLong layout)
      Reads the next value as a long and advances this variable argument list's position. The behavior of this method is equivalent to the C va_arg function.
      Parameters:
      layout - the layout of the value to be read.
      Returns:
      the long value read from this variable argument list.
      Throws:
      IllegalStateException - if the scope associated with this variable argument list has been closed, or if access occurs from a thread other than the thread owning that scope.

    • nextVarg

      double nextVarg(ValueLayout.OfDouble layout)
      Reads the next value as a double and advances this variable argument list's position. The behavior of this method is equivalent to the C va_arg function.
      Parameters:
      layout - the layout of the value
      Returns:
      the double value read from this variable argument list.
      Throws:
      IllegalStateException - if the scope associated with this variable argument list has been closed, or if access occurs from a thread other than the thread owning that scope.

    • nextVarg

      MemoryAddress nextVarg(ValueLayout.OfAddress layout)
      Reads the next value as a MemoryAddress and advances this variable argument list's position. The behavior of this method is equivalent to the C va_arg function.
      Parameters:
      layout - the layout of the value to be read.
      Returns:
      the MemoryAddress value read from this variable argument list.
      Throws:
      IllegalStateException - if the scope associated with this variable argument list has been closed, or if access occurs from a thread other than the thread owning that scope.

    • nextVarg

      MemorySegment nextVarg(GroupLayout layout, SegmentAllocator allocator)
      Reads the next value as a MemorySegment, and advances this variable argument list's position. The behavior of this method is equivalent to the C va_arg function. The provided group layout must correspond to a C struct or union type.

      How the value is read in the returned segment is ABI-dependent: calling this method on a group layout with member layouts L_1, L_2, ... L_n is not guaranteed to be semantically equivalent to perform distinct calls to nextVarg for each of the layouts in L_1, L_2, ... L_n.

      The memory segment returned by this method will be allocated using the given SegmentAllocator.

      Parameters:
      layout - the layout of the value to be read.
      allocator - the allocator to be used to create a segment where the contents of the variable argument list will be copied.
      Returns:
      the MemorySegment value read from this variable argument list.
      Throws:
      IllegalStateException - if the scope associated with this variable argument list has been closed, or if access occurs from a thread other than the thread owning that scope.

    • skip

      void skip(MemoryLayout... layouts)
      Skips a number of elements with the given memory layouts, and advances this variable argument list's position.
      Parameters:
      layouts - the layouts of the values to be skipped.
      Throws:
      IllegalStateException - if the scope associated with this variable argument list has been closed, or if access occurs from a thread other than the thread owning that scope.

    • scope

      ResourceScope scope()
      Returns the resource scope associated with this variable argument list.
      Returns:
      the resource scope associated with this variable argument list

    • copy

      VaList copy()
      Copies this variable argument list at its current position into a new variable argument list associated with the same scope as this variable argument list. The behavior of this method is equivalent to the C va_copy function.

      Copying is useful to traverse the variable argument list elements, starting from the current position, without affecting the state of the original variable argument list, essentially allowing the elements to be traversed multiple times.

      Returns:
      a copy of this variable argument list.
      Throws:
      IllegalStateException - if the scope associated with this variable argument list has been closed, or if access occurs from a thread other than the thread owning that scope.

    • address

      MemoryAddress address()
      Returns the memory address associated with this variable argument list.
      Specified by:
      address in interface Addressable
      Returns:
      the memory address associated with this variable argument list
      Throws:
      IllegalStateException - if the scope associated with this variable argument list has been closed, or if access occurs from a thread other than the thread owning that scope.

    • ofAddress

      static VaList ofAddress(MemoryAddress address, ResourceScope scope)
      Constructs a new variable argument list from a memory address pointing to an existing variable argument list, with given resource scope.

      This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

      Parameters:
      address - a memory address pointing to an existing variable argument list.
      scope - the resource scope to be associated with the returned variable argument list.
      Returns:
      a new variable argument list backed by the memory region at address.
      Throws:
      IllegalStateException - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.
      IllegalCallerException - if access to this method occurs from a module M and the command line option --enable-native-access is either absent, or does not mention the module name M, or ALL-UNNAMED in case M is an unnamed module.

    • make

      static VaList make(Consumer<VaList.Builder> actions, ResourceScope scope)
      Constructs a new variable argument list using a builder (see VaList.Builder), with a given resource scope.

      If this method needs to allocate native memory, such memory will be managed by the given resource scope, and will be released when the resource scope is closed.

      Note that when there are no elements added to the created va list, this method will return the same as empty().

      Parameters:
      actions - a consumer for a builder (see VaList.Builder) which can be used to specify the elements of the underlying variable argument list.
      scope - scope the scope to be associated with the new variable arity list.
      Returns:
      a new variable argument list.
      Throws:
      IllegalStateException - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.

    • empty

      static VaList empty()
      Returns an empty variable argument list, associated with the global scope. The resulting variable argument list does not contain any argument, and throws UnsupportedOperationException on all operations, except for scope(), copy() and address().
      Returns:
      an empty variable argument list.