dissyslab 1.0.2__py3-none-any.whl

dissyslab/__init__.py

@@ -0,0 +1,25 @@
+# dissyslab/__init__.py
+"""
+DisSysLab - Distributed Systems Teaching Framework
+
+Public API exports.
+"""
+
+from dissyslab.core import Agent, ExceptionThread
+from dissyslab.network import Network
+from dissyslab.builder import network, PortReference
+
+__all__ = [
+    # Core
+    'Agent',
+    'ExceptionThread',
+
+    # Network
+    'Network',
+    'network',
+
+    # Builder
+    'PortReference',
+]
+
+__version__ = '1.0.2'

dissyslab/blocks/__init__.py

@@ -0,0 +1,32 @@
+# dissyslab/blocks/__init__.py
+"""
+Standard agent blocks for building distributed systems.
+
+Available blocks:
+- Source: Generate messages (no inputs)
+- Transform: Process messages (one input, one output)
+- Sink: Consume messages (one input, no outputs)
+- Broadcast: Fanout - copy message to multiple outputs
+- MergeAsynch: Fanin - merge multiple inputs into one stream
+- Split: Content-based routing to multiple outputs
+"""
+
+from dissyslab.blocks.source import Source
+from dissyslab.blocks.transform import Transform
+from dissyslab.blocks.sink import Sink
+from dissyslab.blocks.fanout import Broadcast
+from dissyslab.blocks.fanin import MergeAsynch
+from dissyslab.blocks.merge_synch import MergeSynch
+from dissyslab.blocks.split import Split
+from dissyslab.blocks.role import Role
+
+__all__ = [
+    "Source",
+    "Transform",
+    "Sink",
+    "Broadcast",
+    "MergeAsynch",
+    "MergeSynch",
+    "Split",
+    "Role",
+]

dissyslab/blocks/fanin.py

@@ -0,0 +1,90 @@
+# dissyslab/blocks/fanin.py
+"""
+Merge Agents: Combine multiple inputs into single output (fanin).
+
+MergeAsynch is the recommended merge for most use cases. Termination is
+signaled by os_agent via _Shutdown, handled transparently by recv().
+No STOP coordination needed.
+"""
+
+from __future__ import annotations
+from typing import Optional
+import threading
+
+from dissyslab.core import Agent, _ShutdownSignal
+
+
+class MergeAsynch(Agent):
+    """
+    MergeAsynch agent: combines multiple inputs (fanin, non-deterministic).
+
+    Multiple inputs, single output. Receives from whichever input has
+    a message available first. Fast but non-deterministic order.
+
+    **Ports:**
+    - Inports: ["in_0", "in_1", ..., "in_{n-1}"]
+    - Outports: ["out_"]
+
+    **Termination:**
+    Termination is detected by os_agent and signaled via _Shutdown on
+    each inport, handled transparently by recv(). No STOP coordination
+    needed — worker threads exit cleanly via _ShutdownSignal.
+    """
+
+    def __init__(self, *, num_inputs: int, name: Optional[str] = None):
+        if num_inputs < 1:
+            raise ValueError(
+                f"MergeAsynch requires at least 1 input, got {num_inputs}"
+            )
+
+        inports = [f"in_{i}" for i in range(num_inputs)]
+        super().__init__(name=name, inports=inports, outports=["out_"])
+        self.num_inputs = num_inputs
+
+    @property
+    def default_inport(self) -> Optional[str]:
+        """No default input (multiple inputs - ambiguous)."""
+        return None
+
+    @property
+    def default_outport(self) -> str:
+        """Default output port for edge syntax."""
+        return "out_"
+
+    def _worker(self, port: str) -> None:
+        """
+        Worker thread for one input port.
+        Forwards messages to out_ until _ShutdownSignal is raised by recv().
+        """
+        try:
+            while True:
+                msg = self.recv(port)
+                self.send(msg, "out_")
+        except _ShutdownSignal:
+            pass  # clean exit — os_agent declared termination
+
+    def run(self) -> None:
+        """
+        Spawn one worker thread per input port and wait for all to finish.
+
+        Workers exit when recv() raises _ShutdownSignal on _Shutdown receipt.
+        """
+        threads = []
+        for p in self.inports:
+            t = threading.Thread(
+                target=self._worker,
+                args=(p,),
+                name=f"merge_worker_{p}",
+                daemon=False
+            )
+            t.start()
+            threads.append(t)
+
+        for t in threads:
+            t.join()
+
+    def __repr__(self) -> str:
+        return f"<MergeAsynch name={self.name} inputs={self.num_inputs}>"
+
+    def __str__(self) -> str:
+        return f"MergeAsynch({self.num_inputs} inputs)"

dissyslab/blocks/fanout.py

