Update Thread.md #1166
Update Thread.md #1166
Conversation
Add helpful tips from discussion in another repository (internal ticket IOTDOCS-1220).
|
@kjbracey-arm Could you please review this to make sure it's right? Is this also where information about thread state (Ready, Blocked and so on) and |
docs/api/rtos/Thread.md
Outdated
| @@ -10,6 +10,8 @@ The Thread class allows defining, creating and controlling parallel tasks. | |||
|
|
|||
| All the internal thread data structures are part of the C++ class, but by default, the thread stack is allocated on the heap. Memory is allocated at the run time during the call to `start` method. If you don't want to use dynamic memory, you can provide your own static memory using the constructor parameters. | |||
|
|
|||
| The main thread stack size is specified as `rtos.main-thread-stack-size` in the configuration .json file. That defines the main thread for `mbed_rtos_start` in `mbed_rtos_rtx.c`. | |||
There was a problem hiding this comment.
Correct, but I think this needs to be the third paragraph. The paragraphs above and below are talking about extra threads you create using the Thread API, but this paragraph is a side point about the memory for the starting main thread (which is not created using Thread).
Possibly it should be a "Note", like in the section above.
It could go here, yes, I can't immediately think of anywhere better. They're both about debugging threads, so if we have a general "debugging tips" page they could go there, but could be notes here. (The |
Move content and format it as a note, as requested in comments.
Add a debugging tips section.
docs/api/rtos/Thread.md
Outdated
| @@ -89,6 +89,12 @@ The Callback API provides a convenient way to pass arguments to spawned threads. | |||
|
|
|||
| [](https://os.mbed.com/teams/mbed_example/code/rtos_threading_with_callback/file/5938bdb7b0bb/main.cpp) | |||
|
|
|||
| ## Debugging tips | |||
|
|
|||
| When debugging Thread, check the full RTX state (ready, blocked and so on) for a deadlock (two things waiting for each other) or a missed signal leading to an event machine stall. You can confirm a deadlock if you see two threads in the "blocked" state waiting for a resource that the other is supposed to signal. | |||
There was a problem hiding this comment.
"debugging threads", I think is better. Otherwise it should be Thread.
"waiting for" -> "each waiting for"?
docs/api/rtos/Thread.md
Outdated
|
|
||
| When debugging Thread, check the full RTX state (ready, blocked and so on) for a deadlock (two things waiting for each other) or a missed signal leading to an event machine stall. You can confirm a deadlock if you see two threads in the "blocked" state waiting for a resource that the other is supposed to signal. | ||
|
|
||
| To reduce deadlocks, proactively code in a safe way by maintaining a mental ordering of your mutexes and never claiming a high-level mutex while holding a low-level one. |
There was a problem hiding this comment.
"mental ordering" sounds weird. Maybe just "ordering"?
I guess the point is that the system doesn't enforce this, so there's no way to follow this rule apart from self-discipline. Feels like you needs some sort of adjective to suggest that, but can't think of anything better.
(For comparison, in Symbian, to help with this, every mutex had a program-specified level number, and debug builds would stop with a diagnostic if you ever claimed a high-level one while holding a low-level one. Although being a debug-build-only check was annoying - if someone broke the rule and never tried a debug build, then other people found out when they made a debug build to look at their stuff and found the system stopped with a mutex diagnostic in debug mode. Debug builds weren't tested in CI.)
Update phrasing, as requested in comments, for clarity.
Add helpful tip from discussion in another repository (internal ticket IOTDOCS-1220) by applying changes from PR #1166
Add helpful tip from discussion in another repository (internal ticket IOTDOCS-1220).