search

nim-lang / threading

New atomics, thread primitives, atomic refcounting for --gc:arc/orc.
MIT License
73 stars 12 forks source link

#52 Expand channel documentation #53

Closed PhilippMDoerner closed 10 months ago

PhilippMDoerner commented 10 months ago

Closes #52

A small PR based on what I learned about channels. Regard every change I made with suspicion, I am still starting out in learning about channels, multithreaded communication etc.

I very deliberately stole a lot of the descriptions from Nim's channels_builtin module (example ) and adjusted them to keep descriptions somewhat consistent.

I also added an external hyperlink to std/isolation to the general module docs, because the imports don't show in them and neither does Isolated have any hyperlinks to its own type. This makes it unclear for users where to find the type if they have no context (I mean, I had none, I'm just diving into the multithreading space now) and therefore there should be a link somewhere.

I am also very uncertain about a sentence I used repeatedly here: ## The memorysrcis moved, not copied.

That is my current understanding of threading/channels, but I don't quite know that for sure, so if that needs correcting please say so.

ZoomRmc commented 10 months ago

Sorry, I'm late to the party. Scanned through the changes and in general it's all good with an exception of tryRecv. Usually, "can fail for all sort of reasons" is not what you want to put in the documentation :P.

The fail case is single and known: an empty channel.

Moreover, "This returns immediately" is also not guaranteed, we're trying to acquire the lock unconditionally after all. May be we need to add the clarification that the procs don't block waiting for the data/space to appear in the channels, but block on lock contention. Just to concoct a scenario when it happens: no one prevents anyone from writing silly code and combining blocking and non-blocking versions so it's possible to put yourself in such a situation.

PhilippMDoerner commented 10 months ago

Happy to make a correction PR!

The failure bit I just took from builtin_channels.nim, the fact that tryRecv does not return immediately was actually not known to me, thanks for the explainer!