@@ -0,0 +1,69 @@
+# dissyslab/blocks/fanout.py
+"""
+Broadcast Agent: Copies messages to multiple outputs (fanout).
+
+Broadcast agents are automatically inserted by the framework when one
+agent connects to multiple receivers. Termination is signaled by os_agent
+via _Shutdown, handled transparently by recv().
+"""
+
+from __future__ import annotations
+from typing import Optional
+import copy
+
+from dissyslab.core import Agent
+
+
+class Broadcast(Agent):
+    """
+    Broadcast agent: copies messages to multiple outputs (fanout).
+
+    Single input, multiple outputs. Receives message and sends a deep
+    copy to each output port.
+
+    **Ports:**
+    - Inports: ["in_"]
+    - Outports: ["out_0", "out_1", ..., "out_{n-1}"]
+
+    **Termination:**
+    Termination is detected by os_agent and signaled via _Shutdown,
+    which recv() handles transparently by raising _ShutdownSignal.
+    """
+
+    def __init__(self, *, num_outputs: int, name: Optional[str] = None):
+        if num_outputs < 1:
+            raise ValueError(
+                f"Broadcast requires at least 1 output, got {num_outputs}"
+            )
+
+        outports = [f"out_{i}" for i in range(num_outputs)]
+        super().__init__(name=name, inports=["in_"], outports=outports)
+        self.num_outputs = num_outputs
+
+    @property
+    def default_inport(self) -> str:
+        """Default input port for edge syntax."""
+        return "in_"
+
+    @property
+    def default_outport(self) -> Optional[str]:
+        """No default output (multiple outputs - ambiguous)."""
+        return None
+
+    def run(self) -> None:
+        """
+        Broadcast messages to all outputs.
+
+        recv() intercepts _Shutdown and raises _ShutdownSignal,
+        which unwinds this loop cleanly.
+        """
+        while True:
+            msg = self.recv("in_")
+            for i in range(self.num_outputs):
+                self.send(copy.deepcopy(msg), f"out_{i}")
+
+    def __repr__(self) -> str:
+        return f"<Broadcast name={self.name} outputs={self.num_outputs}>"
+
+    def __str__(self) -> str:
+        return f"Broadcast({self.num_outputs} outputs)"

dissyslab/blocks/merge_synch.py

@@ -0,0 +1,73 @@
+# dissyslab/blocks/merge_synch.py
+"""
+Merge Agents: Combine multiple inputs into single output.
+
+MergeSynch: Synchronous merge in round-robin order (use sparingly).
+For most use cases, prefer MergeAsynch in fanin.py.
+
+Termination is signaled by os_agent via _Shutdown, handled transparently
+by recv(). No explicit STOP handling needed.
+"""
+
+from __future__ import annotations
+from typing import Optional
+
+from dissyslab.core import Agent
+
+
+class MergeSynch(Agent):
+    """
+    MergeSynch agent: synchronously combines multiple inputs in round-robin order.
+
+    **WARNING: Use only when deterministic ordering is required AND all inputs
+    produce messages at similar rates. For most use cases, prefer MergeAsynch.**
+
+    **Ports:**
+    - Inports: ["in_0", "in_1", ..., "in_{n-1}"]
+    - Outports: ["out_"]
+
+    **Termination:**
+    Termination is detected by os_agent and signaled via _Shutdown,
+    which recv() handles transparently by raising _ShutdownSignal.
+    """
+
+    def __init__(self, *, num_inputs: int, name: Optional[str] = None):
+        if num_inputs < 1:
+            raise ValueError(
+                f"MergeSynch requires at least 1 input, got {num_inputs}"
+            )
+
+        inports = [f"in_{i}" for i in range(num_inputs)]
+        super().__init__(name=name, inports=inports, outports=["out_"])
+        self.num_inputs = num_inputs
+
+    @property
+    def default_inport(self) -> Optional[str]:
+        """No default input (multiple inputs - ambiguous)."""
+        return None
+
+    @property
+    def default_outport(self) -> str:
+        """Default output port for edge syntax."""
+        return "out_"
+
+    def run(self) -> None:
+        """
+        Synchronous merge loop: collect batches in round-robin order.
+
+        Collects one message from each input in order, sends as a list.
+        recv() intercepts _Shutdown and raises _ShutdownSignal,
+        which unwinds this loop cleanly.
+        """
+        while True:
+            batch = []
+            for inport in self.inports:
+                msg = self.recv(inport)
+                batch.append(msg)
+            self.send(batch, "out_")
+
+    def __repr__(self) -> str:
+        return f"<MergeSynch name={self.name} inputs={self.num_inputs}>"
+
+    def __str__(self) -> str:
+        return f"MergeSynch({self.num_inputs} inputs)"

