From b42fbe35a9e8eb35d000cf3ae31f6ad4f40cd2e6 Mon Sep 17 00:00:00 2001 From: Pieter Noordhuis Date: Wed, 13 Nov 2024 13:40:41 +0100 Subject: [PATCH] Comments --- libs/dbr/context.go | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/libs/dbr/context.go b/libs/dbr/context.go index 1901fb601..7512c0fe2 100644 --- a/libs/dbr/context.go +++ b/libs/dbr/context.go @@ -2,7 +2,10 @@ package dbr import "context" -// key is a private type to prevent collisions with other packages. +// key is a package-local type to use for context keys. +// +// Using an unexported type for context keys prevents key collisions across +// packages since external packages cannot create values of this type. type key int const ( @@ -14,7 +17,7 @@ const ( // DetectRuntime detects whether or not the current // process is running inside a Databricks Runtime environment. -// It return a new context with the detection result cached. +// It return a new context with the detection result set. func DetectRuntime(ctx context.Context) context.Context { if v := ctx.Value(dbrKey); v != nil { panic("dbr.DetectRuntime called twice on the same context") @@ -23,7 +26,7 @@ func DetectRuntime(ctx context.Context) context.Context { } // MockRuntime is a helper function to mock the detection result. -// It returns a new context with the detection result cached. +// It returns a new context with the detection result set. func MockRuntime(ctx context.Context, b bool) context.Context { if v := ctx.Value(dbrKey); v != nil { panic("dbr.MockRuntime called twice on the same context") @@ -31,8 +34,12 @@ func MockRuntime(ctx context.Context, b bool) context.Context { return context.WithValue(ctx, dbrKey, b) } -// RunsOnRuntime returns the cached detection result from the context. +// RunsOnRuntime returns the detection result from the context. // It expects a context returned by [DetectRuntime] or [MockRuntime]. +// +// We store this value in a context to avoid having to use either +// a global variable, passing a boolean around everywhere, or +// performing the same detection multiple times. func RunsOnRuntime(ctx context.Context) bool { v := ctx.Value(dbrKey) if v == nil {