BoxLang Core Performance
BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.
Overview
BIFs, components, and runtime code run under load, often inside tight loops.
Code that looks like it only reads data can allocate heavily. This skill lists
the patterns that have bitten core string BIFs and how to avoid them.
Rule zero: measure first. Apply these patterns to hot paths and BIFs, not to
one-off setup code. Readability wins unless a profile or benchmark says otherwise.
Strings
substring() is not free
String.substring() allocates a new String and copies the characters. On a
large input inside a loop this is expensive. Reading code that calls it often
looks harmless.
// BAD: allocates a new String on every iteration
for ( int i = 0; i < input.length(); i++ ) {
if ( input.substring( i ).startsWith( prefix ) ) {
count++;
}
}
// GOOD: no allocation, compares in place
for ( int i = 0; i < input.length(); i++ ) {
if ( input.startsWith( prefix, i ) ) {
count++;
}
}
Allocation-free alternatives:
| Instead of |
Use |
s.substring( n ).startsWith( p ) |
s.startsWith( p, n ) |
s.substring( a, b ).equals( p ) |
s.regionMatches( a, p, 0, p.length() ) (check b - a == p.length()) |
s.substring( a, b ).equalsIgnoreCase( p ) |
s.regionMatches( true, a, p, 0, p.length() ) |
s.substring( n ).indexOf( x ) |
s.indexOf( x, n ) (result is absolute, not relative to n) |
s.substring( n ).endsWith( p ) |
s.endsWith( p ) if n is only trimming the front; otherwise regionMatches |
s.substring( i, i + 1 ) |
s.charAt( i ) |
s.substring( 0, 4 ).equalsIgnoreCase( "http" ) |
s.regionMatches( true, 0, "http", 0, 4 ) |
Remember regionMatches returns false if the region runs past the end of the
string, so you rarely need a separate length check.
If you need the substring more than once, take it once and reuse it. One
substring() outside a loop is fine.
Case-insensitive search allocates twice
a.toLowerCase().indexOf( b.toLowerCase() ) creates two new strings per call.
In a loop, lowercase once outside it, or use regionMatches( true, ... ) for
prefix and region checks.
Build strings with StringBuilder
- Never use
+ or += on a String inside a loop.
- Presize when you know the rough length:
new StringBuilder( input.length() ).
- Append characters and ranges directly:
sb.append( s, start, end ) avoids the intermediate substring.
- Avoid
String.format() in hot paths. It parses the format string on every call.
- Prefer
String.join() or a StringJoiner over manual delimiter handling.
Regex
- Never call
String.split(), replaceAll(), or matches() with a non-trivial
regex in a hot path. Each call compiles a Pattern.
- Precompile as a
private static final Pattern.
- For single-character delimiters, a manual
indexOf loop or split( "x" ) with a
literal that is not a regex metacharacter has a fast path in the JDK.
- Prefer
String.replace( CharSequence, CharSequence ) over replaceAll() when
you do not need a pattern. It does not compile a regex.
// Precompiled once per class, reused for every call
private static final Pattern DECIMAL_SPLIT_PATTERN = Pattern.compile( "\\." );
BoxLang-Specific
Key allocation
Key.of( String ) allocates a new Key on every call. A Key precomputes its
hash code, which makes lookups fast, but creating one per call throws that win away.
// BAD: new Key on every invocation
public Object _invoke( IBoxContext context, ArgumentsScope arguments ) {
String str = arguments.getAsString( Key.of( "str" ) );
}
// GOOD: reuse a shared Key
// Common names already exist as constants on Key (Key.string, Key.value, Key.array ...)
public Object _invoke( IBoxContext context, ArgumentsScope arguments ) {
String str = arguments.getAsString( Key.string );
}
// GOOD: for names that are not on Key, hold your own constant
private static final Key delimsKey = Key.of( "delimiter_list1" );
- Look for an existing
Key.xxx constant before creating a new one.
- Never call
Key.of() inside a loop. Hoist it to a static final field.
- Keys built from dynamic runtime strings (user-supplied struct keys) cannot be
constants, so build them once per operation, not once per iteration.
Immutable value objects
Pre-compute hashCode in the constructor for classes whose fields are all final,
and return the cached field. See ortus.boxlang.runtime.util.NameValuePair and
Key for reference implementations.
Attempt and Optional wrappers
Attempt and Optional allocate a wrapper. They are great at API boundaries, but
avoid creating them per element in tight loops. Use a plain null check in the inner
loop.
Argument access
- Fetch each argument once into a local variable at the top of
_invoke().
Do not call arguments.get( key ) repeatedly inside a loop.
- Use the typed getters (
getAsString, getAsInteger, getAsArray) so you do not
re-run a caster on every iteration.
Logging in hot paths
logger.debug( "x {}", y ) with parameterized messages is cheap when disabled.
String concatenation or building arguments before the call is not. Guard
expensive argument construction with if ( logger.isDebugEnabled() ).
Collections and Allocation
- Presize
ArrayList, HashMap, and StringBuilder when the size is known or
cheaply estimated.
- Avoid boxing in loops. Prefer
int/long/double locals over Integer/Long/Double.
Beware of Map<String, Integer> counters that box on every merge.
- Streams and lambdas are fine for clarity but add allocation and indirection.
In a hot BIF, use a plain
for loop.
- Do not copy to inspect. If you only need to read an
Array or Struct, iterate
it directly rather than calling toArray() or building a defensive copy.
- Hoist invariants out of loops:
size(), length(), lowercased needles, compiled patterns.
- Return early for empty or null inputs before doing any allocation.
Concurrency
- Prefer lock-free structures (
ConcurrentHashMap, LongAdder, AtomicReference)
over synchronized on shared hot paths.
- Inside code that may run on virtual threads, avoid blocking while inside a
synchronized block. It can pin the carrier thread. Use ReentrantLock instead.
- Avoid
ThreadLocal caches holding large objects. Virtual threads make
per-thread state expensive.
- Do not hold locks while calling user-supplied BoxLang code (closures, callbacks).
Measuring
- Reproduce the slow case with realistic input sizes. Large strings expose
substring() costs that tiny test strings hide.
- Benchmark with JMH for micro-level
questions ("is
startsWith( p, i ) faster than substring( i ).startsWith( p )?").
Hand-rolled System.nanoTime() loops lie because of JIT warm-up and dead-code elimination.
- Profile for system-level questions. Java Flight Recorder
(
-XX:+FlightRecorder) and async-profiler show allocation hot spots.
Watch the allocation profile, not just CPU time.
- Keep the benchmark or add a regression test when you fix a hotspot.
Review Checklist for Hot-Path Code
References
1---2name: boxlang-core-dev-performance3description: "Use this skill when writing or reviewing performance-sensitive BoxLang core Java code (BIFs, components, runtime services, hot paths): String.substring() allocation, startsWith with offset, regionMatches, regex precompiling, Key allocation, StringBuilder, boxing, streams, virtual-thread pinning, and measuring with JMH before optimizing."4metadata:5 source: https://skillmd.com/skills/ortus-boxlang/boxlang-core-dev-performance6---78# BoxLang Core Performance910> BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.1112## Overview1314BIFs, components, and runtime code run under load, often inside tight loops.15Code that looks like it only reads data can allocate heavily. This skill lists16the patterns that have bitten core string BIFs and how to avoid them.1718**Rule zero:** measure first. Apply these patterns to hot paths and BIFs, not to19one-off setup code. Readability wins unless a profile or benchmark says otherwise.2021## Strings2223### `substring()` is not free2425`String.substring()` allocates a new `String` and copies the characters. On a26large input inside a loop this is expensive. Reading code that calls it often27looks harmless.2829```java30// BAD: allocates a new String on every iteration31for ( int i = 0; i < input.length(); i++ ) {32 if ( input.substring( i ).startsWith( prefix ) ) {33 count++;34 }35}3637// GOOD: no allocation, compares in place38for ( int i = 0; i < input.length(); i++ ) {39 if ( input.startsWith( prefix, i ) ) {40 count++;41 }42}43```4445Allocation-free alternatives:4647| Instead of | Use |48|------------|-----|49| `s.substring( n ).startsWith( p )` | `s.startsWith( p, n )` |50| `s.substring( a, b ).equals( p )` | `s.regionMatches( a, p, 0, p.length() )` (check `b - a == p.length()`) |51| `s.substring( a, b ).equalsIgnoreCase( p )` | `s.regionMatches( true, a, p, 0, p.length() )` |52| `s.substring( n ).indexOf( x )` | `s.indexOf( x, n )` (result is absolute, not relative to `n`) |53| `s.substring( n ).endsWith( p )` | `s.endsWith( p )` if `n` is only trimming the front; otherwise `regionMatches` |54| `s.substring( i, i + 1 )` | `s.charAt( i )` |55| `s.substring( 0, 4 ).equalsIgnoreCase( "http" )` | `s.regionMatches( true, 0, "http", 0, 4 )` |5657Remember `regionMatches` returns `false` if the region runs past the end of the58string, so you rarely need a separate length check.5960If you need the substring more than once, take it once and reuse it. One61`substring()` outside a loop is fine.6263### Case-insensitive search allocates twice6465`a.toLowerCase().indexOf( b.toLowerCase() )` creates two new strings per call.66In a loop, lowercase once outside it, or use `regionMatches( true, ... )` for67prefix and region checks.6869### Build strings with `StringBuilder`7071- Never use `+` or `+=` on a `String` inside a loop.72- Presize when you know the rough length: `new StringBuilder( input.length() )`.73- Append characters and ranges directly: `sb.append( s, start, end )` avoids the intermediate substring.74- Avoid `String.format()` in hot paths. It parses the format string on every call.75- Prefer `String.join()` or a `StringJoiner` over manual delimiter handling.7677### Regex7879- Never call `String.split()`, `replaceAll()`, or `matches()` with a non-trivial80 regex in a hot path. Each call compiles a `Pattern`.81- Precompile as a `private static final Pattern`.82- For single-character delimiters, a manual `indexOf` loop or `split( "x" )` with a83 literal that is not a regex metacharacter has a fast path in the JDK.84- Prefer `String.replace( CharSequence, CharSequence )` over `replaceAll()` when85 you do not need a pattern. It does not compile a regex.8687```java88// Precompiled once per class, reused for every call89private static final Pattern DECIMAL_SPLIT_PATTERN = Pattern.compile( "\\." );90```9192## BoxLang-Specific9394### `Key` allocation9596`Key.of( String )` allocates a new `Key` on every call. A `Key` precomputes its97hash code, which makes lookups fast, but creating one per call throws that win away.9899```java100// BAD: new Key on every invocation101public Object _invoke( IBoxContext context, ArgumentsScope arguments ) {102 String str = arguments.getAsString( Key.of( "str" ) );103}104105// GOOD: reuse a shared Key106// Common names already exist as constants on Key (Key.string, Key.value, Key.array ...)107public Object _invoke( IBoxContext context, ArgumentsScope arguments ) {108 String str = arguments.getAsString( Key.string );109}110111// GOOD: for names that are not on Key, hold your own constant112private static final Key delimsKey = Key.of( "delimiter_list1" );113```114115- Look for an existing `Key.xxx` constant before creating a new one.116- Never call `Key.of()` inside a loop. Hoist it to a `static final` field.117- Keys built from dynamic runtime strings (user-supplied struct keys) cannot be118 constants, so build them once per operation, not once per iteration.119120### Immutable value objects121122Pre-compute `hashCode` in the constructor for classes whose fields are all `final`,123and return the cached field. See `ortus.boxlang.runtime.util.NameValuePair` and124`Key` for reference implementations.125126### Attempt and Optional wrappers127128`Attempt` and `Optional` allocate a wrapper. They are great at API boundaries, but129avoid creating them per element in tight loops. Use a plain null check in the inner130loop.131132### Argument access133134- Fetch each argument once into a local variable at the top of `_invoke()`.135 Do not call `arguments.get( key )` repeatedly inside a loop.136- Use the typed getters (`getAsString`, `getAsInteger`, `getAsArray`) so you do not137 re-run a caster on every iteration.138139### Logging in hot paths140141`logger.debug( "x {}", y )` with parameterized messages is cheap when disabled.142String concatenation or building arguments before the call is not. Guard143expensive argument construction with `if ( logger.isDebugEnabled() )`.144145## Collections and Allocation146147- **Presize** `ArrayList`, `HashMap`, and `StringBuilder` when the size is known or148 cheaply estimated.149- **Avoid boxing** in loops. Prefer `int`/`long`/`double` locals over `Integer`/`Long`/`Double`.150 Beware of `Map<String, Integer>` counters that box on every `merge`.151- **Streams and lambdas** are fine for clarity but add allocation and indirection.152 In a hot BIF, use a plain `for` loop.153- **Do not copy to inspect.** If you only need to read an `Array` or `Struct`, iterate154 it directly rather than calling `toArray()` or building a defensive copy.155- **Hoist invariants** out of loops: `size()`, `length()`, lowercased needles, compiled patterns.156- **Return early** for empty or null inputs before doing any allocation.157158## Concurrency159160- Prefer lock-free structures (`ConcurrentHashMap`, `LongAdder`, `AtomicReference`)161 over `synchronized` on shared hot paths.162- Inside code that may run on virtual threads, avoid blocking while inside a163 `synchronized` block. It can pin the carrier thread. Use `ReentrantLock` instead.164- Avoid `ThreadLocal` caches holding large objects. Virtual threads make165 per-thread state expensive.166- Do not hold locks while calling user-supplied BoxLang code (closures, callbacks).167168## Measuring1691701. **Reproduce** the slow case with realistic input sizes. Large strings expose171 `substring()` costs that tiny test strings hide.1722. **Benchmark** with [JMH](https://github.com/openjdk/jmh) for micro-level173 questions ("is `startsWith( p, i )` faster than `substring( i ).startsWith( p )`?").174 Hand-rolled `System.nanoTime()` loops lie because of JIT warm-up and dead-code elimination.1753. **Profile** for system-level questions. Java Flight Recorder176 (`-XX:+FlightRecorder`) and async-profiler show allocation hot spots.177 Watch the allocation profile, not just CPU time.1784. **Keep the benchmark** or add a regression test when you fix a hotspot.179180## Review Checklist for Hot-Path Code181182- [ ] No `substring()` whose result is only compared or searched183- [ ] No `toLowerCase()` / `toUpperCase()` inside a loop on the same value184- [ ] No `Key.of()` in loops or per-invocation for fixed names185- [ ] No regex compile per call (`split`, `replaceAll`, `matches`)186- [ ] No `+=` string concatenation in loops187- [ ] `StringBuilder` presized where size is known188- [ ] No streams, `Attempt`, or boxing per element in inner loops189- [ ] Invariants hoisted out of loops190- [ ] Early return for null/empty input191- [ ] No blocking inside `synchronized` on virtual-thread paths192- [ ] Verified with a benchmark or profile, not assumed193194## References195196- [BoxLang Docs](https://boxlang.ortusbooks.com/)197- [JMH](https://github.com/openjdk/jmh)198- [Java Flight Recorder](https://docs.oracle.com/en/java/javase/21/jfr/)199- [JEP 444: Virtual Threads](https://openjdk.org/jeps/444)200- See also: `bif-development`, `runtime-architecture`, `logging`