BundleTracker RFC (#18)

* Summary and motivation for BundleTracker integration * BundleTracker Summary and Motivation first draft * BT API first draft * BundleTracker Requirements * BundleTracker API and teaching sections * Revise BundleTracker summary and motiviation * Revise BundleTracker class API * Add virtual customizer methods * BundleTracker Use unique pointer for constructor * BundleTracker use proper template args * BundleTracker fixes from CR * BundleTracker implementation without diagrams * BundleTracker add diagrams * BundleTracker RFC revisions * Add numbering to communication diagrams * BundleTracker revisions * BundleTracker Aspec style revisions * Add std::optional to API * RFC cleanup * Rename 0009-BundleTracker-integration.md to 0010-BundleTracker-integration.md Co-authored-by: shane-riley (The Mathworks Inc.) <sriley@mathworks.com> Co-authored-by: Jeff DiClemente <jeffdiclemente@users.noreply.github.com>
CppMicroServices · Aug 12, 2022 · e0a8a9d · e0a8a9d
1 parent 0a0204e
commit e0a8a9d
Show file tree

Hide file tree

Showing 15 changed files with 1,265 additions and 0 deletions.
diff --git a/text/0009-BundleTracker-integration/add_bundletracker.puml b/text/0009-BundleTracker-integration/add_bundletracker.puml
@@ -0,0 +1,20 @@
+@startuml addbundle_diagram
+
+rectangle "BundleEvent" as BE
+rectangle "BundleListener" as BL
+'rectangle "BundleTracker" as BT
+'rectangle "BundleTrackerPrivate" as BTP
+rectangle "TrackedBundle" as TB
+'rectangle "BundleContext" as BC
+rectangle "BundleAbstractTracked" as BAT
+rectangle "BundleTrackerCustomizer" as BTC
+
+BE -> BL : 1: Passed into listener
+BL -> TB : 2: BundleChanged()
+TB -> BAT : 3: Track()
+TB <- BAT : 4: CustomizerAdding()
+TB -d-> BTC : 5: AddingBundle()
+
+note bottom of BAT : Bundle not in map\nEntering state mask\nIncrement count
+
+@enduml
diff --git a/text/0009-BundleTracker-integration/addbundle_diagram.svg b/text/0009-BundleTracker-integration/addbundle_diagram.svg
diff --git a/text/0009-BundleTracker-integration/class_diagram.puml b/text/0009-BundleTracker-integration/class_diagram.puml
@@ -0,0 +1,95 @@
+@startuml class_diagram
+package cppmicroservices {
+
+    class "BundleListener" as BL
+    class "BundleContext" as BC
+
+    class "BundleTracker" as BT<T> {
+        - d : std::unique_ptr<BundleTrackerPrivate<TypeTraits>>
+        + Open() : void
+        + Close() : void
+        + GetBundles() : std::vector<Bundle>
+        + GetObject(const Bundle&) : std::optional<TrackedParamType>
+        + GetTracked() : std::unordered_map<Bundle, T>
+        + GetTrackingCount() : int
+        + IsEmpty() : bool
+        + Remove(const Bundle&) : bool
+        + Size() : size_t
+        + AddingBundle(const Bundle&, const BundleEvent&): std::optional<TrackedParamType>
+        + ModifiedBundle(const Bundle&, const BundleEvent&, TrackedParamType): void
+        + RemovedBundle(const Bundle&, const BundleEvent&, TrackedParamType): void
+    }
+    interface "BundleTrackerCustomizer" as BTC<T> {
+        + AddingBundle(const Bundle&, const BundleEvent&) : std::optional<TrackedParamType> 
+        + ModifiedBundle(const Bundle&, const BundleEvent&, TrackedParamType) : void
+        + RemovedBundle(const Bundle&, const BundleEvent&, TrackedParamType) : void
+    }
+
+    package detail {
+        class "BundleTrackerPrivate" as BTP<TTT> {
+            + context : BundleContext
+            + customizer : std::shared_ptr<BundleTrackerCustomizer<TrackedType>>
+            + listenerToken : ListenerToken
+            + trackedBundle : Atomic<std::shared_ptr<TrackedBundle<TTT>>>
+            + Tracked() : std::shared_pointer<TrackedBundle<TTT>>
+            + GetInitialBundles(uint32_t stateMask) : std::vector<Bundle>
+            + GetBundles_unlocked(std::vector<Bundle>&, TrackedBundle<TTT>* t) const : void
+            - q_func() : BundleTracker<T>*
+            - q_func() const : const BundleTracker<T>*
+            - q_ptr : BundleTracker<T>*
+        }
+        interface "TrackedBundleListener" as TBL {
+            + BundleChanged(const BundleEvent&) : void
+        }
+        class "TrackedBundle" as TB<TTT> {
+            - latch : CounterLatch
+            - bundleTracker : BundleTracker<T>*
+            - customizer : BundleTrackerCustomizer<T>*
+
+            - BundleChanged(const BundleEvent&) : void
+            - Modified() : void
+            - CustomizerAdding(const Bundle&, const BundleEvent&) : std::optional<TrackedParamType>
+            - CustomzierModified(const Bundle&, const BundleEvent&, TrackedParamType) : void
+            - CustomzierRemoved(const Bundle&, const BundleEvent&, TrackedParamType) : void
+
+        }
+        class "TrackedService" as TS
+        class "BundleAbstractTracked" as BAT <S, TTT, R> {
+            + SetInitial(const std::vector~<S>&) : void
+            + TrackInitial() : void
+            + Close() : void
+            + Track(S, R) : void
+            + Untrack(S, R) : void
+            + Size_unlocked() : std::size_t
+            + IsEmpty_unlocked() : bool
+            + GetCustomizedObject_unlocked(S) : std::optional<TrackedParamType>
+            + GetTracked_unlocked(std::vector~<S>&) : void
+            + Modified() : void
+            + GetTrackingCount() : int
+            + CopyEntries_unlocked(TrackingMap&) : void
+            + CustomizerAdding(S, R&) : std::optional<TrackedParamType>
+            + CustomzierModified(S, R&, TrackedParamType&) : void
+            + CustomzierRemoved(S, R&, TrackedParamType&) : void
+            + TrackAdding(S, R) : void
+            + initial : std::list~<S>
+            + adding : std::list~<S>
+            + closed : std::atmoic<bool>
+            - tracked : std::unordered_map<S, TrackedParamType>
+            - trackingCount : std::atomic<int>
+            - bc : BundleContext
+            - CustomizerAddingFinal(S, const std::shared_ptr<TrackedParamType>&) : bool
+        }
+    }
+    BTC <|-- BT
+    BT *-- BTP
+    BTP o-- BT
+    BAT <|-- TB
+    TBL <|-- TB
+    TB *-- BTP
+    BTP o-- BC
+    BTP o-- BL
+    BTP o-- BTC
+    BAT <|-- TS
+
+}
+@enduml