A multi-language framework for executing dynamic languages that achieves high performance when combined with Graal.
—
Truffle provides specialized data types and performance optimization features for high-performance language implementations. This includes efficient string handling, profiling utilities, exception management, and performance-oriented data structures.
High-performance string implementation with encoding support and lazy operations.
/**
* Base class for Truffle string implementations
*/
public abstract class AbstractTruffleString {
/**
* Get string length in code points
* @param encoding String encoding
* @return Length in code points
*/
public abstract int codePointLengthUncached(Encoding encoding);
/**
* Get string length in bytes
* @param encoding String encoding
* @return Length in bytes
*/
public abstract int byteLength(Encoding encoding);
/**
* Check if string is valid for encoding
* @param encoding Target encoding
* @return true if valid
*/
public abstract boolean isValidUncached(Encoding encoding);
/**
* Switch to different encoding
* @param encoding Target encoding
* @return String in new encoding
*/
public abstract TruffleString switchEncodingUncached(Encoding encoding);
}
/**
* Immutable string implementation for Truffle languages
*/
public final class TruffleString extends AbstractTruffleString {
/**
* Create TruffleString from Java string
* @param javaString Source Java string
* @param encoding Target encoding
* @return TruffleString instance
*/
public static TruffleString fromJavaStringUncached(String javaString, Encoding encoding) {
return null; // Implementation details
}
/**
* Create TruffleString from byte array
* @param bytes Source bytes
* @param offset Byte offset
* @param length Byte length
* @param encoding Source encoding
* @param copy Whether to copy bytes
* @return TruffleString instance
*/
public static TruffleString fromByteArrayUncached(byte[] bytes, int offset, int length,
Encoding encoding, boolean copy) {
return null; // Implementation details
}
/**
* Create TruffleString from code point array
* @param codePoints Source code points
* @param offset Code point offset
* @param length Code point length
* @param encoding Target encoding
* @param copy Whether to copy array
* @return TruffleString instance
*/
public static TruffleString fromCodePointArrayUncached(int[] codePoints, int offset, int length,
Encoding encoding, boolean copy) {
return null; // Implementation details
}
/**
* Convert to Java string
* @return Java String
*/
public String toJavaStringUncached() {
return null; // Implementation details
}
/**
* Get hash code for specific encoding
* @param encoding String encoding
* @return Hash code
*/
public int hashCodeUncached(Encoding encoding) {
return 0; // Implementation details
}
/**
* Concatenate strings
* @param other String to concatenate
* @param encoding Result encoding
* @param lazy Whether to use lazy concatenation
* @return Concatenated string
*/
public TruffleString concatUncached(TruffleString other, Encoding encoding, boolean lazy) {
return null; // Implementation details
}
/**
* Create substring
* @param fromIndex Start index (code points)
* @param length Substring length (code points)
* @param encoding String encoding
* @param lazy Whether to use lazy substring
* @return Substring
*/
public TruffleString substringUncached(int fromIndex, int length, Encoding encoding, boolean lazy) {
return null; // Implementation details
}
/**
* Compare strings
* @param other String to compare
* @param encoding Comparison encoding
* @return Comparison result
*/
public int compareToUncached(TruffleString other, Encoding encoding) {
return 0; // Implementation details
}
/**
* Check string equality
* @param other String to compare
* @param encoding Comparison encoding
* @return true if equal
*/
public boolean equalsUncached(TruffleString other, Encoding encoding) {
return false; // Implementation details
}
/**
* Find substring index
* @param substring Substring to find
* @param fromIndex Start search index
* @param encoding Search encoding
* @return Index of substring or -1
*/
public int indexOfStringUncached(TruffleString substring, int fromIndex, Encoding encoding) {
return -1; // Implementation details
}
/**
* Find last substring index
* @param substring Substring to find
* @param fromIndex Start search index (backward)
* @param encoding Search encoding
* @return Last index of substring or -1
*/
public int lastIndexOfStringUncached(TruffleString substring, int fromIndex, Encoding encoding) {
return -1; // Implementation details
}
/**
* Get code point at index
* @param index Code point index
* @param encoding String encoding
* @return Code point value
*/
public int codePointAtIndexUncached(int index, Encoding encoding) {
return 0; // Implementation details
}
/**
* Copy to byte array
* @param srcIndex Source start index (code points)
* @param dst Destination byte array
* @param dstIndex Destination start index
* @param length Copy length (code points)
* @param encoding Source encoding
*/
public void copyToByteArrayUncached(int srcIndex, byte[] dst, int dstIndex, int length, Encoding encoding) {
// Implementation details
}
}
/**
* Mutable string implementation for building strings
*/
public final class MutableTruffleString extends AbstractTruffleString {
/**
* Create mutable string with capacity
* @param encoding String encoding
* @param capacity Initial capacity
* @return MutableTruffleString instance
*/
public static MutableTruffleString create(Encoding encoding, int capacity) {
return null; // Implementation details
}
/**
* Write code point at index
* @param index Write index
* @param codePoint Code point to write
* @param encoding String encoding
*/
public void writeCodePointUncached(int index, int codePoint, Encoding encoding) {
// Implementation details
}
/**
* Convert to immutable string
* @param encoding String encoding
* @return Immutable TruffleString
*/
public TruffleString toImmutableUncached(Encoding encoding) {
return null; // Implementation details
}
}
/**
* Builder for constructing strings efficiently
*/
public final class TruffleStringBuilder {
/**
* Create string builder
* @param encoding Target encoding
* @return Builder instance
*/
public static TruffleStringBuilder create(Encoding encoding) {
return null; // Implementation details
}
/**
* Create string builder with capacity
* @param encoding Target encoding
* @param capacity Initial capacity
* @return Builder instance
*/
public static TruffleStringBuilder create(Encoding encoding, int capacity) {
return null; // Implementation details
}
/**
* Append string
* @param string String to append
* @return This builder
*/
public TruffleStringBuilder appendStringUncached(TruffleString string) {
return this; // Implementation details
}
/**
* Append Java string
* @param javaString Java string to append
* @return This builder
*/
public TruffleStringBuilder appendJavaStringUTF16Uncached(String javaString) {
return this; // Implementation details
}
/**
* Append code point
* @param codePoint Code point to append
* @return This builder
*/
public TruffleStringBuilder appendCodePointUncached(int codePoint) {
return this; // Implementation details
}
/**
* Build final string
* @return TruffleString instance
*/
public TruffleString toStringUncached() {
return null; // Implementation details
}
/**
* Get current length
* @return Length in code points
*/
public int lengthUncached() {
return 0; // Implementation details
}
}
/**
* Iterator for traversing strings
*/
public final class TruffleStringIterator {
/**
* Create iterator for string
* @param string String to iterate
* @param encoding String encoding
* @return Iterator instance
*/
public static TruffleStringIterator create(TruffleString string, Encoding encoding) {
return null; // Implementation details
}
/**
* Check if more code points available
* @return true if has next
*/
public boolean hasNext() {
return false; // Implementation details
}
/**
* Get next code point
* @return Next code point
*/
public int nextUncached() {
return 0; // Implementation details
}
/**
* Check if more code points available (backward)
* @return true if has previous
*/
public boolean hasPrevious() {
return false; // Implementation details
}
/**
* Get previous code point
* @return Previous code point
*/
public int previousUncached() {
return 0; // Implementation details
}
}
/**
* Encoding definitions and utilities
*/
public final class Encodings {
/**
* UTF-8 encoding
*/
public static final Encoding UTF_8 = null;
/**
* UTF-16 encoding
*/
public static final Encoding UTF_16 = null;
/**
* UTF-32 encoding
*/
public static final Encoding UTF_32 = null;
/**
* ISO-8859-1 (Latin-1) encoding
*/
public static final Encoding ISO_8859_1 = null;
/**
* US-ASCII encoding
*/
public static final Encoding US_ASCII = null;
/**
* Get encoding by name
* @param name Encoding name
* @return Encoding instance or null
*/
public static Encoding getEncoding(String name) {
return null; // Implementation details
}
}
/**
* String encoding descriptor
*/
public abstract class Encoding {
/**
* Get encoding name
* @return Encoding name
*/
public abstract String getName();
/**
* Get maximum bytes per code point
* @return Maximum bytes per code point
*/
public abstract int getMaxBytesPerCodePoint();
/**
* Check if encoding is fixed width
* @return true if fixed width
*/
public abstract boolean isFixedWidth();
}Profiling utilities for optimizing node execution through speculation and type feedback.
/**
* Base class for all performance profiles
*/
public abstract class Profile {
/**
* Disable profiling for this profile
* @return Disabled profile instance
*/
public abstract Profile disable();
/**
* Reset profile statistics
*/
public abstract void reset();
/**
* Check if profile is generic (no optimization)
* @return true if generic
*/
public abstract boolean isGeneric();
/**
* Check if profile is uninitialized
* @return true if uninitialized
*/
public abstract boolean isUninitialized();
}
/**
* Profile for value-based optimizations
*/
public abstract class ValueProfile extends Profile {
/**
* Profile value and return cached or new value
* @param value Value to profile
* @return Profiled value
*/
public abstract <T> T profile(T value);
/**
* Create identity-based value profile
* @return ValueProfile instance
*/
public static ValueProfile createIdentityProfile() {
return null; // Implementation details
}
/**
* Create class-based value profile
* @return ValueProfile instance
*/
public static ValueProfile createClassProfile() {
return null; // Implementation details
}
/**
* Create equality-based value profile
* @return ValueProfile instance
*/
public static ValueProfile createEqualityProfile() {
return null; // Implementation details
}
/**
* Get cached value if available
* @return Cached value or null
*/
public abstract Object getCachedValue();
}
/**
* Specialized value profile for primitive int values
*/
public abstract class IntValueProfile extends Profile {
/**
* Profile int value
* @param value Value to profile
* @return Profiled value
*/
public abstract int profile(int value);
/**
* Create int value profile
* @return IntValueProfile instance
*/
public static IntValueProfile create() {
return null; // Implementation details
}
}
/**
* Specialized value profile for primitive long values
*/
public abstract class LongValueProfile extends Profile {
/**
* Profile long value
* @param value Value to profile
* @return Profiled value
*/
public abstract long profile(long value);
/**
* Create long value profile
* @return LongValueProfile instance
*/
public static LongValueProfile create() {
return null; // Implementation details
}
}
/**
* Specialized value profile for primitive double values
*/
public abstract class DoubleValueProfile extends Profile {
/**
* Profile double value
* @param value Value to profile
* @return Profiled value
*/
public abstract double profile(double value);
/**
* Create double value profile
* @return DoubleValueProfile instance
*/
public static DoubleValueProfile create() {
return null; // Implementation details
}
}
/**
* Specialized value profile for primitive float values
*/
public abstract class FloatValueProfile extends Profile {
/**
* Profile float value
* @param value Value to profile
* @return Profiled value
*/
public abstract float profile(float value);
/**
* Create float value profile
* @return FloatValueProfile instance
*/
public static FloatValueProfile create() {
return null; // Implementation details
}
}
/**
* Profile for branch conditions
*/
public abstract class ConditionProfile extends Profile {
/**
* Profile boolean condition
* @param condition Condition to profile
* @return Profiled condition
*/
public abstract boolean profile(boolean condition);
/**
* Create binary condition profile (true/false)
* @return ConditionProfile instance
*/
public static ConditionProfile createBinaryProfile() {
return null; // Implementation details
}
/**
* Create counting condition profile
* @return ConditionProfile instance
*/
public static ConditionProfile createCountingProfile() {
return null; // Implementation details
}
/**
* Get true count
* @return Number of true results
*/
public abstract long getTrueCount();
/**
* Get false count
* @return Number of false results
*/
public abstract long getFalseCount();
}
/**
* Profile for method execution frequency
*/
public abstract class BranchProfile extends Profile {
/**
* Enter this branch
*/
public abstract void enter();
/**
* Check if branch was visited
* @return true if visited
*/
public abstract boolean wasVisited();
/**
* Create branch profile
* @return BranchProfile instance
*/
public static BranchProfile create() {
return null; // Implementation details
}
}
/**
* Profile optimized for loop conditions
*/
public abstract class LoopConditionProfile extends Profile {
/**
* Profile loop condition
* @param condition Loop condition
* @return Profiled condition
*/
public abstract boolean profile(boolean condition);
/**
* Inject loop condition profiling
* @param condition Loop condition
* @return Profiled condition
*/
public abstract boolean inject(boolean condition);
/**
* Create loop condition profile
* @return LoopConditionProfile instance
*/
public static LoopConditionProfile create() {
return null; // Implementation details
}
}Optimized exception handling for Truffle languages with stack trace management.
/**
* Base class for Truffle language exceptions
*/
public abstract class AbstractTruffleException extends RuntimeException implements TruffleObject {
/**
* Create exception without message
*/
protected AbstractTruffleException() {
super();
}
/**
* Create exception with message
* @param message Exception message
*/
protected AbstractTruffleException(String message) {
super(message);
}
/**
* Create exception with message and cause
* @param message Exception message
* @param cause Exception cause
*/
protected AbstractTruffleException(String message, Throwable cause) {
super(message, cause);
}
/**
* Create exception with cause
* @param cause Exception cause
*/
protected AbstractTruffleException(Throwable cause) {
super(cause);
}
/**
* Get stack trace element limit
* @return Maximum stack trace elements
*/
public final int getStackTraceElementLimit() {
return 0; // Implementation details
}
/**
* Check if exception is internal
* @return true if internal
*/
public boolean isInternalError() {
return false;
}
/**
* Get exception location
* @return Node where exception occurred
*/
public Node getLocation() {
return null; // Implementation details
}
/**
* Get exception type for interop
* @return ExceptionType enum value
*/
public ExceptionType getExceptionType() {
return ExceptionType.RUNTIME_ERROR;
}
/**
* Check if exception has source location
* @return true if has location
*/
public boolean hasSourceLocation() {
return getLocation() != null;
}
/**
* Get source location
* @return SourceSection or null
*/
public SourceSection getSourceLocation() {
Node location = getLocation();
return location != null ? location.getSourceSection() : null;
}
}
/**
* Default stack trace element implementation
*/
public final class DefaultStackTraceElementObject implements TruffleObject {
/**
* Create stack trace element
* @param rootNode Root node for frame
* @param sourceSection Source section
* @return Stack trace element
*/
public static DefaultStackTraceElementObject create(RootNode rootNode, SourceSection sourceSection) {
return new DefaultStackTraceElementObject(rootNode, sourceSection);
}
private DefaultStackTraceElementObject(RootNode rootNode, SourceSection sourceSection) {
// Implementation details
}
/**
* Get root node
* @return RootNode instance
*/
public RootNode getRootNode() {
return null; // Implementation details
}
/**
* Get source section
* @return SourceSection instance
*/
public SourceSection getSourceSection() {
return null; // Implementation details
}
}
/**
* Host stack trace element for host interop
*/
public final class HostStackTraceElementObject implements TruffleObject {
/**
* Create host stack trace element
* @param element Java StackTraceElement
* @return Host stack trace element
*/
public static HostStackTraceElementObject create(StackTraceElement element) {
return new HostStackTraceElementObject(element);
}
private HostStackTraceElementObject(StackTraceElement element) {
// Implementation details
}
/**
* Get Java stack trace element
* @return StackTraceElement instance
*/
public StackTraceElement getStackTraceElement() {
return null; // Implementation details
}
}High-performance object implementation with shape-based optimization.
/**
* Base class for dynamic objects in Truffle
*/
public abstract class DynamicObject implements TruffleObject {
/**
* Get object shape
* @return Shape instance
*/
public abstract Shape getShape();
/**
* Get property value
* @param key Property key
* @return Property value
*/
public abstract Object get(Object key);
/**
* Get property value with default
* @param key Property key
* @param defaultValue Default value if not found
* @return Property value or default
*/
public abstract Object getOrDefault(Object key, Object defaultValue);
/**
* Set property value
* @param key Property key
* @param value Property value
* @return true if successful
*/
public abstract boolean set(Object key, Object value);
/**
* Check if property exists
* @param key Property key
* @return true if property exists
*/
public abstract boolean containsKey(Object key);
/**
* Define property with attributes
* @param key Property key
* @param value Property value
* @param flags Property flags
* @return true if successful
*/
public abstract boolean define(Object key, Object value, int flags);
/**
* Delete property
* @param key Property key
* @return true if successful
*/
public abstract boolean delete(Object key);
/**
* Get property count
* @return Number of properties
*/
public abstract int size();
/**
* Check if object is empty
* @return true if no properties
*/
public abstract boolean isEmpty();
/**
* Copy object
* @param newShape Target shape
* @return Copied object
*/
public abstract DynamicObject copy(Shape newShape);
}
/**
* Library for operations on dynamic objects
*/
public abstract class DynamicObjectLibrary extends Library {
/**
* Get uncached library instance
* @return Uncached library
*/
public static DynamicObjectLibrary getUncached() {
return null; // Implementation details
}
/**
* Get property value
* @param receiver Dynamic object
* @param key Property key
* @return Property value
* @throws FinalLocationException if location is final
*/
public abstract Object getOrDefault(DynamicObject receiver, Object key, Object defaultValue);
/**
* Set property value
* @param receiver Dynamic object
* @param key Property key
* @param value Property value
* @throws IncompatibleLocationException if incompatible
* @throws FinalLocationException if location is final
*/
public abstract void put(DynamicObject receiver, Object key, Object value);
/**
* Set property value with flags
* @param receiver Dynamic object
* @param key Property key
* @param value Property value
* @param flags Property flags
* @throws IncompatibleLocationException if incompatible
* @throws FinalLocationException if location is final
*/
public abstract void putWithFlags(DynamicObject receiver, Object key, Object value, int flags);
/**
* Check if property exists
* @param receiver Dynamic object
* @param key Property key
* @return true if property exists
*/
public abstract boolean containsKey(DynamicObject receiver, Object key);
/**
* Get property or null
* @param receiver Dynamic object
* @param key Property key
* @return Property value or null
*/
public abstract Object getOrDefault(DynamicObject receiver, Object key, Object defaultValue);
/**
* Remove property
* @param receiver Dynamic object
* @param key Property key
* @return true if removed
*/
public abstract boolean removeKey(DynamicObject receiver, Object key);
/**
* Get property keys
* @param receiver Dynamic object
* @return Array of property keys
*/
public abstract Object[] getKeyArray(DynamicObject receiver);
/**
* Get property count
* @param receiver Dynamic object
* @return Number of properties
*/
public abstract int getShapeFlags(DynamicObject receiver);
/**
* Mark object as shared
* @param receiver Dynamic object
* @return Shared object
*/
public abstract DynamicObject markShared(DynamicObject receiver);
/**
* Check if object is shared
* @param receiver Dynamic object
* @return true if shared
*/
public abstract boolean isShared(DynamicObject receiver);
/**
* Reset shape
* @param receiver Dynamic object
* @param otherShape New shape
* @return Object with new shape
*/
public abstract DynamicObject resetShape(DynamicObject receiver, Shape otherShape);
}
/**
* Object layout descriptor
*/
public abstract class Shape {
/**
* Get property by key
* @param key Property key
* @return Property instance or null
*/
public abstract Property getProperty(Object key);
/**
* Get last property in chain
* @return Property instance
*/
public abstract Property getLastProperty();
/**
* Get property list
* @return List of properties
*/
public abstract List<Property> getPropertyList();
/**
* Get property list filtered by predicate
* @param filter Property filter
* @return Filtered property list
*/
public abstract List<Property> getPropertyList(Predicate<Property> filter);
/**
* Get all property keys
* @return List of property keys
*/
public abstract List<Object> getKeys();
/**
* Get property keys filtered by predicate
* @param filter Property filter
* @return Filtered property keys
*/
public abstract List<Object> getKeys(Predicate<Property> filter);
/**
* Get property count
* @return Number of properties
*/
public abstract int getPropertyCount();
/**
* Check if shape has property
* @param key Property key
* @return true if has property
*/
public abstract boolean hasProperty(Object key);
/**
* Create new instance with this shape
* @return New DynamicObject
*/
public abstract DynamicObject newInstance();
/**
* Create child shape with additional property
* @param key Property key
* @param location Property location
* @param flags Property flags
* @return Child shape
*/
public abstract Shape defineProperty(Object key, Object value, int flags);
/**
* Get shared version of shape
* @return Shared shape
*/
public abstract Shape makeSharedShape();
/**
* Check if shape is shared
* @return true if shared
*/
public abstract boolean isShared();
/**
* Check if shape is valid
* @return true if valid
*/
public abstract boolean isValid();
}/**
* Three-valued logic enumeration
*/
public enum TriState {
TRUE, FALSE, UNDEFINED;
/**
* Convert to boolean with default
* @param defaultValue Default value for UNDEFINED
* @return boolean value
*/
public boolean toBoolean(boolean defaultValue) {
switch (this) {
case TRUE: return true;
case FALSE: return false;
default: return defaultValue;
}
}
/**
* Create from boolean
* @param value boolean value
* @return TriState value
*/
public static TriState valueOf(boolean value) {
return value ? TRUE : FALSE;
}
}
/**
* Immutable bit set implementation
*/
public final class FinalBitSet implements Cloneable {
/**
* Create empty bit set
* @return Empty FinalBitSet
*/
public static FinalBitSet create() {
return new FinalBitSet();
}
/**
* Create bit set from long
* @param value Long value
* @return FinalBitSet instance
*/
public static FinalBitSet create(long value) {
return new FinalBitSet(value);
}
/**
* Check if bit is set
* @param bitIndex Bit index
* @return true if set
*/
public boolean get(int bitIndex) {
return false; // Implementation details
}
/**
* Set bit and return new bit set
* @param bitIndex Bit index
* @return New FinalBitSet with bit set
*/
public FinalBitSet set(int bitIndex) {
return this; // Implementation details
}
/**
* Clear bit and return new bit set
* @param bitIndex Bit index
* @return New FinalBitSet with bit cleared
*/
public FinalBitSet clear(int bitIndex) {
return this; // Implementation details
}
/**
* Get bit count
* @return Number of set bits
*/
public int cardinality() {
return 0; // Implementation details
}
/**
* Check if empty
* @return true if no bits set
*/
public boolean isEmpty() {
return false; // Implementation details
}
}
/**
* Weak reference implementation for Truffle
*/
public final class TruffleWeakReference<T> {
/**
* Create weak reference
* @param referent Target object
* @return Weak reference
*/
public static <T> TruffleWeakReference<T> create(T referent) {
return new TruffleWeakReference<>(referent);
}
private TruffleWeakReference(T referent) {
// Implementation details
}
/**
* Get referenced object
* @return Referenced object or null
*/
public T get() {
return null; // Implementation details
}
/**
* Clear reference
*/
public void clear() {
// Implementation details
}
}
/**
* JSON helper utilities
*/
public final class JSONHelper {
/**
* Parse JSON string
* @param jsonString JSON string
* @return Parsed object
*/
public static Object parseJSON(String jsonString) {
return null; // Implementation details
}
/**
* Convert object to JSON string
* @param object Object to convert
* @return JSON string
*/
public static String toJSONString(Object object) {
return null; // Implementation details
}
}Install with Tessl CLI
npx tessl i tessl/maven-org-graalvm-truffle--truffle-api