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)

```prg
cResult := strings.ToUpper(cText)
```

gengo auto-generates:
```go
// 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)

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

gengo auto-generates:
```go
// 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

```prg
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

```prg
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)
```prg
db := sql.Open("sqlite", ":memory:")     // 1 call — 66ns vs 243ns = imperceptible
cResult := strings.ToUpper("hello")       // 1 call — unnoticeable
```

### Big difference (bulk operations)
```prg
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.