github.com/wasilibs/nottinygc@v0.7.2-0.20240312114022-d59c9478ef51/README.md (about) 1 # nottinygc 2 3 nottinygc requires TinyGo 0.28+ 4 5 _nottinygc has reached end-of-life. The Go compiler [will support][6] wasmexport soon so should compile most binaries, including proxy-wasm. As soon as gotip includes it, this repository will be archived, and until then, it is recommended to pause rather than gamble on this bandaid._ 6 7 nottinygc is a replacement memory allocator for TinyGo targetting WASI. The default allocator 8 is built for small code size which can cause performance issues in higher-scale use cases. 9 nottinygc replaces it with [bdwgc][1] for garbage collection and [mimalloc][2] for standard 10 malloc-based allocation. These mature libraries can dramatically improve the performance of 11 TinyGo WASI applications at the expense of several hundred KB of additional code footprint. 12 13 Note that this library currently only works when the scheduler is disabled. 14 15 ## Usage 16 17 Using the library requires both importing it and modifying flags when invoking TinyGo. 18 19 Add a blank import to the library to your code's `main` package. 20 21 ```go 22 import _ "github.com/wasilibs/nottinygc" 23 ``` 24 25 Additionally, add `-gc=custom` and `-tags=custommalloc` to your TinyGo build flags. 26 27 ```bash 28 tinygo build -o main.wasm -gc=custom -tags=custommalloc -target=wasi -scheduler=none main.go 29 ``` 30 31 ### Using with Envoy 32 33 This library relies on WASI to implement certain functionality, for which Envoy's implementation 34 is incomplete, and in addition, it's ABI, proxy-wasm has design issues that prevent working with 35 defaults appropriate for normal TinyGo applications. As this project is commonly used with Envoy, 36 we provide a build tag, to work around these issues. If building an Envoy plugin, add 37 `-tags=nottinygc_envoy` (or combine it with additional tags) to your TinyGo build flags. This 38 will disable export of `malloc`/`free`/ and define a no-op `sched_yield` function. 39 40 Other hosts that implement WASI fully, such as [wazero][3] and ABIs with correct memory semantics, 41 such as [http-wasm][5], will not have any issue. Implementations of proxy-wasm other than Envoy 42 may also work fine without the build tag. 43 44 ## Performance 45 46 Benchmarks are run against every commit in the [bench][4] workflow. GitHub action runners are highly 47 virtualized and do not have stable performance across runs, but the relative numbers within a run 48 should still be somewhat, though not precisely, informative. 49 50 One run looks like this 51 52 ``` 53 BenchmarkGC/bench.wasm-2 52 220294559 ns/op 54 BenchmarkGC/benchref.wasm-2 6 2000167805 ns/op 55 ``` 56 57 The benchmark is very simple, allocating some large strings in a loop. We see nottinygc perform almost 58 10x better in this benchmark. Note that just allocation / collection time is not the only aspect of 59 GC performance, allocation locality and fragmentation can also affect performance of real-world 60 applications. We have found that the default allocator can cause applications to run out of memory, 61 possibly due to fragmentation, whereas this library will continue to run indefinitely. 62 63 [1]: https://github.com/ivmai/bdwgc 64 [2]: https://github.com/microsoft/mimalloc 65 [3]: https://github.com/tetratelabs/wazero 66 [4]: https://github.com/wasilibs/nottinygc/actions/workflows/bench.yaml 67 [5]: https://http-wasm.io/ 68 [6]: https://github.com/golang/go/issues/65199