Substrate VM (now part of GraalVM Native Image) is a framework that allows ahead-of-time (AOT) compilation of Java applications to native executables. This guide covers its internals, architecture, and practical usage.
1. Substrate VM Architecture Overview
Core Components
// Conceptual architecture of Substrate VM
public class SubstrateVMArchitecture {
// 1. Pointers Analysis
public static class PointsToAnalysis {
private final ReachabilityGraph reachabilityGraph;
private final HeapModel heapModel;
public void analyze(Set<Class<?>> rootClasses) {
// Build call graph from entry points
// Analyze object flows and references
// Determine which classes, methods, and fields are reachable
}
}
// 2. Heap Snapshotting
public static class HeapSnapshotter {
public ImageHeap createImageHeap(PointsToAnalysis analysis) {
// Create immutable heap snapshot
// Initialize objects at build time
// Handle object constants and static fields
}
}
// 3. Code Generation
public static class NativeImageGenerator {
public void generateExecutable(PointsToAnalysis analysis,
ImageHeap imageHeap,
CompilationConfiguration config) {
// Generate machine code for reachable methods
// Layout memory segments
// Create executable with runtime components
}
}
}
2. Native Image Build Process
Build Process Pipeline
public class NativeImageBuildProcess {
public static void main(String[] args) {
// 1. Initialization Phase
initializeBuildEnvironment();
// 2. Analysis Phase
PointsToAnalysis analysis = performPointsToAnalysis();
// 3. Heap Snapshot Phase
ImageHeap imageHeap = createImageHeap(analysis);
// 4. Code Generation Phase
generateNativeExecutable(analysis, imageHeap);
// 5. Finalization Phase
createFinalExecutable();
}
private static void initializeBuildEnvironment() {
// Set up classpath and module path
// Initialize Graal compiler
// Load configuration files
}
private static PointsToAnalysis performPointsToAnalysis() {
PointsToAnalysis analysis = new PointsToAnalysis();
// Start from entry points
analysis.addRootClasses(findMainClass());
analysis.addRootClasses(findReflectionConfiguration());
analysis.addRootClasses(findJNIConfiguration());
// Perform static analysis
analysis.buildCallGraph();
analysis.computeReachableMethods();
analysis.computeReachableFields();
return analysis;
}
private static ImageHeap createImageHeap(PointsToAnalysis analysis) {
ImageHeapBuilder builder = new ImageHeapBuilder();
// Create objects for static fields
builder.initializeStaticFields();
// Handle object constants
builder.processConstantObjects();
// Build immutable heap
return builder.build();
}
private static void generateNativeExecutable(PointsToAnalysis analysis,
ImageHeap imageHeap) {
NativeImageGenerator generator = new NativeImageGenerator();
// Generate code for reachable methods
generator.compileMethods(analysis.getReachableMethods());
// Layout memory segments
generator.layoutImageHeap(imageHeap);
generator.layoutCodeCache();
generator.layoutMetadata();
// Create executable
generator.assembleExecutable();
}
}
3. Points-to Analysis Implementation
Reachability Analysis Core
public class ReachabilityAnalyzer {
private final Set<AnalysisMethod> reachableMethods = new HashSet<>();
private final Set<AnalysisField> reachableFields = new HashSet<>();
private final Set<AnalysisClass> reachableClasses = new HashSet<>();
private final CallGraph callGraph = new CallGraph();
public void analyzeFromRoots(Set<AnalysisMethod> roots) {
Queue<AnalysisMethod> worklist = new LinkedList<>(roots);
while (!worklist.isEmpty()) {
AnalysisMethod current = worklist.poll();
if (reachableMethods.add(current)) {
// Analyze method body for new reachable elements
analyzeMethodBody(current, worklist);
// Add class to reachable set
reachableClasses.add(current.getDeclaringClass());
// Analyze method's exception handlers
analyzeExceptionHandlers(current, worklist);
}
}
}
private void analyzeMethodBody(AnalysisMethod method, Queue<AnalysisMethod> worklist) {
BytecodeParser parser = new BytecodeParser(method);
Instruction[] instructions = parser.parse();
for (Instruction instruction : instructions) {
switch (instruction.getOpcode()) {
case INVOKEVIRTUAL:
case INVOKESPECIAL:
case INVOKESTATIC:
case INVOKEINTERFACE:
AnalysisMethod callee = resolveMethod(instruction);
if (callee != null && !reachableMethods.contains(callee)) {
worklist.add(callee);
callGraph.addEdge(method, callee);
}
break;
case GETFIELD:
case PUTFIELD:
case GETSTATIC:
case PUTSTATIC:
AnalysisField field = resolveField(instruction);
if (field != null) {
reachableFields.add(field);
reachableClasses.add(field.getDeclaringClass());
}
break;
case NEW:
case ANEWARRAY:
case MULTIANEWARRAY:
AnalysisClass clazz = resolveClass(instruction);
if (clazz != null) {
reachableClasses.add(clazz);
// Add class initializer if exists
AnalysisMethod clinit = clazz.getClassInitializer();
if (clinit != null && !reachableMethods.contains(clinit)) {
worklist.add(clinit);
}
}
break;
case LDC:
// Handle constant pool entries
handleConstantPool(instruction, worklist);
break;
}
}
}
private void analyzeExceptionHandlers(AnalysisMethod method, Queue<AnalysisMethod> worklist) {
for (ExceptionHandler handler : method.getExceptionHandlers()) {
AnalysisClass exceptionClass = handler.getExceptionClass();
if (exceptionClass != null) {
reachableClasses.add(exceptionClass);
// Check if exception has a static initializer
AnalysisMethod clinit = exceptionClass.getClassInitializer();
if (clinit != null && !reachableMethods.contains(clinit)) {
worklist.add(clinit);
}
}
}
}
}
Call Graph Construction
public class CallGraph {
private final Map<AnalysisMethod, Set<AnalysisMethod>> edges = new HashMap<>();
private final Map<AnalysisMethod, Set<AnalysisMethod>> callers = new HashMap<>();
public void addEdge(AnalysisMethod caller, AnalysisMethod callee) {
edges.computeIfAbsent(caller, k -> new HashSet<>()).add(callee);
callers.computeIfAbsent(callee, k -> new HashSet<>()).add(caller);
}
public Set<AnalysisMethod> getCallees(AnalysisMethod method) {
return edges.getOrDefault(method, Collections.emptySet());
}
public Set<AnalysisMethod> getCallers(AnalysisMethod method) {
return callers.getOrDefault(method, Collections.emptySet());
}
public boolean isReachable(AnalysisMethod method) {
return !getCallers(method).isEmpty() || method.isEntryPoint();
}
}
public class AnalysisMethod {
private final String className;
private final String methodName;
private final String descriptor;
private final int modifiers;
private final byte[] bytecode;
private final AnalysisClass declaringClass;
public boolean isEntryPoint() {
return "main".equals(methodName) &&
"([Ljava/lang/String;)V".equals(descriptor) &&
Modifier.isStatic(modifiers) &&
Modifier.isPublic(modifiers);
}
public AnalysisClass getDeclaringClass() {
return declaringClass;
}
// Getters for other properties...
}
4. Heap Snapshotting Implementation
Image Heap Builder
public class ImageHeapBuilder {
private final Map<Object, Integer> objectToID = new HashMap<>();
private final List<Object> objects = new ArrayList<>();
private final Map<AnalysisField, Object> staticFieldValues = new HashMap<>();
public ImageHeap build() {
// Create immutable snapshot of the heap
Object[] heapObjects = objects.toArray();
Map<AnalysisField, Object> frozenStaticFields =
Collections.unmodifiableMap(new HashMap<>(staticFieldValues));
return new ImageHeap(heapObjects, frozenStaticFields);
}
public void initializeStaticFields() {
for (AnalysisClass clazz : getReachableClasses()) {
initializeClassStaticFields(clazz);
}
}
private void initializeClassStaticFields(AnalysisClass clazz) {
try {
// Force class initialization at build time
Class<?> runtimeClass = Class.forName(clazz.getName());
for (AnalysisField field : clazz.getStaticFields()) {
if (field.isReachable()) {
initializeStaticField(field, runtimeClass);
}
}
} catch (ClassNotFoundException e) {
// Handle class not found during build
initializeStaticFieldsStatically(clazz);
}
}
private void initializeStaticField(AnalysisField field, Class<?> runtimeClass) {
try {
java.lang.reflect.Field reflectiveField =
runtimeClass.getDeclaredField(field.getName());
reflectiveField.setAccessible(true);
Object value = reflectiveField.get(null);
if (value != null) {
staticFieldValues.put(field, value);
registerObject(value);
}
} catch (Exception e) {
// Handle initialization failure
System.err.println("Failed to initialize field: " + field);
}
}
private void registerObject(Object obj) {
if (!objectToID.containsKey(obj)) {
int id = objects.size();
objectToID.put(obj, id);
objects.add(obj);
// Recursively register referenced objects
registerReferencedObjects(obj);
}
}
private void registerReferencedObjects(Object obj) {
if (obj instanceof Object[]) {
for (Object element : (Object[]) obj) {
if (element != null) {
registerObject(element);
}
}
} else if (obj instanceof String) {
// Strings are handled specially
registerStringReferences((String) obj);
}
// Handle other object types as needed
}
}
5. Runtime Components
Substrate VM Runtime
public class SubstrateVMRuntime {
// Memory management
public static class ImageHeapMemory {
private final long heapStart;
private final long heapSize;
public ImageHeapMemory(long start, long size) {
this.heapStart = start;
this.heapSize = size;
}
public native long allocateObject(int size);
public native void freeObject(long address);
}
// Thread management
public static class VMThreads {
private static final ThreadLocal<VMThread> currentThread = new ThreadLocal<>();
public static VMThread currentThread() {
VMThread thread = currentThread.get();
if (thread == null) {
thread = new VMThread(Thread.currentThread());
currentThread.set(thread);
}
return thread;
}
}
// Garbage Collection (simplified)
public static class ImageHeapGC {
public static void collectGarbage() {
// Since most objects are in image heap and immutable,
// GC mainly handles runtime-allocated objects
markRuntimeObjects();
sweepRuntimeObjects();
}
private static native void markRuntimeObjects();
private static native void sweepRuntimeObjects();
}
// Reflection support
public static class ReflectionSupport {
private static final Map<String, Class<?>> knownClasses = new HashMap<>();
private static final Map<String, Method> knownMethods = new HashMap<>();
static {
initializeReflectionData();
}
private static void initializeReflectionData() {
// Load reflection configuration generated during build
loadReflectionConfiguration();
}
public static Class<?> forName(String className) {
Class<?> clazz = knownClasses.get(className);
if (clazz == null) {
throw new NoClassDefFoundError("Class not included in native image: " + className);
}
return clazz;
}
public static Method getMethod(Class<?> clazz, String methodName, Class<?>... parameterTypes) {
String key = clazz.getName() + "#" + methodName;
Method method = knownMethods.get(key);
if (method == null) {
throw new NoSuchMethodError("Method not included in native image: " + key);
}
return method;
}
}
}
6. Configuration Files
Reflection Configuration
{
"name": "com.example.MyClass",
"methods": [
{
"name": "myMethod",
"parameterTypes": ["java.lang.String", "int"]
},
{
"name": "<init>",
"parameterTypes": []
}
],
"fields": [
{
"name": "myField"
}
]
}
Native Image Configuration
public class NativeImageConfiguration {
@AutomaticallyFeature
public static class RuntimeInitializedClassesFeature implements Feature {
@Override
public void beforeAnalysis(BeforeAnalysisAccess access) {
// Register classes that need runtime initialization
RuntimeClassInitialization.initializeAtRunTime(
"com.example.SomeClass",
"com.example.AnotherClass"
);
}
}
@AutomaticallyFeature
public static class ReflectionConfigurationFeature implements Feature {
@Override
public void duringSetup(DuringSetupAccess access) {
// Register classes for reflection
ReflectionRegistry registry = ImageSingletons.lookup(ReflectionRegistry.class);
registry.register(MyClass.class);
registry.register(MyClass.class.getDeclaredMethod("myMethod", String.class, int.class));
}
}
@AutomaticallyFeature
public static class ResourceConfigurationFeature implements Feature {
@Override
public void beforeAnalysis(BeforeAnalysisAccess access) {
// Include resources in native image
ResourceConfiguration resourceConfig = ImageSingletons.lookup(ResourceConfiguration.class);
resourceConfig.addResourceBundle("com.example.messages");
resourceConfig.addResources("META-INF/services/.*");
}
}
}
7. Custom Features and Hooks
Building Custom Features
public class CustomNativeImageFeatures {
// Feature for custom initialization
@AutomaticallyFeature
public static class CustomInitializationFeature implements Feature {
@Override
public void beforeAnalysis(BeforeAnalysisAccess access) {
System.out.println("Starting analysis phase...");
// Register custom reachability handlers
access.registerReachabilityHandler(this::handleClassReachable,
access.getMetaAccess().lookupJavaType(MyCriticalClass.class));
}
private void handleClassReachable(DuringAnalysisAccess access, Class<?> clazz) {
System.out.println("Class became reachable: " + clazz.getName());
// Force initialization of related classes
access.requireAnalysisIteration();
}
@Override
public void duringAnalysis(DuringAnalysisAccess access) {
// Custom analysis logic
analyzeDynamicProxyUsage(access);
analyzeResourceUsage(access);
}
@Override
public void afterAnalysis(AfterAnalysisAccess access) {
System.out.println("Analysis completed");
// Generate additional configuration
generateAdditionalReflectionConfig();
}
private void analyzeDynamicProxyUsage(DuringAnalysisAccess access) {
// Analyze dynamic proxy creation
access.getBigBang().getUniverse().getMethods().stream()
.filter(method -> method.getName().contains("$Proxy"))
.forEach(proxyMethod -> {
System.out.println("Found dynamic proxy: " + proxyMethod.getName());
});
}
private void generateAdditionalReflectionConfig() {
// Generate reflection configuration for dynamically discovered classes
try (FileWriter writer = new FileWriter("generated-reflection.json")) {
writer.write(generateReflectionJson());
} catch (IOException e) {
e.printStackTrace();
}
}
}
// Feature for JNI support
@AutomaticallyFeature
public static class JNISupportFeature implements Feature {
@Override
public void duringSetup(DuringSetupAccess access) {
// Register JNI libraries
JNIRegistration jniReg = ImageSingletons.lookup(JNIRegistration.class);
jniReg.addLibrary("mylibrary");
// Register JNI methods
jniReg.registerMethods(MyJNIClass.class);
}
}
// Feature for resource management
@AutomaticallyFeature
public static class ResourceManagementFeature implements Feature {
@Override
public void beforeAnalysis(BeforeAnalysisAccess access) {
// Configure resource inclusion patterns
ResourceConfiguration resources = ImageSingletons.lookup(ResourceConfiguration.class);
// Include all properties files
resources.addResourceRegex(".*\\.properties");
// Include specific directories
resources.addResourceRegex("META-INF/.*");
resources.addResourceRegex("WEB-INF/.*");
}
}
}
8. Build-Time Initialization
Build-Time Code Execution
public class BuildTimeInitialization {
@Feature
public static class BuildTimeInitFeature implements Feature {
private static final Set<String> INITIALIZED_CLASSES = new HashSet<>();
@Override
public void beforeAnalysis(BeforeAnalysisAccess access) {
// Initialize classes at build time for better performance
initializeClassesAtBuildTime(access);
}
private void initializeClassesAtBuildTime(BeforeAnalysisAccess access) {
String[] buildTimeClasses = {
"java.util.Locale",
"java.time.ZoneId",
"java.text.DecimalFormatSymbols",
"com.example.config.AppConfig"
};
for (String className : buildTimeClasses) {
try {
Class<?> clazz = Class.forName(className);
forceInitialization(clazz);
INITIALIZED_CLASSES.add(className);
} catch (Exception e) {
System.err.println("Failed to initialize " + className + " at build time: " + e.getMessage());
}
}
}
private void forceInitialization(Class<?> clazz) {
try {
Class.forName(clazz.getName(), true, clazz.getClassLoader());
} catch (ClassNotFoundException e) {
throw new RuntimeException("Failed to initialize class: " + clazz.getName(), e);
}
}
}
}
// Example of a class designed for build-time initialization
public class AppConfig {
private static final Properties CONFIG = loadConfig();
static {
// This static initializer runs at build time
System.out.println("AppConfig initialized at build time");
}
private static Properties loadConfig() {
Properties props = new Properties();
try (InputStream is = AppConfig.class.getResourceAsStream("/application.properties")) {
if (is != null) {
props.load(is);
}
} catch (IOException e) {
System.err.println("Failed to load configuration: " + e.getMessage());
}
return props;
}
public static String getProperty(String key) {
return CONFIG.getProperty(key);
}
public static String getProperty(String key, String defaultValue) {
return CONFIG.getProperty(key, defaultValue);
}
}
9. Debugging and Monitoring
Build Process Monitoring
public class BuildProcessMonitor {
@Feature
public static class BuildMonitoringFeature implements Feature {
private long analysisStartTime;
private long codeGenStartTime;
@Override
public void beforeAnalysis(BeforeAnalysisAccess access) {
analysisStartTime = System.currentTimeMillis();
System.out.println("Starting points-to analysis...");
}
@Override
public void afterAnalysis(AfterAnalysisAccess access) {
long analysisTime = System.currentTimeMillis() - analysisStartTime;
System.out.printf("Points-to analysis completed in %d ms%n", analysisTime);
// Print analysis statistics
printAnalysisStatistics(access);
}
@Override
public void beforeCompilation(BeforeCompilationAccess access) {
codeGenStartTime = System.currentTimeMillis();
System.out.println("Starting code generation...");
}
@Override
public void afterCompilation(AfterCompilationAccess access) {
long codeGenTime = System.currentTimeMillis() - codeGenStartTime;
System.out.printf("Code generation completed in %d ms%n", codeGenTime);
}
private void printAnalysisStatistics(DuringAnalysisAccess access) {
AnalysisUniverse universe = access.getUniverse();
System.out.printf("Reachable classes: %d%n", universe.getTypes().size());
System.out.printf("Reachable methods: %d%n", universe.getMethods().size());
System.out.printf("Reachable fields: %d%n", universe.getFields().size());
// Print memory usage
Runtime runtime = Runtime.getRuntime();
long usedMemory = runtime.totalMemory() - runtime.freeMemory();
System.out.printf("Memory usage: %d MB%n", usedMemory / (1024 * 1024));
}
}
// Feature for generating build reports
@Feature
public static class BuildReportFeature implements Feature {
@Override
public void afterAnalysis(AfterAnalysisAccess access) {
generateReachabilityReport(access);
generateDependencyReport(access);
}
private void generateReachabilityReport(DuringAnalysisAccess access) {
try (PrintWriter writer = new PrintWriter("reachability-report.txt")) {
writer.println("=== Reachability Report ===");
writer.println();
AnalysisUniverse universe = access.getUniverse();
writer.println("Reachable Classes:");
universe.getTypes().stream()
.sorted(Comparator.comparing(AnalysisType::getName))
.forEach(type -> writer.println(" " + type.getName()));
writer.println();
writer.println("Reachable Methods:");
universe.getMethods().stream()
.sorted(Comparator.comparing(AnalysisMethod::getQualifiedName))
.forEach(method -> writer.println(" " + method.getQualifiedName()));
} catch (IOException e) {
e.printStackTrace();
}
}
private void generateDependencyReport(DuringAnalysisAccess access) {
try (PrintWriter writer = new PrintWriter("dependency-report.txt")) {
writer.println("=== Dependency Report ===");
writer.println();
AnalysisUniverse universe = access.getUniverse();
CallGraph callGraph = universe.getCallGraph();
// Print method dependencies
for (AnalysisMethod method : universe.getMethods()) {
Set<AnalysisMethod> callees = callGraph.getCallees(method);
if (!callees.isEmpty()) {
writer.println(method.getQualifiedName() + " calls:");
for (AnalysisMethod callee : callees) {
writer.println(" -> " + callee.getQualifiedName());
}
writer.println();
}
}
} catch (IOException e) {
e.printStackTrace();
}
}
}
}
10. Advanced Usage Patterns
Dynamic Features with Conditional Logic
public class ConditionalNativeImageFeatures {
@AutomaticallyFeature
public static class ConditionalInitializationFeature implements Feature {
@Override
public void duringSetup(DuringSetupAccess access) {
// Check system properties to conditionally enable features
String profile = System.getProperty("native.image.profile", "default");
switch (profile) {
case "minimal":
configureMinimalProfile(access);
break;
case "full":
configureFullProfile(access);
break;
case "server":
configureServerProfile(access);
break;
default:
configureDefaultProfile(access);
}
}
private void configureMinimalProfile(DuringSetupAccess access) {
// Minimal configuration for small footprint
System.out.println("Configuring minimal profile");
// Only include essential classes
RuntimeClassInitialization.initializeAtBuildTime(
"java.util.Collections",
"java.util.Arrays"
);
}
private void configureFullProfile(DuringSetupAccess access) {
// Full configuration with all features
System.out.println("Configuring full profile");
// Include additional libraries and features
includeAdditionalLibraries(access);
enableAdvancedFeatures(access);
}
private void includeAdditionalLibraries(DuringSetupAccess access) {
// Conditionally include libraries based on classpath
if (isClassPresent("com.fasterxml.jackson.databind.ObjectMapper")) {
System.out.println("Jackson detected - configuring JSON support");
configureJacksonSupport(access);
}
if (isClassPresent("org.slf4j.Logger")) {
System.out.println("SLF4J detected - configuring logging");
configureLoggingSupport(access);
}
}
private boolean isClassPresent(String className) {
try {
Class.forName(className);
return true;
} catch (ClassNotFoundException e) {
return false;
}
}
}
// Feature for plugin system support
@AutomaticallyFeature
public static class PluginSystemFeature implements Feature {
@Override
public void duringAnalysis(DuringAnalysisAccess access) {
// Discover plugins using service loader pattern
discoverPlugins(access);
// Generate plugin configuration
generatePluginConfiguration(access);
}
private void discoverPlugins(DuringAnalysisAccess access) {
// Use ServiceLoader to discover plugins at build time
ServiceLoader<Plugin> plugins = ServiceLoader.load(Plugin.class);
for (Plugin plugin : plugins) {
System.out.println("Discovered plugin: " + plugin.getClass().getName());
// Register plugin classes for reflection
registerPluginForReflection(plugin.getClass());
// Initialize plugin at build time if possible
initializePlugin(plugin);
}
}
private void generatePluginConfiguration(DuringAnalysisAccess access) {
// Generate configuration file for discovered plugins
Properties pluginConfig = new Properties();
ServiceLoader<Plugin> plugins = ServiceLoader.load(Plugin.class);
for (Plugin plugin : plugins) {
pluginConfig.setProperty(plugin.getName(), plugin.getClass().getName());
}
try (FileOutputStream fos = new FileOutputStream("plugins.properties")) {
pluginConfig.store(fos, "Auto-generated plugin configuration");
} catch (IOException e) {
e.printStackTrace();
}
}
}
}
// Plugin interface for dynamic discovery
public interface Plugin {
String getName();
void initialize();
}
// Example plugin implementation
public class DatabasePlugin implements Plugin {
@Override
public String getName() {
return "database";
}
@Override
public void initialize() {
System.out.println("Database plugin initialized at build time");
}
// This method will be called by reflection
public static void registerDrivers() {
try {
Class.forName("org.h2.Driver");
Class.forName("org.postgresql.Driver");
} catch (ClassNotFoundException e) {
System.err.println("Database drivers not found: " + e.getMessage());
}
}
}
This comprehensive guide covers Substrate VM internals, from the build process and points-to analysis to runtime components and advanced features. Understanding these internals helps in creating optimized native images and troubleshooting build issues.