Signal support

[Gelox]

Add a status field to the custom block that takes a value between 0 and 30. These correspond to SIGRTMIN+0 to SIGRTMIN+30.
This causes the block to be updated by sending the corresponding SIGRT signal to i3status-rs. This can be done via
pkill -SIGRTMIN+1 i3status-rs in order to send a signal to blocks listening for signal 1.

This feature allows custom blocks to not need to be updated on an interval, but instead can be updated via scripts sending a signal when they need to update.

A possible flaw is that I was not able to find a good way of pulling in the signal range dynamically from the users computer, instead the range is hard-coded to listen to signals between 34 and 64 (where this is the range on my computer).
The relevant constants can be found in src/signals.rs

[ammgws]

A possible flaw is that I was not able to find a good way of pulling in the signal range dynamically from the users computer, instead the range is hard-coded to listen to signals between 34 and 64 (where this is the range on my computer).

I guess we just have to wait for this: nix-rust/nix#1143

Can you update blocks.md as well?

[ammgws]

I haven't had time to test it yet, how has it been going for you so far?

[Gelox]

I have used this feature on my own computer, it works fine. I updated the relevant blocks.md parts.
However the signal value constants I don't have an idea for how to make progress on. I think I started an issue in libc asking what they thought about exposing SIGRTMIN and SIGRTMAX but I haven't got a response nor do I think one will be given for a long time. I think the issue is that these specific constants change depending on your system and in libc they expose constants by hard-coding them. One would have to MAYBE create a function, but that entails its own troubles.

So far I don't know how to get the relevant constants in a dynamic way (perhaps we could add C-bindings).

The options that I see available are:

• Provide this feature behind a feature flag and keep the constants as they are
• Recreate the update mechanism without signals in some other way
• Do not merge this feature
• Keep the constants as they are, it will work on any system that has allocated 2 RT signals for system purposes (which is all the systems that I am familiar with, debian, arch, ..)
• Explore adding C-bindings
• Figure out another solution

I'll let the community (or you) decide with what direction they want to go, I do not mind helping with the decided way assuming it's not too much work.

[Gelox]

I'll add on to that list of possible solutions.
If there would be a way to get the SIGRTMIN and SIGRTMAX values from a shell then we could run a shell command from rust to get it.
However as far as I can tell there is no such possibility. Getting this value seems to be exceedingly hard if you are not in C.
kill -L and kill -l seem to be out of date for me, so that's not a possibility to finding these values for all systems.

[ammgws]

On mobile now so can't review the code but what happens in the case a user sets an invalid signal value? (In the case that we don't check the bounds ourselves and someone sets something like 99)

[Gelox]

//In ConfigBlock::new()...
if let Some(signal) = block_config.signal {
         // If the signal is not in the valid range we return an error
         if signal < 0 || signal > SIGMAX - SIGMIN {
            return Err(Error::BlockError(
                    custom.id,
                    format!("The provided signal was out of bounds. An allowed signal needs to be between {} and {}", 0, SIGMAX - SIGMIN)
                    ));
        } else {
            custom.signal = Some(signal + SIGMIN)
        }
    };
}

It returns an error from the ConfigBlock::new() method.

[ammgws]

Sorry I meant something like this: For example say we hardcoded the range as 34 to 64, what would happen in the two situations below.

1. SIGRTMIN starts at 35 on someone's system, and they choose signal 34 for one of their blocks.

2. Someone only has 20 realtime signals on their system and they choose signal 64 for one of their blocks.

