From f52c4ab7215d81d7fea1fd2f4043b1f20c92dce3 Mon Sep 17 00:00:00 2001 From: Jakob Nybo Nissen Date: Thu, 23 Jan 2025 12:12:15 +0100 Subject: [PATCH] Expand on docstring of GC.safepoint (#57128) Update the docstring to mention the following points: * Safepoints are very fast, but may still degrade performance in tight loops * Safepoints do not trigger the GC, but instead stops a task from blocking GC that would otherwise run. * Switch terminology from mentioning 'threads' to 'tasks' --- base/gcutils.jl | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/base/gcutils.jl b/base/gcutils.jl index 84a184537ffc0..60b8ecdd17d65 100644 --- a/base/gcutils.jl +++ b/base/gcutils.jl @@ -243,12 +243,21 @@ end GC.safepoint() Inserts a point in the program where garbage collection may run. -This can be useful in rare cases in multi-threaded programs where some threads -are allocating memory (and hence may need to run GC) but other threads are doing -only simple operations (no allocation, task switches, or I/O). -Calling this function periodically in non-allocating threads allows garbage + +Safepoints are fast and do not themselves trigger garbage collection. +However, if another thread has requested the GC to run, reaching a safepoint will +cause the current thread to block and wait for the GC. + +This can be useful in rare cases in multi-threaded programs where some tasks +are allocating memory (and hence may need to run GC) but other tasks are doing +only simple operations (no allocation, task switches, or I/O), which do not +yield control to Julia's runtime, and therefore blocks the GC from running. +Calling this function periodically in the non-allocating tasks allows garbage collection to run. +Note that even though safepoints are fast (typically around 2 clock cycles), +they can still degrade performance if called in a tight loop. + !!! compat "Julia 1.4" This function is available as of Julia 1.4. """