:warning: This package doesn't support Go1.17.* due to Go runtime changes. Don't use this package until #10 is resolved.
WARNING: It's not recommended to use this package in any production environment. It may crash you at any time. Use context
instead when possible.
Package tls
provides TLS for any goroutine by hijacking runtime.goexit
on stack. Comparing with other similar packages, this package avoids any potential resource leak in TLS.
Use go get
to install this package.
go get github.com/huandu/go-tls
Set arbitrary data and get it later.
k := "my key"
v := 1234
tls.Set(k, tls.MakeData(v))
// Get data by k.
d, ok := tls.Get(k)
assert(ok)
assert(d.Value().(int) == v)
// Get a unique ID for current goroutine.
// It's guaranteed to be unique.
id := tls.ID()
// Delete data by k.
tls.Del(k)
// Reset TLS so that all keys are removed and all data is closed if necessary.
// It doesn't remove any AtExit handler.
tls.Reset()
// Completely unload TLS and discard all data and AtExit handlers.
// If TLS method is called after Unload, a new TLS stub will be created.
// The ID() will return a different value.
tls.Unload()
If the data implements io.Closer
, it will be called automatically when Reset
is called or goroutine exits. It's not allowed to use any TLS methods in the Close
method of TLS data. It will cause permanent memory leak.
AtExit
pushes a function to a slice of at-exit handlers and executes them when goroutine is exiting in FILO order. All TLS data is still available when calling at-exit handlers.
AtExit
doesn't work on main goroutine as it doesn't exit at all.
tls.AtExit(func() {
// Do something when goroutine is exiting...
})
Several limitations so far.
AtExit
doesn't work on main goroutine, as this goroutine always exits with os.Exit(0)
instead of calling goexit
. See main()
in src/runtime/proc.go
.It's quite a long story I don't have time to write everything down right now.
TL; DR. Package tls
uses goroutine's g
struct pointer to identify a goroutine and hacks runtime.goexit
to do house clean work when goroutine exits.
This approach is relatively safe, because all technics are based on runtime types which doesn't change since Go1.0.
Following runtime types are used.
g.stack
: It's the first field of g
. It stores stack memory range of a g
.runtime.goexit
to another function pc, runtime will complain it as it's not a valid top of stack function (checked by runtime.topofstack
). As a workaround, I hacks function symbol table to set _func.pcsp
of the hacked goexit to 0
to skip checks.Go
func explicitly before using any context methods.goid
as a unique key for any goroutine and store contextual information.This package is licensed under MIT license. See LICENSE for details.