docs(bigtable): document implicit session.Client sharing behavior

[sushanb]

Documents the process-wide session.Client sharing behavior introduced in #20335 and benchmarked in #20336.

Changes

• `bigtable/CHANGES.md` — Unreleased-section entry noting the new sharing behavior and the incompatible-options guardrail.
• `bigtable/client.go` — `NewClient` godoc gains one paragraph on implicit sharing + opt-outs (distinct app profile, `DisableSession`).
• `bigtable/example_shared_session_test.go` — two Godoc examples:
  • `ExampleNewClient_multipleClientsShare` — happy path with two matching-identity `NewClient` calls.
  • `ExampleNewClientWithConfig_incompatibleOptions` — guardrail: mismatched options against the same identity return an error at construction.

Compile-only examples (no `// Output:` line) — matches the existing `ExampleCheckDirectAccessSupported` pattern.

Stacked on

• Base: feat(bigtable): share underlying session.Client across NewClient calls with matching identity #20335 (feat: implicit session.Client sharing across NewClient calls)
• Base: perf(bigtable): add benchmarks for implicit session.Client sharing #20336 (perf: benchmarks for implicit session.Client sharing)

This PR's diff currently includes both of the above; once they merge this PR will be rebased onto `main` and only the docs changes will remain.

[gemini-code-assist]

Code Review

This pull request introduces process-wide implicit sharing of the underlying session.Client across NewClient calls targeting the same project, instance, app profile, and endpoint, reducing connection costs to O(1). The review feedback highlights several critical areas for improvement: first, holding the global mutex while executing the build callback (which performs a gRPC dial) creates a significant performance bottleneck, which could be resolved using a coordination mechanism like singleflight; second, EnableDebug and other feature flags are missing from the sessionFingerprint, allowing mismatched configurations to be silently ignored; and third, the metricsProviderKind type switch should be updated to handle pointer types (e.g., *NoopMetricsProvider) to avoid preventing sharing when pointer and value types are mixed.

[gemini-code-assist]

Holding the global sharedSessionsMu mutex while calling the build() callback (which performs a gRPC dial) is a significant performance bottleneck and violates the general rule against calling external callbacks while holding internal locks. If one dial hangs or takes several seconds, all other concurrent NewClient calls across the entire process (even for completely different projects or instances) will be blocked.

Consider using a coordination mechanism like golang.org/x/sync/singleflight or a map of pending builds/channels to ensure that:

1. Callers targeting different keys can dial concurrently without blocking each other.
2. Concurrent callers targeting the same key still deduplicate to a single dial.

References

1. Avoid calling external callbacks while holding internal mutex locks to prevent potential deadlocks or lock inversion.
2. Avoid performing slow operations, such as gRPC channel creation, while holding an exclusive lock, as this can block other operations and slow down the entire client.

[gemini-code-assist]

The changelog and documentation state that mismatched EnableDebug or FeatureFlags will return an error at NewClient time. However, sessionFingerprint only contains metricsProviderKind, clientSideMetricsEnabled, and enableDirectAccess.

If EnableDebug or other feature flags are configured differently between two clients targeting the same identity, they will currently share the same session, and the second client's configuration will be silently ignored. Please add EnableDebug and any other relevant feature flags to sessionFingerprint to ensure they are compared and mismatched configurations are correctly rejected.

[gemini-code-assist]

The type switch in metricsProviderKind currently only checks for the value types DefaultMetricsProvider and NoopMetricsProvider. If a caller passes a pointer (e.g., &NoopMetricsProvider{}), it will fall into the default case and return "*bigtable.NoopMetricsProvider" instead of "noop". This prevents two otherwise identical clients from sharing a session if one passes a value and the other passes a pointer.

We should update the type switch to handle both value and pointer types.

Suggested change

	func metricsProviderKind(mp MetricsProvider) string {
	switch mp.(type) {
	case nil, DefaultMetricsProvider:
	return "default"
	case NoopMetricsProvider:
	return "noop"
	default:
	return fmt.Sprintf("%T", mp)
	}
	}
	func metricsProviderKind(mp MetricsProvider) string {
	switch mp.(type) {
	case nil, DefaultMetricsProvider, *DefaultMetricsProvider:
	return "default"
	case NoopMetricsProvider, *NoopMetricsProvider:
	return "noop"
	default:
	return fmt.Sprintf("%T", mp)
	}
	}