[glibc] stdlib: Describe __cxa_finalize usage in function comment

[glibc] stdlib: Describe __cxa_finalize usage in function comment

[Florian Weimer]

https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=992daa0b4b5fa8a9f403c9575638cec288e12bfa

commit 992daa0b4b5fa8a9f403c9575638cec288e12bfa
Author: Florian Weimer <fweimer@redhat.com>
Date:   Mon Jun 3 19:04:58 2024 +0200

    stdlib: Describe __cxa_finalize usage in function comment
    
    Reviewed-by: Jonathan Wakely <jwakely@redhat.com>

Diff:
---
 stdlib/cxa_finalize.c | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/stdlib/cxa_finalize.c b/stdlib/cxa_finalize.c
index 258fa56ce5..496141d802 100644
--- a/stdlib/cxa_finalize.c
+++ b/stdlib/cxa_finalize.c
@@ -24,7 +24,22 @@
 
 /* If D is non-NULL, call all functions registered with `__cxa_atexit'
    with the same dso handle.  Otherwise, if D is NULL, call all of the
-   registered handlers.  */
+   registered handlers.
+
+   A __cxa_finalize function is declared in the libstdc++ <cxxabi.h>
+   header, and the libstdc++ implementation calls this function.  GCC
+   calls the glibc variant directly from its CRT files, from an ELF
+   destructor.  this call always passes a non-null D argument.  In the
+   current implementation, the GCC-provided __cxa_finalize call is
+   responsible for removing the registered __cxa_atexit (C++)
+   destructors of an object that is undergoing dlclose.  Note that
+   this is specific to dlclose.  During process termination, glibc
+   invokes the __run_exit_handlers, which calls registered
+   __cxa_atexit (C++) destructors in reverse registration order,
+   across all objects.  The subsequent GCC-provided __cxa_finalize
+   calls (which are ordered according to ELF object dependencies, not
+   __cxa_atexit call order, and group destructor calls per object
+   during dlclose) do not result in further destructor invocations.  */
 void
 __cxa_finalize (void *d)
 {