Doc tweaks for ev/deadline and ev/with-deadline

[sogaiu]

This is an attempt to address #1349.

Background can be seen in that issue, and a summary is available at this comment.

Thanks to @amano-kenji and @llmII for discussions and investigations.

[amano-kenji]

That's confusing as hell.......

[sogaiu]

I'm still working on ev/with-deadline.

These are very much in draft state, but FWIW.

I'm very much against inventing fictions for the most part.

[sogaiu]

@amano-kenji Please stop with the use of profanity and consider rephrasing the instances made already.

It is completely unnecessary. Alternative expressions would do fine.

[amano-kenji]

Fine... But, that docstring doesn't explain the intention behind ev/with-deadline.

[sogaiu]

Which docstring are you referring to? The current one?

I don't necessarily disagree.

[llmII]

@amano-kenji It is known that obviating what exactly is getting canceled with ev/with-deadline is difficult, to the degree I nop'd and went with just say exactly what happens. The only other way I could figure out to outline what's getting canceled would mean the docstring would contain documentation on the event loop.

@sogaiu Looking at those I so far like the first one the best.

[amano-kenji]

the value of (fiber/root) will be canceled

This sounds esoteric and confusing. It would throw me off balance if I haven't been in the discussion for the last few days.

I would write

The task(the root fiber) running the body of ev/with-deadline will be cancelled with an error.

If the body of ev/with-deadline blocks the whole task with CPU intensive operations, then what happens? Perhaps, the task will receive an error after the body finishes CPU intensive operations?

[sogaiu]

If the body of ev/with-deadline blocks the whole task with CPU intensive operations, then what happens?

I didn't test, but IIUC, the website docs say this about the event loop:

When using the event loop, it is important to be aware that CPU bound loops will block all other tasks on the event loop.

Have you read that page recently?

[amano-kenji]

So, reception of the cancellation error will be delayed after deadline if the body of ev/with-deadline stalls the task.

[sogaiu]

As I mentioned, I have not tested.

[llmII]

I would write

The task(the root fiber) running the body of ev/with-deadline will be cancelled.

That's closer to the wording @sogaiu has in what he linked which I'm fine with.

If the body of ev/with-deadline blocks the whole task with CPU intensive operations, then what happens?

It does exactly that, it blocks the whole task... It's why we can't say that ev/with-deadline kills the body because the body can be ill-behaved. It could even perhaps interact with some event loop from another project where it ends up not actually being cpu intensive but since it never calls into Janet's event loop it actually successfully completes.

[amano-kenji]

The value of (fiber/root)

This has a disorienting effect on my psyche. This is a riddle unless the relationship between the root fiber and the body of ev/with-deadliine is made clear.

The word, root fiber, still throws me off balance. The value of (fiber/root) throws me off balance even more.

I kind of understand the root fiber, but I don't really.

[llmII]

That relationship I believe is beyond the scope of a docstring (wherein it'd likely pertain to documenting the event loop in more detail than belongs in a docstring). That said, something similar to your wording of

The task (the root fiber) running

is fine with me.

@sogaiu has a link that if you look has similar wording for one of the ideas of what the docstring should be.

[sogaiu]

Re: (fiber/root)

This sounds esoteric and confusing.

I think this is not a reasonable characterization for a few reasons:

• It specifically mentions something you can look up the docstring for
• fiber/root is explicitly mentioned in the website docs event loop page in this section

ev/* callables have to do with the event loop and the docstrings for ev/deadline and ev/with-deadline should be able to assume a certain amount of familiarity with the event loop.

---

If you are thrown off-balance, perhaps you should consider whether there are other factors that are contributing to that as well. Are you calm right now? Or are you caught up in emotion?

[amano-kenji]

I read the event loop documentation three times from top to bottom while working on j3blocks. Perhaps, the documentation doesn't inculcate the concept of root fiber enough.

Root fiber just slips off my memory...

[sogaiu]

Glad you read them.

I am thinking to suggest the addition of a glossary to the website docs. You can see the beginning of a draft here.

[amano-kenji]

I think https://janet-lang.org/docs/event_loop.html doesn't account for the fact that humans don't remember concepts they pass by just once.

Only after they encounter example making you think about root fiber several times, root fiber sinks in your psyche.

[sogaiu]

Your observations are not lost on me. It's part of why I work on docstrings and examples and have been doing so over the past few years.

[amano-kenji]

Because humans just forget words they pass by briefly, docstring should reinforce the concept of root fiber... here and there....

The task (the root fiber) running the body of ev/with-deadline will be cancelled..

This reinforces the concept of root fiber and task, and makes people read the documentation again...

[sogaiu]

I don't agree with that necessarily though.

Update: the text that the above was a response to changed after I wrote the text above. So I am adding a fuller response below.

---

I find the reasoning in:

Because humans just forget words they pass by briefly, docstring should reinforce the concept of root fiber... here and there....

to be flawed.

However, I don't disagree that occasional hints / reinforcement in docstrings is necessarily a bad idea and I have actually been doing this.

Regarding "humans just forget words they pass by briefly" -- knowing this, I think the authors of documents can make an effort, but at the same time, readers can also take steps to help themselves in ways customized to their own needs.

One concrete step one can take is to take one's own notes along with writing and keeping sample code. This can also include the projects one has worked on. This method has worked well for me -- I am often able to recreate enough context / knowledge by looking over what I produced earlier. It's also much safer from other parties modifying it (^^;

---

I'll stop here though because this is not about this issue directly.

[sogaiu]

I'll remind you that bakpakin has stated that this is an issue tracker and not a chat room.

Please consider our discussion from yesterday regarding drafting your responses and going over them / revising them before posting.

[amano-kenji]