Add write buffer pooling

[ghost]

This PR proposes an API for write buffer pooling #9. If the API is
approved, I'll complete the implementation.

This proposed API has a typesafe API for the buffer pool and adds a
helper function to make it easy to use sync.Pool.

[elithrar]

Note that the buffers in this pool will grow over time: unless they are resized by the user, the pool will inevitably contain only the largest buffers used by your program, even if most of your buffers were small.

This can lead to growing memory usage between GC cycles, and increased GC pressure.

golang/go#23199 covers this well.

[garyburd]

The byte slices in this scenario all have the same capacity.

[garyburd]

The byte slices in this scenario all have the same capacity.

The pooled value should be opaque to the application. This opens the possibility of pooling other state with the byte slice and hides the fact that the connection adds the max header size to the application's requested buffer size.

[ghost]

I updated the PR with new proposed API and much of the implementation. The API adds a single bool to Upgrader and Dialer:

// UseWriteBufferPool specifies whether the connection should use a shared
// pool of write buffers or allocate a write buffer per connection.  A pool
// is useful for applications that have a large number of connections with
// a modest volume of writes.
//
// When UserWriteBufferPool is true, a small amount of memmory is
// permanatlly allocated for each unique value of WriteBufferSize.
UseWriteBufferPool bool

The package maintains a map of *sync.Pool keyed by buffer size. The map is currently a sync.Map, but I'll change to plain map with lock for compatibility with older versions of Go.

I got a little carried away when modifying newConnBRW for the feature. Let me know if you want me to dial (no pun intended!) some of that back to reduce the number of lines changed. I obviously think the code is better with the rework that I did.

I did not add tests for the feature yet. I'd like to get feedback on API and general approach before doing that work.

[garyburd]

The new API is easy to use, but it's not flexible as the BufferPool interface proposed earlier. The current PR does not allow the application to instrument buffer reuse or use something other than sync.Pool. Use this API:

type BufferPool interface {
     Get() interface{}
     Put(interface{})
}
...
type Upgrader struct {
   ...
   WriteBufferPool BufferPool
   ...
}

[ghost]

Updated per request.

A []byte is stored in the pool. You want the value to be opaque. Does it make sense to wrap the slice to keep applications from peeking at the value?

type writePoolValue struct {
     buf []byte
}

[garyburd]

The current test is good. Add another test that uses sync.Pool.

[garyburd]

Remove WIP from commit title

[garyburd]

This LGTM. I am curious if others have any feedback on the API.