[Issue 17850] New: Poor Documentation of the Realtime thread feature

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=17850

          Issue ID: 17850
           Summary: Poor Documentation of the Realtime thread feature
           Product: D
           Version: D2
          Hardware: x86_64
                OS: Windows
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: vorlent at web.de

I've spent far more time than an average C/C++ developer taking a quick glance
at Dlang and then immediately dismissed it as not suitable because it has a gc
and yet I still had trouble finding this feature and even after knowing it
exists it still wasn't easy to find it. Without seeing some ad hoc comments
from Walter Bright on reddit I probably would even know a about the existence
of this feature at all. The other reddit users always suggested a suboptimal
solution to the problem.

The https://dlang.org/spec/garbage.html page drowns you with a wall of text yet
hides the ability to avoid the garbage collector for individual threads. This
is a critical feature for D to compete with C/C++/Rust rather than Java or the
billion other programming languages with a garbage collector. Without it I
didn't even consider using D at all.

"Normally, all threads other than the collector thread must be halted while the
collection is in progress."

Should be clarified by something along the lines of "The stop the world pause
can be mitigated by detaching the thread from the runtime to turn it into a
realtime thread. The thread function of a realtime thread must be marked with
@nogc and it must not hold any GC roots." which is written here
https://wiki.dlang.org/Memory_Management#Real_Time but unless you're looking
for it you won't find it.

I also have a problem with the documentation of the detaching functions.

https://dlang.org/phobos/core_thread.html#.thread_detachThis
"Deregisters the calling thread from use with the runtime. If this routine is
called for a thread which is not registered, the result is undefined."

They do not clarify what detaching the runtime actually does. At the very least
the documentation should mention that detached threads will not be paused by
the garbage collector.

The general description of the thread class should also hint at the possibility
of realtime threads so that it will be more visible even to those who just want
to use regular threads which should include most developers.

https://dlang.org/phobos/core_thread.html#.Thread

Finally I would suggest that someone writes a small blogpost about realtime
threads that illustrates how to use them which hopefully appears at the top of
google search results.

--