Some questions

[flip111]

Hello i was reading through the readme and i have some questions

This library is an implementation of a trivial pub/sub model for PureScript

The library doesn't look so trivial, it also has 66 commits. Don't really get how it's trivial, care to explain??

It tries to immitate similar functionality to Chans from Haskell, but isn't nearly as cool.

What's more cool about Chans from Haskell ?

Queue, IxQueue, Queue.One

Did i understand correctly that:

• Queue: will trigger all handlers. Handlers must remain present and can only be added
• IxQueue: triggers none, one or more handlers. Handlers can be add or removed at will.
• Queue.One: triggers one handler. The single handler must be present at all times.

Queue.Aff is useful when you might have multiple registerSyncOnce

This section is not very clear because it requires knowledge of what registerSyncOnce is doing

Queue.Aff ... if you know the network statically (deletion clears all of them).

Not sure what is deleted here. Something is deleted but the handlers must stay registered?

IxQueue.Aff is useful when you need async calls, but need to integrate into an existing IxQueue of other recipients.

So it's possible to take an IxQueue and integrate it into another IxQueue? Can you tell something about this scenario?

An advantage of Queue.Aff and Queue.One.Aff, naturally, is they don't need to be registered before invoked

What does it mean to register Queue or Queue.One?

The behavior of this library is such that, if no handlers are registered, then store pending messages first-in-first-out until one is available.

What does this mean? I see it's possible to take the first or last

[athanclark]

Thank you for this critique; there are clearly many open ends that need tying in the documentation. Unfortunately at the moment, I'm very busy, but I will revise these docs and answer your questions over the weekend!

[athanclark]

@flip111 Alright, I made a bunch of edits to the README. I tried to engage as many questions you had, and also adjusted a lot of the inconsistencies I had there, especially cruft from an outdated version. Please tell me what you think, and if you still have more questions, I tried to be as verbose as I could!

[flip111]

Awesome, i'll get on reading then

[flip111]

First impression is that it has improved a lot. I understood much more things than before !

Some other questions ..

which handlers receive the message ? all ?
When you selectively want to trigger handlers, should you make multiple queues or let handlers return no-op?

what happens when all handlers get a message ? Can it be a race condition ? Or is there an order in which they are processed ?
--> this is partially answered later in the text.

Is there any relation to javascript Promise ?

---

readOnly removes the read :: READ label from the row type

I think this should be

readOnly removes the write :: WRITE label from the row type

with some thread (fiber).

This "thread" and "fiber" is a new concept not introduced earlier in the readme. Don't really understand what a return value with a fiber is.

while writing to the queue these functions return

i don't really understand what you mean by "functions return"

and blocks until an output is available in Aff

Wasn't Aff non-blocking because it's async? Or is it blocking one "fiber" ?

but does so in lock-step

i don't understand what this mean (even with the sentence behind it)

callAsyncEff

So as i understand this blocks your whole program, maybe useful for console application only ?

registerSyncOnce

Maybe the order of functions in the readme could be:
new, callAsync, callAsyncEff, registerSync, registerSyncOnce

result <- callAsync io 20 -- invoke delegated computation in Aff
liftEffect $ log $ "Should be 21 - Result: " <> show result

So callAsync is basically await / yield in other language right? Maybe mention this.

Either way, this use case would probably not be stable or in your favor, and should generally be avoided.

I thought attaching multiple handlers of Queue was the normal usecase. What is the different between "this use case" (in the text) as supposed to maybe another "normal" use case ?

[flip111]

By the way i added your package to spago purescript/package-sets#593

[athanclark]

Hey, sorry again for the delay.

which handlers receive the message ? all ?
When you selectively want to trigger handlers, should you make multiple queues or let handlers
return no-op?

With module Queue, all handlers receive the messages, where if multiple messages are sent, all handlers process each individual message before continuing to the next message. If you selectively want to trigger one handler, but still would like the ability to broadcast to multiple at a different time, module IxQueue would cover that purpose, where each handler is identified by a String, and you can send a message strictly to one handler (or multiple) via those same identifiers.

