- All Superinterfaces:
AddressablePREVIEW
VaList
is a preview API of the Java platform.
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 handlePREVIEW.
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
.
Safety considerations
It is possible for clients to access elements outside the spatial bounds of a variable argument list. Variable argument list implementations will try to detect out-of-bounds reads on a best-effort basis.Whether this detection succeeds depends on the factory method used to create the variable argument list:
- Variable argument lists created safely, using
make(Consumer, MemorySession)
are capable of detecting out-of-bounds reads; - Variable argument lists created unsafely, using
ofAddress(MemoryAddress, MemorySession)
are not capable of detecting out-of-bounds reads
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
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
Preview.A builder used to construct a variable argument listPREVIEW. -
Method Summary
Modifier and TypeMethodDescriptionaddress()
Returns the memory addressPREVIEW associated with this variable argument list.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.empty()
make
(Consumer<VaList.BuilderPREVIEW> actions, MemorySessionPREVIEW session) Creates a variable argument list using a builder (seeVaList.Builder
PREVIEW), with the given memory session.nextVarg
(GroupLayoutPREVIEW layout, SegmentAllocatorPREVIEW allocator) Reads the next value as aMemorySegment
, and advances this variable argument list's position.nextVarg
(ValueLayout.OfAddressPREVIEW layout) Reads the next value as aMemoryAddress
and advances this variable argument list's position.double
nextVarg
(ValueLayout.OfDoublePREVIEW layout) Reads the next value as adouble
and advances this variable argument list's position.int
nextVarg
(ValueLayout.OfIntPREVIEW layout) Reads the next value as anint
and advances this variable argument list's position.long
nextVarg
(ValueLayout.OfLongPREVIEW layout) Reads the next value as along
and advances this variable argument list's position.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.session()
Returns the memory session associated with this variable argument list.void
skip
(MemoryLayoutPREVIEW... layouts) Skips a number of elements with the given memory layouts, and advances this variable argument list's position.
-
Method Details
-
session
MemorySessionPREVIEW session()Returns the memory session associated with this variable argument list.- Returns:
- the memory session associated with this variable argument list
-
nextVarg
Reads the next value as anint
and advances this variable argument list's position. The behavior of this method is equivalent to the Cva_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.NoSuchElementException
- if an out-of-bounds read is detected.
-
nextVarg
Reads the next value as along
and advances this variable argument list's position. The behavior of this method is equivalent to the Cva_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.NoSuchElementException
- if an out-of-bounds read is detected.
-
nextVarg
Reads the next value as adouble
and advances this variable argument list's position. The behavior of this method is equivalent to the Cva_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.NoSuchElementException
- if an out-of-bounds read is detected.
-
nextVarg
Reads the next value as aMemoryAddress
and advances this variable argument list's position. The behavior of this method is equivalent to the Cva_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.NoSuchElementException
- if an out-of-bounds read is detected.
-
nextVarg
Reads the next value as aMemorySegment
, and advances this variable argument list's position. The behavior of this method is equivalent to the Cva_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 tonextVarg
for each of the layouts inL_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.NoSuchElementException
- if an out-of-bounds read is detected.
-
skip
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.NoSuchElementException
- if an out-of-bounds read is detected.
-
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 Cva_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.
-
address
MemoryAddressPREVIEW address()Returns the memory addressPREVIEW associated with this variable argument list.- Specified by:
address
in interfaceAddressablePREVIEW
- Returns:
- the memory addressPREVIEW 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.
-
ofAddress
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.
- Implementation Note:
- variable argument lists created using this method can not detect out-of-bounds reads.
- 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
- ifsession
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread other than the thread owningPREVIEWsession
.UnsupportedOperationException
- if the underlying native platform is not supported.IllegalCallerException
- if access to this method occurs from a moduleM
and the command line option--enable-native-access
is specified, but does not mention the module nameM
, orALL-UNNAMED
in caseM
is an unnamed module.
-
make
Creates a variable argument list using a builder (seeVaList.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()
.- Implementation Note:
- variable argument lists created using this method can detect out-of-bounds reads.
- Parameters:
actions
- a consumer for a builder (seeVaList.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
- ifsession
is not alivePREVIEW.WrongThreadException
- if this method is called from a thread other than the thread owningPREVIEWsession
.
-
empty
Returns an empty variable argument list, associated with the globalPREVIEW memory session. The resulting variable argument list does not contain any argument, and throwsUnsupportedOperationException
on all operations, except foraddress()
,copy()
andsession()
.- Returns:
- an empty variable argument list.
- Throws:
UnsupportedOperationException
- if the underlying native platform is not supported.
-
VaList
when preview features are enabled.