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

# Interface NativeSymbol

All Superinterfaces:
  `Addressable`

public sealed interface NativeSymbol extends Addressable
A native symbol models a reference to a location (typically the entry point of a function) in a native library. A native symbol has a name, and is associated with a scope, which governs the native symbol's lifecycle. This is useful, since the library a native symbol refers to can be unloaded, thus invalidating the native symbol. While native symbols are typically obtained using a `symbol lookup`, it is also possible to obtain an anonymous native symbol, in the form of an upcall stub, that is, a reference to a dynamically-generated native symbol which can be used to call back into Java code.

## Method Summary

Modifier and Type
Method
Description
`MemoryAddress`
`address()`
Returns the memory address associated with this symbol.
`String`
`name()`
Returns the name of this symbol.
`static NativeSymbol`
`ofAddress(String name, MemoryAddress address, ResourceScope scope)`
Creates a new symbol from given name, address and scope.
`ResourceScope`
`scope()`
Returns the resource scope associated with this symbol.

## Method Details

### name

String name()
Returns the name of this symbol.

Returns:
  the name of this symbol

### scope

ResourceScope scope()
Returns the resource scope associated with this symbol.

Returns:
  the resource scope associated with this symbol

### address

MemoryAddress address()
Returns the memory address associated with this symbol.

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

### ofAddress

static NativeSymbol ofAddress(String name, MemoryAddress address, ResourceScope scope)
Creates a new symbol from given name, address and 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:
  `name` - the symbol name.
  `address` - the symbol address.
  `scope` - the symbol scope.
Returns:
  A new symbol from given name, address and scope.
Throws:
  `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.