dissyslab/blocks/role.py

@@ -0,0 +1,113 @@
+# dissyslab/blocks/role.py
+"""
+Role Agent: Routes messages based on status strings.
+
+A Role agent is a generalization of Split where:
+- The function returns an arbitrary list of (message, status) pairs
+- Status strings determine which outport each message goes to
+- The number of output messages is independent of the number of outports
+
+Termination is signaled by os_agent via _Shutdown, handled transparently
+by recv(). No explicit STOP handling needed.
+"""
+
+from __future__ import annotations
+from typing import Callable, Any, Optional, List, Tuple
+import traceback
+
+from dissyslab.core import Agent
+
+
+class Role(Agent):
+    """
+    Role agent: routes messages based on status strings.
+
+    Single input, multiple outputs. The function returns either:
+    (1) an arbitrary list of (message, status) pairs, or
+    (2) a list of messages without explicit status values — coerced to "all", or
+    (3) a single message (not a list) — treated as [(message, "all")], or
+    (4) None — message is dropped.
+
+    **Ports:**
+    - Inports: ["in_"]
+    - Outports: ["out_0", "out_1", ..., "out_{n-1}"]
+      where n = len(statuses)
+
+    **Termination:**
+    Termination is detected by os_agent and signaled via _Shutdown,
+    which recv() handles transparently by raising _ShutdownSignal.
+    """
+
+    def __init__(
+        self,
+        *,
+        fn: Callable[[Any], List[Tuple[Any, str]]],
+        statuses: List[str],
+        name: Optional[str] = None
+    ):
+        if not callable(fn):
+            raise TypeError(
+                f"Role fn must be callable, got {type(fn).__name__}"
+            )
+
+        if not statuses:
+            statuses = ["all"]
+
+        if len(set(statuses)) != len(statuses):
+            raise ValueError(
+                f"Role statuses must be unique, got duplicates: {statuses}"
+            )
+
+        self._status_to_port: dict = {
+            status: f"out_{i}" for i, status in enumerate(statuses)
+        }
+
+        outports = [f"out_{i}" for i in range(len(statuses))]
+
+        super().__init__(name=name, inports=["in_"], outports=outports)
+        self._fn = fn
+        self.statuses = list(statuses)
+
+    def run(self) -> None:
+        """
+        Process messages and route by status.
+
+        recv() intercepts _Shutdown and raises _ShutdownSignal,
+        which unwinds this loop cleanly.
+        """
+        while True:
+            msg = self.recv("in_")
+
+            try:
+                results = self._fn(msg)
+
+                if results is None:
+                    continue
+
+                if not isinstance(results, (list, tuple)):
+                    results = [(results, "all")]
+                elif results and not isinstance(results[0], (list, tuple)):
+                    results = [(item, "all") for item in results]
+
+                for out_msg, status in results:
+                    if status not in self._status_to_port:
+                        raise ValueError(
+                            f"Role '{self.name}' returned undeclared status "
+                            f"'{status}'. Declared statuses: {self.statuses}"
+                        )
+                    self.send(out_msg, self._status_to_port[status])
+
+            except Exception as e:
+                print(f"[Role '{self.name}'] Error in fn: {e}")
+                print(traceback.format_exc())
+                return
+
+    def __repr__(self) -> str:
+        fn_name = getattr(self._fn, "__name__", repr(self._fn))
+        return (
+            f"<Role name={self.name} fn={fn_name} "
+            f"statuses={self.statuses}>"
+        )
+
+    def __str__(self) -> str:
+        return f"Role({self.statuses})"

dissyslab/blocks/sink.py

