Create eventqueue-background.md #507
Conversation
Create tutorial to fulfill issue #494
There was a problem hiding this comment.
@kjbracey-arm @geky Could one of you please address my two comments?
|
|
||
| You want to tightly control the memory consumption of each event loop. | ||
|
|
||
| Consider an example Sonar class driven by a complicated FSM that I'm too lazy to write: |
There was a problem hiding this comment.
Could an engineer please create an example to replace this one?
There was a problem hiding this comment.
Petition to replace this with a link to the sonar example as per our discussion @geky @AnotherButler
There was a problem hiding this comment.
@geky @AnotherButler Thoughts on the sonar example link?
There was a problem hiding this comment.
Sounds reasonable to me. That or we could just remove the sentence about laziness. The example does have the part that's important to users of the event queue.
I'd remove it but I don't think I can push to this branch.
| You can even pass 0 ms to execute any pending events and return immediately, which lets you spend all of your time blinking the LED. | ||
|
|
||
| However, that's still rather limiting. If you want to do stuff in your thread, execute events _and_ sleep, you need to learn how long to sleep from the event queue. However, because any IRQ can update the event queue, the time to sleep can change, so you also need a way to receive notifications when a new sleep time has been decided. | ||
|
|
There was a problem hiding this comment.
Query: Could we summarize lines 6-58 with "Performing concurrent functions with an event queue can become complicated. For example, to concurrently perform operations in a thread, execute events and sleep, you need to..."?
I ask because we're spending 50+ lines to show a user how not to solve a problem. User documentation should tell users what to do, not what not to do. Similarly, user documentation can tell users why we chose the features we did, but it shouldn't say why we didn't choose the features we didn't.
There was a problem hiding this comment.
These examples build up the problem and also demonstrate alternative solutions that a user may choose if they don't have the exact problem we're demonstrating a solution for.
Performing concurrent functions with an event queue can become complicated. For example, to concurrently perform operations in a thread, execute events and sleep
What if the user doesn't care about sleeping? Where do they go? Should they stop reading this tutorial?
There was a problem hiding this comment.
If this is a tutorial about EventQueue.background, it should tell people what this is and how and when to use it. It should not give lots of solutions for lots of problems that aren't related to using this method.
When I read this, what I got out of it is that you need EventQueue.background if "you want to do stuff in your thread, execute events and sleep" because you need to learn how long to sleep from the event queue. Are there other use cases? Is this just a specific example of a much broader use? If so, it's not obvious.
That's why I'm trying to summarize a general use case for this method. That's why I'm asking if adding a sentence such as "Performing concurrent functions with an event queue can become complicated." would help. It doesn't make sense to spend 50 lines telling users how other solutions to a specific situation don't work instead of telling people when to use the method we're describing.
There was a problem hiding this comment.
This doesn't match what I thought the tutorials are. Why would this documentation go here and not in the reference page?
Where do we put documentation that tells users how to solve problems?
I'm happy if this is the wrong place for that to go, but I want to know where that is.
There was a problem hiding this comment.
A tutorial about using the dispatch function should be a step-by-step guide about how and when to use the dispatch function. A tutorial about how to use dispatch without consuming the whole thread should be a step-by-step guide to using dispatch without consuming the whole thread and should talk about passing a timeout for 0 ms. A tutorial about EventQueue.background should be a step-by-step guide about how and when to use EventQueue.background. A tutorial about EventQueue.background should not be a guide about how to solve problems without using EventQueue.background. Does that make sense?
If the purpose of this tutorial is how to EventQueue.background, other information about how to solve unrelated problems without using EventQueue.background don't belong on this page. They could be great information we could include somewhere else, but it seems distracting.
There was a problem hiding this comment.
Ah so this tutorial should be renamed to "how to run event queues without extra threads"?
Considering it ends with "here's how you use EventQueue.chain" it sounds like this document doesn't fit here at all.
(I'm still confused how "how to EventQueue.background" is not the same as the reference page)
There was a problem hiding this comment.
Yes, that works. I thought community developers were asking for how to use EventQueue.background, but if they're really asking how to run event queues without extra threads, then we can use that as a title and keep the beginning information here.
|
@geky @kjbracey-arm ping |
|
Fyi, @kjbracey-arm is still on vacation. |
|
Looks good to me except the lazy sentence |
|
@kjbracey-arm Should be back now ;) |
|
@yennster FYI |
|
We still don;t have event queue background information in docs, this PR is relevant. Please add this to docs so we can close ARMmbed/mbed-os#6759. Not sure what is pending here |
|
Because we don't have plans to resolve this PR in the near future, I'm closing this PR. We can reopen it at a later date if necessary. |
|
@AGlass0fMilk how do you feel about this closing? |
|
I don't understand the closure here neither. How can we fix this one? Should this be taken over by someone else? |
7 participants
Create tutorial to fulfill issue #494