0
# Engine Management
1

2
Engine management provides the central execution infrastructure for polyglot programming. Engines coordinate multiple contexts, manage compilation caches, provide access to installed languages and instruments, and enable resource sharing across contexts.
3

4
## Capabilities
5

6
### Engine Creation
7

8
Create polyglot engines for shared execution infrastructure.
9

10
```java { .api }
11
public final class Engine implements AutoCloseable {
12
    public static Engine create();
13
}
14
```
15

16
**Usage:**
17

18
```java
19
// Create default engine
20
Engine engine = Engine.create();
21

22
// Use engine with multiple contexts
23
try (Context ctx1 = Context.newBuilder("js").engine(engine).build();
24
     Context ctx2 = Context.newBuilder("python").engine(engine).build()) {
25
    // Both contexts share the same engine
26
}
27

28
engine.close();
29
```
30

31
### Engine Builder
32

33
Configure engines with advanced options before creation.
34

35
```java { .api }
36
public static final class Engine.Builder {
37
    public Engine.Builder allowExperimentalOptions(boolean enabled);
38
    public Engine.Builder option(String key, String value);
39
    public Engine.Builder options(Map<String, String> options);
40
    public Engine.Builder out(OutputStream out);
41
    public Engine.Builder err(OutputStream err);
42
    public Engine.Builder in(InputStream in);
43
    public Engine.Builder sandbox(SandboxPolicy policy);
44
    public Engine.Builder useSystemProperties(boolean enabled);
45
    public Engine build();
46
}
47
```
48

49
**Usage:**
50

51
```java
52
Engine engine = Engine.newBuilder()
53
    .allowExperimentalOptions(true)
54
    .option("js.ecmascript-version", "2022")
55
    .option("python.ForceImportSite", "false")
56
    .sandbox(SandboxPolicy.CONSTRAINED)
57
    .build();
58
```
59

60
### Language Discovery
61

62
Access information about installed language implementations.
63

64
```java { .api }
65
public Map<String, Language> getLanguages();
66
```
67

68
**Usage:**
69

70
```java
71
Engine engine = Engine.create();
72
Map<String, Language> languages = engine.getLanguages();
73

74
for (Map.Entry<String, Language> entry : languages.entrySet()) {
75
    String id = entry.getKey();
76
    Language lang = entry.getValue();
77
    
78
    System.out.println("Language: " + id);
79
    System.out.println("  Name: " + lang.getName());
80
    System.out.println("  Version: " + lang.getVersion());
81
    System.out.println("  Implementation: " + lang.getImplementationName());
82
    System.out.println("  MIME types: " + lang.getMimeTypes());
83
}
84

85
// Check if specific language is available
86
if (languages.containsKey("js")) {
87
    System.out.println("JavaScript is available");
88
}
89
```
90

91
### Instrument Discovery
92

93
Access information about installed instrumentation tools.
94

95
```java { .api }
96
public Map<String, Instrument> getInstruments();
97
```
98

99
**Usage:**
100

101
```java
102
Engine engine = Engine.create();
103
Map<String, Instrument> instruments = engine.getInstruments();
104

105
for (Map.Entry<String, Instrument> entry : instruments.entrySet()) {
106
    String id = entry.getKey();
107
    Instrument instrument = entry.getValue();
108
    
109
    System.out.println("Instrument: " + id);
110
    System.out.println("  Name: " + instrument.getName());
111
    System.out.println("  Version: " + instrument.getVersion());
112
    
113
    // Lookup instrument services
114
    if (id.equals("profiler")) {
115
        CPUSampler sampler = instrument.lookup(CPUSampler.class);
116
        if (sampler != null) {
117
            sampler.setCollecting(true);
118
        }
119
    }
120
}
121
```
122

123
### Engine Options
124

125
Access engine-wide configuration options.
126

127
```java { .api }
128
public OptionValues getOptions();
129
```
130

131
**Usage:**
132

133
```java
134
Engine engine = Engine.create();
135
OptionValues options = engine.getOptions();
136

137
// Access option values
138
for (OptionDescriptor desc : options.getDescriptors()) {
139
    System.out.println("Option: " + desc.getName());
140
    System.out.println("  Value: " + options.get(desc.getKey()));
141
    System.out.println("  Help: " + desc.getHelp());
142
}
143
```
144

