github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-07-30 15:05:27 +00:00
Code Issues Projects Releases Wiki Activity

Add details to watch interface method comments

Browse Source 
The watch.Interface design is hard to change, because it would break
most client-go users that perform watches. So instead of changing the
interface to be more user friendly, this change updates the method
comments to explain the different responsibilities of the consumer
(client user) and the producer (interface implementer).
This commit is contained in:
Karl Isenberg 2024-06-12 13:06:22 -07:00
parent 9c8c61aee4
commit 1f35231a1d
2 changed files with 21 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
staging/src/k8s.io/apimachinery/pkg/watch/watch.go
View File

@ -27,13 +27,25 @@ import (
// Interface can be implemented by anything that knows how to watch and report changes.
type Interface interface {
// Stop stops watching. Will close the channel returned by ResultChan(). Releases
// any resources used by the watch.
// Stop tells the producer that the consumer is done watching, so the
// producer should stop sending events and close the result channel. The
// consumer should keep watching for events until the result channel is
// closed.
//
// Because some implementations may create channels when constructed, Stop
// must always be called, even if the consumer has not yet called
// ResultChan().
//
// Only the consumer should call Stop(), not the producer. If the producer
// errors and needs to stop the watch prematurely, it should instead send
// an error event and close the result channel.
Stop()
// ResultChan returns a chan which will receive all the events. If an error occurs
// or Stop() is called, the implementation will close this channel and
// release any resources used by the watch.
// ResultChan returns a channel which will receive events from the event
// producer. If an error occurs or Stop() is called, the producer must
// close this channel and release any resources used by the watch.
// Closing the result channel tells the consumer that no more events will be
// sent.
ResultChan() <-chan Event
}

4
staging/src/k8s.io/client-go/tools/cache/listwatch.go vendored
View File

@ -36,6 +36,10 @@ type Lister interface {
// Watcher is any object that knows how to start a watch on a resource.
type Watcher interface {
// Watch should begin a watch at the specified version.
//
// If Watch returns an error, it should handle its own cleanup, including
// but not limited to calling Stop() on the watch, if one was constructed.
// This allows the caller to ignore the watch, if the error is non-nil.
Watch(options metav1.ListOptions) (watch.Interface, error)
}