context: add APIs for writing and reading cancelation cause

Extend the context package to allow users to specify why a context was
canceled in the form of an error, the "cause". Users write the cause
by calling WithCancelCause to construct a derived context, then
calling cancel(cause) to cancel the context with the provided cause.
Users retrieve the cause by calling context.Cause(ctx), which returns
the cause of the first cancelation for ctx or any of its parents.

The cause is implemented as a field of cancelCtx, since only cancelCtx
can be canceled. Calling cancel copies the cause to all derived (child)
cancelCtxs. Calling Cause(ctx) finds the nearest parent cancelCtx by
looking up the context value keyed by cancelCtxKey.

API changes:
+pkg context, func Cause(Context) error
+pkg context, func WithCancelCause(Context) (Context, CancelCauseFunc)
+pkg context, type CancelCauseFunc func(error)

Fixes #26356
Fixes #51365

Change-Id: I15b62bd454c014db3f4f1498b35204451509e641
Reviewed-on: https://go-review.googlesource.com/c/go/+/375977
Reviewed-by: Damien Neil <dneil@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Sameer Ajmani <sameer@golang.org>
Auto-Submit: Sameer Ajmani <sameer@golang.org>

1 files changed, 151 insertions, 2 deletions

diff --git a/src/context/context_test.go b/src/context/context_test.go
index 0991880907..593a7b1521 100644
--- a/src/context/context_test.go
+++ b/src/context/context_test.go
@@ -650,8 +650,9 @@ func XTestCancelRemoves(t testingT) {
 }
 
 func XTestWithCancelCanceledParent(t testingT) {
-	parent, pcancel := WithCancel(Background())
-	pcancel()
+	parent, pcancel := WithCancelCause(Background())
+	cause := fmt.Errorf("Because!")
+	pcancel(cause)
 
 	c, _ := WithCancel(parent)
 	select {
@@ -662,6 +663,9 @@ func XTestWithCancelCanceledParent(t testingT) {
 	if got, want := c.Err(), Canceled; got != want {
 		t.Errorf("child not canceled; got = %v, want = %v", got, want)
 	}
+	if got, want := Cause(c), cause; got != want {
+		t.Errorf("child has wrong cause; got = %v, want = %v", got, want)
+	}
 }
 
 func XTestWithValueChecksKey(t testingT) {
@@ -785,3 +789,148 @@ func XTestCustomContextGoroutines(t testingT) {
 	defer cancel7()
 	checkNoGoroutine()
 }
+
+func XTestCause(t testingT) {
+	var (
+		parentCause = fmt.Errorf("parentCause")
+		childCause  = fmt.Errorf("childCause")
+	)
+	for _, test := range []struct {
+		name  string
+		ctx   Context
+		err   error
+		cause error
+	}{
+		{
+			name:  "Background",
+			ctx:   Background(),
+			err:   nil,
+			cause: nil,
+		},
+		{
+			name:  "TODO",
+			ctx:   TODO(),
+			err:   nil,
+			cause: nil,
+		},
+		{
+			name: "WithCancel",
+			ctx: func() Context {
+				ctx, cancel := WithCancel(Background())
+				cancel()
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: Canceled,
+		},
+		{
+			name: "WithCancelCause",
+			ctx: func() Context {
+				ctx, cancel := WithCancelCause(Background())
+				cancel(parentCause)
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: parentCause,
+		},
+		{
+			name: "WithCancelCause nil",
+			ctx: func() Context {
+				ctx, cancel := WithCancelCause(Background())
+				cancel(nil)
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: Canceled,
+		},
+		{
+			name: "WithCancelCause: parent cause before child",
+			ctx: func() Context {
+				ctx, cancelParent := WithCancelCause(Background())
+				ctx, cancelChild := WithCancelCause(ctx)
+				cancelParent(parentCause)
+				cancelChild(childCause)
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: parentCause,
+		},
+		{
+			name: "WithCancelCause: parent cause after child",
+			ctx: func() Context {
+				ctx, cancelParent := WithCancelCause(Background())
+				ctx, cancelChild := WithCancelCause(ctx)
+				cancelChild(childCause)
+				cancelParent(parentCause)
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: childCause,
+		},
+		{
+			name: "WithCancelCause: parent cause before nil",
+			ctx: func() Context {
+				ctx, cancelParent := WithCancelCause(Background())
+				ctx, cancelChild := WithCancel(ctx)
+				cancelParent(parentCause)
+				cancelChild()
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: parentCause,
+		},
+		{
+			name: "WithCancelCause: parent cause after nil",
+			ctx: func() Context {
+				ctx, cancelParent := WithCancelCause(Background())
+				ctx, cancelChild := WithCancel(ctx)
+				cancelChild()
+				cancelParent(parentCause)
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: Canceled,
+		},
+		{
+			name: "WithCancelCause: child cause after nil",
+			ctx: func() Context {
+				ctx, cancelParent := WithCancel(Background())
+				ctx, cancelChild := WithCancelCause(ctx)
+				cancelParent()
+				cancelChild(childCause)
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: Canceled,
+		},
+		{
+			name: "WithCancelCause: child cause before nil",
+			ctx: func() Context {
+				ctx, cancelParent := WithCancel(Background())
+				ctx, cancelChild := WithCancelCause(ctx)
+				cancelChild(childCause)
+				cancelParent()
+				return ctx
+			}(),
+			err:   Canceled,
+			cause: childCause,
+		},
+		{
+			name: "WithTimeout",
+			ctx: func() Context {
+				ctx, cancel := WithTimeout(Background(), 0)
+				cancel()
+				return ctx
+			}(),
+			err:   DeadlineExceeded,
+			cause: DeadlineExceeded,
+		},
+	} {
+		if got, want := test.ctx.Err(), test.err; want != got {
+			t.Errorf("%s: ctx.Err() = %v want %v", test.name, got, want)
+		}
+		if got, want := Cause(test.ctx), test.cause; want != got {
+			t.Errorf("%s: Cause(ctx) = %v want %v", test.name, got, want)
+		}
+	}
+}