tikv: close region cache before PD client

[fzzf678]

Fixes #1852.

KVStore.Close() previously closed the PD client before closing RegionCache. RegionCache has background tasks (store list refresh / store re-resolve) that may still call PD APIs (GetStore/GetAllStores). When PD client is closed first, those background calls fail and emit noisy logs like:

• loadStore from PD failed: rpc error: code = Canceled desc = grpc: the client connection is closing

This PR reorders KVStore.Close() to close RegionCache (and other dependents) before closing the PD clients, avoiding the shutdown window error.

Summary by CodeRabbit

• Chores

  • Improved shutdown sequencing and resource cleanup so caches are closed before dependent clients, reducing shutdown races.

• Public API

  • Added a lightweight introspection method to report background-runner state (intended for tests/debugging).

• Tests

  • Added an automated test and runtime check to verify shutdown ordering and ensure the region cache is closed before client shutdown.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[ti-chi-bot]

Welcome @fzzf678!

It looks like this is your first PR to tikv/client-go 🎉.

I'm the bot to help you request reviewers, add labels and more, See available commands.

We want to make sure your contribution gets all the attention it needs!



Thank you, and welcome to tikv/client-go. 😃

[coderabbitai]

📝 Walkthrough

Walkthrough

Reorders KVStore shutdown: txn latches closed earlier, region cache closed before PD clients (with a failpoint-checked runtime panic if not), PD HTTP then PD gRPC clients closed, then TiKV clients. Adds RegionCache.IsBackgroundRunnerClosed and a test validating close ordering.

Changes

Cohort / File(s)	Summary
KVStore shutdown & test tikv/kv.go, tikv/kv_test.go	Reordered KVStore.Close() to close txn latches early, call regionCache.Close() before closing PD clients, close pdHttpClient then pdClient, then TiKV clients. Added failpoint check in Close and test TestKVStoreCloseCheckRegionCacheClosedBeforePDClose.
RegionCache helper internal/locate/region_cache.go	Added func (c *RegionCache) IsBackgroundRunnerClosed() bool to expose whether the RegionCache background runner has been canceled (for tests/debugging).

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant KV as KVStore
  participant TL as TxnLatches
  participant RC as RegionCache
  participant PHTTP as PD_HTTP_Client
  participant PGRPC as PD_gRPC_Client
  participant TK as TiKV_Client

  rect rgba(200,230,255,0.5)
    KV->>TL: Close() (if present)
    TL-->>KV: closed
  end

  rect rgba(200,255,200,0.5)
    KV->>RC: Close() (cancel background runner)
    RC-->>KV: background goroutines stopped
  end

  rect rgba(255,230,200,0.5)
    KV->>PHTTP: Close()
    PHTTP-->>KV: closed
    KV->>PGRPC: Close()
    PGRPC-->>KV: closed
  end

  rect rgba(240,200,255,0.5)
    KV->>TK: Close()
    TK-->>KV: closed
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through shutdown, neat and quick,
Latches first, then cache—no trick,
PD doors closed in proper line,
TiKV settles, quiet and fine,
A carrot nod to order, slick.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'tikv: close region cache before PD client' directly describes the main change—reordering shutdown sequence to close RegionCache before PD clients.
Linked Issues check	✅ Passed	The PR implements all requirements from #1852: reorders KVStore.Close() to close RegionCache before PD clients, adds runtime validation, and includes test coverage for the fix.
Out of Scope Changes check	✅ Passed	All changes directly address the linked issue: kv.go reorders shutdown sequence, region_cache.go adds debugging method, kv_test.go adds validation test. No unrelated changes present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[lcwangchao]

Could we panic here? seems easier to understand and the panic in failpoint does not affect the production code

[fzzf678]

Of course

[fzzf678]

update in 62192c0

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2026-01-26 08:07:35.120988485 +0000 UTC m=+999682.734945341: ☑️ agreed by lcwangchao.

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: lcwangchao
Once this PR has been reviewed and has the lgtm label, please assign iosmanthus for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[lcwangchao]

Please repair the DCO with git commit --amend -s