Merge commit '152cc5b980f1f929b6e7c9044257844ae39652e4' as 'src/githu…

…b.com/getlantern/gls'

src/github.com/getlantern/gls/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2013, Space Monkey, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

src/github.com/getlantern/gls/README.md

@@ -0,0 +1,89 @@
+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).

src/github.com/getlantern/gls/context.go

@@ -0,0 +1,160 @@
+// Package gls implements goroutine-local storage.
+package gls
+
+import (
+	"sync"
+)
+
+const (
+	maxCallers = 64
+)
+
+var (
+	stackTagPool   = &idPool{}
+	mgrRegistry    = make(map[*ContextManager]bool)
+	mgrRegistryMtx sync.RWMutex
+)
+
+// Values is simply a map of key types to value types. Used by SetValues to
+// set multiple values at once.
+type Values map[interface{}]interface{}
+
+// ContextManager is the main entrypoint for interacting with
+// Goroutine-local-storage. You can have multiple independent ContextManagers
+// at any given time. ContextManagers are usually declared globally for a given
+// class of context variables. You should use NewContextManager for
+// construction.
+type ContextManager struct {
+	mtx    sync.RWMutex
+	values map[uint]Values
+}
+
+// NewContextManager returns a brand new ContextManager. It also registers the
+// new ContextManager in the ContextManager registry which is used by the Go
+// method. ContextManagers are typically defined globally at package scope.
+func NewContextManager() *ContextManager {
+	mgr := &ContextManager{values: make(map[uint]Values)}
+	mgrRegistryMtx.Lock()
+	defer mgrRegistryMtx.Unlock()
+	mgrRegistry[mgr] = true
+	return mgr
+}
+
+// Unregister removes a ContextManager from the global registry, used by the
+// Go method. Only intended for use when you're completely done with a
+// ContextManager. Use of Unregister at all is rare.
+func (m *ContextManager) Unregister() {
+	mgrRegistryMtx.Lock()
+	defer mgrRegistryMtx.Unlock()
+	delete(mgrRegistry, m)
+}
+
+// SetValues takes a collection of values and a function to call for those
+// values to be set in. Anything further down the stack will have the set
+// values available through GetValue. SetValues will add new values or replace
+// existing values of the same key and will not mutate or change values for
+// previous stack frames.
+// SetValues is slow (makes a copy of all current and new values for the new
+// gls-context) in order to reduce the amount of lookups GetValue requires.
+func (m *ContextManager) SetValues(new_values Values, context_call func()) {
+	if len(new_values) == 0 {
+		context_call()
+		return
+	}
+
+	tags := readStackTags(1)
+
+	m.mtx.Lock()
+	values := new_values
+	for _, tag := range tags {
+		if existing_values, ok := m.values[tag]; ok {
+			// oh, we found existing values, let's make a copy
+			values = make(Values, len(existing_values)+len(new_values))
+			for key, val := range existing_values {
+				values[key] = val
+			}
+			for key, val := range new_values {
+				values[key] = val
+			}
+			break
+		}
+	}
+	new_tag := stackTagPool.Acquire()
+	m.values[new_tag] = values
+	m.mtx.Unlock()
+	defer func() {
+		m.mtx.Lock()
+		delete(m.values, new_tag)
+		m.mtx.Unlock()
+		stackTagPool.Release(new_tag)
+	}()
+
+	addStackTag(new_tag, context_call)
+}
+
+// GetValue will return a previously set value, provided that the value was set
+// by SetValues somewhere higher up the stack. If the value is not found, ok
+// will be false.
+func (m *ContextManager) GetValue(key interface{}) (value interface{}, ok bool) {
+
+	tags := readStackTags(1)
+	m.mtx.RLock()
+	defer m.mtx.RUnlock()
+	for _, tag := range tags {
+		if values, ok := m.values[tag]; ok {
+			value, ok := values[key]
+			return value, ok
+		}
+	}
+	return "", false
+}
+
+// GetAll gets all values.
+func (m *ContextManager) GetAll() map[interface{}]interface{} {
+	tags := readStackTags(1)
+	m.mtx.RLock()
+	defer m.mtx.RUnlock()
+	allValues := make(map[interface{}]interface{})
+	for _, tag := range tags {
+		if values, ok := m.values[tag]; ok {
+			for key, value := range values {
+				allValues[key] = value
+			}
+		}
+	}
+	return allValues
+}
+
+func (m *ContextManager) getValues() Values {
+	tags := readStackTags(2)
+	m.mtx.RLock()
+	defer m.mtx.RUnlock()
+	for _, tag := range tags {
+		if values, ok := m.values[tag]; ok {
+			return values
+		}
+	}
+	return nil
+}
+
+// Go preserves ContextManager values and Goroutine-local-storage across new
+// goroutine invocations. The Go method makes a copy of all existing values on
+// all registered context managers and makes sure they are still set after
+// kicking off the provided function in a new goroutine. If you don't use this
+// Go method instead of the standard 'go' keyword, you will lose values in
+// ContextManagers, as goroutines have brand new stacks.
+func Go(cb func()) {
+	mgrRegistryMtx.RLock()
+	defer mgrRegistryMtx.RUnlock()
+
+	for mgr, _ := range mgrRegistry {
+		values := mgr.getValues()
+		if len(values) > 0 {
+			mgr_copy := mgr
+			cb_copy := cb
+			cb = func() { mgr_copy.SetValues(values, cb_copy) }
+		}
+	}
+
+	go cb()
+}