X-Git-Url: http://nitlanguage.org

diff --git a/lib/signals.nit b/lib/signals.nit
index 7d67bc0..89f4a1b 100644
--- a/lib/signals.nit
+++ b/lib/signals.nit
@@ -24,6 +24,21 @@ module signals
 	#include <stdio.h>
 
 	/*
+		This guard prevents errors by the C compiler when the Nit code imports this
+		module but do not use handle_signal. When it is _not_ used, the C type
+		SignalHandler and C function SignalHandler_receive_signal are not generated.
+		Which does not please the C compiler. This guard ensure that we compile this
+		code only if the type SignalHandler has been defined.
+
+		This is a HACK, FIXME by:
+		* Adding the macro to the FFI spec, or
+		* Attach the callbacks to this code block (or the module itself)
+		* Avoid using Nit types and callbacks or use them only in the C implementation
+		  of Nit method.
+	*/
+	#ifdef NIT_TYPE_SignalHandler
+
+	/*
 		Structure to manage each possible signals
 		are used in an array of 32 maximum signals.
 		This array is global to the software.
@@ -49,22 +64,53 @@ module signals
 			}
 		}
 	}
+
+	#endif
 `}
 
 # Receives the callback from system when a given signal arise
 interface SignalHandler
-	# Called on any signal received
-	fun receive_signal(signal: Int) `{
-	`}
-
-	# Called on any unsafe signal received
-	fun receive_signal_unsafe(signal: Int) `{
-	`}
+	# Invoked after a call to `check_signals` if a signal has been raised
+	# (should be redefed by subclasses)
+	#
+	# Should be used by most signals except `sigkill` and `sigstop` since they
+	# cannot be caught, blocked or ignored.
+	#
+	#     class MyReceiver
+	#         super SignalHandler
+	#     
+	#         redef fun receive_signal(signal) do print "received safely {signal}"
+	#     end
+	#     
+	#     var r = new MyReceiver
+	#     r.handle_signal(sigint, true) # will call back when "check_signals" is called
+	#     # ...
+	#     check_signals # if a signal was received, it will invoke `r.receive_signal`
+	fun receive_signal(signal: Int) do end
+
+	# Called immediatly on receiving an unsafe signal (should be redefed by subclasses)
+	#
+	# Should be used for `sigkill` and `sigstop` since they cannot be caught,
+	# blocked or ignored.
+	#
+	# You should consider this methods as being fragile. It should be implemented in C
+	# and you should not do too much callbacks to Nit.
+	#
+	#     class MyReceiver
+	#         super SignalHandler
+	#     
+	#         redef fun receive_signal_unsafe(signal) do print "received unsafely {signal}"
+	#     end
+	#     
+	#     var r = new MyReceiver
+	#     r.handle_signal(sigsegv, false) # `r.receive_signal_unsafe` will be invoked on sigsegv
+	fun receive_signal_unsafe(signal: Int) do end
 
 	# Set the receiver as the handler of the signal
-	# If safely, receiver will be called when check_signals in invoked
-	#    otherwise the receiver is invoked when the signal is raised, it may
-	#    crash the Nit system but is unavoidable for unstoppable signals
+	#
+	# If `safely`, receiver will be called when `check_signals` in invoked
+	# otherwise the receiver is invoked when the signal is raised, it may
+	# crash the Nit system but is unavoidable for unstoppable signals.
 	fun handle_signal(signal: Int, safely: Bool) import
 		receive_signal `{
 		SignalHandler last_handler;