@@ -0,0 +1,77 @@
+# dissyslab/blocks/sink.py
+"""
+Sink Agent: Consumes messages for side effects.
+
+Sinks have one input and no outputs. They are terminal nodes that call
+fn(msg, **params) for each message to perform side effects like printing,
+saving, or collecting. Termination is signaled by os_agent via _Shutdown,
+which is handled transparently by recv().
+"""
+
+from __future__ import annotations
+from typing import Any, Callable, Optional, Dict
+import traceback
+
+from dissyslab.core import Agent
+
+
+class Sink(Agent):
+    """
+    Sink agent: consumes messages for side effects.
+
+    Single input, no outputs. Terminal node that calls fn(msg, **params)
+    for each message. Used for actions like printing, saving, or sending.
+
+    **Ports:**
+    - Inports: ["in_"]
+    - Outports: [] (no outputs)
+
+    **Termination:**
+    Termination is detected by os_agent and signaled via _Shutdown,
+    which recv() handles transparently by raising _ShutdownSignal.
+    No explicit STOP handling needed.
+    """
+
+    def __init__(
+        self,
+        *,
+        fn: Callable[..., None],
+        name: Optional[str] = None,
+        params: Optional[Dict[str, Any]] = None
+    ):
+        if not callable(fn):
+            raise TypeError(
+                f"Sink fn must be callable, got {type(fn).__name__}"
+            )
+
+        super().__init__(name=name, inports=["in_"], outports=[])
+        self._fn = fn
+        self._params = params or {}
+
+    @property
+    def default_inport(self) -> str:
+        """Default input port for edge syntax."""
+        return "in_"
+
+    def run(self) -> None:
+        """
+        Process messages until _Shutdown is received.
+
+        recv() intercepts _Shutdown and raises _ShutdownSignal,
+        which unwinds this loop cleanly.
+        """
+        while True:
+            msg = self.recv("in_")
+            try:
+                self._fn(msg, **self._params)
+            except Exception as e:
+                print(f"[Sink '{self.name}'] Error in fn: {e}")
+                print(traceback.format_exc())
+                return
+
+    def __repr__(self) -> str:
+        fn_name = getattr(self._fn, "__name__", repr(self._fn))
+        return f"<Sink name={self.name} fn={fn_name}>"
+
+    def __str__(self) -> str:
+        return "Sink"

dissyslab/blocks/source.py

@@ -0,0 +1,119 @@
+# dissyslab/blocks/source.py
+"""
+Source Agent: Repeatedly calls a function to generate messages.
+
+Sources have no inputs and generate data by calling fn() repeatedly until
+it returns None. When exhausted, the source sends a termination message to
+os_agent with its final sent counts. Termination is detected by os_agent —
+sources do not send STOP signals.
+"""
+
+from __future__ import annotations
+import inspect
+import traceback
+import time
+from typing import Any, Callable, Optional
+
+from dissyslab.core import Agent
+
+
+class Source(Agent):
+    """
+    Source Agent: Repeatedly calls a function to generate messages.
+
+    **Ports:**
+    - Inports: [] (no inputs - sources generate data)
+    - Outports: ["out_"] (emits generated messages)
+
+    **Function Requirements:**
+    The fn callable must:
+    - Return a message (any type) on each call
+    - Return None when exhausted (no more messages)
+    - Maintain its own state between calls (if needed)
+
+    Generator functions are also accepted — Source wraps them automatically
+    so that each call to fn() advances the generator by one step.
+
+    **Termination:**
+    When fn() returns None, the source sends a termination message to
+    os_agent containing its final sent counts, then returns from run().
+    os_agent uses this message to detect when all sources are done.
+
+    **Optional Rate Limiting:**
+    The interval parameter adds a delay between messages:
+    - interval=0 (default): emit as fast as possible
+    - interval=1.0: emit one message per second
+    """
+
+    def __init__(
+        self,
+        *,
+        fn: Callable[[], Optional[Any]],
+        name: Optional[str] = None,
+        interval: float = 0
+    ):
+        if not callable(fn):
+            raise TypeError(
+                "Source fn must be callable with signature: fn() -> Optional[message]"
+            )
+
+        super().__init__(name=name, inports=[], outports=["out_"])
+
+        # If fn is a generator function, wrap it so each call returns one item.
+        if inspect.isgeneratorfunction(fn):
+            _gen = fn()
+            def fn(): return next(_gen, None)
+
+        self._fn = fn
+        self._interval = interval
+
+    @property
+    def default_outport(self) -> str:
+        """Default output port for edge syntax."""
+        return "out_"
+
+    def _send_termination(self) -> None:
+        """
+        Send final sent counts to os_agent.
+        Called when source is exhausted or encounters an error.
+        """
+        self.send_os({
+            "agent":    self.name,
+            "sent":     dict(self.sent),
+            "received": {},
+        })
+
+    def run(self) -> None:
+        """
+        Main processing loop for the Source agent.
+
+        Repeatedly calls self._fn() to get messages and emits them.
+        When fn() returns None or an exception occurs, sends termination
+        message to os_agent and returns.
+        """
+        try:
+            while True:
+                msg = self._fn()
+
+                # None means the source is exhausted
+                if msg is None:
+                    self._send_termination()
+                    return
+
+                self.send(msg, "out_")
+
+                if self._interval > 0:
+                    time.sleep(self._interval)
+
+        except Exception as e:
+            print(f"[Source '{self.name}'] Error in fn: {e}")
+            print(traceback.format_exc())
+            self._send_termination()
+
+    def __repr__(self) -> str:
+        fn_name = getattr(self._fn, "__name__", repr(self._fn))
+        interval_str = f", interval={self._interval}" if self._interval > 0 else ""
+        return f"<Source name={self.name} fn={fn_name}{interval_str}>"
+
+    def __str__(self) -> str:
+        return "Source"