Code documentation: task scheduling about smol HOT 3 CLOSED

Thank you for the feedback! Perhaps it'd be useful to define somewhere what words mean, i.e. what is a 'task' and 'future', or what does 'schedule' and 'wake' mean.

Is this a useful comment to you, did you find it (perhaps it was not easy to find)?
https://github.com/stjepang/smol/blob/5acde03d5a971054603dcbbc616963270e56cdd2/src/task.rs#L14-L22

from smol.

Ah, I don't believe I looked that closely at that comment. My tunnel vision here was to look really hard at the reactor and executor modules, but not look as closely at the task module.

That comment is pretty helpful. I think that I didn't really understand what Runnable meant on first pass, I thought it just generically meant Task and didn't dig too much because I didn't expect it to be as important as the executor for my understanding.

Maybe additionally having something like "When a task is woken up, its Task reference is recreated and passed to the schedule function. In most executors, scheduling simply pushes the Task reference into a queue of runnable tasks." from the async_task docs would make it even clearer.

Perhaps in this case, it's not even about better definitions, but about providing breadcrumbs to the connections. While your comment definitely helps with my deeper understanding of Runnable, it may not have jumped out to me when trying to put the pieces together, unless I saw awake task ... schedule... executor... queue.

And perhaps it's also just a case of me having an incorrect model which made it hard for me to see what's in front of me. :)

So, it may be good to wait and see if others have the same issue I do before deciding whether to do anything.

from smol.

I see, thank you for the elaborate explanation of your thought process :)

I can try to improve the comments later, but if you'd like to help and add them yourself, go ahead! I believe you could even just click "edit" on GitHub, add more comments, and submit a PR.

from smol.