Documentation wording: “blocked on respond/request”

[k0001]

I was reading the new documentation and I had to stop for a while to reason about the documentation for (>->). It says:

Compose two proxies blocked on a respond, creating a new proxy blocked on a respond

Perhaps I'm seeing this from the wrong perspective, but I interpret that sentence as the execution of the composed proxies “getting stuck” once they reach a respond action. However, what happens is quite the opposite; these proxies “get stuck” once they execute a request action, waiting for a respond from upstream.

¿Do you think that saying something like the following could be clearer?

… blocked waiting for a respond from upstream.

The opposite applies to (>~>).

[Gabriella439]

I think you mean something like:

... blocked waiting for a request from upstream

Yeah, I like this idea. I will switch to that wording.

[k0001]

No, actually for (>->) I meant what I said:

… blocked waiting for a respond from upstream.

However, I might be seeing this description from the wrong perspective. This is what I understand:

p1 :: () -> Producer Int IO r
p1 () = forever $ respond 42

p2 :: () -> Consumer Int IO r
p2 () = forever $ request () >>= lift . print

p3 :: () -> Effect IO r
p3 = p1 >-> p2

¿Doesn't p3 “get stuck” on the first request in p2 waiting for a respond from its upstream?

[k0001]

Wait, that last question was even more confusing. Let me put it like this:

In p1 >-> p2:

• p2 gets to run first and blocks on request, since once it executes that request it gets stuck waiting for a respond from upstream.
• p1 does nothing until p2 “wakes him up” by issuing a request, and then it blocks on respond, waiting for a request from downstream.

(I accidentally closed the issue and then reopened it)

[k0001]

Hmm… as usual, you are right. It was my misinterpretation.

I looked up the precise meaning of “blocked on” in the dictionary and it says it is “waiting for something”. So it is true; these proxies are “blocked on respond”, that is, waiting for a respond. So we can blame my misunderstanding of the English language for this confusion. But still, perhaps saying “waiting for a respond from upstream” is clearer. What do you think?

It's not a big deal, anyway.

[k0001]

To add some context: I thought that being blocked on something meant being stuck at that something. That is, I thought that if you wanted to cross a door but you couldn't because you were waiting for the key, you would say that you are blocked on the door, but actually, you are blocked on the key, which is the thing that's missing.

[pthariensflame]

@k0001 Just so you know, the expression that means what you thought blocked on did is blocked by: you are blocked on the key and blocked by the door.

[Gabriella439]

Maybe I should rephrase it to say "blocked waiting for upstream to request a new value".

[Gabriella439]

Sorry, I meant "blocked waiting for downstream to request a new value".

[k0001]

Thanks for educating me @pthariensflame.

@Gabriel439 I think your idea is nice since it also suggests that the request happens first :)

[Gabriella439]

Ok, so I updated it to read: "Compose two proxies blocked waiting for a downstream value, creating a new proxy blocked waiting for a downstream value"

I decided to avoid using the terms request and respond since technically that value could be supplied from anywhere, such as when you manually supply the () right before calling runEffect.

Just review that wording and suggest any changes if it's still unclear.

[k0001]

Yes, this is excellent, super clear :)

Thanks for your time.