context

長時間かかる処理や外部通信を含む処理では、「ユーザがリクエストをキャンセルした」「処理がタイムアウトした」といった理由で途中で止めたい場面があります。そのまま書くと、以下のような「一度始めたら止められない」処理になります。

func fetchData() Result {
    // 数秒かかる処理
    return heavy()
}

呼び出し側が「もういらない」と思っても、fetchData の中から中断する術がなく、その分のリソースを浪費し続けてしまいます。goroutine が階層的に呼び出されている場合、キャンセルの指示を末端まで伝える手段を自前で用意するのは大変です。

Go はこの課題に対して、キャンセル・タイムアウトを goroutine の連鎖を跨いで伝える context パッケージを提供しています。多くのGoコードでは、関数の第1引数に ctx context.Context を渡すのがほぼ標準的な作法です。

1. タイムアウト付きの実行

context.WithTimeout は指定時間後に自動的にキャンセルされる context を返します。受け側は ctx.Done() を select で待ち受け、キャンセル時は ctx.Err() で理由を取り出します。書き方は以下のとおりです。

ctx, cancel := context.WithTimeout(context.Background(), 制限時間)
defer cancel()

select {
case <-通常の処理完了を示すchannel:
    // 正常終了
case <-ctx.Done():
    // ctx.Err() でキャンセルの理由を取り出せる
}

次のコードは、2秒かかる処理 longJob に対して 1 秒のタイムアウトを設定し、時間切れでキャンセルされる様子を確認する例です。

package main

import (
    "context"
    "fmt"
    "time"
)

func longJob(ctx context.Context) error {
    select {
    case <-time.After(2 * time.Second):
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
    defer cancel()

    if err := longJob(ctx); err != nil {
        fmt.Println("エラー:", err)
        return
    }
    fmt.Println("完了")
}

以下のような実行結果が表示されます。

エラー: context deadline exceeded

longJob は 2 秒かかる想定ですが、1 秒のタイムアウトが先に発火したため、context deadline exceeded エラーが返り、それが表示されました。

コードを解説します。

func longJob(ctx context.Context) error {
    select {
    case <-time.After(2 * time.Second):
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

select で「2秒後の完了」と「ctx.Done()(キャンセル通知)」の両方を待っています。どちらか先に発火したほうが処理されます。ctx.Done() が先に発火した場合は ctx.Err() でキャンセルの理由(context deadline exceeded など)を取り出して返します。

ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
defer cancel()

context.WithTimeout は指定時間後に自動的にキャンセルされる context を返します。第2戻り値の cancel は「明示的にキャンセルする関数」で、defer cancel() で必ず呼び出しておくとリソース解放のためにも安全です。

2. context の伝播

context は関数間で受け渡すことで、上位の処理から下位の処理まで一貫してキャンセル信号を伝えられます。HTTPサーバ、DBクライアント、外部API呼び出しは全て context.Context を第1引数で受ける設計になっているため、上位で作った ctx を下位に渡していけば、途中でどこかがキャンセル・タイムアウトしたときに末端まで一気に伝わります。

書き方は以下のとおりです。関数の第1引数で ctx context.Context を受け取り、内部で呼び出す別の関数にもそのまま渡していきます。

func 上位の関数(ctx context.Context) error {
    return 下位の関数(ctx)   // 受け取った ctx をそのまま渡す
}

次のコードは、main で作った1秒タイムアウトの ctx を callWorkflow → doWork と渡し、doWork の処理が2秒かかることでタイムアウトが末端まで伝播する例です。main.go を以下の内容に書き換えて保存し、go run main.go で実行します。

package main

import (
    "context"
    "fmt"
    "time"
)

func doWork(ctx context.Context) error {
    select {
    case <-time.After(2 * time.Second): // 2秒かかる処理を想定
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

func callWorkflow(ctx context.Context) error {
    return doWork(ctx)
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
    defer cancel()

    if err := callWorkflow(ctx); err != nil {
        fmt.Println("エラー:", err)
        return
    }
    fmt.Println("完了")
}

以下のような実行結果が表示されます。

エラー: context deadline exceeded

doWork は2秒かかる想定ですが、main が作った ctx の1秒タイムアウトが先に発火し、ctx.Done() の case が選ばれました。ctx.Err() から得た context deadline exceeded が callWorkflow を経由して main まで戻り、エラーとして表示されています。

コードを解説します。

func callWorkflow(ctx context.Context) error {
    return doWork(ctx)
}

callWorkflow は受け取った ctx を加工せずそのまま doWork に渡しています。中間層は自分でキャンセル判定を行わなくても、ctx を素通しさせるだけで下位に信号が届きます。

func doWork(ctx context.Context) error {
    select {
    case <-time.After(2 * time.Second):
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

末端の doWork で select を使って「通常の処理の完了」と「ctx からのキャンセル」の両方を待ち受けています。main が作った ctx の1秒タイムアウトが、関数呼び出しの連鎖を跨いでこの select まで届いていることが分かります。

上位で ctx の寿命を変えれば、callWorkflow や doWork の実装を変えずにタイムアウトの長さを調整できます。これが context を関数間で受け渡す最大のメリットです。