- All Superinterfaces:
Addressable
- Enclosing interface:
- CLinker
va_list.
A va list is a stateful cursor used to iterate over a set of variadic arguments.
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.
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 ClassesModifier and TypeInterfaceDescriptionstatic interfaceA builder interface used to construct a Cva_list. -
Method Summary
Modifier and TypeMethodDescriptionaddress()Returns the memory address of the Cva_listassociated with this instance.copy()Copies this Cva_listat its current position.static CLinker.VaListempty()Returns an empty Cva_listconstant.static CLinker.VaListmake(Consumer<CLinker.VaList.Builder> actions, ResourceScope scope) Constructs a newVaListusing a builder (seeCLinker.VaList.Builder), associated with a given resource scope.static CLinker.VaListofAddress(MemoryAddress address) Constructs a newVaListinstance out of a memory address pointing to an existing Cva_list, backed by the global resource scope.static CLinker.VaListofAddress(MemoryAddress address, ResourceScope scope) Constructs a newVaListinstance out of a memory address pointing to an existing Cva_list, with given resource scope.scope()Returns the resource scope associated with this instance.voidskip(MemoryLayout... layouts) Skips a number of elements with the given memory layouts, and advances this va list's position.vargAsAddress(MemoryLayout layout) Reads the next value as aMemoryAddressand advances this va list's position.doublevargAsDouble(MemoryLayout layout) Reads the next value as adoubleand advances this va list's position.intvargAsInt(MemoryLayout layout) Reads the next value as anintand advances this va list's position.longvargAsLong(MemoryLayout layout) Reads the next value as alongand advances this va list's position.vargAsSegment(MemoryLayout layout, ResourceScope scope) Reads the next value as aMemorySegment, and advances this va list's position.vargAsSegment(MemoryLayout layout, SegmentAllocator allocator) Reads the next value as aMemorySegment, and advances this va list's position.
-
Method Details
-
vargAsInt
Reads the next value as anintand advances this va list's position.- Parameters:
layout- the layout of the value- Returns:
- the value read as an
int - Throws:
IllegalStateException- if the resource scope associated with this instance has been closed (seescope()).IllegalArgumentException- if the given memory layout is not compatible withint
-
vargAsLong
Reads the next value as alongand advances this va list's position.- Parameters:
layout- the layout of the value- Returns:
- the value read as an
long - Throws:
IllegalStateException- if the resource scope associated with this instance has been closed (seescope()).IllegalArgumentException- if the given memory layout is not compatible withlong
-
vargAsDouble
Reads the next value as adoubleand advances this va list's position.- Parameters:
layout- the layout of the value- Returns:
- the value read as an
double - Throws:
IllegalStateException- if the resource scope associated with this instance has been closed (seescope()).IllegalArgumentException- if the given memory layout is not compatible withdouble
-
vargAsAddress
Reads the next value as aMemoryAddressand advances this va list's position.- Parameters:
layout- the layout of the value- Returns:
- the value read as an
MemoryAddress - Throws:
IllegalStateException- if the resource scope associated with this instance has been closed (seescope()).IllegalArgumentException- if the given memory layout is not compatible withMemoryAddress
-
vargAsSegment
Reads the next value as aMemorySegment, and advances this va list's position.The memory segment returned by this method will be allocated using the given
SegmentAllocator.- Parameters:
layout- the layout of the valueallocator- the allocator to be used for the native segment allocation- Returns:
- the value read as an
MemorySegment - Throws:
IllegalStateException- if the resource scope associated with this instance has been closed (seescope()).IllegalArgumentException- if the given memory layout is not compatible withMemorySegment
-
vargAsSegment
Reads the next value as aMemorySegment, and advances this va list's position.The memory segment returned by this method will be associated with the given
ResourceScope.- Parameters:
layout- the layout of the valuescope- the resource scope to be associated with the returned segment- Returns:
- the value read as an
MemorySegment - Throws:
IllegalStateException- if the resource scope associated with this instance has been closed (seescope()).IllegalArgumentException- if the given memory layout is not compatible withMemorySegmentIllegalStateException- ifscopehas been already closed, or if access occurs from a thread other than the thread owningscope.
-
skip
Skips a number of elements with the given memory layouts, and advances this va list's position.- Parameters:
layouts- the layout of the value- Throws:
IllegalStateException- if the resource scope associated with this instance has been closed (seescope()).
-
scope
ResourceScope scope()Returns the resource scope associated with this instance.- Returns:
- the resource scope associated with this instance.
-
copy
CLinker.VaList copy()Copies this Cva_listat its current position. Copying is useful to traverse the va list's elements starting from the current position, without affecting the state of the original va list, essentially allowing the elements to be traversed multiple times.Any native resource required by the execution of this method will be allocated in the resource scope associated with this instance (see
scope()).This method only copies the va list cursor itself and not the memory that may be attached to the va list which holds its elements. That means that if this va list was created with the
make(Consumer, ResourceScope)method, closing this va list will also release the native memory that holds its elements, making the copy unusable.- Returns:
- a copy of this C
va_list. - Throws:
IllegalStateException- if the resource scope associated with this instance has been closed (seescope()).
-
address
MemoryAddress address()Returns the memory address of the Cva_listassociated with this instance. The returned memory address is associated with same resource scope as that associated with this instance.- Specified by:
addressin interfaceAddressable- Returns:
- the memory address of the C
va_listassociated with this instance.
-
ofAddress
Constructs a newVaListinstance out of a memory address pointing to an existing Cva_list, backed by the global 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 Cva_list.- Returns:
- a new
VaListinstance backed by the Cva_listataddress. - Throws:
IllegalCallerException- if access to this method occurs from a moduleMand the command line option--enable-native-accessis either absent, or does not mention the module nameM, orALL-UNNAMEDin caseMis an unnamed module.
-
ofAddress
Constructs a newVaListinstance out of a memory address pointing to an existing Cva_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 Cva_list.scope- the resource scope to be associated with the returnedVaListinstance.- Returns:
- a new
VaListinstance backed by the Cva_listataddress. - Throws:
IllegalStateException- ifscopehas been already closed, or if access occurs from a thread other than the thread owningscope.IllegalCallerException- if access to this method occurs from a moduleMand the command line option--enable-native-accessis either absent, or does not mention the module nameM, orALL-UNNAMEDin caseMis an unnamed module.
-
make
Constructs a newVaListusing a builder (seeCLinker.VaList.Builder), associated 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 (seeCLinker.VaList.Builder) which can be used to specify the elements of the underlying Cva_list.scope- the scope to be used for the valist allocation.- Returns:
- a new
VaListinstance backed by a fresh Cva_list. - Throws:
IllegalStateException- ifscopehas been already closed, or if access occurs from a thread other than the thread owningscope.
-
empty
Returns an empty Cva_listconstant.The returned
VaListcan not be closed.- Returns:
- a
VaListmodelling an empty Cva_list.
-