I have hard time understanding what is meant by “Note that this circuit needs a clock to latch the incoming Maybe values in case of backpressure from the RHS”. Does it mean:
For reference this concerns this function from clash-protocols.
That this circuit requires a clock is indeed enforced on the type level via HiddenClockResetEnable. Which essentially means this function can only be called in a context that has a hidden clock/reset/enable available.
The comment exists to clarify why this circuit requires a clock, as it may not be immediately obvious to the reader. The underlying reason is that the Df protocol requires that the payload remains stable until it is acknowledged.
If you have a stream of incoming `Maybe` values these can change arbitrarily. This violates the stability requirement. To fix this unsafeToMaybe essentially contains a single element buffer.
If no value is buffered, incoming Maybe values are passed through. If a value is buffered, that value is presented to the RHS until it is acknowledged. When the RHS does not acknowledge a value is placed into the buffer.
If a new Just value arrives while a value is already buffered and the RHS is not acknowledging, the new value is dropped. Which is why this circuit is considered unsafe as it can cause data loss.
Thanks. If I may suggested to rephrase it to “Note that this circuit needs a clock to latch the incoming
‘Maybe’ values in case of backpressure from the RHS. This is enforced by HiddenClockResetEnable.” to clarify that this is not a safety requirement.
I was wary as the function was named ‘unsafe’ and I was trying to understand what is unsafe about it.
I started a PR to collect small documentation improvements, if you notice more unclear pieces of documentation, feel free to ask for clarification.