This enhancement adds the ability to stash transient information (i.e., not intended to be persisted) in the context object for a dance. It also introduces a new TransientCollection type.
Motivation
During processing of complex dances, there may arise the need to stash state information in a well-known location that is accessible to various functions without having to explicit pass these various bits of state in function parameters. For example, during L0 Schema Loading, there is a requirement to keep track of previously staged or committed descriptors so they can be added as targets for various relationships. We already have a HolonsContext structure being passed in many function signatures. Adding a dance_state:TransientCollection field to context addresses these requirements.
Dependencies
Issue #110
Current State
During schema loading, new schema components need to be related to other Schema components. This demands a way of discovering those other components without having to know or care whether the referenced component is still Staged or previously committed.
HolonReference's provide this encapsulation
HolonCollections contain a vector of HolonReferences and a keyed index that supports a _get_bykey function
Thus, HolonCollections already implement behaviors well-suited to the load schema requirements.
However, HolonCollections are only created as targets of staged or previously committed holon relationship maps -- not as standalone and temporary data structures. They are either staged for commit or retrieved from the persistent store from previously committed SmartLinks.
The goal is to leverage the desirable behaviors of HolonCollection without the entanglement of their being targeted for persistent storage.
Analysis of Design Options
_Should Transient just be a new state of HolonCollection or should we introduce a TransientCollection struct?_
My initial thought was to introduce a new state. This allows us to share the method implementations for _addreferences and _get_bykey. But this benefit comes at the cost of adding complexity, overhead, and greater error potential to HolonCollection. It also requires the struct definitions to be identical (i.e., representing collection members as HolonReference). If we also introduce transient holons then to allow transient collections to contain transient holons, we may be forced to create a new HolonReference variant (TransientReference). Then we have to go to special measures to account for difference between them and prevent each type of reference being used in the wrong context.
Recommendation: Leave the current design of HolonCollection unchanged, add a new TransientCollection datatype:
Proposal
Introduce TransientCollection
used when we have a transient (i.e., temporary) need for a collection of Holons, but not as part of a relationship and NOT with the intention to eventually persist the collection.
TransientCollections do not undergo state transitions, so they don't need a state field or a guard function
pub struct TransientCollection {
members: Vec<HolonReference>,
keyed_index: BTreeMap<MapString, usize>, // usize is an index into the members vector
}
NOTE: We may need to wrap HolonReference in a new TransientReference enum if transient holons are implemented and allowed as members of TransientCollection.
[x] Create new transient_collection.rs file
[x] Implement new method
[x] Implement add_references method (that updates vector and keyed_index)
[x] Implement get_by_key method
Introduce dance_state: TransientCollection
[x] Introduce a dance_state field within HolonsContext as a shared place to stash information during the course of a single dance. dance_state itself is not ping-ponged between client and guest, but it MAY serve as a source for a ResponseBody to be populated.
[x] Implement a add_references_to_dance_state method on context
[x] Implement a get_by_key_from_dance_state method on context
Testing
This functionality is not exposed externally and so is not amenable to sweetest or tryorama. But by using the dance_state as part of the load_core_schema dance we can indirectly test that the dance_state is behaving as expected.
Definition of Done
[ ] No regression. All test cases pass.
[ ] Load_core_schema dance uses dance_state to store and retrieve at least 3 references successfully.
This enhancement adds the ability to stash transient information (i.e., not intended to be persisted) in the
contextobject for a dance. It also introduces a newTransientCollectiontype.Motivation
During processing of complex dances, there may arise the need to stash state information in a well-known location that is accessible to various functions without having to explicit pass these various bits of state in function parameters. For example, during L0 Schema Loading, there is a requirement to keep track of previously staged or committed descriptors so they can be added as targets for various relationships. We already have a HolonsContext structure being passed in many function signatures. Adding a
dance_state:TransientCollectionfield to context addresses these requirements.Dependencies
Issue #110
Current State
The goal is to leverage the desirable behaviors of HolonCollection without the entanglement of their being targeted for persistent storage.
Analysis of Design Options
_Should
Transientjust be a new state of HolonCollection or should we introduce a TransientCollection struct?_My initial thought was to introduce a new state. This allows us to share the method implementations for _addreferences and _get_bykey. But this benefit comes at the cost of adding complexity, overhead, and greater error potential to HolonCollection. It also requires the struct definitions to be identical (i.e., representing collection members as HolonReference). If we also introduce transient holons then to allow transient collections to contain transient holons, we may be forced to create a new HolonReference variant (TransientReference). Then we have to go to special measures to account for difference between them and prevent each type of reference being used in the wrong context.
Recommendation: Leave the current design of HolonCollection unchanged, add a new TransientCollection datatype:
Proposal
Introduce
TransientCollectionNOTE: We may need to wrap HolonReference in a new TransientReference enum if transient holons are implemented and allowed as members of TransientCollection.
newmethodadd_referencesmethod (that updates vector and keyed_index)get_by_keymethodIntroduce
dance_state: TransientCollectiondance_statefield within HolonsContext as a shared place to stash information during the course of a single dance.dance_stateitself is not ping-ponged between client and guest, but it MAY serve as a source for a ResponseBody to be populated.Testing
This functionality is not exposed externally and so is not amenable to sweetest or tryorama. But by using the dance_state as part of the load_core_schema dance we can indirectly test that the dance_state is behaving as expected.
Definition of Done