https://man7.org/linux/man-pages/man7/signal.7.html

   Starting with version 2.2, Linux supports real-time signals as
   originally defined in the POSIX.1b real-time extensions (and now
   included in POSIX.1-2001).  The range of supported real-time signals
   is defined by the macros SIGRTMIN and SIGRTMAX.  POSIX.1-2001
   requires that an implementation support at least _POSIX_RTSIG_MAX (8)
   real-time signals.

   The Linux kernel supports a range of 33 different real-time signals,
   numbered 32 to 64.  However, the glibc POSIX threads implementation
   internally uses two (for NPTL) or three (for LinuxThreads) real-time
   signals (see pthreads(7)), and adjusts the value of SIGRTMIN suitably
   (to 34 or 35).  Because the range of available real-time signals
   varies according to the glibc threading implementation (and this
   variation can occur at run time according to the available kernel and
   glibc), and indeed the range of real-time signals varies across UNIX
   systems, programs should never refer to real-time signals using hard-
   coded numbers, but instead should always refer to real-time signals
   using the notation SIGRTMIN+n, and include suitable (run-time) checks
   that SIGRTMIN+n does not exceed SIGRTMAX.

Or realistically, if SIGRTMIN and SIGRTMAX only vary on non-Linux kernels then we could hardcode the range without any any worries?

[Gelox]

SIGRTMIN starts at 35 on someone's system, and they choose signal 34 for one of their blocks.

Well this would cause incorrect behavior but not necessarily break anything. If their SIGRTMIN is 35 and they choose to listen to signal 0 (which corresponds to 34) then the result would be that for them to update i3status-rs they'd have to send SIGRTMIN-1 which would be an occupied signal.
However realistically they wouldn't send SIGRTMIN-1 signals, rather they'd try to send SIGRTMIN+0 and see that it does not update (as they'd be sending signal 35 rather than 34).
However I guess you would also be listening to potential 34 signals from the OS, which could potentially create problems?

Someone only has 20 realtime signals on their system and they choose signal 64 for one of their blocks.

As far as I know SIGRTMAX does not vary, someone having 20 realtime signals would have to be a result of SIGRTMIN being 44 which would be the same problem as the previous one.

Or realistically, if SIGRTMIN and SIGRTMAX only vary on non-Linux kernels then we could hardcode the range without any any worries?

Well, if we are only targeting Linux kernels and SIGRTMIN and SIGRTMAX do not vary on Linux kernels then no issue would appear. I have not seen a guarantee that they do not vary however. In fact in the man-page you referenced it seems to indicate that it can sometimes be 35 on Linux kernels.

It seems that libc is open to adding SIGRTMIN support to their library, I'm thinking I might try to add it myself when I get around to it. This means that eventually we should be able to add this feature correctly regardless of merging it right now, but if we do merge it right now we can always push a fix later.
:)

[ammgws]

However I guess you would also be listening to potential 34 signals from the OS, which could potentially create problems?

Yeah that was what I was trying to hint at.

it can sometimes be 35 on Linux kernels.

I guess we could just make our range start a bit higher like 40 - 64 to be safe, at least until libc is enhanced.

[Gelox]

So, I just checked how difficult it is to bring the SIGRTMIN into rust through C bindings, super simple. I didn't realize this before so I learned my lesson.
Either way this should solve all of our problems, it does require we do 1 temporary C binding but this can be removed when libc updates their API and this propagates to the nix crate.

I'll try to update this right now. How does that sound?

[ammgws]

Sounds reasonable to me. Hopefully nix/libc get updated by the next time we want to do a release.

Do you think we could also add support for a signal that schedules an update for the whole bar (every block) at once? Maybe could use SIGUSR1 or SIGUSR2 for that.

In addition to the above another use case we could hopefully cover at some time is reloading the config (see #302) but this one probably isn't trivial enough to cover with this PR.

[Gelox]

I added the C-bindings, there shouldn't be an issue now.
As for adding support for an entire bar update that isn't added in this PR, I think that's best left to another PR.

I could also look a bit at the reloading thing. But again better left to another PR. :)

[ammgws]

LGTM!

I suppose in the future the implementation could be made block agnostic so it can apply to any block, but it's not a cause for delaying this PR.

Thanks for working on this!

[Gelox]

Fantastic! Currently no documentation exists that SIGUSR1 updates all blocks, I don't know where this fits. Not sure if it is necessary but just giving a heads up.

Thanks for letting me work on this! 💯

[ammgws]

Good catch. Not really sure where to put it either. I think the README needs a rewrite.