more docs wip

thorstink · Aug 28, 2023 · 0f565e6 · 0f565e6
1 parent 1b9c2ab
commit 0f565e6
Show file tree

Hide file tree

Showing 20 changed files with 473 additions and 270 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -1353,7 +1353,7 @@ HTML_EXTRA_FILES       =
 # The default value is: AUTO_LIGHT.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE        = AUTO_LIGHT
+HTML_COLORSTYLE        = LIGHT
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
 # will adjust the colors in the style sheet and background images according to
@@ -1653,7 +1653,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the
 # FULL_SIDEBAR option determines if the side bar is limited to only the treeview
@@ -2736,10 +2736,7 @@ GENERATE_LEGEND        = YES
 DOT_CLEANUP            = YES
 IMAGE_PATH += docs
 
-# USE_MDFILE_AS_MAINPAGE = README.md
-INPUT                  += README.md \
-                            docs/symmetri_nets.md \
-                            docs/symmetri_lib.md
-
-DISABLE_INDEX = NO
-GENERATE_TREEVIEW = YES
+USE_MDFILE_AS_MAINPAGE = docs/main.md
+INPUT                  +=   docs/symmetri_nets.md \
+                            docs/symmetri_lib.md \
+                            docs/main.md
diff --git a/docs/architecture.drawio b/docs/architecture.drawio
diff --git a/docs/img/architecture_dark.svg b/docs/img/architecture_dark.svg
diff --git a/docs/img/architecture_light.svg b/docs/img/architecture_light.svg
diff --git a/docs/main.md b/docs/main.md
@@ -0,0 +1,3 @@
+# Symmetri, Petri Nets in C++
+
+Welcome to the documentation for the Symmetri library.
diff --git a/docs/symmetri_lib.md b/docs/symmetri_lib.md
@@ -1,9 +1,47 @@
 # Symmetri library
 
-blabla
-
 ## Build
 
+### Vanilla CMake:
+
+Symmetri can be build as stand-alone CMake-project:
+
+```bash
+git clone --recurse-submodules https://github.com/thorstink/Symmetri.git
+mkdir build
+cd build
+cmake ..
+make
+```
+
+### In a Colcon-workspace
+It can also be build as part of a [colcon-workspace](https://colcon.readthedocs.io/en/released/user/what-is-a-workspace.html):
+
+```bash
+mkdir ws/src
+cd ws/src
+git clone --recurse-submodules https://github.com/thorstink/Symmetri.git
+cd .. # back to ws-directory
+colcon build
+```
+
 ## Test
 
+Symmetri has a set of tests. There are three build configurations:
+
+- No sanitizers
+- [ASAN](https://github.com/google/sanitizers/wiki/AddressSanitizer) + [UBSAN](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)
+- [TSAN](https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual)
+
+Each sanitizer can be enabled by setting either the 'ASAN_BUILD'- or 'TSAN_BUILD'-flag to true. They can not both be true at the same time.
+
+The sanitizers generally increase compiltation time quite significantly, hence they are off by default. In the CI-pipeline however they are turned on for testing.
+
+```bash
+# from the build directory...
+cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_EXAMPLES=ON -DBUILD_TESTING=ON -DASAN_BUILD=OFF -DTSAN_BUILD=OFF ..
+make
+make test
+```
+
 ## Architecture
diff --git a/docs/symmetri_nets.md b/docs/symmetri_nets.md
@@ -6,7 +6,7 @@ Transition T<sub>1</sub> is enabled             |  Conflict: either T<sub>1</sub
 :-------------------------:|:-------------------------:|:-------------------------:
 ![](img/simple.svg)  |  ![](img/conflict.svg)  |  ![](img/parallel.svg)
 
-There are many variations in Petri nets. In the most basic form there are transitions that produce tokens that are indistinguishable (e.g. if a place holds two tokens you can not distinguish one token from the other) and firing is atomic (meaning that tokens are consumed and produced instantaneous at the moment of firing). All transitions are also equal in the sense that if two transitions are active, meaning their input places have the required amount of tokens, simultaneously the order of firing is not determined. In a special case the transitions can be simultaneously active and share input places, this is called conflict. In Symmetri Petri Nets are used to encode the process- or business-logic of a (software) program. In many realistic applications the aforementioned properties are, subtly put, not ideal for modelling. In this text I will explain what kind of ‘Petri net modifications’ are applied to make Petri nets more applicable to the use-case of Symmetri: modelling business logic. I call the resulting cocktail of Petri net semantics Symmetri nets.
+There are many variations in Petri nets. In the most basic form there are transitions that produce tokens that are indistinguishable (e.g. if a place holds two tokens you can not distinguish one token from the other) and firing is atomic (meaning that tokens are consumed and produced instantaneous at the moment of firing). All transitions are also equal in the sense that if two transitions are simultaneously active, meaning their input places have the required amount of tokens, the order of firing is not determined. In a special case the transitions can be simultaneously active and share input places, this is called conflict. In Symmetri Petri Nets are used to encode the process- or business-logic of a (software) program. In many realistic applications the aforementioned properties are, subtly put, not ideal for modelling. In this text I will explain what kind of ‘Petri net modifications’ are applied to make Petri nets more applicable to the use-case of Symmetri: modelling business logic. I call the resulting cocktail of Petri net semantics Symmetri nets.
 
 ## Transitions as callbacks
 

diff --git a/symmetri/include/symmetri/callback.h b/symmetri/include/symmetri/callback.h
@@ -1,5 +1,7 @@
 #pragma once
 
+/** @file callback.h */
+
 #include <memory>
 
 #include "symmetri/types.h"

diff --git a/symmetri/include/symmetri/parsers.h b/symmetri/include/symmetri/parsers.h
@@ -1,4 +1,7 @@
 #pragma once
+
+/** @file parsers.h */
+
 #include <set>
 #include <tuple>
 

diff --git a/symmetri/include/symmetri/symmetri.h b/symmetri/include/symmetri/symmetri.h
@@ -1,5 +1,7 @@
 #pragma once
 
+/** @file symmetri.h */
+
 #include <set>
 #include <unordered_map>
 

diff --git a/symmetri/include/symmetri/tasks.h b/symmetri/include/symmetri/tasks.h
@@ -1,5 +1,7 @@
 #pragma once
 
+/** @file tasks.h */
+
 #include <atomic>
 #include <functional>
 #include <memory>

diff --git a/symmetri/include/symmetri/types.h b/symmetri/include/symmetri/types.h
@@ -1,4 +1,7 @@
 #pragma once
+
+/** @file types.h */
+
 #include <chrono>
 #include <string>
 #include <unordered_map>
@@ -23,7 +26,7 @@ enum class State {
   Started,    ///< The transition started
   Completed,  ///< The transition completed as expected
   Deadlock,   ///< The transition deadlocked
-  UserExit,   ///< The transition or interrupted and possibly stopped
+  UserExit,   ///< The transition is interrupted and possibly stopped
   Paused,     ///< The transition is paused
   Error       ///< None of the above
 };
@@ -37,8 +40,7 @@ struct Event {
   std::string case_id;      ///< The case_id of this event
   std::string transition;   ///< The transition that generated the event
   State state;              ///< The resulting state of the event
-  Clock::time_point stamp;  ///< The timestamp when the reducer of this
-                            ///< event was processed
+  Clock::time_point stamp;  ///< The timestamp of the event
 };
 
 using Eventlog = std::vector<Event>;  ///< The eventlog is simply a log of
@@ -49,9 +51,9 @@ using Result =
 using Net = std::unordered_map<
     Transition,
     std::pair<std::vector<Place>,
-              std::vector<Place>>>;  ///< This is the class multiset definition
+              std::vector<Place>>>;  ///< This is the multiset definition
                                      ///< of a Petri net. For each transition
-                                     ///< there is a pair of sets for input and
+                                     ///< there is a pair of lists for input and
                                      ///< output transitions
 using Marking =
     std::unordered_map<Place,

diff --git a/symmetri/include/symmetri/utilities.hpp b/symmetri/include/symmetri/utilities.hpp
@@ -1,4 +1,7 @@
 #pragma once
+
+/** @file utilities.hpp */
+
 #include <algorithm>
 
 #include "symmetri/types.h"

diff --git a/symmetri/model_utilities.cc b/symmetri/model_utilities.cc
@@ -14,11 +14,10 @@ bool canFire(const SmallVector &pre, const std::vector<size_t> &tokens) {
   });
 }
 
