more process safeguards (fixes #65)

docs/userguide/docs/changes.md

@@ -17,6 +17,7 @@ Minor improvements
 * Expose `Environment.getOrNull<T>()` from [koin](https://github.com/InsertKoinIO/koin/issues/182) to check for presence of registered dependencies in simulation environment
 * [#46](https://github.com/holgerbrandl/kalasim/issues/46) clarify use of collect with filter 
 * [#52](https://github.com/holgerbrandl/kalasim/issues/54) Improved visualization of metric timelines to support zoom range
+* [#67](https://github.com/holgerbrandl/kalasim/issues/67) & [#65](https://github.com/holgerbrandl/kalasim/issues/65)  Added more safety guard mechanisms to prevent context violations when branching component processes.
 
 Starting with this release we have switched to calendar versioning for better clarity regarding our release density, timing and schedule.
 

docs/userguide/docs/examples/shipyard/bom_example.md

@@ -0,0 +1,70 @@
+
+**Hull Components:**
+
+1.Steel Plates (Quantity: 20)
+
+2.Bulkheads (Quantity: 5)
+
+3.Frames (Quantity: 15)
+
+4.Keel (Quantity: 1)
+
+**Engines:**
+
+1.Main Engine (Quantity: 2)
+
+2.Auxiliary Engines (Quantity: 3)
+
+**Electrical Systems:**
+
+- **Generators:**
+
+1.Diesel Generators (Quantity: 2)
+
+2.Emergency Generator (Quantity: 1)
+
+- **Cabling and Wiring:**
+
+1.Electrical Cables (Quantity: 500 meters)
+
+2.Wiring Harnesses (Quantity: 50)
+
+- **Switchgear:**
+
+1.Circuit Breakers (Quantity: 30)
+
+2.Switch Panels (Quantity: 10)
+
+**Navigation Equipment:**
+
+1.Radar Systems (Quantity: 2)
+
+2.GPS Navigation Units (Quantity: 1)
+
+3.Compass (Quantity: 1)
+
+**Safety Equipment:**
+
+1.Lifeboats (Quantity: 4)
+
+2.Life Jackets (Quantity: 50)
+
+3.Fire Extinguishers (Quantity: 10)
+
+**Interior Fixtures:**
+
+1.Cabin Furniture (Quantity: 10 sets)
+
+2.Galley Equipment (Quantity: 1 set)
+
+**Deck Machinery:**
+
+1.Cranes (Quantity: 2)
+
+2.Winches (Quantity: 4)
+
+**Miscellaneous:**
+
+1.Paint (Quantity: 50 gallons)
+
+2.Nuts, Bolts, and Fasteners (Quantity: Assorted)

docs/userguide/docs/examples/shipyard/shipyard.md

@@ -12,20 +12,22 @@ A Bill of Materials (BOM) is a structured list of all the items, components, and
 
 Inventory Management: BOMs help shipbuilders keep track of all the components needed for assembly. This allows for efficient inventory management, ensuring that the right materials are available when needed, minimizing delays in production.
 
-Quality Assurance: BOMs also include specifications and quality requirements for each component. This ensures that only the approved parts are used, reducing the likelihood of defects or safety issues in the final product.
+**Quality Assurance**: BOMs also include specifications and quality requirements for each component. This ensures that only the approved parts are used, reducing the likelihood of defects or safety issues in the final product.
 
-Cost Estimation: By providing a detailed list of materials and components, BOMs are invaluable in cost estimation and budgeting. They allow shipbuilders to calculate the overall production costs accurately, ensuring that the project remains within budget.
+**Cost Estimation**: By providing a detailed list of materials and components, BOMs are invaluable in cost estimation and budgeting. They allow shipbuilders to calculate the overall production costs accurately, ensuring that the project remains within budget.
 
-Sourcing and Procurement: BOMs are used to create purchase orders for required materials and components. This helps streamline the procurement process, ensuring that the right parts are ordered in the correct quantities and from approved suppliers.
+**Sourcing and Procurement**: BOMs are used to create purchase orders for required materials and components. This helps streamline the procurement process, ensuring that the right parts are ordered in the correct quantities and from approved suppliers.
 
-Assembly Planning: BOMs serve as a roadmap for the assembly process. They help in organizing the assembly line and ensuring that workers have access to the necessary components in the right order, reducing assembly time and improving efficiency.
+**Assembly Planning**: BOMs serve as a roadmap for the assembly process. They help in organizing the assembly line and ensuring that workers have access to the necessary components in the right order, reducing assembly time and improving efficiency.
 
 ### Example: Ship Final Assembly
 
 Let's consider the assembly of a cargo ship as an example. The ship's BOM would include a detailed list of all components, such as the hull, engines, electrical systems, navigation equipment, and more. Each of these components would have its own sub-BOMs, breaking down further into individual parts. For instance, the electrical system's sub-BOM might include cables, switches, and circuit boards, specifying the quantity, specifications, and suppliers for each.
 
 By having a well-structured BOM for the cargo ship, the shipbuilder can ensure that all components are available on time, that quality standards are met, and that the assembly process is efficient. This not only reduces the production timeline but also increases the overall quality and safety of the final product.
 
+How would a typical BOM in cargo ship final assembly look like
+
 ### Conclusion
 
 Bill of Materials (BOMs) are an essential tool in the production process, especially in the complex field of ship assembly. They provide a detailed and organized overview of the materials and components required for final assembly, allowing for efficient management of inventory, quality assurance, cost estimation, and assembly planning. In shipbuilding, BOMs play a crucial role in ensuring that the final product is not only completed on time but also meets the highest quality and safety standards.

src/main/kotlin/org/kalasim/Component.kt

@@ -80,7 +80,18 @@ data class RequestContext(
     }
 }
 
-//@AmbiguousDurationComponent
+/**
+ * Represents a ticked component in the simulation. A ticked component provides in addition to `SimTime` interactions,
+ * complementary methods that do work with TickTime instead
+ *
+ * @param name The name of the ticked component.
+ * @param at The initial simulation time at which the ticked component is created.
+ * @param delay The delay time before the ticked component becomes active.
+ * @param priority The priority of the ticked component.
+ * @param process The process pointer associated with the ticked component.
+ * @param trackingConfig The component tracking configuration.
+ * @param koin The Koin instance used for dependency injection.
+ */
 @AmbiguousDurationComponent
 open class TickedComponent(
     name: String? = null,
@@ -103,17 +114,13 @@ open class TickedComponent(
      * @param priority If a component has the same time on the event list, this component is sorted according to
      * the priority. An event with a higher priority will be scheduled first.
      */
-//    @Deprecated("Use Duration instead of Number")
     suspend fun SequenceScope<Component>.hold(
         duration: Number? = null,
         description: String? = null,
         until: SimTime? = null,
         priority: Priority = NORMAL,
         urgent: Boolean = false
     ) {
-//        val component = getThis()
-//        val other = this
-//        println(component)
         yieldCurrent {
             this@TickedComponent.hold(duration?.toDuration(), description, until, priority, urgent)
         }
@@ -134,7 +141,6 @@ open class TickedComponent(
 }
 
 
-// todo https://github.com/holgerbrandl/kalasim/issues/47
 /**
  * A kalasim component is used as component (primarily for queueing) or as a component with a process.
  * Usually, a component will be defined as a subclass of Component.
@@ -225,18 +231,20 @@ open class Component(
 
         val overriddenProcess = javaClass.getMethod("process").declaringClass.simpleName != "Component"
         val overriddenRepeated = javaClass.getMethod("repeatedProcess").declaringClass.simpleName != "Component"
-        val customProcess = process != null && process.name != "process"
+        val isCustomProcess = process != null && process.name != "process"
         val isNone = process != null && process.name == "none"
 
-        require(!overriddenProcess || !overriddenRepeated || !customProcess) {
-            "Just one custom process can be provided. So either provide a custom pointer, or override process, or override repeatedProcess"
+        if(!isCustomProcess) {
+            require(!(overriddenProcess && overriddenRepeated)) {
+                " So either override process or override repeatedProcess but not both"
+            }
         }
 
         val processPointer: KFunction1<Nothing, Sequence<Component>>? = when {
             isNone -> null
             overriddenProcess -> Component::process
             overriddenRepeated -> Component::processLoop
-            customProcess -> process
+            isCustomProcess -> process
             else -> null
         }
 
@@ -1655,7 +1663,6 @@ open class Component(
            """.trimIndent()
         }
 
-
         builder()
 
         if(initialStatus == CURRENT) {