Skip to content

Commit

Permalink
Add more comments about how atree inlining works
Browse files Browse the repository at this point in the history
  • Loading branch information
@fxamacker
fxamacker committed Oct 1, 2023
1 parent 00a6df8 commit a75e388
Show file tree
Hide file tree
Showing 2 changed files with 66 additions and 14 deletions.
50 changes: 41 additions & 9 deletions array.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2709,8 +2709,8 @@ func (a *Array) setParentUpdater(f parentUpdater) {
a.parentUpdater = f
}

// setCallbackWithChild sets up callback function with child value so
// parent array a can be notified when child value is modified.
// setCallbackWithChild sets up callback function with child value (child)
// so parent array (a) can be notified when child value is modified.
func (a *Array) setCallbackWithChild(i uint64, child Value, maxInlineSize uint64) {
c, ok := child.(mutableValueNotifier)
if !ok {
Expand Down Expand Up @@ -2784,7 +2784,7 @@ func (a *Array) setCallbackWithChild(i uint64, child Value, maxInlineSize uint64
})
}

// notifyParentIfNeeded calls parent updater if this array is a child value.
// notifyParentIfNeeded calls parent updater if this array (a) is a child element in another container.
func (a *Array) notifyParentIfNeeded() error {
if a.parentUpdater == nil {
return nil
Expand All @@ -2805,8 +2805,8 @@ func (a *Array) Get(i uint64) (Value, error) {
return nil, wrapErrorfAsExternalErrorIfNeeded(err, "failed to get storable's stored value")
}

// Set up notification callback in child value so
// when child value is modified parent a is notified.
// As a parent, this array (a) sets up notification callback with child
// value (v) so this array can be notified when child value is modified.
a.setCallbackWithChild(i, v, maxInlineArrayElementSize)

return v, nil
Expand Down Expand Up @@ -2839,13 +2839,28 @@ func (a *Array) Set(index uint64, value Value) (Storable, error) {
}
}

// This array (a) is a parent to the new child (value), and this array
// can also be a child in another container.
//
// As a parent, this array needs to setup notification callback with
// the new child value, so it can be notified when child is modified.
//
// If this array is a child, it needs to notify its parent because its
// content (maybe also its size) is changed by this "Set" operation.

// If this array is a child, it notifies parent by invoking callback because
// this array is changed by setting new child.
err = a.notifyParentIfNeeded()
if err != nil {
return nil, err
}

// Set up notification callback in child value so
// when child value is modified parent a is notified.
// As a parent, this array sets up notification callback with child value
// so this array can be notified when child value is modified.
//
// Setting up notification with new child value can happen at any time
// (either before or after this array notifies its parent) because
// setting up notification doesn't trigger any read/write ops on parent or child.
a.setCallbackWithChild(index, value, maxInlineArrayElementSize)

return existingStorable, nil
Expand All @@ -2870,13 +2885,28 @@ func (a *Array) Insert(index uint64, value Value) error {

a.incrementIndexFrom(index)

// This array (a) is a parent to the new child (value), and this array
// can also be a child in another container.
//
// As a parent, this array needs to setup notification callback with
// the new child value, so it can be notified when child is modified.
//
// If this array is a child, it needs to notify its parent because its
// content (also its size) is changed by this "Insert" operation.

// If this array is a child, it notifies parent by invoking callback because
// this array is changed by inserting new child.
err = a.notifyParentIfNeeded()
if err != nil {
return err
}

// Set up notification callback in child value so
// when child value is modified parent a is notified.
// As a parent, this array sets up notification callback with child value
// so this array can be notified when child value is modified.
//
// Setting up notification with new child value can happen at any time
// (either before or after this array notifies its parent) because
// setting up notification doesn't trigger any read/write ops on parent or child.
a.setCallbackWithChild(index, value, maxInlineArrayElementSize)

return nil
Expand All @@ -2903,6 +2933,8 @@ func (a *Array) Remove(index uint64) (Storable, error) {

a.decrementIndexFrom(index)

// If this array is a child, it notifies parent by invoking callback because
// this array is changed by removing element.
err = a.notifyParentIfNeeded()
if err != nil {
return nil, err
Expand Down
30 changes: 25 additions & 5 deletions map.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4618,8 +4618,8 @@ func (m *OrderedMap) setParentUpdater(f parentUpdater) {
m.parentUpdater = f
}

// setCallbackWithChild sets up callback function with child value so
// parent map m can be notified when child value is modified.
// setCallbackWithChild sets up callback function with child value (child)
// so parent map (m) can be notified when child value is modified.
func (m *OrderedMap) setCallbackWithChild(
comparator ValueComparator,
hip HashInputProvider,
Expand Down Expand Up @@ -4689,7 +4689,8 @@ func (m *OrderedMap) setCallbackWithChild(
})
}

// notifyParentIfNeeded calls parent updater if this map is a child value.
// notifyParentIfNeeded calls parent updater if this map (m) is a child
// element in another container.
func (m *OrderedMap) notifyParentIfNeeded() error {
if m.parentUpdater == nil {
return nil
Expand Down Expand Up @@ -4724,8 +4725,9 @@ func (m *OrderedMap) Get(comparator ValueComparator, hip HashInputProvider, key
return nil, wrapErrorfAsExternalErrorIfNeeded(err, "failed to get storable's stored value")
}

// As a parent, this map (m) sets up notification callback with child
// value (v) so this map can be notified when child value is modified.
maxInlineSize := maxInlineMapValueSize(uint64(keyStorable.ByteSize()))

m.setCallbackWithChild(comparator, hip, key, v, maxInlineSize)

return v, nil
Expand Down Expand Up @@ -4800,13 +4802,29 @@ func (m *OrderedMap) Set(comparator ValueComparator, hip HashInputProvider, key
}
}

// This map (m) is a parent to the new child (value), and this map
// can also be a child in another container.
//
// As a parent, this map needs to setup notification callback with
// the new child value, so it can be notified when child is modified.
//
// If this map is a child, it needs to notify its parent because its
// content (maybe also its size) is changed by this "Set" operation.

// If this map is a child, it notifies parent by invoking callback because
// this map is changed by setting new child.
err = m.notifyParentIfNeeded()
if err != nil {
return nil, err
}

// As a parent, this map sets up notification callback with child value
// so this map can be notified when child value is modified.
//
// Setting up notification with new child value can happen at any time
// (either before or after this map notifies its parent) because
// setting up notification doesn't trigger any read/write ops on parent or child.
maxInlineSize := maxInlineMapValueSize(uint64(keyStorable.ByteSize()))

m.setCallbackWithChild(comparator, hip, key, value, maxInlineSize)

return existingValue, nil
Expand Down Expand Up @@ -4858,6 +4876,8 @@ func (m *OrderedMap) Remove(comparator ValueComparator, hip HashInputProvider, k
}
}

// If this map is a child, it notifies parent by invoking callback because
// this map is changed by removing element.
err = m.notifyParentIfNeeded()
if err != nil {
return nil, nil, err
Expand Down

0 comments on commit a75e388

Please sign in to comment.