what happens when all handlers get a message ? Can it be a race condition ? Or is there an order
in which they are processed ?

--> this is partially answered later in the text.

It depends on your programming model. Generally speaking, if you aren't using IOQueues, then you should be already prepared to engage multiple handlers at any given time, ambiguous to the order in which they're executed (if you're working with module Queue or module IxQueue). Again, if you're using module Queue.One, you can only have at most one handler at a time.

Is there any relation to javascript Promise ?

Somewhat, but it isn't defined with one. A promise is supposed to be something like a "pending execution", where the result could happen at any given time. Promise is very similar to Aff, and I often bind the two.

A Queue is best thought of as a container of messages, that you can read from later, but tries to work well with asynchronous code.

---

readOnly removes the read :: READ label from the row type

I think this should be

readOnly removes the write :: WRITE label from the row type

Holy cow how did I miss that?! Thank you!

with some thread (fiber).

This "thread" and "fiber" is a new concept not introduced earlier in the readme. Don't really
understand what a return value with a fiber is.

A thread is a concept from Aff - there is a bit of prerequisite of familiarity with Aff before diving into this project. Basically, when you fork an Aff, you get a "fiber" as a result (think of it as a thing that's thicker than a thread).

while writing to the queue these functions return

i don't really understand what you mean by "functions return"

If you check out the type signature of debounceStatic, you'll see that it returns a Queue: https://pursuit.purescript.org/packages/purescript-queue/8.0.2/docs/Queue.Types#v:debounceStatic

and blocks until an output is available in Aff

Wasn't Aff non-blocking because it's async? Or is it blocking one "fiber" ?

Right, so in JavaScript / single threaded code, "async" just means "I can only execute one bit of code at a time, but because the bits are really small and interleaved (one function at a time), I can kinda-sorta execute multiple at a time, because I'm just bouncing around to different ones when I can"

(don't quote me on that)

Basically, blocking while in Aff just means "this async block isn't executing right now", but the whole thread (because JavaScript is single-threaded) is not blocked. In a sense, Aff grants you cost-free blocking. (again don't quote me)

but does so in lock-step

i don't understand what this mean (even with the sentence behind it)

Basically, in Effect, you are guaranteed that the previous block of code executes right before the next block, with no "smaller bits" executing in-between (because JavaScript is single-threaded). The same can be said for any pure function in PureScript, but it's a little harder to think about because it's more focused on "the parameters to a function are evaluated before the function itself" - but similarly, in "lock-step". The term I'm using is slang, basically, for atomic evaluation - that you can ensure one thing happens before another, without anything in-between.

I'm making emphasis on this for registerSync, because it's in Effect, and not in Aff (which could allow for a race condition).

callAsyncEff

So as i understand this blocks your whole program, maybe useful for console application only ?

Well... not entirely. It's just a different type signature, but has the same results - in fact, callAsync is defined with callAsyncEff. The main take-away is that it just uses Effect, in case you don't want to mess with Aff; but in general, Aff is a better programming model for that kind of code. If you look at the type signature in the docs, you'll see it takes a Handler output, which is just a -> Effect Unit. We don't know when the handler is executed; and in-fact, we can't know if it's executed atomically.

registerSyncOnce

Maybe the order of functions in the readme could be:

new, callAsync, callAsyncEff, registerSync, registerSyncOnce

Yeah... you're right lol

result <- callAsync io 20 -- invoke delegated computation in Aff

liftEffect $ log $ "Should be 21 - Result: " <> show result

So callAsync is basically await / yield in other language right? Maybe mention this.

That's exactly the goal!

And... you're totally right, I should lol

Either way, this use case would probably not be stable or in your favor, and should generally be avoided.

I thought attaching multiple handlers of Queue was the normal usecase. What is the different
between "this use case" (in the text) as supposed to maybe another "normal" use case ?

So, module Queue allows for multiple handlers, right? But it doesn't let you declare which ones you want to engage, it only lets you broadcast. If you want async / await behavior, you can't really get away with it, because there could be multiple entrances back into Aff... it's pretty confusing even to explain.