Documentation
¶
Index ¶
- type DataplaneSetView
- type DataplaneView
- func (c *DataplaneView[K, V]) Delete(k K)
- func (c *DataplaneView[K, V]) DeleteAll()
- func (c *DataplaneView[K, V]) Get(k K) (V, bool)
- func (c *DataplaneView[K, V]) Iter(f func(k K, v V))
- func (c *DataplaneView[K, V]) Len() int
- func (c *DataplaneView[K, V]) ReplaceAllIter(iter func(func(k K, v V)) error) error
- func (c *DataplaneView[K, V]) ReplaceAllMap(dpKVs map[K]V)
- func (c *DataplaneView[K, V]) Set(k K, v V)
- type DeltaTracker
- func (c *DeltaTracker[K, V]) Dataplane() *DataplaneView[K, V]
- func (c *DeltaTracker[K, V]) Desired() *DesiredView[K, V]
- func (c *DeltaTracker[K, V]) InSync() bool
- func (c *DeltaTracker[K, V]) PendingDeletions() *PendingDeletionsView[K, V]
- func (c *DeltaTracker[K, V]) PendingUpdates() *PendingUpdatesView[K, V]
- type DesiredSetView
- type DesiredView
- type IterAction
- type Option
- type PendingDeletionsSetView
- type PendingDeletionsView
- type PendingUpdatesSetView
- type PendingUpdatesView
- type SetDeltaTracker
- func (s *SetDeltaTracker[K]) Dataplane() *DataplaneSetView[K]
- func (s *SetDeltaTracker[K]) Desired() *DesiredSetView[K]
- func (s *SetDeltaTracker[K]) InSync() bool
- func (s *SetDeltaTracker[K]) PendingDeletions() *PendingDeletionsSetView[K]
- func (s *SetDeltaTracker[K]) PendingUpdates() *PendingUpdatesSetView[K]
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DataplaneSetView ¶
type DataplaneSetView[K comparable] DesiredView[K, struct{}]
func (*DataplaneSetView[K]) Add ¶
func (s *DataplaneSetView[K]) Add(k K)
func (*DataplaneSetView[K]) Contains ¶
func (s *DataplaneSetView[K]) Contains(k K) bool
func (*DataplaneSetView[K]) Delete ¶
func (s *DataplaneSetView[K]) Delete(k K)
func (*DataplaneSetView[K]) DeleteAll ¶
func (s *DataplaneSetView[K]) DeleteAll()
func (*DataplaneSetView[K]) Iter ¶
func (s *DataplaneSetView[K]) Iter(f func(k K))
func (*DataplaneSetView[K]) ReplaceFromIter ¶
func (s *DataplaneSetView[K]) ReplaceFromIter(iter func(func(k K)) error) error
type DataplaneView ¶
type DataplaneView[K comparable, V any] DeltaTracker[K, V]
func (*DataplaneView[K, V]) Delete ¶
func (c *DataplaneView[K, V]) Delete(k K)
Delete deletes a key from the dataplane cache. I.e. it tells this tracker that the key no longer exists in the dataplane.
func (*DataplaneView[K, V]) DeleteAll ¶
func (c *DataplaneView[K, V]) DeleteAll()
func (*DataplaneView[K, V]) Get ¶
func (c *DataplaneView[K, V]) Get(k K) (V, bool)
Get gets a single value from the cache of the dataplane. The cache must have previously been loaded with a successful call to LoadCacheFromDataplane() or one of the ApplyXXX methods.
func (*DataplaneView[K, V]) Iter ¶
func (c *DataplaneView[K, V]) Iter(f func(k K, v V))
Iter iterates over the cache of the dataplane.
func (*DataplaneView[K, V]) Len ¶
func (c *DataplaneView[K, V]) Len() int
func (*DataplaneView[K, V]) ReplaceAllIter ¶
func (c *DataplaneView[K, V]) ReplaceAllIter(iter func(func(k K, v V)) error) error
ReplaceAllIter clears the dataplane cache and replaces its contents with the KVs returned by the iterator. The pending update and deletion tracking is updated accordingly.
Only returns an error if the iterator returns an error. In case of error, the dataplane state is partially updated with the keys that have already been seen.
func (*DataplaneView[K, V]) ReplaceAllMap ¶
func (c *DataplaneView[K, V]) ReplaceAllMap(dpKVs map[K]V)
ReplaceAllMap replaces the state of the dataplane map with the KVs from dpKVs; the input map is not modified or retained. The pending update and deletion tracking is updated accordingly.
func (*DataplaneView[K, V]) Set ¶
func (c *DataplaneView[K, V]) Set(k K, v V)
Set updates a key in the dataplane cache. I.e. it tells this tracker that the dataplane has the given KV. Updated the pending update/deletion set if the new KV differs from what is desired.
type DeltaTracker ¶
type DeltaTracker[K comparable, V any] struct { // contains filtered or unexported fields }
DeltaTracker (conceptually) tracks the differences between two key/value maps the "desired" map contains the KV-pairs that we _want_ to be in the dataplane; the "dataplane" map contains the KV-pairs that we think are _actually_ in the dataplane. The name "dataplane" map is intended to hint at its use but(!) this is a pure in-memory datastructure; it doesn't actually interact with the dataplane directly.
The desired and dataplane maps are exposed via the Desired() and Dataplane() methods, which each return a similar map API featuring Set(...) Get(...) Delete() and Iter(...). The dataplane map view has an additional ReplaceAllIter method, which allows for the whole contents of the dataplane map to be replaced via an iterator; this is more efficient than doing an external iteration and Set/Delete calls.
In addition to the desired and dataplane maps, the differences between them are continuously tracked in two other maps: the "pending updates" map and the "pending deletions" map. "Pending updates" contains all keys that are in the "desired" map but not in the dataplane map (or that have a different value in the desired map vs the dataplane map). "Pending deletions" contains keys that are in the dataplane map but not in the desired map. The pending maps are exposed via the IterPendingUpdates and IterPendingDeletions methods.
Note: it is not safe to mutate keys/values that are stored in a DeltaTracker because it would corrupt the internal state. Surprisingly(!), it is also unsafe to delete a key, modify the value and then re-insert the value! This is because (as an occupancy optimisation) the DeltaTracker aliases the Desired and Dataplane values if they happen to be equal. So, to safely mutate a value, you must take a copy, mutate the copy and re-insert the copy.
Example (Resync) ¶
dt := New[string, int](WithValuesEqualFn[string, int](func(a, b int) bool {
return a == b // ints support simple comparison.
}))
// Set up our desired state.
desired := map[string]int{
"one": 1,
"two": 2,
}
for k, v := range desired {
dt.Desired().Set(k, v)
}
fmt.Printf("Desired state: %v\n", desired)
// Resync with the dataplane
mockDataplane := map[string]int{
"one": 1,
"three": 3,
}
fmt.Printf("Initial dataplane state: %v\n", mockDataplane)
_ = dt.Dataplane().ReplaceAllIter(func(f func(k string, v int)) error {
// Replace this with the actual dataplane loading logic.
for k, v := range mockDataplane {
f(k, v)
}
return nil
})
// Check the deltas.
dt.PendingUpdates().Iter(func(k string, v int) IterAction {
fmt.Printf("Applying pending update: %s = %v\n", k, v)
mockDataplane[k] = v
// Tell the tracker that we updated the dataplane.
return IterActionUpdateDataplane
})
dt.PendingDeletions().Iter(func(k string) IterAction {
fmt.Printf("Applying pending deletion: %v\n", k)
delete(mockDataplane, k)
// Tell the tracker that we updated the dataplane.
return IterActionUpdateDataplane
})
// Dataplane should now be in sync.
fmt.Printf("Updated dataplane state: %v\n", mockDataplane)
Output: Desired state: map[one:1 two:2] Initial dataplane state: map[one:1 three:3] Applying pending update: two = 2 Applying pending deletion: three Updated dataplane state: map[one:1 two:2]
func New ¶
func New[K comparable, V any](opts ...Option[K, V]) *DeltaTracker[K, V]
func (*DeltaTracker[K, V]) Dataplane ¶
func (c *DeltaTracker[K, V]) Dataplane() *DataplaneView[K, V]
func (*DeltaTracker[K, V]) Desired ¶
func (c *DeltaTracker[K, V]) Desired() *DesiredView[K, V]
func (*DeltaTracker[K, V]) InSync ¶
func (c *DeltaTracker[K, V]) InSync() bool
func (*DeltaTracker[K, V]) PendingDeletions ¶
func (c *DeltaTracker[K, V]) PendingDeletions() *PendingDeletionsView[K, V]
func (*DeltaTracker[K, V]) PendingUpdates ¶
func (c *DeltaTracker[K, V]) PendingUpdates() *PendingUpdatesView[K, V]
type DesiredSetView ¶
type DesiredSetView[K comparable] DesiredView[K, struct{}]
func (*DesiredSetView[K]) Add ¶
func (s *DesiredSetView[K]) Add(k K)
func (*DesiredSetView[K]) Contains ¶
func (s *DesiredSetView[K]) Contains(k K) bool
func (*DesiredSetView[K]) Delete ¶
func (s *DesiredSetView[K]) Delete(k K)
func (*DesiredSetView[K]) DeleteAll ¶
func (s *DesiredSetView[K]) DeleteAll()
func (*DesiredSetView[K]) Iter ¶
func (s *DesiredSetView[K]) Iter(f func(k K))
func (*DesiredSetView[K]) LenUpperBound ¶
func (s *DesiredSetView[K]) LenUpperBound() int
type DesiredView ¶
type DesiredView[K comparable, V any] DeltaTracker[K, V]
func (*DesiredView[K, V]) Delete ¶
func (c *DesiredView[K, V]) Delete(k K)
Delete deletes the given key from the desired state of the dataplane. If the KV is in the dataplane cache, it is added to the pending deletions set. Removes the key from the pending updates set.
func (*DesiredView[K, V]) DeleteAll ¶
func (c *DesiredView[K, V]) DeleteAll()
DeleteAll deletes all entries from the in-memory desired state, updating pending updates/deletions accordingly.
func (*DesiredView[K, V]) Get ¶
func (c *DesiredView[K, V]) Get(k K) (V, bool)
Get gets a single value from the desired map.
func (*DesiredView[K, V]) Iter ¶
func (c *DesiredView[K, V]) Iter(f func(k K, v V))
Iter iterates over the desired KVs.
func (*DesiredView[K, V]) Len ¶
func (c *DesiredView[K, V]) Len() int
func (*DesiredView[K, V]) Set ¶
func (c *DesiredView[K, V]) Set(k K, v V)
Set sets the desired state of the given key to the given value. If the value differs from what the dataplane cache records as being in the dataplane, the update is added to the pending updates set. Removes the key from the pending deletions set.
type IterAction ¶
type IterAction int
const ( IterActionNoOp IterAction = iota IterActionUpdateDataplane IterActionNoOpStopIteration )
type Option ¶
type Option[K comparable, V any] func(tracker *DeltaTracker[K, V])
func WithLogCtx ¶
func WithLogCtx[K comparable, V any](lc *logrus.Entry) Option[K, V]
func WithValuesEqualFn ¶
func WithValuesEqualFn[K comparable, V any](f func(a, b V) bool) Option[K, V]
type PendingDeletionsSetView ¶
type PendingDeletionsSetView[K comparable] PendingDeletionsView[K, struct{}]
func (*PendingDeletionsSetView[K]) Contains ¶
func (v *PendingDeletionsSetView[K]) Contains(k K) bool
func (*PendingDeletionsSetView[K]) Iter ¶
func (v *PendingDeletionsSetView[K]) Iter(f func(k K) IterAction)
Iter iterates over the pending deletion set. If the passed in function returns IterActionUpdateDataplane then the pending deletion is cleared, and, the KV is applied to the dataplane cache (as if the function had called Dataplane().Delete(k)).
func (*PendingDeletionsSetView[K]) Len ¶
func (v *PendingDeletionsSetView[K]) Len() int
type PendingDeletionsView ¶
type PendingDeletionsView[K comparable, V any] DeltaTracker[K, V]
func (*PendingDeletionsView[K, V]) Get ¶
func (c *PendingDeletionsView[K, V]) Get(k K) (V, bool)
func (*PendingDeletionsView[K, V]) Iter ¶
func (c *PendingDeletionsView[K, V]) Iter(f func(k K) IterAction)
Iter iterates over the pending deletion set. If the passed in function returns IterActionUpdateDataplane then the pending deletion is cleared, and, the KV is applied to the dataplane cache (as if the function had called Dataplane().Delete(k)).
func (*PendingDeletionsView[K, V]) Len ¶
func (c *PendingDeletionsView[K, V]) Len() int
type PendingUpdatesSetView ¶
type PendingUpdatesSetView[K comparable] PendingUpdatesView[K, struct{}]
func (*PendingUpdatesSetView[K]) Contains ¶
func (v *PendingUpdatesSetView[K]) Contains(k K) bool
func (*PendingUpdatesSetView[K]) Iter ¶
func (v *PendingUpdatesSetView[K]) Iter(f func(k K) IterAction)
Iter iterates over the pending updates. If the passed in function returns IterActionUpdateDataplane then the pending update is cleared, and, the KV is applied to the dataplane cache (as if the function had called Dataplane().Set(k, v)).
func (*PendingUpdatesSetView[K]) Len ¶
func (v *PendingUpdatesSetView[K]) Len() int
type PendingUpdatesView ¶
type PendingUpdatesView[K comparable, V any] DeltaTracker[K, V]
func (*PendingUpdatesView[K, V]) Get ¶
func (c *PendingUpdatesView[K, V]) Get(k K) (V, bool)
func (*PendingUpdatesView[K, V]) Iter ¶
func (c *PendingUpdatesView[K, V]) Iter(f func(k K, v V) IterAction)
Iter iterates over the pending updates. If the passed in function returns IterActionUpdateDataplane then the pending update is cleared, and, the KV is applied to the dataplane cache (as if the function had called Dataplane().Set(k, v)).
func (*PendingUpdatesView[K, V]) Len ¶
func (c *PendingUpdatesView[K, V]) Len() int
type SetDeltaTracker ¶
type SetDeltaTracker[K comparable] DeltaTracker[K, struct{}]
SetDeltaTracker (conceptually) tracks the differences between two sets the "desired" set contains the members that we _want_ to be in the dataplane; the "dataplane" set contains the members that we think are _actually_ in the dataplane. The name "dataplane" set is intended to hint at its use but(!) this is a pure in-memory datastructure; it doesn't actually interact with the dataplane directly.
The desired and dataplane sets are exposed via the Desired() and Dataplane() methods, which each return a similar set API featuring Set(...) Contains(...) Delete(...) and Iter(...). The dataplane set view has an additional ReplaceAllIter method, which allows for the whole contents of the dataplane set to be replaced via an iterator; this is more efficient than doing an external iteration and Set/Delete calls.
In addition to the desired and dataplane sets, the differences between them are continuously tracked in two other sets: the "pending updates" set and the "pending deletions" set. "Pending updates" contains all keys that are in the "desired" set but not in the dataplane set. "Pending deletions" contains keys that are in the dataplane set but not in the desired set. The pending sets are exposed via the IterPendingUpdates and IterPendingDeletions methods.
func NewSetDeltaTracker ¶
func NewSetDeltaTracker[K comparable]() *SetDeltaTracker[K]
func (*SetDeltaTracker[K]) Dataplane ¶
func (s *SetDeltaTracker[K]) Dataplane() *DataplaneSetView[K]
func (*SetDeltaTracker[K]) Desired ¶
func (s *SetDeltaTracker[K]) Desired() *DesiredSetView[K]
func (*SetDeltaTracker[K]) InSync ¶
func (s *SetDeltaTracker[K]) InSync() bool
func (*SetDeltaTracker[K]) PendingDeletions ¶
func (s *SetDeltaTracker[K]) PendingDeletions() *PendingDeletionsSetView[K]
func (*SetDeltaTracker[K]) PendingUpdates ¶
func (s *SetDeltaTracker[K]) PendingUpdates() *PendingUpdatesSetView[K]
Source Files