-gch::small_vector<uint8_t, 32> possibleTransitions(
+gch::small_vector<size_t, 32> possibleTransitions(
     const std::vector<size_t> &tokens,
-    const std::vector<SmallVector> &p_to_ts_n,
-    const std::vector<int8_t> &priorities) {
-  gch::small_vector<uint8_t, 32> possible_transition_list_n;
+    const std::vector<SmallVector> &p_to_ts_n) {
+  gch::small_vector<size_t, 32> possible_transition_list_n;
   for (const size_t place : tokens) {
     for (size_t t : p_to_ts_n[place]) {
       if (std::find(possible_transition_list_n.begin(),
@@ -29,16 +28,10 @@ gch::small_vector<uint8_t, 32> possibleTransitions(
     }
   }
 
-  // sort transition list according to priority
-  std::sort(possible_transition_list_n.begin(),
-            possible_transition_list_n.end(),
-            [&](size_t a, size_t b) { return priorities[a] > priorities[b]; });
-
   return possible_transition_list_n;
 }
 
-Reducer createReducerForTransition(size_t t_i, const Eventlog &ev,
-                                   State result) {
+Reducer createReducerForCallback(size_t t_i, const Eventlog &ev, State result) {
   return [=](Petri &model) {
     // if it is in the active transition set it means it is finished and we
     // should process it.
@@ -56,7 +49,7 @@ Reducer createReducerForTransition(size_t t_i, const Eventlog &ev,
   };
 }
 
-Reducer fireTransition(
+Reducer scheduleCallback(
     size_t t_i, const std::string &transition, const Callback &task,
     const std::string &case_id,
     const std::shared_ptr<moodycamel::BlockingConcurrentQueue<Reducer>>
@@ -67,9 +60,9 @@ Reducer fireTransition(
         {case_id, transition, State::Started, start_time});
   });
 
-  auto [ev, res] = fire(task);
+  auto [ev, res] = ::fire(task);
   ev.push_back({case_id, transition, res, Clock::now()});
-  return createReducerForTransition(t_i, ev, res);
+  return createReducerForCallback(t_i, ev, res);
 }
 
 }  // namespace symmetri