带小伙伴手写 golang context
前言 - context 源码
可以先了解官方 轮廓. 这里捎带保存一份当前 context 版本备份.
// copyright 2014 the go authors. all rights reserved.
// use of this source code is governed by a bsd-style
// license that can be found in the license file.
// package context defines the context type, which carries deadlines,
// cancellation signals, and other request-scoped values across api boundaries
// and between processes.
//
// incoming requests to a server should create a context, and outgoing
// calls to servers should accept a context. the chain of function
// calls between them must propagate the context, optionally replacing
// it with a derived context created using withcancel, withdeadline,
// withtimeout, or withvalue. when a context is canceled, all
// contexts derived from it are also canceled.
//
// the withcancel, withdeadline, and withtimeout functions take a
// context (the parent) and return a derived context (the child) and a
// cancelfunc. calling the cancelfunc cancels the child and its
// children, removes the parent's reference to the child, and stops
// any associated timers. failing to call the cancelfunc leaks the
// child and its children until the parent is canceled or the timer
// fires. the go vet tool checks that cancelfuncs are used on all
// control-flow paths.
//
// programs that use contexts should follow these rules to keep interfaces
// consistent across packages and enable static analysis tools to check context
// propagation:
//
// do not store contexts inside a struct type; instead, pass a context
// explicitly to each function that needs it. the context should be the first
// parameter, typically named ctx:
//
// func dosomething(ctx context.context, arg arg) error {
// // ... use ctx ...
// }
//
// do not pass a nil context, even if a function permits it. pass context.todo
// if you are unsure about which context to use.
//
// use context values only for request-scoped data that transits processes and
// apis, not for passing optional parameters to functions.
//
// the same context may be passed to functions running in different goroutines;
// contexts are safe for simultaneous use by multiple goroutines.
//
// see https://blog.golang.org/context for example code for a server that uses
// contexts.
package context
import (
"errors"
"internal/reflectlite"
"sync"
"time"
)
// a context carries a deadline, a cancellation signal, and other values across
// api boundaries.
//
// context's methods may be called by multiple goroutines simultaneously.
type context interface {
// deadline returns the time when work done on behalf of this context
// should be canceled. deadline returns ok==false when no deadline is
// set. successive calls to deadline return the same results.
deadline() (deadline time.time, ok bool)
// done returns a channel that's closed when work done on behalf of this
// context should be canceled. done may return nil if this context can
// never be canceled. successive calls to done return the same value.
//
// withcancel arranges for done to be closed when cancel is called;
// withdeadline arranges for done to be closed when the deadline
// expires; withtimeout arranges for done to be closed when the timeout
// elapses.
//
// done is provided for use in select statements:
//
// // stream generates values with dosomething and sends them to out
// // until dosomething returns an error or ctx.done is closed.
// func stream(ctx context.context, out chan<- value) error {
// for {
// v, err := dosomething(ctx)
// if err != nil {
// return err
// }
// select {
// case <-ctx.done():
// return ctx.err()
// case out <- v:
// }
// }
// }
//
// see https://blog.golang.org/pipelines for more examples of how to use
// a done channel for cancellation.
done() <-chan struct{}
// if done is not yet closed, err returns nil.
// if done is closed, err returns a non-nil error explaining why:
// canceled if the context was canceled
// or deadlineexceeded if the context's deadline passed.
// after err returns a non-nil error, successive calls to err return the same error.
err() error
// value returns the value associated with this context for key, or nil
// if no value is associated with key. successive calls to value with
// the same key returns the same result.
//
// use context values only for request-scoped data that transits
// processes and api boundaries, not for passing optional parameters to
// functions.
//
// a key identifies a specific value in a context. functions that wish
// to store values in context typically allocate a key in a global
// variable then use that key as the argument to context.withvalue and
// context.value. a key can be any type that supports equality;
// packages should define keys as an unexported type to avoid
// collisions.
//
// packages that define a context key should provide type-safe accessors
// for the values stored using that key:
//
// // package user defines a user type that's stored in contexts.
// package user
//
// import "context"
//
// // user is the type of value stored in the contexts.
// type user struct {...}
//
// // key is an unexported type for keys defined in this package.
// // this prevents collisions with keys defined in other packages.
// type key int
//
// // userkey is the key for user.user values in contexts. it is
// // unexported; clients use user.newcontext and user.fromcontext
// // instead of using this key directly.
// var userkey key
//
// // newcontext returns a new context that carries value u.
// func newcontext(ctx context.context, u *user) context.context {
// return context.withvalue(ctx, userkey, u)
// }
//
// // fromcontext returns the user value stored in ctx, if any.
// func fromcontext(ctx context.context) (*user, bool) {
// u, ok := ctx.value(userkey).(*user)
// return u, ok
// }
value(key interface{}) interface{}
}
// canceled is the error returned by context.err when the context is canceled.
var canceled = errors.new("context canceled")
// deadlineexceeded is the error returned by context.err when the context's
// deadline passes.
var deadlineexceeded error = deadlineexceedederror{}
type deadlineexceedederror struct{}
func (deadlineexceedederror) error() string { return "context deadline exceeded" }
func (deadlineexceedederror) timeout() bool { return true }
func (deadlineexceedederror) temporary() bool { return true }
// an emptyctx is never canceled, has no values, and has no deadline. it is not
// struct{}, since vars of this type must have distinct addresses.
type emptyctx int
func (*emptyctx) deadline() (deadline time.time, ok bool) {
return
}
func (*emptyctx) done() <-chan struct{} {
return nil
}
func (*emptyctx) err() error {
return nil
}
func (*emptyctx) value(key interface{}) interface{} {
return nil
}
func (e *emptyctx) string() string {
switch e {
case background:
return "context.background"
case todo:
return "context.todo"
}
return "unknown empty context"
}
var (
background = new(emptyctx)
todo = new(emptyctx)
)
// background returns a non-nil, empty context. it is never canceled, has no
// values, and has no deadline. it is typically used by the main function,
// initialization, and tests, and as the top-level context for incoming
// requests.
func background() context {
return background
}
// todo returns a non-nil, empty context. code should use context.todo when
// it's unclear which context to use or it is not yet available (because the
// surrounding function has not yet been extended to accept a context
// parameter).
func todo() context {
return todo
}
// a cancelfunc tells an operation to abandon its work.
// a cancelfunc does not wait for the work to stop.
// after the first call, subsequent calls to a cancelfunc do nothing.
type cancelfunc func()
// withcancel returns a copy of parent with a new done channel. the returned
// context's done channel is closed when the returned cancel function is called
// or when the parent context's done channel is closed, whichever happens first.
//
// canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this context complete.
func withcancel(parent context) (ctx context, cancel cancelfunc) {
c := newcancelctx(parent)
propagatecancel(parent, &c)
return &c, func() { c.cancel(true, canceled) }
}
// newcancelctx returns an initialized cancelctx.
func newcancelctx(parent context) cancelctx {
return cancelctx{context: parent}
}
// propagatecancel arranges for child to be canceled when parent is.
func propagatecancel(parent context, child canceler) {
if parent.done() == nil {
return // parent is never canceled
}
if p, ok := parentcancelctx(parent); ok {
p.mu.lock()
if p.err != nil {
// parent has already been canceled
child.cancel(false, p.err)
} else {
if p.children == nil {
p.children = make(map[canceler]struct{})
}
p.children[child] = struct{}{}
}
p.mu.unlock()
} else {
go func() {
select {
case <-parent.done():
child.cancel(false, parent.err())
case <-child.done():
}
}()
}
}
// parentcancelctx follows a chain of parent references until it finds a
// *cancelctx. this function understands how each of the concrete types in this
// package represents its parent.
func parentcancelctx(parent context) (*cancelctx, bool) {
for {
switch c := parent.(type) {
case *cancelctx:
return c, true
case *timerctx:
return &c.cancelctx, true
case *valuectx:
parent = c.context
default:
return nil, false
}
}
}
// removechild removes a context from its parent.
func removechild(parent context, child canceler) {
p, ok := parentcancelctx(parent)
if !ok {
return
}
p.mu.lock()
if p.children != nil {
delete(p.children, child)
}
p.mu.unlock()
}
// a canceler is a context type that can be canceled directly. the
// implementations are *cancelctx and *timerctx.
type canceler interface {
cancel(removefromparent bool, err error)
done() <-chan struct{}
}
// closedchan is a reusable closed channel.
var closedchan = make(chan struct{})
func init() {
close(closedchan)
}
// a cancelctx can be canceled. when canceled, it also cancels any children
// that implement canceler.
type cancelctx struct {
context
mu sync.mutex // protects following fields
done chan struct{} // created lazily, closed by first cancel call
children map[canceler]struct{} // set to nil by the first cancel call
err error // set to non-nil by the first cancel call
}
func (c *cancelctx) done() <-chan struct{} {
c.mu.lock()
if c.done == nil {
c.done = make(chan struct{})
}
d := c.done
c.mu.unlock()
return d
}
func (c *cancelctx) err() error {
c.mu.lock()
err := c.err
c.mu.unlock()
return err
}
type stringer interface {
string() string
}
func contextname(c context) string {
if s, ok := c.(stringer); ok {
return s.string()
}
return reflectlite.typeof(c).string()
}
func (c *cancelctx) string() string {
return contextname(c.context) + ".withcancel"
}
// cancel closes c.done, cancels each of c's children, and, if
// removefromparent is true, removes c from its parent's children.
func (c *cancelctx) cancel(removefromparent bool, err error) {
if err == nil {
panic("context: internal error: missing cancel error")
}
c.mu.lock()
if c.err != nil {
c.mu.unlock()
return // already canceled
}
c.err = err
if c.done == nil {
c.done = closedchan
} else {
close(c.done)
}
for child := range c.children {
// note: acquiring the child's lock while holding parent's lock.
child.cancel(false, err)
}
c.children = nil
c.mu.unlock()
if removefromparent {
removechild(c.context, c)
}
}
// withdeadline returns a copy of the parent context with the deadline adjusted
// to be no later than d. if the parent's deadline is already earlier than d,
// withdeadline(parent, d) is semantically equivalent to parent. the returned
// context's done channel is closed when the deadline expires, when the returned
// cancel function is called, or when the parent context's done channel is
// closed, whichever happens first.
//
// canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this context complete.
func withdeadline(parent context, d time.time) (context, cancelfunc) {
if cur, ok := parent.deadline(); ok && cur.before(d) {
// the current deadline is already sooner than the new one.
return withcancel(parent)
}
c := &timerctx{
cancelctx: newcancelctx(parent),
deadline: d,
}
propagatecancel(parent, c)
dur := time.until(d)
if dur <= 0 {
c.cancel(true, deadlineexceeded) // deadline has already passed
return c, func() { c.cancel(false, canceled) }
}
c.mu.lock()
defer c.mu.unlock()
if c.err == nil {
c.timer = time.afterfunc(dur, func() {
c.cancel(true, deadlineexceeded)
})
}
return c, func() { c.cancel(true, canceled) }
}
// a timerctx carries a timer and a deadline. it embeds a cancelctx to
// implement done and err. it implements cancel by stopping its timer then
// delegating to cancelctx.cancel.
type timerctx struct {
cancelctx
timer *time.timer // under cancelctx.mu.
deadline time.time
}
func (c *timerctx) deadline() (deadline time.time, ok bool) {
return c.deadline, true
}
func (c *timerctx) string() string {
return contextname(c.cancelctx.context) + ".withdeadline(" +
c.deadline.string() + " [" +
time.until(c.deadline).string() + "])"
}
func (c *timerctx) cancel(removefromparent bool, err error) {
c.cancelctx.cancel(false, err)
if removefromparent {
// remove this timerctx from its parent cancelctx's children.
removechild(c.cancelctx.context, c)
}
c.mu.lock()
if c.timer != nil {
c.timer.stop()
c.timer = nil
}
c.mu.unlock()
}
// withtimeout returns withdeadline(parent, time.now().add(timeout)).
//
// canceling this context releases resources associated with it, so code should
// call cancel as soon as the operations running in this context complete:
//
// func slowoperationwithtimeout(ctx context.context) (result, error) {
// ctx, cancel := context.withtimeout(ctx, 100*time.millisecond)
// defer cancel() // releases resources if slowoperation completes before timeout elapses
// return slowoperation(ctx)
// }
func withtimeout(parent context, timeout time.duration) (context, cancelfunc) {
return withdeadline(parent, time.now().add(timeout))
}
// withvalue returns a copy of parent in which the value associated with key is
// val.
//
// use context values only for request-scoped data that transits processes and
// apis, not for passing optional parameters to functions.
//
// the provided key must be comparable and should not be of type
// string or any other built-in type to avoid collisions between
// packages using context. users of withvalue should define their own
// types for keys. to avoid allocating when assigning to an
// interface{}, context keys often have concrete type
// struct{}. alternatively, exported context key variables' static
// type should be a pointer or interface.
func withvalue(parent context, key, val interface{}) context {
if key == nil {
panic("nil key")
}
if !reflectlite.typeof(key).comparable() {
panic("key is not comparable")
}
return &valuectx{parent, key, val}
}
// a valuectx carries a key-value pair. it implements value for that key and
// delegates all other calls to the embedded context.
type valuectx struct {
context
key, val interface{}
}
// stringify tries a bit to stringify v, without using fmt, since we don't
// want context depending on the unicode tables. this is only used by
// *valuectx.string().
func stringify(v interface{}) string {
switch s := v.(type) {
case stringer:
return s.string()
case string:
return s
}
return "<not stringer>"
}
func (c *valuectx) string() string {
return contextname(c.context) + ".withvalue(type " +
reflectlite.typeof(c.key).string() +
", val " + stringify(c.val) + ")"
}
func (c *valuectx) value(key interface{}) interface{} {
if c.key == key {
return c.val
}
return c.context.value(key)
}
golang 标准库 1.7 版本引入 context 包, 用于 golang 函数链安全的管理和控制.
说真 golang context 实现非常漂亮, 代码中说明也事无巨细, 整体很赏心悦目.
那我们带大家宏观过一遍 context 设计布局.
// context 上下文调用链条
type context interface {
// deadline 返回是否完成和结束时刻
deadline() (deadline time.time, ok bool)
// done 返回是否完成的阻塞 chan
done() (done <-chan struct{})
// err done 时候储存 error 信息, canceled or deadlineexceeded
err() (err error)
// value context 中获取 key 的值
value(key interface{}) (val interface{})
}
// emptyctx 永远不会被取消的 context
type emptyctx int
// cancelctx 可被取消的 context
type cancelctx struct { context ... }
// timerctx 带计时器和截止日期的 cancelctx
type timerctx struct { cancelctx ... }
// valuectx 储存键值对 context
type valuectx struct {
context
key, val interface{}
}
可以看出 context 是个 interface, context.go 中有四种结构实现了 context interface, 分别
是 emptyctx, cancelctx, timerctx, valuectx. 细看这类数据结构设计思路, 只记录父亲是谁,
单线联系. 可以反着类比普通树结构只记录儿子是谁哈哈, 大众货居然被玩出❀, 真强.
正文 - context 手写
废话不多说, 开始写代码. 上面 context.go 文件一把梭哈, 对于初学者还是无从学起的. 我们
这里按照结构分模式展开书写,
├── context │ ├── cancel.go │ ├── context.go │ ├── empty.go │ ├── timer.go │ ├── value.go │ └── with.go
让其看起来好理解些.
context.go
package context
import (
"errors"
"time"
)
// canceled 取消上下文时 context.err 返回的错误
var canceled = errors.new("context canceled")
// deadlineexceeded 上下文超时时候 context.err 返回的错误
var deadlineexceeded error = deadlineexceedederror{}
type deadlineexceedederror struct{}
func (deadlineexceedederror) error() string { return "context deadline exceeded" }
func (deadlineexceedederror) timeout() bool { return true }
func (deadlineexceedederror) temporary() bool { return true }
// context 上下文调用链条
type context interface {
// deadline 返回是否完成和结束时刻
deadline() (deadline time.time, ok bool)
// done 返回是否完成的阻塞 chan
done() (done <-chan struct{})
// err done 时候储存 error 信息, canceled or deadlineexceeded
err() (err error)
// value context 中获取 key 的值
value(key interface{}) (val interface{})
}
empty.go
package context
import "time"
// emptyctx 永远不会被取消的 context
type emptyctx int
func (*emptyctx) deadline() (deadline time.time, ok bool) { return }
func (*emptyctx) done() (done <-chan struct{}) { return }
func (*emptyctx) err() (err error) { return }
func (*emptyctx) value(key interface{}) (val interface{}) { return }
var (
background = new(emptyctx)
todo = new(emptyctx)
)
// string emptyctx 打印方法
func (e *emptyctx) string() string {
switch e {
case background:
return "context.background"
case todo:
return "context.todo"
}
return "unknown empty context"
}
// background 不会被取消的 context, 一般用做* context
func background() context {
return background
}
// todo 当你不知道用什么 context 时候, 记住那就用这个
func todo() context {
return todo
}
cancel.go
package context
import (
"reflect"
"sync"
)
type stringer interface {
string() string
}
func contextname(c context) string {
if s, ok := c.(stringer); ok {
return s.string()
}
return reflect.typeof(c).string()
}
// canceler 可以直接取消的上下文, 详情见 *cancelctx 和 *timerctx
type canceler interface {
cancel(removefromparent bool, err error)
done() (done <-chan struct{})
}
// cancelctx 可被取消的 context
type cancelctx struct {
context
mu sync.mutex // 互斥锁保证 goroutine 安全
done chan struct{} // 慢创建, 首次取消才会被调用的开关
children map[canceler]struct{} // 首次 context 取消后待取消的 child context
err error // 首次取消 context 保留的 error
}
func (c *cancelctx) done() (done <-chan struct{}) {
c.mu.lock()
if c.done == nil {
c.done = make(chan struct{})
}
done = c.done
c.mu.unlock()
return
}
func (c *cancelctx) err() (err error) {
c.mu.lock()
err = c.err
c.mu.unlock()
return
}
func (c *cancelctx) string() string {
return contextname(c) + ".withcancel"
}
// newcancelctx returns an initialized cancelctx
func newcancelctx(parent context) cancelctx {
return cancelctx{context: parent}
}
(这里用 "reflect" 标准包来表述 "internal/reflectlite" 内部才能使用的 "reflect" 包)
timer.go
package context
import (
"time"
)
// timerctx 带计时器和截止日期的 cancelctx
type timerctx struct {
cancelctx
timer *time.timer // 依赖 cancelctx.mu
deadline time.time // context 截止时间
}
func (c *timerctx) deadline() (time.time, bool) {
return c.deadline, true
}
func (c *timerctx) string() string {
return contextname(c.cancelctx.context) + ".withdeadline(" + c.deadline.string() + " [" + time.until(c.deadline).string() + "])"
}
value.go
package context
import "reflect"
// valuectx 储存键值对 context
type valuectx struct {
context
key, val interface{}
}
func (c *valuectx) value(key interface{}) interface{} {
if c.key == key {
return c.val
}
return c.context.value(key)
}
// stringify tries a bit to stringify v, without using fmt, since we don't
// want context depending on the unicode tables. this is only used by *valuectx.string()
func stringify(v interface{}) string {
switch s := v.(type) {
case stringer:
return s.string()
case string:
return s
}
return "<not stringer>"
}
func (c *valuectx) string() string {
return contextname(c.context) + ".withvalue(type " + reflect.typeof(c.key).string() + ", val " + stringify(c.val) + ")"
}
with.go
package context
import (
"reflect"
"time"
)
// withvalue returns a copy of parent in which the value associated with key is val
func withvalue(parent context, key, val interface{}) context {
if key == nil {
panic("nil key")
}
// key 不具备可比性时候, 会引发运行时恐慌 panic
if !reflect.typeof(key).comparable() {
panic("key is not comparable")
}
return &valuectx{parent, key, val}
}
// parentcancelctx 获取 parent cancelctx
func parentcancelctx(parent context) (*cancelctx, bool) {
for {
switch c := parent.(type) {
case *cancelctx:
return c, true
case *timerctx:
return &c.cancelctx, true
case *valuectx:
parent = c.context
default:
return nil, false
}
}
}
// removechild removes a context from its parent
func removechild(parent context, child canceler) {
p, ok := parentcancelctx(parent)
if !ok {
return
}
p.mu.lock()
if p.children != nil {
delete(p.children, child)
}
p.mu.unlock()
}
// closedchan 可重复使用且已经关闭通道
var closedchan = make(chan struct{})
func init() {
close(closedchan)
}
// cancel cancelctx 取消操作, 关闭 c.done, 取消每个 child context, removefromparent is true 从 parent 删除 child
func (c *cancelctx) cancel(removefromparent bool, err error) {
c.mu.lock()
if c.err != nil {
c.mu.unlock()
return // already canceled
}
c.err = err
if c.done == nil {
c.done = closedchan
} else {
close(c.done)
}
for child := range c.children {
// note: 保留 parent 锁, 继续获取 child 锁
child.cancel(false, err)
}
c.children = nil
c.mu.unlock()
if removefromparent {
removechild(c.context, c)
}
}
// cancel timerctx 取消操作
func (c *timerctx) cancel(removefromparent bool, err error) {
c.cancelctx.cancel(false, err)
if removefromparent {
// remove this timerctx from its parent cancelctx's children
removechild(c.cancelctx.context, c)
}
c.mu.lock()
if c.timer != nil {
c.timer.stop()
c.timer = nil
}
c.mu.unlock()
}
// propagatecancel parent 取消 map 中添加 child 子项
func propagatecancel(parent context, child canceler) {
if parent.done() == nil {
return // parent is never canceled
}
if p, ok := parentcancelctx(parent); ok {
p.mu.lock()
if p.err != nil {
// parent has already been canceled
child.cancel(false, p.err)
} else {
if p.children == nil {
p.children = make(map[canceler]struct{})
}
p.children[child] = struct{}{}
}
p.mu.unlock()
} else {
go func() {
select {
case <-parent.done():
child.cancel(false, parent.err())
case <-child.done():
}
}()
}
}
// cancelfunc cancel func 行为
type cancelfunc func()
// withcancel 基于 parent context 构造可取消的 child context
func withcancel(parent context) (ctx context, cancel cancelfunc) {
c := newcancelctx(parent)
propagatecancel(parent, &c)
return &c, func() { c.cancel(true, canceled) }
}
// withdeadline 返回 child context 并调整 parent deadline
func withdeadline(parent context, d time.time) (context, cancelfunc) {
if cur, ok := parent.deadline(); ok && cur.before(d) {
// 当前截止日期早于新设置的截止日期, 直接使用当前截止日期
return withcancel(parent)
}
c := &timerctx{
cancelctx: newcancelctx(parent),
deadline: d,
}
propagatecancel(parent, c)
dur := time.until(d)
if dur <= 0 {
c.cancel(true, deadlineexceeded) // deadline has already passed
return c, func() { c.cancel(false, canceled) }
}
c.mu.lock()
defer c.mu.unlock()
if c.err == nil {
c.timer = time.afterfunc(dur, func() {
c.cancel(true, deadlineexceeded)
})
}
return c, func() { c.cancel(true, canceled) }
}
// withtimeout returns withdeadline(parent, time.now().add(timeout))
func withtimeout(parent context, timeout time.duration) (context, cancelfunc) {
return withdeadline(parent, time.now().add(timeout))
}
看到 with.go 是不是有种 mmp 感觉, 第一问还好, 第二问也爽爽, 这第三问怎么就有了压轴最后一问思索感 ~
其实还好, 多关怀下 propagatecancel 和 cancelctx.cancel 操作怎么打配合. 其实上面源码中最难写的是
reflect 和 time (errors 和 sync 接触多好理解) 有兴趣的同行可以深入研究 . 水文该说再见了, 希望大家有
所得 ~
后记 - 代码和注释并存
错误是难免的, 欢迎勘误 ~ 共同成长提高 ❉
-