diff options
Diffstat (limited to 'vendor/github.com/jtolds/gls/README.md')
-rw-r--r-- | vendor/github.com/jtolds/gls/README.md | 89 |
1 files changed, 0 insertions, 89 deletions
diff --git a/vendor/github.com/jtolds/gls/README.md b/vendor/github.com/jtolds/gls/README.md deleted file mode 100644 index 4ebb692f..00000000 --- a/vendor/github.com/jtolds/gls/README.md +++ /dev/null @@ -1,89 +0,0 @@ -gls -=== - -Goroutine local storage - -### IMPORTANT NOTE ### - -It is my duty to point you to https://blog.golang.org/context, which is how -Google solves all of the problems you'd perhaps consider using this package -for at scale. - -One downside to Google's approach is that *all* of your functions must have -a new first argument, but after clearing that hurdle everything else is much -better. - -If you aren't interested in this warning, read on. - -### Huhwaht? Why? ### - -Every so often, a thread shows up on the -[golang-nuts](https://groups.google.com/d/forum/golang-nuts) asking for some -form of goroutine-local-storage, or some kind of goroutine id, or some kind of -context. There are a few valid use cases for goroutine-local-storage, one of -the most prominent being log line context. One poster was interested in being -able to log an HTTP request context id in every log line in the same goroutine -as the incoming HTTP request, without having to change every library and -function call he was interested in logging. - -This would be pretty useful. Provided that you could get some kind of -goroutine-local-storage, you could call -[log.SetOutput](http://golang.org/pkg/log/#SetOutput) with your own logging -writer that checks goroutine-local-storage for some context information and -adds that context to your log lines. - -But alas, Andrew Gerrand's typically diplomatic answer to the question of -goroutine-local variables was: - -> We wouldn't even be having this discussion if thread local storage wasn't -> useful. But every feature comes at a cost, and in my opinion the cost of -> threadlocals far outweighs their benefits. They're just not a good fit for -> Go. - -So, yeah, that makes sense. That's a pretty good reason for why the language -won't support a specific and (relatively) unuseful feature that requires some -runtime changes, just for the sake of a little bit of log improvement. - -But does Go require runtime changes? - -### How it works ### - -Go has pretty fantastic introspective and reflective features, but one thing Go -doesn't give you is any kind of access to the stack pointer, or frame pointer, -or goroutine id, or anything contextual about your current stack. It gives you -access to your list of callers, but only along with program counters, which are -fixed at compile time. - -But it does give you the stack. - -So, we define 16 special functions and embed base-16 tags into the stack using -the call order of those 16 functions. Then, we can read our tags back out of -the stack looking at the callers list. - -We then use these tags as an index into a traditional map for implementing -this library. - -### What are people saying? ### - -"Wow, that's horrifying." - -"This is the most terrible thing I have seen in a very long time." - -"Where is it getting a context from? Is this serializing all the requests? -What the heck is the client being bound to? What are these tags? Why does he -need callers? Oh god no. No no no." - -### Docs ### - -Please see the docs at http://godoc.org/github.com/jtolds/gls - -### Related ### - -If you're okay relying on the string format of the current runtime stacktrace -including a unique goroutine id (not guaranteed by the spec or anything, but -very unlikely to change within a Go release), you might be able to squeeze -out a bit more performance by using this similar library, inspired by some -code Brad Fitzpatrick wrote for debugging his HTTP/2 library: -https://github.com/tylerb/gls (in contrast, jtolds/gls doesn't require -any knowledge of the string format of the runtime stacktrace, which -probably adds unnecessary overhead). |