[MIRROR] Add a guideline for providing a comment with override = TRUE [MDB IGNORE] (#16408)

* Add a guideline for providing a comment with override = TRUE (#70046)

* Add a guideline for providing a comment with override = TRUE

* Add a guideline for providing a comment with override = TRUE

Co-authored-by: Mothblocks <35135081+Mothblocks@users.noreply.github.com>
This commit is contained in:
SkyratBot
2022-09-24 15:33:16 -04:00
committed by GitHub
co-authored by Mothblocks
parent 99fb800c6e
commit 2c3ebd9c8a
+13 -1
View File
@@ -97,7 +97,9 @@ While we normally encourage (and in some cases, even require) bringing out of da
* Files and path accessed and referenced by code above simply being #included should be strictly lowercase to avoid issues on filesystems where case matters.
### Signal Handlers
### RegisterSignal()
#### Signal Handlers
All procs that are registered to listen for signals using `RegisterSignal()` must contain at the start of the proc `SIGNAL_HANDLER` eg;
```
@@ -109,6 +111,16 @@ This is to ensure that it is clear the proc handles signals and turns on a lint
Any sleeping behaviour that you need to perform inside a `SIGNAL_HANDLER` proc must be called asynchronously (e.g. with `INVOKE_ASYNC()`) or be redone to work asynchronously.
#### `override`
Each atom can only register a signal on the same object once, or else you will get a runtime. Overriding signals is usually a bug, but if you are confident that it is not, you can silence this runtime with `override = TRUE`.
```dm
RegisterSignal(fork, COMSIG_FORK_STAB, .proc/on_fork_stab, override = TRUE)
```
If you decide to do this, you should make it clear with a comment explaining why it is necessary. This helps us to understand that the signal override is not a bug, and may help us to remove it in the future if the assumptions change.
### Enforcing parent calling
When adding new signals to root level procs, eg;