Add a comment to mg.c to clarify that words like "raise" and

"pending" in the context of Perl's deferred signals bear only
an analogous relationship to the underlying signal mechanism.

p4raw-id: //depot/perl@30393

1 files changed, 13 insertions, 0 deletions

diff --git a/mg.c b/mg.c
index 47d9cb437c..b9b2ca288a 100644
--- a/mg.c
+++ b/mg.c
@@ -1278,6 +1278,19 @@ Perl_magic_clearsig(pTHX_ SV *sv, MAGIC *mg)
     return 0;
 }
 
+/*
+ * The signal handling nomenclature has gotten a bit confusing since the advent of
+ * safe signals.  S_raise_signal only raises signals by analogy with what the 
+ * underlying system's signal mechanism does.  It might be more proper to say that
+ * it defers signals that have already been raised and caught.  
+ *
+ * PL_sig_pending and PL_psig_pend likewise do not track signals that are pending 
+ * in the sense of being on the system's signal queue in between raising and delivery.  
+ * They are only pending on Perl's deferral list, i.e., they track deferred signals 
+ * awaiting delivery after the current Perl opcode completes and say nothing about
+ * signals raised but not yet caught in the underlying signal implementation.
+ */
+
 #ifndef SIG_PENDING_DIE_COUNT
 #  define SIG_PENDING_DIE_COUNT 120
 #endif