type PreconditionFunc … type ConditionFunc … var ErrWatchClosed … // UntilWithoutRetry reads items from the watch until each provided condition succeeds, and then returns the last watch // encountered. The first condition that returns an error terminates the watch (and the event is also returned). // If no event has been received, the returned event will be nil. // Conditions are satisfied sequentially so as to provide a useful primitive for higher level composition. // Waits until context deadline or until context is canceled. // // Warning: Unless you have a very specific use case (probably a special Watcher) don't use this function!!! // Warning: This will fail e.g. on API timeouts and/or 'too old resource version' error. // Warning: You are most probably looking for a function *Until* or *UntilWithSync* below, // Warning: solving such issues. // TODO: Consider making this function private to prevent misuse when the other occurrences in our codebase are gone. func UntilWithoutRetry(ctx context.Context, watcher watch.Interface, conditions ...ConditionFunc) (*watch.Event, error) { … } // Until wraps the watcherClient's watch function with RetryWatcher making sure that watcher gets restarted in case of errors. // The initialResourceVersion will be given to watch method when first called. It shall not be "" or "0" // given the underlying WATCH call issues (#74022). // Remaining behaviour is identical to function UntilWithoutRetry. (See above.) // Until can deal with API timeouts and lost connections. // It guarantees you to see all events and in the order they happened. // Due to this guarantee there is no way it can deal with 'Resource version too old error'. It will fail in this case. // (See `UntilWithSync` if you'd prefer to recover from all the errors including RV too old by re-listing // those items. In normal code you should care about being level driven so you'd not care about not seeing all the edges.) // // The most frequent usage for Until would be a test where you want to verify exact order of events ("edges"). func Until(ctx context.Context, initialResourceVersion string, watcherClient cache.Watcher, conditions ...ConditionFunc) (*watch.Event, error) { … } // UntilWithSync creates an informer from lw, optionally checks precondition when the store is synced, // and watches the output until each provided condition succeeds, in a way that is identical // to function UntilWithoutRetry. (See above.) // UntilWithSync can deal with all errors like API timeout, lost connections and 'Resource version too old'. // It is the only function that can recover from 'Resource version too old', Until and UntilWithoutRetry will // just fail in that case. On the other hand it can't provide you with guarantees as strong as using simple // Watch method with Until. It can skip some intermediate events in case of watch function failing but it will // re-list to recover and you always get an event, if there has been a change, after recovery. // Also with the current implementation based on DeltaFIFO, order of the events you receive is guaranteed only for // particular object, not between more of them even it's the same resource. // The most frequent usage would be a command that needs to watch the "state of the world" and should't fail, like: // waiting for object reaching a state, "small" controllers, ... func UntilWithSync(ctx context.Context, lw cache.ListerWatcher, objType runtime.Object, precondition PreconditionFunc, conditions ...ConditionFunc) (*watch.Event, error) { … } // ContextWithOptionalTimeout wraps context.WithTimeout and handles infinite timeouts expressed as 0 duration. func ContextWithOptionalTimeout(parent context.Context, timeout time.Duration) (context.Context, context.CancelFunc) { … }
Codebase Browser
kubernetes