Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 

noescape

GoDoc Go Report Card

go get lukechampine.com/noescape

noescape provides Read and Write functions that do not heap-allocate their argument.

Normally, when you pass a []byte to an io.Reader or io.Writer, the compiler must heap-allocate the slice data. This is because, at compile-time, there is no way to know which concrete type is satisfying the interface, and therefore the compiler cannot prove that the slice data will not be retained.

This is sad, because the vast majority of Read and Write methods do not retain their argument, but still incur the performance penalty of heap-allocation. The noescape package allows you to promise to the compiler that your Read or Write method is perfectly safe, thank you very much, thus allowing you to avoid the allocation.

This can be illustrated via benchmark:

type yesReader struct{}

func (yesReader) Read(p []byte) (int, error) {
    return copy(p, "yes"), nil
}

func BenchmarkConcrete(b *testing.B) {
    r := yesReader{}
    for i := 0; i < b.N; i++ {
        buf := make([]byte, 100)
        r.Read(buf)
    }
}

func BenchmarkInterface(b *testing.B) {
    var r io.Reader = yesReader{}
    for i := 0; i < b.N; i++ {
        buf := make([]byte, 100)
        r.Read(buf)
    }
}

func BenchmarkNoEscape(b *testing.B) {
    var r io.Reader = yesReader{}
    for i := 0; i < b.N; i++ {
        buf := make([]byte, 100)
        noescape.Read(r, buf)
    }
}
BenchmarkConcrete-4     1000000000        0.372 ns/op       0 B/op      0 allocs/op
BenchmarkInterface-4      28114684       44.8 ns/op       112 B/op      1 allocs/op
BenchmarkNoEscape-4       88440447       11.8 ns/op        0 B/op       0 allocs/op

How?

The gc compiler recognizes a //go:noescape pragma that promises to the compiler that a function's arguments do not escape. So we just need to stick this pragma on top of our Read and Write functions:

//go:noescape
func Read(r io.Reader, b []byte) (int, error) { return r.Read(b) }
//go:noescape
func Write(w io.Writer, b []byte) (int, error) { return w.Write(b) }

There's a complication, though: the go:noescape pragma can only be applied to externally-defined functions. So in order to use it, we need to implement Read and Write in assembly! Not a big deal, it's just one line of Go, after all; but it turned out to be trickier than I thought. If you're interested in the details, check out the comments in noescape_amd64.s.

On that note: only amd64 is supported for now. If you want to contribute implementations for other architectures, I'll gladly merge them. Also, for maximum compatibility, I should add non-assembly implementations; this would defeat the whole point, but it would also allow this package to be used in cross-platform code as an architecture-dependent optimization.

About

Promise to the Go compiler that your Reads and Writes are well-behaved

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published