five/docs/go-performance-en.md

Five Go Interop Performance

Summary

When calling Go functions from PRG, Five automatically applies 3-tier optimization. No code changes needed — gengo selects the optimal path automatically.

Benchmark Results (Intel Ultra 7 255H)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Function          Direct Go   Reflect     FastPath    Speedup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 strings.ToUpper      34ns       242ns        66ns     3.7x
 strings.Contains      3ns       218ns        19ns    11.7x
 strings.ReplaceAll   43ns       327ns        77ns     4.4x
 math.Sqrt           0.1ns       173ns        16ns    11.0x
 obj:Method()          —         412ns       235ns     1.8x
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Memory allocs       1x         7-9x        1-3x      3x less
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

3-Tier Automatic Optimization

Tier 1: FastPath — Package Function Calls (3-12x faster)

cResult := strings.ToUpper(cText)

gengo auto-generates:

// Compile-time: register type-specialized function
var _ff_strings_ToUpper = hbrt.RegisterFastFunc("strings.ToUpper", strings.ToUpper)

// Runtime: bypass reflect, direct type assertion
_results := hbrt.GoCallFast(_ff_strings_ToUpper, _a0)  // 66ns

RegisterFastFunc detects the function signature and auto-sets fast path:

• func(string) string → direct call
• func(string, string) bool → direct call
• func(float64) float64 → direct call
• Others → reflect fallback

Tier 2: Method Cache — Object Method Calls (1.8x faster)

db:Exec("CREATE TABLE ...")

gengo auto-generates:

// First call: reflect.MethodByName → cache
// Subsequent calls: instant cache lookup
hbrt.GoCallCached(_obj, "Exec", _sa0)  // 235ns (vs 412ns)

Eliminates method lookup cost when calling the same method on the same type repeatedly.

Tier 3: Auto Type Conversion — 3x Less Memory

PRG Type	Go Type	Conversion Cost
String	string	zero-copy (pointer pass)
Numeric(int)	int	bit cast (0 alloc)
Numeric(double)	float64	bit cast (0 alloc)
Logical	bool	bit cast (0 alloc)
Array	[]T	slice conversion (1 alloc)

Real-World Performance

100K String Conversions

FOR i := 1 TO 100000
   aData[i] := strings.ToUpper(aData[i])
NEXT

Method	100K items	1M items
Reflect (old)	24ms	243ms
FastPath (current)	6.6ms	66ms
Native Go	3.4ms	34ms

PRG code runs within 2x of native Go performance.

Bulk DB Query

aRows := SqlQuery(db, "SELECT * FROM products")  // 100K rows
FOR i := 1 TO Len(aRows)
   aRows[i]["name"] := strings.ToUpper(aRows[i]["name"])
NEXT

Stage	Time
SQL query (Go database/sql)	~50ms
Result conversion (Go → Harbour)	~15ms
String processing (FastPath)	~7ms
Total	~72ms

Pure Go program: ~55ms. Less than 30% overhead.

HTTP Server Request Handling

Metric	Throughput
Go net/http native	~100,000 req/sec
Five PRG handler (FastPath)	~80,000 req/sec
Five PRG handler (Reflect)	~30,000 req/sec

FastPath enables HTTP servers at 80% of native Go performance.

When Does It Matter?

No difference (single call)

db := sql.Open("sqlite", ":memory:")     // 1 call — 66ns vs 243ns = imperceptible
cResult := strings.ToUpper("hello")       // 1 call — unnoticeable

Big difference (bulk operations)

FOR i := 1 TO 100000                      // 100K iterations
   aData[i] := strings.ToUpper(aData[i])  // FastPath: 6.6ms vs Reflect: 24ms
NEXT

DO WHILE rows:Next()                      // Full DB scan
   ? rows:Column(1)                       // Cached: 23ms vs Reflect: 42ms
ENDDO

Five vs Other Language Interop

Language	Foreign Call Method	Overhead
Python → C (ctypes)	FFI marshal	~1,000ns
Java → C (JNI)	JNI bridge	~100ns
Node.js → C (N-API)	V8 bridge	~200ns
Five → Go (FastPath)	Type assertion	16-77ns
Five → Go (Method)	Reflect + cache	235ns

Five's Go interop is faster than JNI and 10x faster than Python ctypes.

Stress Test Results

Volume:      40,000 calls (4 types x 10K)                  PASS
Large Data:  1MB string, 10K array, 1K map                 PASS
Boundary:    int/int64/float64/string edge values           PASS
Concurrent:  20,000 goroutine simultaneous calls            PASS
Object:      1,000 Go objects, method chain, nil safety     PASS
Coercion:    7 x 6 = 42 type combinations, 41 succeeded    PASS
Fuzz:        5,000 random input verification                PASS

Why It's Fast — Technical Background

1. Compile-time decisions: gengo analyzes IMPORT packages and generates FastFunc registration code. Zero runtime decision cost.

2. Type specialization: Common signatures like func(string) string use Go type assertions instead of reflect.Call. Allocations drop from 7 to 1.

3. Method cache: reflect.Method lookups for identical type+method pairs are cached in a sync.RWMutex-protected map. Second call onward has zero lookup cost.

4. Zero-copy strings: Harbour's HbString and Go's string are both immutable. Only the pointer is passed, no copying needed.

5. 24-byte Value: Five's Tagged Value is fixed 24 bytes. Stack-allocatable, minimal GC pressure.