Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Flag ¶
type Flag interface {
// GetIndex should return unique index among all defined flags, starting
// from 0.
GetIndex() int
// GetName should return name of the flag.
GetName() string
// GetValue return the associated value. Can be empty.
GetValue() string
}
Flag is a (index+name):value pair.
type FlagSelector ¶
type FlagSelector struct {
// contains filtered or unexported fields
}
FlagSelector is used to select node with(out) given flags assigned.
Flag value=="" => any value
func WithFlags ¶
func WithFlags(flags ...Flag) FlagSelector
WithFlags creates flag selector selecting nodes that have all the listed flags assigned.
func WithoutFlags ¶
func WithoutFlags(flags ...Flag) FlagSelector
WithoutFlags creates flag selector selecting nodes that do not have any of the listed flags assigned.
type FlagStats ¶
type FlagStats struct {
TotalCount uint // number of revisions with the given flag assigned
PerValueCount map[string]uint // number of revisions with the given flag having the given value
}
FlagStats is a summary of the usage for a given flag.
type Graph ¶
type Graph interface {
// Read returns a graph handle for read-only access.
// The graph supports multiple concurrent readers.
// Release eventually using Release() method.
Read() ReadAccess // acquires R-lock
// Write returns a graph handle for read-write access.
// The graph supports at most one writer at a time - i.e. it is assumed
// there is no write-concurrency.
// If <inPlace> is enabled, the changes are applied with immediate effect,
// otherwise they are propagated to the graph using Save().
// In-place Write handle holds write lock, therefore reading is blocked until
// the handle is released.
// If <record> is true, the changes will be recorded once the handle is
// released.
// Release eventually using Release() method.
Write(inPlace, record bool) RWAccess
}
Graph is an in-memory graph representation of key-value pairs and their relations, where nodes are kv-pairs and each relation is a separate set of direct labeled edges.
The graph furthermore allows to associate metadata and flags (idx/name:value pairs) with every node. It is possible to register instances of NamedMapping, each for a different set of selected nodes, and the graph will keep them up-to-date with the latest value-label->metadata associations.
The graph provides various getter method, for example it is possible to select a set of nodes using a key selector and/or a flag selector. As for editing, Graph allows to either write in-place (immediate effect) or to prepare new changes and then save them later or let them get discarded by GC.
The graph supports multiple-readers single-writer access, i.e. it is assumed there is no write-concurrency.
Last but not least, the graph maintains a history of revisions for all nodes that have ever existed. The history of changes and a graph snapshot from a selected moment in time are exposed via ReadAccess interface.
func NewGraph ¶
NewGraph creates and new instance of key-value graph. <recordOldRevs> if enabled, will cause the graph to record the previous revisions of every node that have ever existed. <recordAgeLimit> is in minutes and allows to limit the maximum age of a record to keep, avoiding infinite memory usage growth. The initial phase of the execution is, however, of greater significance and <permanentInitPeriod> allows to keep records from that period permanently in memory.
type MethodTracker ¶
type MethodTracker func(method string) (onReturn func())
MethodTracker can be optionally supplied to track beginning and end of calls for (non-trivial) graph methods.
type Node ¶
type Node interface {
// GetKey returns the key associated with the node.
GetKey() string
// GetLabel returns the label associated with this node.
GetLabel() string
// GetKey returns the value associated with the node.
GetValue() proto.Message
// GetFlag returns reference to the given flag or nil if the node doesn't have
// this flag associated.
GetFlag(flagIndex int) Flag
// GetMetadata returns the value metadata associated with the node.
GetMetadata() interface{}
// GetTargets returns a set of nodes, indexed by relation labels, that the
// edges of the given relation points to.
GetTargets(relation string) RuntimeTargets
// IterTargets allows to iterate over the set of nodes that the edges of the given
// relation points to.
IterTargets(relation string, callback TargetIterator)
// GetSources returns edges pointing to this node in the reverse
// orientation.
GetSources(relation string) RuntimeTargets
}
Node is a read-only handle to a single graph node.
type NodeRW ¶
type NodeRW interface {
Node
// SetLabel associates given label with this node.
SetLabel(label string)
// SetValue associates given value with this node.
SetValue(value proto.Message)
// SetFlags associates given flag with this node.
SetFlags(flags ...Flag)
// DelFlags removes given flags from this node.
DelFlags(flagIndexes ...int)
// SetMetadataMap chooses metadata map to be used to store the association
// between this node's value label and metadata.
SetMetadataMap(mapName string)
// SetMetadata associates given value metadata with this node.
SetMetadata(metadata interface{})
// SetTargets updates definitions of all edges pointing from this node.
SetTargets(targets []RelationTargetDef)
}
NodeRW is a read-write handle to a single graph node.
type Opts ¶
type Opts struct {
RecordOldRevs bool
RecordAgeLimit uint32
PermanentInitPeriod uint32
MethodTracker MethodTracker
}
Opts groups input options for the graph constructor.
type RWAccess ¶
type RWAccess interface {
ReadAccess
// RegisterMetadataMap registers new metadata map for value-label->metadata
// associations of selected node.
RegisterMetadataMap(mapName string, mapping idxmap.NamedMappingRW)
// SetNode creates new node or returns read-write handle to an existing node.
// If in-place writing is disabled, the changes are propagated to the graph
// only after Save() is called.
SetNode(key string) NodeRW
// DeleteNode deletes node with the given key.
// Returns true if the node really existed before the operation.
DeleteNode(key string) bool
// Save propagates all changes to the graph.
// Use for **not-in-place** writing.
// NOOP if no changes performed, acquires RW-lock for the time of the operation
Save()
}
RWAccess lists operations provided by the read-write graph handle.
type ReadAccess ¶
type ReadAccess interface {
// GetMetadataMap returns registered metadata map.
GetMetadataMap(mapName string) idxmap.NamedMapping
// GetKeys returns sorted keys.
GetKeys() []string
// GetNode returns node with the given key or nil if the key is unused.
GetNode(key string) Node
// GetNodes returns a set of nodes matching the key selector (can be nil)
// and every provided flag selector.
GetNodes(keySelector KeySelector, flagSelectors ...FlagSelector) []Node
// GetFlagStats returns stats for a given flag.
GetFlagStats(flagIndex int, filter KeySelector) FlagStats
// GetNodeTimeline returns timeline of all node revisions, ordered from
// the oldest to the newest.
GetNodeTimeline(key string) []*RecordedNode
// GetSnapshot returns the snapshot of the graph at a given time.
GetSnapshot(time time.Time) []*RecordedNode
// Dump returns a human-readable string representation of the current graph
// content for debugging purposes.
Dump() string
// Release releases the graph handle (both Read() & Write() should end with
// release).
// For reader, the method releases R-lock.
// For in-place writer, the method releases W-lock.
Release()
// ValidateEdges checks if targets and sources of all nodes correspond with
// each other.
// Use only for UTs, debugging, etc.
ValidateEdges() error
}
ReadAccess lists operations provided by the read-only graph handle.
type RecordedFlags ¶
type RecordedFlags struct {
Flags [maxFlags]Flag
}
RecordedFlags is a record of assigned flags at a given time.
func (RecordedFlags) GetFlag ¶
func (rf RecordedFlags) GetFlag(flagIndex int) Flag
GetFlag returns reference to the given flag or nil if the node hasn't had this flag associated at the given time.
func (RecordedFlags) MarshalJSON ¶
func (rf RecordedFlags) MarshalJSON() ([]byte, error)
MarshalJSON marshalls recorded flags into JSON.
type RecordedNode ¶
type RecordedNode struct {
Since time.Time
Until time.Time
Key string
Label string
Value proto.Message
Flags RecordedFlags
MetadataFields map[string][]string // field name -> values
Targets Targets
TargetUpdateOnly bool // true if only runtime Targets have changed since the last rev
}
RecordedNode saves all attributes of a single node revision.
func (*RecordedNode) GetFlag ¶
func (node *RecordedNode) GetFlag(flagIndex int) Flag
GetFlag returns reference to the given flag or nil if the node didn't have this flag associated at the time when it was recorded.
type RelationTargetDef ¶
type RelationTargetDef struct {
// Relation name.
Relation string
// Label for the edge.
Label string // mandatory, unique for a given (source, relation)
// Key of the target node.
Key string
// Selector selecting a set of target nodes.
Selector TargetSelector
}
RelationTargetDef is a definition of a relation between a source node and a set of target nodes.
func (RelationTargetDef) Compare ¶
func (t RelationTargetDef) Compare(t2 RelationTargetDef) (equal bool, order int)
Compare compares two relation target definitions (with the exception of KeySelector-s).
func (RelationTargetDef) Singleton ¶
func (t RelationTargetDef) Singleton() bool
Singleton returns true if the target matches at most one key.
func (RelationTargetDef) WithKeySelector ¶
func (t RelationTargetDef) WithKeySelector() bool
WithKeySelector returns true if the target is defined with key selector.
type RuntimeTarget ¶
RuntimeTarget, unlike Target, contains direct runtime references pointing to instances of target nodes (suitable for runtime processing but not for recording).
type RuntimeTargets ¶
type RuntimeTargets []RuntimeTarget
RuntimeTargets is a slice of single-relation (runtime reference-based) targets, grouped by labels.
func (RuntimeTargets) GetTargetForLabel ¶
func (rt RuntimeTargets) GetTargetForLabel(label string) *RuntimeTarget
GetTargetForLabel returns target (single node or a set of nodes) for the given label. Linear complexity is OK, it is used only in UTs.
type Target ¶
type Target struct {
Relation string
Label string
ExpectedKey string // empty if Selector is used instead
MatchingKeys utils.KeySet
}
Target nodes - not referenced directly, instead via their keys (suitable for recording).
type TargetIterator ¶
TargetIterator is a callback applied on every target. For each label it will be called n+1 times, where n is the number of targets available for the given label and the extra call will be made with nil target.
type TargetSelector ¶
type TargetSelector struct {
// KeyPrefixes is a list of key prefixes, each selecting a subset of target
// nodes, which are then combined together - i.e. **union** is computed.
KeyPrefixes []string
// KeySelector allows to dynamically select target nodes.
KeySelector KeySelector
}
TargetSelector allows to dynamically select a set of target nodes. The selections of KeyPrefixes and KeySelector are **intersected**.
type Targets ¶
type Targets []Target
Targets is a slice of all targets of a single node, sorted by relation+label (in this order).
func (Targets) GetTargetForLabel ¶
GetTargetForLabel returns reference(+index) to target with the given relation+label.
func (Targets) RelationBegin ¶
RelationBegin returns index where targets for a given relation start in the array, or len(ts) if there are none.
Source Files