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