From 3b3bf3ff2085ff06d914db51e8e12c047546cc63 Mon Sep 17 00:00:00 2001 From: Sargun Dhillon Date: Tue, 13 Aug 2019 10:19:08 -0700 Subject: [PATCH] Add documentation to the provider API about concurrency / mutability This adds documentation around what is allowed to be mutated and what may be accessed concurrently from the provider API. Previously, the API was ambigious, and that meant providers could return pods and change them. This resulted in data races occuring. --- node/podcontroller.go | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/node/podcontroller.go b/node/podcontroller.go index a923c5d7c..434df976d 100644 --- a/node/podcontroller.go +++ b/node/podcontroller.go @@ -55,12 +55,21 @@ type PodLifecycleHandler interface { DeletePod(ctx context.Context, pod *corev1.Pod) error // GetPod retrieves a pod by name from the provider (can be cached). + // The Pod returned is expected to be immutable, and may be accessed + // concurrently outside of the calling goroutine. Therefore it is recommended + // to return a version after DeepCopy. GetPod(ctx context.Context, namespace, name string) (*corev1.Pod, error) // GetPodStatus retrieves the status of a pod by name from the provider. + // The PodStatus returned is expected to be immutable, and may be accessed + // concurrently outside of the calling goroutine. Therefore it is recommended + // to return a version after DeepCopy. GetPodStatus(ctx context.Context, namespace, name string) (*corev1.PodStatus, error) // GetPods retrieves a list of all pods running on the provider (can be cached). + // The Pods returned are expected to be immutable, and may be accessed + // concurrently outside of the calling goroutine. Therefore it is recommended + // to return a version after DeepCopy. GetPods(context.Context) ([]*corev1.Pod, error) }