145
### Compilation Cache
146

147
Manage compilation caches for performance optimization.
148

149
```java { .api }
150
public void storeCache(Cache cache);
151
public Collection<Source> getCachedSources();
152
```
153

154
**Usage:**
155

156
```java
157
Engine engine = Engine.create();
158

159
// Create and store cache
160
Cache cache = Cache.newBuilder()
161
    .maximumSize(100)
162
    .expireAfterAccess(Duration.ofMinutes(30))
163
    .build();
164
engine.storeCache(cache);
165

166
// Check cached sources
167
Collection<Source> cachedSources = engine.getCachedSources();
168
System.out.println("Cached sources: " + cachedSources.size());
169
```
170

171
### Resource Management
172

173
Manage engine lifecycle and resource cleanup.
174

175
```java { .api }
176
public void close();
177
public void close(boolean cancelIfExecuting);
178
```
179

180
**Usage:**
181

182
```java
183
Engine engine = Engine.create();
184

185
// Normal close (waits for executing contexts)
186
engine.close();
187

188
// Force close (cancels executing contexts)
189
engine.close(true);
190

191
// Using try-with-resources (recommended)
192
try (Engine engine = Engine.create()) {
193
    // Use engine
194
} // Automatically closed
195
```
196

197
### GraalVM Home Discovery
198

199
Locate GraalVM installation directory.
200

201
```java { .api }
202
public static Path findHome();
203
public static void copyResources(Path targetFolder, String... resources);
204
```
205

206
**Usage:**
207

208
```java
209
// Find GraalVM home directory
210
Path graalHome = Engine.findHome();
211
System.out.println("GraalVM home: " + graalHome);
212

213
// Copy GraalVM resources
214
Engine.copyResources(Paths.get("/tmp/graal-resources"), 
215
    "languages/js", "tools/profiler");
216
```
217

218
## Advanced Usage
219

220
### Shared Engine Pattern
221

222
Share engines across multiple contexts for better resource utilization:
223

224
```java
225
Engine sharedEngine = Engine.create();
226

227
// Multiple contexts sharing the same engine
228
List<Context> contexts = new ArrayList<>();
229
for (int i = 0; i < 10; i++) {
230
    Context ctx = Context.newBuilder("js")
231
        .engine(sharedEngine)
232
        .build();
233
    contexts.add(ctx);
234
}
235

236
// Use contexts...
237

238
// Clean up
239
contexts.forEach(Context::close);
240
sharedEngine.close();
241
```
242

243
### Engine Configuration
244

245
Configure engines for specific use cases:
246

247
```java
248
// High-performance engine
249
Engine performanceEngine = Engine.newBuilder()
250
    .option("js.v8-compat", "true")
251
    .option("js.ecmascript-version", "2022")
252
    .option("python.EmulateJython", "true")
253
    .build();
254

255
// Sandboxed engine
256
Engine sandboxEngine = Engine.newBuilder()
257
    .sandbox(SandboxPolicy.ISOLATED)
258
    .option("js.allow-eval", "false")
259
    .build();
260

261
// Development engine with debugging
262
ByteArrayOutputStream debugOut = new ByteArrayOutputStream();
263
Engine debugEngine = Engine.newBuilder()
264
    .allowExperimentalOptions(true)
265
    .option("inspect", "9229")
266
    .out(debugOut)
267
    .err(debugOut)
268
    .build();
269
```
270

271
## Thread Safety
272

273
Engines are **thread-safe** and can be shared across multiple threads and contexts. Multiple contexts can safely use the same engine concurrently.
274

275
## Performance Considerations
276

277
- **Engine Reuse**: Reusing engines across contexts improves performance by sharing compilation caches and language implementations
278
- **Warm-up**: Engines and languages have warm-up phases; reusing engines amortizes this cost
279
- **Memory**: Engines maintain compilation caches which consume memory; configure cache limits appropriately
280
- **Resource Sharing**: Shared engines enable better resource utilization in multi-context applications