Re-indent all the comments

Author: Frizlab

Doc/signal-tests/run-tests.sh

@@ -3,7 +3,7 @@ set -uo pipefail
 
 readonly LINUX_SWIFT_IMAGE="swift:5.3.3"
 
-# This can only be run on macOS
+# This can only be run on macOS.
 test "$(uname -s)" = "Darwin"
 
 cd "$(dirname "$0")"
@@ -36,7 +36,7 @@ docker run --rm -it -v "$(pwd):/tmp/cwd" --workdir /tmp/cwd --security-opt=secco
 echo
 echo
 echo "*** RUNNING GENERIC TESTS (SWIFT) ON MACOS"
-# We must compile, when run via swift as a script, some signal are handled by Swift itself
+# We must compile, when run via swift as a script, some signal are handled by Swift itself.
 swiftc ./signal-tests-macos.swift && ./signal-tests-macos
 rm signal-tests-macos
 

Doc/signal-tests/signal-test-blocked.c

@@ -105,11 +105,10 @@ int main(int argc, const char * argv[]) {
 	fprintf(stderr, "✊ Main thread pending: %d\n", sigismember(&set, s));
 
 	sleep(3);
-	/* On macOS, when all threads block the signal, the system chooses one thread
-	 * and assigns the signal to it. Unblocking in another thread won’t move the
-	 * signal to it, and we won’t be able to access it.
-	 * On Linux, when a process-wide signal is pending, it is pending on all
-	 * the threads. If a thread unblocks the signal, it will handle it. */
+	/* On macOS, when all threads block the signal, the system chooses one thread and assigns the signal to it.
+	 * Unblocking in another thread won’t move the signal to it, and we won’t be able to access it.
+	 * On Linux, when a process-wide signal is pending, it is pending on all the threads.
+	 * If a thread unblocks the signal, it will handle it. */
 	fprintf(stderr, "✊ Unblocking signal\n");
 	pthread_mutex_lock(&mutex);
 	thread_action = UNBLOCK_SIGNAL;

Doc/signal-tests/signal-test-sigaction.c

@@ -24,9 +24,8 @@ int main(void) {
 	struct sigaction newAction = {};
 	newAction.sa_flags = 0;
 	sigemptyset(&newAction.sa_mask);
-	/* We do not use sa_sigaction because it generates a warning on Linux w/
-	 * function signature `void action(int, struct __siginfo *, void *)` because
-	 * args are not exactly the same as on macOS, but would work too */
+	/* We do not use sa_sigaction because it generates a warning on Linux w/ function signature `void action(int, struct __siginfo *, void *)`
+	 *  because args are not exactly the same as on macOS, but would work too. */
 	newAction.sa_handler = &action;
 	sigaction(15, &newAction, NULL);
 	fprintf(stderr, "%p\n", newAction.sa_handler);

Doc/signal-tests/signal-tests-linux.swift

@@ -80,7 +80,7 @@ if doFirstTest {
 	print("after dispatch and delay: newAction: \(oldActionHandlerPtr == newActionHandlerPtr)")
 	print("after dispatch and delay: mask: \(oldAction.sa_mask)")
 	print("after dispatch and delay: flags: \(oldAction.sa_flags)")
-	/* raise and kill are not the same in a multi-threaded env */
+	/* raise and kill are not the same in a multi-threaded env. */
 	//raise(15)
 	kill(getpid(), 15)
 	sleep(1)
@@ -116,7 +116,7 @@ if doSecondTest {
 	pthread_cond_wait(&cond, &mutex)
 	pthread_mutex_unlock(&mutex);
 
-	/* Thread is initialized and running */
+	/* Thread is initialized and running. */
 	print("thread initialized and running")
 
 	sigaction(15, &defaultAction, nil)

Doc/signal-tests/signal-tests-macos.swift

@@ -64,7 +64,7 @@ if doFirstTest {
 	print("after dispatch: flags: \(oldAction.sa_flags)")
 
 	usleep(500)
-	/* raise and kill are not the same in a multi-threaded env */
+	/* raise and kill are not the same in a multi-threaded env. */
 	//raise(15)
 	kill(getpid(), 15)
 	sleep(1)
@@ -100,7 +100,7 @@ if doSecondTest {
 	pthread_cond_wait(&cond, &mutex)
 	pthread_mutex_unlock(&mutex);
 
-	/* Thread is initialized and running */
+	/* Thread is initialized and running. */
 	print("thread initialized and running")
 
 	sigaction(15, &defaultAction, nil)

Readme.adoc

@@ -1,11 +1,9 @@
 = Signal Handling in Swift
 François Lamboley <francois[email protected]>
 
-This package provides a Swift syntax for the low-level C `sigaction` function
-and a way to delay or cancel sigaction handlers.
+This package provides a Swift syntax for the low-level C `sigaction` function and a way to delay or cancel sigaction handlers.
 
-It is compatible with macOS and Linux. Read the documentation carefully before
-using the sigaction handler delaying capabilities.
+It is compatible with macOS and Linux. Read the documentation carefully before using the sigaction handler delaying capabilities.
 
 == Example of Use
 
@@ -34,8 +32,7 @@ let delayedSigaction = try SigactionDelayer_Unsig.registerDelayedSigaction(Signa
 })
 ----
 
-With both examples in the same code, when the program receives the terminated
-signal (15 on macOS), the following will be logged:
+With both examples in the same code, when the program receives the terminated signal (15 on macOS), the following will be logged:
 
 [source,text]
 ----
@@ -46,94 +43,75 @@ Handling signal SIGTERM from sigaction
 
 == How Does Delaying the Sigaction Work?
 
-Delaying a signal is an unusual process and you should be aware of the inner
-workings of this method before using it.
+Delaying a signal is an unusual process and you should be aware of the inner workings of this method before using it.
 
-We have two delaying strategies. One sets the signal as ignored until the signal
-is allowed to go through (`SigactionDelayer_Unsig`); the other blocks the
-incoming signal until the signal is allowed to go through
-(`SigactionDelayer_Block`).
+We have two delaying strategies.
+One sets the signal as ignored until the signal is allowed to go through (`SigactionDelayer_Unsig`);
+ the other blocks the incoming signal until the signal is allowed to go through (`SigactionDelayer_Block`).
 
 Both strategies have pros and cons.
 
-While the signal is blocked or ignored, it is also monitored using `libdispatch`
-(aka. GCD), which itself monitors the signals using `kqueue` on BSD and
-`signalfd` on Linux. This allows unblocking the signal or setting the sigaction
-handler when needed.
+While the signal is blocked or ignored, it is also monitored using `libdispatch` (aka. GCD),
+ which itself monitors the signals using `kqueue` on BSD and `signalfd` on Linux.
+This allows unblocking the signal or setting the sigaction handler when needed.
 
-**Important caveat of both methods**: `libdispatch` can only detect signals sent
-to the whole process, not threads. A delayed signal sent to a thread is thus
-blocked or ignored forever.
+**Important caveat of both methods**:
+`libdispatch` can only detect signals sent to the whole process, not threads.
+A delayed signal sent to a thread is thus blocked or ignored forever.
 
 === Details of the Unsigaction Strategy (`SigactionDelayer_Unsig`)
 
 This is the recommended method.
 
-This method does not require any particular bootstrap. You can delay a signal
-whenever you want.
+This method does not require any particular bootstrap.
+You can delay a signal whenever you want.
 
-Once a signal has been registered for delay though, the sigaction should not be
-manually changed. (Exception being made of the `install` method provided by the
-`Sigaction` struct in this project, which is aware of the possible unsigactions
-on the signal and can update them accordingly.)
+Once a signal has been registered for delay though, the sigaction should not be manually changed.
+(Exception being made of the `install` method provided by the `Sigaction` struct in this project,
+ which is aware of the possible unsigactions on the signal and can update them accordingly.)
 
 When a signal is first registered for delay a few things happen:
 
 * The sigaction handler is saved in an internal structure;
 * The signal is set to be ignored;
-* A dedicated thread is spawned (if not already spawned), which unblocks all
-signals;
+* A dedicated thread is spawned (if not already spawned), which unblocks all signals;
 * A dispatch source is created to monitor the incoming signal using GCD.
 
 Then, when a signal is received, this happens:
 
 * `libdispatch` notifies the sigaction delayer, which will in turn
-* Reinstall temporarily the saved sigaction for the signal (after the clients
-say it’s ok), and
-* Send the signal to the dedicated thread. This triggers the sigaction but does
-not notify `libdispatch`.
+* Reinstall temporarily the saved sigaction for the signal (after the clients say it’s ok), and
+* Send the signal to the dedicated thread. This triggers the sigaction but does not notify `libdispatch`.
 * Finally, the delayer sets the signal back to being ignored.
 
 **Caveats of this method**:
 
-* There is a non-avoidable race-condition (AFAICT) between the time the signal
-is sent and set back to ignored;
+* There is a non-avoidable race-condition (AFAICT) between the time the signal is sent and set back to ignored;
 * The signal that is sent back has lost the siginfo of the original signal;
-* On Linux signal delaying is fragile. See Linux caveat of the blocking strategy
-for more information.
+* On Linux signal delaying is fragile. See Linux caveat of the blocking strategy for more information.
 
 === Details of the Blocking Strategy (`SigactionDelayer_Block`)
 
-You must bootstrap this method before using it, giving the bootstrap method all
-the signals you’ll want to delay, _before any threads are created_.
-The bootstrap will first block all the given signals on the current (main)
-thread, then spawn a thread on which all these signals will be unblocked.
+You must bootstrap this method before using it, giving the bootstrap method all the signals you’ll want to delay, _before any threads are created_.
+The bootstrap will first block all the given signals on the current (main) thread,
+ then spawn a thread on which all these signals will be unblocked.
 
-This allows our dedicated thread to be the only one allowed to receive the
-signals that are to be monitored.
+This allows our dedicated thread to be the only one allowed to receive the signals that are to be monitored.
 
-When a signal is registered for delay, the delayer will block the signal on the
-dedicated thread too!
+When a signal is registered for delay, the delayer will block the signal on the dedicated thread too!
 
-When the signal is received, `libdispatch` will notify the delayer, which will
-unblock the signal, thus allowing it to be delivered.
+When the signal is received, `libdispatch` will notify the delayer, which will unblock the signal, thus allowing it to be delivered.
 
 **Caveats of this method**:
 
-* On macOS, when a signal blocked on all threads is received, it seems to be
-assigned to an arbitrary thread. Unblocking the signal on another thread will
-not unblock it at all. To workaround this problem we check if the signal is
-pending on the dedicated thread before unblocking it. If it is not, we send the
-signal to our thread, thus losing the sigaction again, exactly like when using
-the unsigaction strategy. Plus the original signal will stay pending on the
-affected thread forever.
-* On Linux, there is an issue where contrary to what the man page says,
-`libdispatch` https://github.com/apple/swift-corelibs-libdispatch/pull/560[does
-modify the sigaction of a signal when a dispatch source for this signal is first
-installed].
-So in theory this strategy should not work (and to be honest, the other one
-should not either). However, it has been noticed that changing the sigaction
-_after_ the signal source has been installed is enough to avoid this problem. So
-we save the sigaction before installing the signal source, then restore it after
-the source is installed, and we’re good. This solution seems fragile though, and
-might break in the future, or not even work reliably right now.
+* On macOS, when a signal blocked on all threads is received, it seems to be assigned to an arbitrary thread.
+Unblocking the signal on another thread will not unblock it at all.
+To workaround this problem we check if the signal is pending on the dedicated thread before unblocking it.
+If it is not, we send the signal to our thread, thus losing the sigaction again, exactly like when using the unsigaction strategy.
+Plus the original signal will stay pending on the affected thread forever.
+* On Linux, there is an issue where contrary to what the man page says, `libdispatch`
+https://github.com/apple/swift-corelibs-libdispatch/pull/560[does modify the sigaction of a signal when a dispatch source for this signal is first installed].
+So in theory this strategy should not work (and to be honest, the other one should not either).
+However, it has been noticed that changing the sigaction _after_ the signal source has been installed is enough to avoid this problem.
+So we save the sigaction before installing the signal source, then restore it after the source is installed, and we’re good.
+This solution seems fragile though, and might break in the future, or not even work reliably right now.

Sources/SignalHandling/CStructsInSwift/Sigaction.swift

@@ -41,9 +41,8 @@ public struct Sigaction : Equatable, RawRepresentable {
 	/**
 	 Create a `Sigaction` from a `sigaction`.
 
-	 If the handler of the sigaction is `SIG_IGN` or `SIG_DFL`, we check the
-	 `sa_flags` not to contains the `SA_SIGINFO` bit. If they do, we log an
-	 error, as this is invalid. */
+	 If the handler of the sigaction is `SIG_IGN` or `SIG_DFL`, we check the `sa_flags` not to contains the `SA_SIGINFO` bit.
+	 If they do, we log an error, as this is invalid. */
 	public init(rawValue: sigaction) {
 		self.mask = Signal.set(from: rawValue.sa_mask)
 		self.flags = SigactionFlags(rawValue: rawValue.sa_flags)
@@ -108,22 +107,21 @@ public struct Sigaction : Equatable, RawRepresentable {
 	}
 
 	/**
-	 Only one check: do the flags **not** contain `siginfo` if handler is either
-	 `.ignoreHandler` or `.defaultHandler`. */
+	 Only one check: do the flags **not** contain `siginfo` if handler is either `.ignoreHandler` or `.defaultHandler`. */
 	public var isValid: Bool {
 		return !flags.contains(.siginfo) || (handler != .ignoreHandler && handler != .defaultHandler)
 	}
 
 	/**
 	 Installs the sigaction and returns the old one if different.
 
-	 It is impossible for a sigaction handler to be `nil`. If the method returns
-	 `nil`, the previous handler was exactly the same as the one you installed.
+	 It is impossible for a sigaction handler to be `nil`.
+	 If the method returns `nil`, the previous handler was exactly the same as the one you installed.
 	 Note however the sigaction function is always called in this method.
 
-	 If `updateUnsigRegistrations` is true (default), If there are delayed
-	 sigactions registered with `SigactionDelayer_Unsig`, these registrations
-	 will be updated and `sigaction` will not be called. */
+	 If `updateUnsigRegistrations` is true (default),
+	  if there are delayed sigactions registered with `SigactionDelayer_Unsig`,
+	  these registrations will be updated and `sigaction` will not be called. */
 	@discardableResult
 	public func install(on signal: Signal, revertIfIgnored: Bool = true, updateUnsigRegistrations: Bool = true) throws -> Sigaction? {
 		if updateUnsigRegistrations, let oldSigaction = SigactionDelayer_Unsig.updateOriginalSigaction(for: signal, to: self) {

Sources/SignalHandling/CStructsInSwift/SigactionFlag.swift

@@ -6,41 +6,37 @@ import Foundation
 public struct SigactionFlags : OptionSet {
 
 	/**
-	 If this bit is set when installing a catching function for the `SIGCHLD`
-	 signal, the `SIGCHLD` signal will be generated only when a child process
-	 exits, not when a child process stops. */
+	 If this bit is set when installing a catching function for the `SIGCHLD` signal,
+	  the `SIGCHLD` signal will be generated only when a child process exits, not when a child process stops. */
 	public static let noChildStop = SigactionFlags(rawValue: SA_NOCLDSTOP)
 
 	/**
-	 If this bit is set when calling `sigaction()` for the `SIGCHLD` signal, the
-	 system will not create zombie processes when children of the calling process
-	 exit. If the calling process subsequently issues a `wait(2)` (or
-	 equivalent), it blocks until all of the calling process’s child processes
-	 terminate, and then returns a value of -1 with errno set to ECHILD. */
+	 If this bit is set when calling `sigaction()` for the `SIGCHLD` signal,
+	  the system will not create zombie processes when children of the calling process exit.
+	 If the calling process subsequently issues a `wait(2)` (or equivalent),
+	  it blocks until all of the calling process’s child processes terminate,
+	  and then returns a value of -1 with errno set to ECHILD. */
 	public static let noChildWait = SigactionFlags(rawValue: SA_NOCLDWAIT)
 
 	/**
-	 If this bit is set, the system will deliver the signal to the process on a
-	 signal stack, specified with `sigaltstack(2)`. */
+	 If this bit is set, the system will deliver the signal to the process on a signal stack, specified with `sigaltstack(2)`. */
 	public static let onStack = SigactionFlags(rawValue: SA_ONSTACK)
 
 	/**
-	 If this bit is set, further occurrences of the delivered signal are not
-	 masked during the execution of the handler. */
+	 If this bit is set, further occurrences of the delivered signal are not masked during the execution of the handler. */
 	public static let noDefer = SigactionFlags(rawValue: SA_NODEFER)
 
 	/**
-	 If this bit is set, the handler is reset back to `SIG_DFL` at the moment the
-	 signal is delivered. */
+	 If this bit is set, the handler is reset back to `SIG_DFL` at the moment the signal is delivered. */
 	public static let resetHandler = SigactionFlags(rawValue: CInt(SA_RESETHAND) /* On Linux, an UInt32 instead of Int32, so we cast… */)
 
 	/** See `sigaction(2)`. */
 	public static let restart = SigactionFlags(rawValue: SA_RESTART)
 
 	/**
-	 If this bit is set, the handler function is assumed to be pointed to by the
-	 `sa_sigaction` member of struct sigaction and should match the matching
-	 prototype. This bit should not be set when assigning `SIG_DFL` or `SIG_IGN`. */
+	 If this bit is set, the handler function is assumed to be pointed to by the `sa_sigaction` member of struct sigaction
+	  and should match the matching prototype.
+	 This bit should not be set when assigning `SIG_DFL` or `SIG_IGN`. */
 	public static let siginfo = SigactionFlags(rawValue: SA_SIGINFO)
 
 	public let rawValue: CInt

Sources/SignalHandling/CStructsInSwift/SigactionHandler.swift

@@ -5,15 +5,12 @@ import Foundation
 /**
  A `sigaction` handler.
 
- Two `SigactionHandler`s are equal iif their cases are equal and the handler
- they contain point to the same address (if applicable). */
+ Two `SigactionHandler`s are equal iif their cases are equal and the handler they contain point to the same address (if applicable). */
 public enum SigactionHandler : Equatable {
 
-	/* The ignore and default handlers are special cases represented respectively
-	 * by the `SIG_IGN` and `SIG_DFL` values in C.
-	 * We choose the represent them using a special case in the enum. You should
-	 * not (though you could) use `.ansiC(SIG_IGN)` (it is not possible with
-	 * `SIG_DFL` because `SIG_DFL` is optional… and nil).
+	/* The ignore and default handlers are special cases represented respectively by the `SIG_IGN` and `SIG_DFL` values in C.
+	 * We choose the represent them using a special case in the enum.
+	 * You should not (though you could) use `.ansiC(SIG_IGN)` (it is not possible with `SIG_DFL` because `SIG_DFL` is optional… and nil).
 	 * In particular, `.ignoreHandler != .ansiC(SIG_IGN)` */
 	case ignoreHandler
 	case defaultHandler
@@ -29,8 +26,8 @@ public enum SigactionHandler : Equatable {
 			case (.ansiC, .ansiC), (.posix, .posix):
 				return lhs.asOpaquePointer == rhs.asOpaquePointer
 
-				/* Using this matching patterns instead of simply default, we force
-				 * a compilation error in case more cases are added later. */
+				/* Using this matching patterns instead of simply default,
+				 *  we force a compilation error in case more cases are added later. */
 			case (.ignoreHandler, _), (.defaultHandler, _), (.ansiC, _), (.posix, _):
 				return false
 		}