Package Summary Overview Summary

### class:VaList [NONE]
All Superinterfaces: `AddressablePREVIEW` public sealed interface VaList extends AddressablePREVIEW `VaList` is a preview API of the Java platform. Programs can only use `VaList` when preview features are enabled. Preview features may be removed in a future release, or upgraded to permanent features of the Java platform. 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 PREVIEW. Per the C specification (see C99 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 C99 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 memory session associated with the variable arity list). Since: 19

### method:session() [NONE]
### session MemorySessionPREVIEW session() Returns the memory session associated with this variable argument list. Returns: the memory session associated with this variable argument list

### method:nextVarg(java.lang.foreign.ValueLayout.OfInt) [CHANGED]
### nextVarg int nextVarg (ValueLayout.OfIntPREVIEW 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 session associated with this variable argument list is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owning that the session associated with this variable argument list.
### nextVarg int nextVarg (ValueLayout.OfIntPREVIEW 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 session associated with this variable argument list is not alivePREVIEW, or if access occurs from a thread other than the thread owning that session. | ### nextVarg int nextVarg (ValueLayout.OfIntPREVIEW 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 session associated with this variable argument list is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owning the session associated with this variable argument list.

### method:nextVarg(java.lang.foreign.ValueLayout.OfLong) [CHANGED]
### nextVarg long nextVarg (ValueLayout.OfLongPREVIEW 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 session associated with this variable argument list is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owning that the session associated with this variable argument list.
### nextVarg long nextVarg (ValueLayout.OfLongPREVIEW 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 session associated with this variable argument list is not alivePREVIEW, or if access occurs from a thread other than the thread owning that session. | ### nextVarg long nextVarg (ValueLayout.OfLongPREVIEW 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 session associated with this variable argument list is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owning the session associated with this variable argument list.

### method:nextVarg(java.lang.foreign.ValueLayout.OfDouble) [CHANGED]
### nextVarg double nextVarg (ValueLayout.OfDoublePREVIEW 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 session associated with this variable argument list is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owning that the session associated with this variable argument list.
### nextVarg double nextVarg (ValueLayout.OfDoublePREVIEW 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 session associated with this variable argument list is not alivePREVIEW, or if access occurs from a thread other than the thread owning that session. | ### nextVarg double nextVarg (ValueLayout.OfDoublePREVIEW 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 session associated with this variable argument list is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owning the session associated with this variable argument list.

### method:nextVarg(java.lang.foreign.ValueLayout.OfAddress) [CHANGED]
### nextVarg MemoryAddressPREVIEW nextVarg (ValueLayout.OfAddressPREVIEW 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 session associated with this variable argument list is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owning that the session associated with this variable argument list.
### nextVarg MemoryAddressPREVIEW nextVarg (ValueLayout.OfAddressPREVIEW 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 session associated with this variable argument list is not alivePREVIEW, or if access occurs from a thread other than the thread owning that session. | ### nextVarg MemoryAddressPREVIEW nextVarg (ValueLayout.OfAddressPREVIEW 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 session associated with this variable argument list is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owning the session associated with this variable argument list.

### method:nextVarg(java.lang.foreign.GroupLayout,java.lang.foreign.SegmentAllocator) [CHANGED]
### nextVarg MemorySegmentPREVIEW nextVarg (GroupLayoutPREVIEW layout, SegmentAllocatorPREVIEW 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`PREVIEW. 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 session associated with this variable argument list is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owning that the session associated with this variable argument list.
### nextVarg MemorySegmentPREVIEW nextVarg (GroupLayoutPREVIEW layout, SegmentAllocatorPREVIEW 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`PREVIEW. 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 session associated with this variable argument list is not alivePREVIEW, or if access occurs from a thread other than the thread owning that session. | ### nextVarg MemorySegmentPREVIEW nextVarg (GroupLayoutPREVIEW layout, SegmentAllocatorPREVIEW 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`PREVIEW. 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 session associated with this variable argument list is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owning the session associated with this variable argument list.

### method:skip(java.lang.foreign.MemoryLayout...) [CHANGED]
### skip void skip (MemoryLayoutPREVIEW... 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 session associated with this variable argument list is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owning that the session associated with this variable argument list.
### skip void skip (MemoryLayoutPREVIEW... 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 session associated with this variable argument list is not alivePREVIEW, or if access occurs from a thread other than the thread owning that session. | ### skip void skip (MemoryLayoutPREVIEW... 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 session associated with this variable argument list is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owning the session associated with this variable argument list.

### method:copy() [CHANGED]
### copy VaListPREVIEW copy() Copies this variable argument list at its current position into a new variable argument list associated with the same memory session 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 session associated with this variable argument list is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owning that the session associated with this variable argument list.
### copy VaListPREVIEW copy() Copies this variable argument list at its current position into a new variable argument list associated with the same memory session 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 session associated with this variable argument list is not alivePREVIEW, or if access occurs from a thread other than the thread owning that session. | ### copy VaListPREVIEW copy() Copies this variable argument list at its current position into a new variable argument list associated with the same memory session 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 session associated with this variable argument list is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owning the session associated with this variable argument list.

