From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Wed, 31 Jul 2019 00:21:45 +0000 (+0100)
Subject: document the DynamicPipe metaclass
X-Git-Tag: ls180-24jan2020~656
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=9f4164043624b293a54aa8a34bf3f2d1e406c68d;p=ieee754fpu.git

document the DynamicPipe metaclass
---

diff --git a/src/ieee754/pipeline.py b/src/ieee754/pipeline.py
index 2e572459..9c6866d6 100644
--- a/src/ieee754/pipeline.py
+++ b/src/ieee754/pipeline.py
@@ -38,6 +38,8 @@ class PipelineSpec:
 
 # with many thanks to jsbueno on stackexchange for this one
 # https://stackoverflow.com/questions/57273070/
+# list post:
+# http://lists.libre-riscv.org/pipermail/libre-riscv-dev/2019-July/002259.html
 
 class Meta(ABCMeta):
     registry = {}
@@ -50,7 +52,7 @@ class Meta(ABCMeta):
         if mcls.recursing.check:
             return super().__call__(*args, **kw)
         spec = args[0]
-        base = spec.pipekls
+        base = spec.pipekls # pick up the dynamic class from PipelineSpec, HERE
 
         if (cls, base) not in mcls.registry:
             print ("__call__", args, kw, cls, base, base.__bases__, cls.__bases__)
@@ -68,6 +70,21 @@ class Meta(ABCMeta):
         return instance
 
 
+# Inherit from this class instead of SimpleHandshake (or other ControlBase
+# derivative), and the metaclass will instead *replace* DynamicPipe -
+# *at runtime* - with the class that is specified *as a parameter*
+# in PipelineSpec.
+#
+# as explained in the list posting and in the stackexchange post, this is
+# needed to avoid a MASSIVE suite of duplicated multiple-inheritance classes
+# that "Mix in" SimpleHandshake (or other).
+#
+# unfortunately, composition does not work in this instance
+# (make an *instance* of SimpleHandshake or other class and pass it in)
+# due to the multiple level inheritance, and in several places
+# the inheriting class needs to do some setup that the deriving class
+# needs in order to function correctly.
+
 class DynamicPipe(metaclass=Meta):
     def __init__(self, *args):
         print ("DynamicPipe init", super(), args)