Package atree provides scalable arrays and scalable ordered maps. It is used by Cadence in the Flow blockchain.
Atree is maintained at https://github.com/onflow/atree
const ( CBORTagTypeInfoRef = 246 CBORTagInlinedArray = 250 CBORTagInlinedMap = 251 CBORTagInlinedCompactMap = 252 CBORTagInlineCollisionGroup = 253 CBORTagExternalCollisionGroup = 254 CBORTagSlabID = 255 )
MaxCollisionLimitPerDigest is the noncryptographic hash collision limit (per digest per map) we enforce in the first level. In the same map for the same digest, having a non-intentional collision should be rare and several collisions should be extremely rare. The default limit should be high enough to ignore accidental collisions while mitigating attacks.
CheckStorageHealth checks for the health of slab storage. It traverses the slabs and checks these factors: - All non-root slabs only has a single parent reference (no double referencing) - Every child of a parent shares the same ownership (childSlabID.Address == parentSlabID.Address) - The number of root slabs are equal to the expected number (skipped if expectedNumberOfRootSlabs is -1) This should be used for testing purposes only, as it might be slow to process
GetArrayStats returns stats about array slabs.
func IsCBORTagNumberRangeAvailable(minTagNum, maxTagNum uint64) (bool, error)
IsCBORTagNumberRangeAvailable returns true if the specified range is not reserved for internal use by atree. Applications must only use available (unreserved) CBOR tag numbers to encode elements in atree managed containers.
func MaxInlineArrayElementSize() uint64
func MaxInlineMapElementSize() uint64
func MaxInlineMapKeySize() uint64
func NewCollisionLimitError(collisionLimitPerDigest uint32) error
NewCollisionLimitError constructs a CollisionLimitError
NewDecodingError constructs a DecodingError
NewDecodingErrorf constructs a new DecodingError with error formating
func NewDuplicateKeyError(key any) error
NewEncodingError constructs a EncodingError
NewEncodingErrorf constructs a new EncodingError with error formating
NewHashError constructs a HashError
NewHashLevelError constructs a HashLevelError
func NewHashSeedUninitializedError() error
func NewIndexOutOfBoundsError(index, min, max uint64) error
NewIndexOutOfBoundsError constructs a IndexOutOfBoundsError
func NewInvalidSliceIndexError(startIndex, endIndex uint64) error
NewInvalidSliceIndexError constructs an InvalidSliceIndexError
NewKeyNotFoundError constructs a KeyNotFoundError
NewMapElementCountError constructs a MapElementCountError.
func NewNotApplicableError(typeName, interfaceName, methodName string) error
NewNotApplicableError constructs a NotImplementedError
NewNotImplementedError constructs a NotImplementedError
NewNotValueError constructs a NotValueError.
func NewReadOnlyIteratorElementMutationError(containerValueID, elementValueID ValueID) error
NewReadOnlyIteratorElementMutationError creates ReadOnlyIteratorElementMutationError.
NewSlabDataError constructs a SlabDataError
NewSlabDataErrorf constructs a new SlabError with error formating
NewSlabIDError constructs a fatal error of SlabIDError.
NewSlabIDErrorf constructs a fatal error of SlabIDError.
NewSlabMergeError constructs a SlabMergeError
NewSlabMergeErrorf constructs a new SlabMergeError with error formating
NewSlabNotFoundError constructs a SlabNotFoundError
NewSlabNotFoundErrorf constructs a new SlabNotFoundError with error formating
NewSlabRebalanceError constructs a SlabRebalanceError
NewSlabErrorf constructs a new SlabError with error formating
NewSlabSplitError constructs a SlabSplitError
NewSlabSplitErrorf constructs a new SlabSplitError with error formating
func NewSliceOutOfBoundsError(startIndex, endIndex, min, max uint64) error
NewSliceOutOfBoundsError constructs a SliceOutOfBoundsError.
func NewUnreachableError() error
func PrintArray(a *Array)
PrintArray prints array slab data to stdout.
func ReservedCBORTagNumberRange() (minTagNum, maxTagNum uint64)
ReservedCBORTagNumberRange returns minTagNum and maxTagNum of the range of CBOR tag numbers reserved for internal use by atree.
VerifyArraySerialization traverses array tree and verifies serialization by encoding, decoding, and re-encoding slabs. It compares in-memory objects of original slab with decoded slab. It also compares encoded data of original slab with encoded data of decoded slab.
VerifyMapSerialization traverses ordered map tree and verifies serialization by encoding, decoding, and re-encoding slabs. It compares in-memory objects of original slab with decoded slab. It also compares encoded data of original slab with encoded data of decoded slab.
WARNING: Any changes to SlabID or its components (Address and SlabIndex) require updates to ValueID definition and functions.
Array is a heterogeneous variable-size array, storing any type of values into a smaller ordered list of values and provides efficient functionality to lookup, insert and remove elements anywhere in the array.
Array elements can be stored in one or more relatively fixed-sized segments.
Array can be inlined into its parent container when the entire content fits in parent container's element size limit. Specifically, array with one segment which fits in size limit can be inlined, while arrays with multiple segments can't be inlined.
IterateReadOnly iterates readonly array elements. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. NOTE: Use readonly iterator if mutation is not needed for better performance. If callback is needed (e.g. for logging mutation, etc.), use IterateReadOnlyWithMutationCallback().
IterateReadOnlyLoadedValues iterates loaded array values.
IterateReadOnlyRange iterates readonly array elements from specified startIndex to endIndex. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. NOTE: Use readonly iterator if mutation is not needed for better performance. If callback is needed (e.g. for logging mutation, etc.), use IterateReadOnlyRangeWithMutatinoCallback().
IterateReadOnlyRangeWithMutationCallback iterates readonly array elements from specified startIndex to endIndex. valueMutationCallback is useful for logging, etc. with more context when mutation occurs. Mutation handling here is the same with or without this callback. If values are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. - valueMutatinCallback is called if provided NOTE: Use readonly iterator if mutation is not needed for better performance. If callback isn't needed, use IterateReadOnlyRange().
IterateReadOnlyWithMutationCallback iterates readonly array elements. valueMutationCallback is useful for logging, etc. with more context when mutation occurs. Mutation handling here is the same with or without this callback. If values are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. - valueMutatinCallback is called if provided NOTE: Use readonly iterator if mutation is not needed for better performance. If callback isn't needed, use IterateReadOnly().
Iterator returns mutable iterator for array elements. Mutable iterator handles: - indirect element mutation, such as modifying nested container - direct element mutation, such as overwriting existing element with new element Mutable iterator doesn't handle: - inserting new elements into the array - removing existing elements from the array NOTE: Use readonly iterator if mutation is not needed for better performance.
PopIterate iterates and removes elements backward. Each element is passed to ArrayPopIterationFunc callback before removal.
ReadOnlyIterator returns readonly iterator for array elements. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. NOTE: Use readonly iterator if mutation is not needed for better performance. If callback is needed (e.g. for logging mutation, etc.), use ReadOnlyIteratorWithMutationCallback().
ReadOnlyIteratorWithMutationCallback returns readonly iterator for array elements. valueMutationCallback is useful for logging, etc. with more context when mutation occurs. Mutation handling here is the same with or without callback. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. - valueMutationCallback is called if provided NOTE: Use readonly iterator if mutation is not needed for better performance. If callback isn't needed, use ReadOnlyIterator().
ReadOnlyLoadedValueIterator returns iterator to iterate loaded array elements.
ReadOnlyRangeIterator iterates readonly array elements from specified startIndex to endIndex. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. NOTE: Use readonly iterator if mutation is not needed for better performance. If callback is needed (e.g. for logging mutation, etc.), use ReadOnlyRangeIteratorWithMutationCallback().
ReadOnlyRangeIteratorWithMutationCallback iterates readonly array elements from specified startIndex to endIndex. valueMutationCallback is useful for logging, etc. with more context when mutation occurs. Mutation handling here is the same with or without callback. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. - valueMutationCallback is called if provided NOTE: Use readonly iterator if mutation is not needed for better performance. If callback isn't needed, use ReadOnlyRangeIterator().
Storable returns array a as either: - SlabIDStorable, or - inlined data slab storable
type ArrayDataSlab struct {
}
ArrayDataSlab is leaf node, implementing ArraySlab.
BorrowFromRight rebalances slabs by moving elements from right slab to left slab.
CanLendToLeft returns true if elements on the left of the slab could be removed so that the slab still stores more than the min threshold.
CanLendToRight returns true if elements on the right of the slab could be removed so that the slab still stores more than the min threshold.
Encode encodes this array data slab to the given encoder.
DataSlab Header:
+-------------------------------+----------------------+---------------------------------+-----------------------------+ | slab version + flag (2 bytes) | extra data (if root) | inlined extra data (if present) | next slab ID (if non-empty) | +-------------------------------+----------------------+---------------------------------+-----------------------------+
Content:
CBOR encoded array of elements
See ArrayExtraData.Encode() for extra data section format. See InlinedExtraData.Encode() for inlined extra data section format.
Inlinable returns true if - array data slab is root slab - size of inlined array data slab <= maxInlineSize
Inline converts not-inlined ArrayDataSlab to inlined ArrayDataSlab and removes it from storage.
IsUnderflow returns the number of bytes needed for the data slab to reach the min threshold. Returns true if the min threshold has not been reached yet.
LendToRight rebalances slabs by moving elements from left slab to right slab
Uninline converts an inlined ArrayDataSlab to uninlined ArrayDataSlab and stores it in storage.
type ArrayExtraData struct {
}
Encode encodes extra data as CBOR array:
[type info]
type ArrayIterator interface {
CanMutate() bool
Next() (Value, error)
}
type ArrayLoadedValueIterator struct {
}
ArrayLoadedValueIterator is used to iterate over loaded array elements.
Next iterates and returns next loaded element. It returns nil Value at end of loaded elements.
type ArrayMetaDataSlab struct {
}
ArrayMetaDataSlab is internal node, implementing ArraySlab.
Encode encodes this array meta-data slab to the given encoder.
Root MetaDataSlab Header:
+------------------------------+------------+--------------------------------+------------------------------+ | slab version + flag (2 byte) | extra data | child shared address (8 bytes) | child header count (2 bytes) | +------------------------------+------------+--------------------------------+------------------------------+
Non-root MetaDataSlab Header (12 bytes):
+------------------------------+--------------------------------+------------------------------+ | slab version + flag (2 byte) | child shared address (8 bytes) | child header count (2 bytes) | +------------------------------+--------------------------------+------------------------------+
Content (n * 14 bytes):
[[slab index (8 bytes), count (4 bytes), size (2 bytes)], ...]
See ArrayExtraData.Encode() for extra data section format.
Insert inserts v into the correct child slab. index must be >=0 and <= a.header.count. If index == a.header.count, Insert appends v to the end of underlying slab.
MergeOrRebalanceChildSlab merges or rebalances child slab. If merged, then parent slab's data is adjusted.
+-----------------------+-----------------------+----------------------+-----------------------+ | | no left sibling (sib) | left sib can't lend | left sib can lend | +=======================+=======================+======================+=======================+ | no right sib | panic | merge with left | rebalance with left | +-----------------------+-----------------------+----------------------+-----------------------+ | right sib can't lend | merge with right | merge with smaller | rebalance with left | +-----------------------+-----------------------+----------------------+-----------------------+ | right sib can lend | rebalance with right | rebalance with right | rebalance with bigger | +-----------------------+-----------------------+----------------------+-----------------------+
type ArrayPopIterationFunc func(Storable)
type ArraySlab interface {
Slab
Get(storage SlabStorage, index uint64) (Storable, error)
Set(storage SlabStorage, address Address, index uint64, value Value) (Storable, error)
Insert(storage SlabStorage, address Address, index uint64, value Value) error
Remove(storage SlabStorage, index uint64) (Storable, error)
IsData() bool
IsFull() bool
IsUnderflow() (uint32, bool)
CanLendToLeft(size uint32) bool
CanLendToRight(size uint32) bool
SetSlabID(SlabID)
PopIterate(SlabStorage, ArrayPopIterationFunc) error
Inlined() bool
Inlinable(maxInlineSize uint64) bool
Inline(SlabStorage) error
Uninline(SlabStorage) error
}
type ArraySlabHeader struct {
}
type BaseStorageUsageReporter interface {
BytesRetrieved() int
BytesStored() int
SegmentsReturned() int
SegmentsUpdated() int
SegmentsTouched() int
ResetReporter()
}
Encode returns serialized slabs in storage. This is currently used for testing.
type CollisionLimitError struct {
}
CollisionLimitError is a fatal error returned when a noncryptographic hash collision would exceed collision limit (per digest per map) we enforce in the first level.
ComparableStorable is an interface that supports comparison and cloning of Storable. This is only used for compact keys.
type ContainerStorable interface {
Storable
HasPointer() bool
}
ContainerStorable is an interface that supports Storable containing other storables.
type DecodingError struct {
}
DecodingError is a fatal error returned when a decoding operation fails
type DuplicateKeyError struct {
}
DuplicateKeyError is returned when the duplicate key is found in the dictionary when none is expected.
type Encoder struct {
io.Writer
CBOR *cbor.StreamEncoder
Scratch [64]byte
}
Encoder writes atree slabs to io.Writer.
type EncodingError struct {
}
EncodingError is a fatal error returned when a encoding operation fails
type ExternalError struct {
}
type ExtraData interface {
}
type FatalError struct {
}
type HashError struct {
}
HashError is a fatal error returned when hash calculation fails
type HashLevelError struct {
}
HashLevelError is a fatal error returned when hash level is wrong.
type HashSeedUninitializedError struct {
}
HashSeedUninitializedError is a fatal error returned when hash seed is uninitialized.
type IndexOutOfBoundsError struct {
}
IndexOutOfBoundsError is returned when get, insert or delete operation is attempted on an array index which is out of bounds
type InlinedExtraData struct {
}
Encode encodes inlined extra data as 2-element array:
+-----------------------+------------------------+ | [+ inlined type info] | [+ inlined extra data] | +-----------------------+------------------------+
type InvalidSliceIndexError struct {
}
InvalidSliceIndexError is returned when array slice index is invalid, such as startIndex > endIndex This error can be returned even when startIndex and endIndex are both within bounds.
type KeyNotFoundError struct {
}
KeyNotFoundError is returned when the key not found in the dictionary
type LedgerBaseStorage struct {
}
type MapDataSlab struct {
}
MapDataSlab is leaf node, implementing MapSlab. anySize is true for data slab that isn't restricted by size requirement.
CanLendToLeft returns true if elements on the left of the slab could be removed so that the slab still stores more than the min threshold.
CanLendToRight returns true if elements on the right of the slab could be removed so that the slab still stores more than the min threshold.
Encode encodes this map data slab to the given encoder.
Root DataSlab Header:
+-------------------------------+----------------------+---------------------------------+-----------------------------+ | slab version + flag (2 bytes) | extra data (if root) | inlined extra data (if present) | next slab ID (if non-empty) | +-------------------------------+----------------------+---------------------------------+-----------------------------+
Content:
CBOR encoded elements
See MapExtraData.Encode() for extra data section format. See InlinedExtraData.Encode() for inlined extra data section format. See hkeyElements.Encode() and singleElements.Encode() for elements section format.
Inlinable returns true if - map data slab is root slab - size of inlined map data slab <= maxInlineSize
inline converts not-inlined MapDataSlab to inlined MapDataSlab and removes it from storage.
IsUnderflow returns the number of bytes needed for the data slab to reach the min threshold. Returns true if the min threshold has not been reached yet.
func (m *MapDataSlab) Set( storage SlabStorage, b DigesterBuilder, digester Digester, level uint, hkey Digest, comparator ValueComparator, hip HashInputProvider, key Value, value Value, ) (MapKey, MapValue, error)
uninline converts an inlined MapDataSlab to uninlined MapDataSlab and stores it in storage.
type MapElementCountError struct {
}
MapElementCountError is a fatal error returned when element count is unexpected. It is an implementation error.
type MapExtraData struct {
}
Encode encodes extra data as CBOR array:
[type info, count, seed]
type MapLoadedValueIterator struct {
}
MapLoadedValueIterator is used to iterate loaded map elements.
Next iterates and returns next loaded element. It returns nil Value at end of loaded elements.
type MapMetaDataSlab struct {
}
MapMetaDataSlab is internal node, implementing MapSlab.
Encode encodes map meta-data slab to the given encoder.
Root MetaDataSlab Header:
+------------------------------+------------+--------------------------------+------------------------------+ | slab version + flag (2 byte) | extra data | child shared address (8 bytes) | child header count (2 bytes) | +------------------------------+------------+--------------------------------+------------------------------+
Non-root MetaDataSlab Header (12 bytes):
+------------------------------+--------------------------------+------------------------------+ | slab version + flag (2 byte) | child shared address (8 bytes) | child header count (2 bytes) | +------------------------------+--------------------------------+------------------------------+
Content (n * 18 bytes):
[ +[slab index (8 bytes), first key (8 bytes), size (2 bytes)]]
See MapExtraData.Encode() for extra data section format.
MergeOrRebalanceChildSlab merges or rebalances child slab. parent slab's data is adjusted. If merged, then parent slab's data is adjusted.
+-----------------------+-----------------------+----------------------+-----------------------+ | | no left sibling (sib) | left sib can't lend | left sib can lend | +=======================+=======================+======================+=======================+ | no right sib | panic | merge with left | rebalance with left | +-----------------------+-----------------------+----------------------+-----------------------+ | right sib can't lend | merge with right | merge with smaller | rebalance with left | +-----------------------+-----------------------+----------------------+-----------------------+ | right sib can lend | rebalance with right | rebalance with right | rebalance with bigger | +-----------------------+-----------------------+----------------------+-----------------------+
func (m *MapMetaDataSlab) Set( storage SlabStorage, b DigesterBuilder, digester Digester, level uint, hkey Digest, comparator ValueComparator, hip HashInputProvider, key Value, value Value, ) (MapKey, MapValue, error)
type MapSlab interface {
Slab
Get(
storage SlabStorage,
digester Digester,
level uint,
hkey Digest,
comparator ValueComparator,
key Value,
) (MapKey, MapValue, error)
Set(
storage SlabStorage,
b DigesterBuilder,
digester Digester,
level uint,
hkey Digest,
comparator ValueComparator,
hip HashInputProvider,
key Value,
value Value,
) (MapKey, MapValue, error)
Remove(
storage SlabStorage,
digester Digester,
level uint,
hkey Digest,
comparator ValueComparator,
key Value,
) (MapKey, MapValue, error)
IsData() bool
IsFull() bool
IsUnderflow() (uint32, bool)
CanLendToLeft(size uint32) bool
CanLendToRight(size uint32) bool
SetSlabID(SlabID)
PopIterate(SlabStorage, MapPopIterationFunc) error
Inlined() bool
Inlinable(maxInlineSize uint64) bool
Inline(SlabStorage) error
Uninline(SlabStorage) error
}
type MapSlabHeader struct {
}
GetMapStats returns stats about the map slabs.
type NotApplicableError struct {
}
NotApplicableError is a fatal error returned when a not applicable method is called
type NotImplementedError struct {
}
NotImplementedError is a fatal error returned when a method is called which is not yet implemented this is a temporary error
type NotValueError struct {
}
NotValueError is returned when we try to create Value objects from non-root slabs.
OrderedMap is an ordered map of key-value pairs; keys can be any hashable type and values can be any serializable value type. It supports heterogeneous key or value types (e.g. first key storing a boolean and second key storing a string). OrderedMap keeps values in specific sorted order and operations are deterministic so the state of the segments after a sequence of operations are always unique.
OrderedMap key-value pairs can be stored in one or more relatively fixed-sized segments.
OrderedMap can be inlined into its parent container when the entire content fits in parent container's element size limit. Specifically, OrderedMap with one segment which fits in size limit can be inlined, while OrderedMap with multiple segments can't be inlined.
func NewMapFromBatchData( storage SlabStorage, address Address, digesterBuilder DigesterBuilder, typeInfo TypeInfo, comparator ValueComparator, hip HashInputProvider, seed uint64, fn MapElementProvider, ) ( *OrderedMap, error, )
NewMapFromBatchData returns a new map with elements provided by fn callback. Provided seed must be the same seed used to create the original map. And callback function must return elements in the same order as the original map. New map uses and stores the same seed as the original map. This function should only be used for copying a map.
IterateReadOnly iterates readonly map elements. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. NOTE: Use readonly iterator if mutation is not needed for better performance. If callback is needed (e.g. for logging mutation, etc.), use IterateReadOnlyWithMutationCallback().
IterateReadOnlyKeys iterates readonly map keys. If keys are mutated: - those changes are not guaranteed to persist. - mutation functions of key containers return ReadOnlyIteratorElementMutationError. NOTE: Use readonly iterator if mutation is not needed for better performance. If callback is needed (e.g. for logging mutation, etc.), use IterateReadOnlyKeysWithMutationCallback().
IterateReadOnlyKeysWithMutationCallback iterates readonly map keys. keyMutatinCallback is useful for logging, etc. with more context when mutation occurs. Mutation handling here is the same with or without this callback. If keys are mutated: - those changes are not guaranteed to persist. - mutation functions of key containers return ReadOnlyIteratorElementMutationError. - keyMutatinCallback is called if provided NOTE: Use readonly iterator if mutation is not needed for better performance. If callback isn't needed, use IterateReadOnlyKeys().
IterateReadOnlyLoadedValues iterates loaded map values.
IterateReadOnlyValues iterates readonly map values. If values are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. NOTE: Use readonly iterator if mutation is not needed for better performance. If callback is needed (e.g. for logging mutation, etc.), use IterateReadOnlyValuesWithMutationCallback().
IterateReadOnlyValuesWithMutationCallback iterates readonly map values. valueMutationCallback is useful for logging, etc. with more context when mutation occurs. Mutation handling here is the same with or without this callback. If values are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. - keyMutatinCallback is called if provided NOTE: Use readonly iterator if mutation is not needed for better performance. If callback isn't needed, use IterateReadOnlyValues().
IterateReadOnlyWithMutationCallback iterates readonly map elements. keyMutatinCallback and valueMutationCallback are useful for logging, etc. with more context when mutation occurs. Mutation handling here is the same with or without these callbacks. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. - keyMutatinCallback/valueMutationCallback is called if provided NOTE: Use readonly iterator if mutation is not needed for better performance. If callback isn't needed, use IterateReadOnly().
Iterator returns mutable iterator for map elements. Mutable iterator handles: - indirect element mutation, such as modifying nested container - direct element mutation, such as overwriting existing element with new element Mutable iterator doesn't handle: - inserting new elements into the map - removing existing elements from the map NOTE: Use readonly iterator if mutation is not needed for better performance.
PopIterate iterates and removes elements backward. Each element is passed to MapPopIterationFunc callback before removal.
ReadOnlyIterator returns readonly iterator for map elements. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. NOTE: Use readonly iterator if mutation is not needed for better performance. If callback is needed (e.g. for logging mutation, etc.), use ReadOnlyIteratorWithMutationCallback().
ReadOnlyIteratorWithMutationCallback returns readonly iterator for map elements. keyMutatinCallback and valueMutationCallback are useful for logging, etc. with more context when mutation occurs. Mutation handling here is the same with or without these callbacks. If elements are mutated: - those changes are not guaranteed to persist. - mutation functions of child containers return ReadOnlyIteratorElementMutationError. - keyMutatinCallback and valueMutationCallback are called if provided NOTE: Use readonly iterator if mutation is not needed for better performance. If callback isn't needed, use ReadOnlyIterator().
ReadOnlyLoadedValueIterator returns iterator to iterate loaded map elements.
Storable returns OrderedMap m as either: - SlabIDStorable, or - inlined data slab storable
BatchPreload decodeds and caches slabs of given ids in parallel. This is useful for storage health or data validation in migration programs.
Warning Counts doesn't consider new segments in the deltas and only returns committed values
Deltas returns number of uncommitted slabs, including slabs with temp addresses.
DeltasSizeWithoutTempAddresses returns total size of uncommitted slabs (in bytes), excluding slabs with temp addresses.
DeltasWithoutTempAddresses returns number of uncommitted slabs, excluding slabs with temp addresses.
FixLoadedBrokenReferences traverses loaded slabs and fixes broken references in maps. A broken reference is a SlabID referencing a non-existent slab. To fix a map containing broken references, this function replaces broken map with empty map having the same SlabID and also removes all slabs in the old map. Limitations: - only fix broken references in map - only traverse loaded slabs in deltas and cache NOTE: The intended use case is to enable migration programs in onflow/flow-go to fix broken references. As of April 2024, only 10 registers in testnet (not mainnet) were found to have broken references and they seem to have resulted from a bug that was fixed 2 years ago by https://github.com/onflow/cadence/pull/1565.
GetAllChildReferences returns child references of given slab (all levels), including nested container and theirs child references.
HasUnsavedChanges returns true if there are any modified and unsaved slabs in storage with given address.
NondeterministicFastCommit commits changed slabs in nondeterministic order. Encoded slab data is deterministic (e.g. array and map iteration is deterministic). IMPORTANT: This function is used by migration programs when commit order of slabs is not required to be deterministic (while preserving deterministic array and map iteration).
type ReadOnlyArrayIteratorMutationCallback func(mutatedValue Value)
type ReadOnlyIteratorElementMutationError struct {
}
ReadOnlyIteratorElementMutationError is the error returned when readonly iterator element is mutated.
type ReadOnlyMapIteratorMutationCallback func(mutatedValue Value)
type SlabDataError struct {
}
SlabError is a always fatal error returned when something is wrong with the content or type of the slab you can make this a fatal error by calling Fatal()
SlabID identifies slab in storage. SlabID should only be used to retrieve, store, and remove slab in storage.
Address returns the address of SlabID.
type SlabIDError struct {
}
SlabIDError is returned when slab id can't be created or it's invalid.
Encode encodes SlabIDStorable as
cbor.Tag{
Number: cborTagSlabID,
Content: byte(v),
}
WARNING: Any changes to SlabID or its components (Address and SlabIndex) require updates to ValueID definition and functions.
Next returns new SlabIndex with index+1 value. The caller is responsible for preventing overflow by checking if the index value is valid before calling this function.
type SlabMergeError struct {
}
SlabMergeError is always a fatal error returned when merging two slabs fails
type SlabNotFoundError struct {
}
SlabNotFoundError is always a fatal error returned when an slab is not found
type SlabRebalanceError struct {
}
SlabRebalanceError is always a fatal error returned when rebalancing a slab has failed
type SlabSplitError struct {
}
SlabSplitError is always a fatal error returned when splitting an slab has failed
type SliceOutOfBoundsError struct {
}
SliceOutOfBoundsError is returned when index for array slice is out of bounds.
DecodeInlinedArrayStorable decodes inlined array data slab. Encoding is version 1 with CBOR tag having tag number CBORTagInlinedArray, and tag contant as 3-element array:
+------------------+----------------+----------+ | extra data index | value ID index | elements | +------------------+----------------+----------+
NOTE: This function doesn't decode tag number because tag number is decoded in the caller and decoder only contains tag content.
DecodeInlinedCompactMapStorable decodes inlined compact map data. Encoding is version 1 with CBOR tag having tag number CBORTagInlinedCompactMap, and tag contant as 3-element array:
- index of inlined extra data - value ID index - CBOR array of elements
NOTE: This function doesn't decode tag number because tag number is decoded in the caller and decoder only contains tag content.
DecodeInlinedMapStorable decodes inlined map data slab. Encoding is version 1 with CBOR tag having tag number CBORTagInlinedMap, and tag contant as 3-element array:
+------------------+----------------+----------+ | extra data index | value ID index | elements | +------------------+----------------+----------+
NOTE: This function doesn't decode tag number because tag number is decoded in the caller and decoder only contains tag content.
func DecodeSlabIDStorable(dec *cbor.StreamDecoder) (Storable, error)
type StorableSlab struct {
}
StorableSlab allows storing storables (CBOR encoded data) directly in a slab. Eventually we will only have a dictionary at the account storage root, so this won't be needed, but during the refactor we have the need to store other non-dictionary values (e.g. strings, integers, etc.) directly in accounts (i.e. directly in slabs aka registers)
type TypeInfo interface {
Encode(*cbor.StreamEncoder) error
IsComposite() bool
Copy() TypeInfo
}
type TypeInfoDecoder func( decoder *cbor.StreamDecoder, ) ( TypeInfo, error, )
type UnreachableError struct {
Stack []byte
}
UnreachableError is used by panic when unreachable code is reached. This is copied from Cadence.
type UserError struct {
}
ValueID identifies an Array or OrderedMap. ValueID is consistent independent of inlining status, while ValueID and SlabID are used differently despite having the same size and content under the hood. By contrast, SlabID is affected by inlining because it identifies a slab in storage. Given this, ValueID should be used for resource tracking, etc.
WrapperStorable is an interface that supports storable wrapping another storable.
WrapperValue is an interface that supports value wrapping another value.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4