cosmos72 / gls

Fast goroutine local storage

gls

Fast goroutine local storage

WARNING

There is extensive documentation and discussion on why implementing and using thread-local storage in Go - actually, goroutine-local storage - is a bad idea.

See for example the Go FAQ on goroutine id and context.Context, which is how you're encouraged to solve problems that would require a goroutine-local storage.

The main obstacle in adopting context.Context is that all of your functions must have a new first argument. So, if that horrifies you or is simply not feasible for your use case, feel free to ignore this warning and read on.

Just remember that, if some Go programmers frowns at your use of goroutine-local storage, there are good reasons.

Why?

To retrieve per-goroutine data that some function did not - or could not - pass through the call chain, down to where you need it.

Other goroutine-local libraries, as jtolds/gls and tylerb/gls explain the reasons and use cases for goroutine-local storage more in detail.

Status

Beta.

Lightly tested on 386, amd64, arm, arm64, mips, ppc64le with Go 1.10.1.
Other architectures (mipsle, mips64, ppc64, riscv64, s390x) supported in theory but not tested.

How it works

Go runtime has an internal, i.e. unexported, goroutine-local runtime.g struct. It is used for several purposes, including defer(), recover(), by the goroutine scheduler, and it even has an unexported goid field, i.e. a goroutine ID.

Several other goroutine-local libraries extract this goroutine ID with various tricks, most notably from runtime.Stack() textual output.

Instead, we use a tiny bit of assembler code to retrieve the address of the runtime.g struct and return it converted to an opaque uintptr.

We use it as the key in a global variable containing per-goroutine data.

This is also fast, probably orders of magnitude faster than most other solutions.

Why not the same goroutine ID?

To avoid fiddling with the internal layout of runtime.g struct, we only take its address.

Accessing the goid field would require knowing its offset within the struct, which is both tedious and error-prone to retrieve, since it's an unexported field of an unexported struct type.

Documentation

See the autogenerated API docs at http://godoc.org/github.com/cosmos72/gls

License

BSD 3-Clause License

gls's Issues

Needs riscv64 support

Greetings! I'm trying to fix the gomacro port for riscv64 freebsd and noticed that gls support code for this platform is missing. Could you add it?

WASM Support

Greetings,

I'm using your gls package and encountered an issue when building an app for the WASM platform.

Upon reviewing your gomacro project, I observed the WASM stub. It appears the stub was created under the assumption that goroutines don't operate on WASM due to its lack of thread support. However, as mentioned in this StackOverflow post while WASM doesn't support threads, goroutines are fully functional there.

To address this, I crafted an id_wasm.s file, adopting content from id_arm64.s, which resolved the matter. Later, I identified a similar solution here.

I've assembled a demonstration through a simple WASM application, showcasing gls operating efficiently with WASM. The example is available at https://github.com/pilat/gls-wasm-test.

If it's of interest to you, I'm willing to open a PR here to integrate these changes, facilitating better support for the WASM platform.