### method:address() [CHANGED]
### address MemoryAddressPREVIEW address() Returns the memory address PREVIEW associated with this variable argument list. Specified by: `address` in interface `AddressablePREVIEW` Returns: the memory address PREVIEW associated with this variable argument list Throws: `IllegalStateException` - if the session associated with this variable argument list is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owning that the session associated with this variable argument list.
### address MemoryAddressPREVIEW address() Returns the memory address PREVIEW associated with this variable argument list. Specified by: `address` in interface `AddressablePREVIEW` Returns: the memory address PREVIEW associated with this variable argument list Throws: `IllegalStateException` - if the session associated with this variable argument list is not alivePREVIEW, or if access occurs from a thread other than the thread owning that session. | ### address MemoryAddressPREVIEW address() Returns the memory address PREVIEW associated with this variable argument list. Specified by: `address` in interface `AddressablePREVIEW` Returns: the memory address PREVIEW associated with this variable argument list Throws: `IllegalStateException` - if the session associated with this variable argument list is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owning the session associated with this variable argument list.

### method:ofAddress(java.lang.foreign.MemoryAddress,java.lang.foreign.MemorySession) [CHANGED]
### ofAddress static VaListPREVIEW ofAddress (MemoryAddressPREVIEW address, MemorySessionPREVIEW session) Creates a variable argument list from a memory address pointing to an existing variable argument list, with the given memory session. 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. `session` - the memory session 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 `session` is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owningPREVIEW`session`. `UnsupportedOperationException` - if the underlying native platform is not supported. `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is specified, but does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.
### ofAddress static VaListPREVIEW ofAddress (MemoryAddressPREVIEW address, MemorySessionPREVIEW session) Creates a variable argument list from a memory address pointing to an existing variable argument list, with the given memory session. 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. `session` - the memory session 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 `session` is not alivePREVIEW, or if access occurs from a thread other than the thread owningPREVIEW`session`. `UnsupportedOperationException` - if the underlying native platform is not supported. `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is specified, but does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module. | ### ofAddress static VaListPREVIEW ofAddress (MemoryAddressPREVIEW address, MemorySessionPREVIEW session) Creates a variable argument list from a memory address pointing to an existing variable argument list, with the given memory session. 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. `session` - the memory session 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 `session` is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owningPREVIEW`session`. `UnsupportedOperationException` - if the underlying native platform is not supported. `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is specified, but does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

### method:make(java.util.function.Consumer,java.lang.foreign.MemorySession) [CHANGED]
### make static VaListPREVIEW make (Consumer<VaList.BuilderPREVIEW> actions, MemorySessionPREVIEW session) Creates a variable argument list using a builder (see `VaList.Builder`PREVIEW), with the given memory session. If this method needs to allocate memory, such memory will be managed by the given memory session, and will be released when the memory session is closedPREVIEW. 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`PREVIEW) which can be used to specify the elements of the underlying variable argument list. `session` - the memory session to be associated with the new variable arity list. Returns: a new variable argument list. Throws: `UnsupportedOperationException` - if the underlying native platform is not supported. `IllegalStateException` - if `session` is not alivePREVIEW, or. `WrongThreadException` - if access occurs this method is called from a thread other than the thread owningPREVIEW`session`.
### make static VaListPREVIEW make (Consumer<VaList.BuilderPREVIEW> actions, MemorySessionPREVIEW session) Creates a variable argument list using a builder (see `VaList.Builder`PREVIEW), with the given memory session. If this method needs to allocate memory, such memory will be managed by the given memory session, and will be released when the memory session is closedPREVIEW. 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`PREVIEW) which can be used to specify the elements of the underlying variable argument list. `session` - the memory session to be associated with the new variable arity list. Returns: a new variable argument list. Throws: `UnsupportedOperationException` - if the underlying native platform is not supported. `IllegalStateException` - if `session` is not alivePREVIEW, or if access occurs from a thread other than the thread owningPREVIEW`session`. | ### make static VaListPREVIEW make (Consumer<VaList.BuilderPREVIEW> actions, MemorySessionPREVIEW session) Creates a variable argument list using a builder (see `VaList.Builder`PREVIEW), with the given memory session. If this method needs to allocate memory, such memory will be managed by the given memory session, and will be released when the memory session is closedPREVIEW. 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`PREVIEW) which can be used to specify the elements of the underlying variable argument list. `session` - the memory session to be associated with the new variable arity list. Returns: a new variable argument list. Throws: `UnsupportedOperationException` - if the underlying native platform is not supported. `IllegalStateException` - if `session` is not alivePREVIEW. `WrongThreadException` - if this method is called from a thread other than the thread owningPREVIEW`session`.

### method:empty() [NONE]
### empty static VaListPREVIEW empty() Returns an empty variable argument list, associated with the globalPREVIEW memory session. The resulting variable argument list does not contain any argument, and throws `UnsupportedOperationException` on all operations, except for `address()`, `copy()` and `session()`. Returns: an empty variable argument list. Throws: `UnsupportedOperationException` - if the underlying native platform is not supported.