Page 1 of 1
A few documentation typos in doxgen automatic links and release of threads
Posted: Wed Feb 12, 2025 4:15 pm
by anotheruserofchibios
Hi,
I spotted a few typos in the documentation:
- "Initializes s @p" -> "Initializes a @p"
- @p bsem -> @p chBSem
- @p chthd -> @p chThd
- @p threads.h -> @p chschd.h
- how to release dynamic threads and when they are removed from registry
Please find attached a single patch file containing multiple commits (one for each of the above points).
I'm not so sure about the last point but I think the documentation was not consistent everywhere. It may still be improved of course.
Kind regards,
Re: A few documentation typos in doxgen automatic links and release of threads
Posted: Wed Feb 12, 2025 5:35 pm
by Giovanni
Thanks, typo fixes are never enough
Giovanni
Re: A few documentation typos in doxgen automatic links and release of threads
Posted: Tue Jul 01, 2025 9:55 am
by Giovanni
Fixes committed, thanks.
Giovanni
Re: A few documentation typos in doxgen automatic links and release of threads
Posted: Tue Jul 01, 2025 8:35 pm
by anotheruserofchibios
Hi,
Thank you for the commit. Apparently you didn't apply the last pieces of the diff, was it intended? Specifically:
Code: Select all
diff --git a/os/rt/src/chthreads.c b/os/rt/src/chthreads.c
index 6663e4b71..56880fd42 100644
--- a/os/rt/src/chthreads.c
+++ b/os/rt/src/chthreads.c
@@ -622,10 +622,12 @@ thread_t *chThdAddRef(thread_t *tp) {
* returned to the proper allocator and the thread is removed
* from the registry.<br>
* Threads whose counter reaches zero and are still active become
- * "detached" and will be removed from registry on termination.
+ * "detached". Detached static threads will be removed from the
+ * registry on termination. Detached non-static threads can only be
+ * removed by performing a registry scan operation.
* @pre The configuration option @p CH_CFG_USE_REGISTRY must be enabled in
* order to use this function.
- * @note Static threads are not affected.
+ * @note Static threads are not affected, only removed from the registry.
*
* @param[in] tp pointer to the thread
*
@@ -741,7 +743,7 @@ void chThdExitS(msg_t msg) {
* @details This function waits for the specified thread to terminate then
* decrements its reference counter, if the counter reaches zero then
* the thread working area is returned to the proper allocator and
- * the thread is removed from registry.
+ * the thread is removed from the registry.
* @pre The configuration option @p CH_CFG_USE_WAITEXIT must be enabled in
* order to use this function.
* @post Enabling @p chThdWait() requires 2-4 (depending on the
diff --git a/os/various/cpp_wrappers/ch.hpp b/os/various/cpp_wrappers/ch.hpp
index 72328e0b4..33bc6ca83 100644
--- a/os/various/cpp_wrappers/ch.hpp
+++ b/os/various/cpp_wrappers/ch.hpp
@@ -680,11 +680,13 @@ namespace chibios_rt {
* returned to the proper allocator and the thread is removed
* from the registry.<br>
* Threads whose counter reaches zero and are still active become
- * "detached" and will be removed from registry on termination.
+ * "detached". Detached static threads will be removed from the
+ * registry on termination. Detached non-static threads can only be
+ * removed by performing a registry scan operation.
* @pre The configuration option @p CH_CFG_USE_REGISTRY must be enabled in
* order to use this function.
* @post The reference is set to @p nullptr.
- * @note Static threads are not affected.
+ * @note Static threads are not affected, only removed from the registry.
*
* @api
*/
My intent was to clarify what happens for static and dynamic (i.e., non-static) threads, respectively. Because clearly, "will be removed from registry on termination" is wrong for non-static threads, and "static threads are not affected" is wrong regarding removal from the registry. Am I mistaken?
Re: A few documentation typos in doxgen automatic links and release of threads
Posted: Tue Jul 01, 2025 9:04 pm
by Giovanni
Hi,
Strange, I applied the whole thing, will do also this one tomorrow.
Giovanni
Re: A few documentation typos in doxgen automatic links and release of threads
Posted: Wed Jul 02, 2025 12:52 pm
by anotheruserofchibios
Still missing a few things, you should scroll the code block in my previous message. :)
Re: A few documentation typos in doxgen automatic links and release of threads
Posted: Thu Jul 03, 2025 1:53 pm
by anotheruserofchibios
Last bit on
this line to be consistent:
Code: Select all
- * @note Static threads are not affected.
+ * @note Static threads are not affected, only removed from the registry.
Thank you!