DEV Community: Tal

Rust Generic Types in Method Definitions

Tal — Sat, 03 Apr 2021 23:48:32 +0000

Intro

If you're new to Rust, reading through the official Rust book (which you definitely should), you may have been confused by the examples in the In Method Definitions section of Chapter 10.1 like I was. In this article, I'll try to clear up any confusion you may have.

For this article to make sense, you are expected to have already read through the book up to that part, and have a basic understanding of generic data types.

I think that most of the confusion stems from the fact that the topic is introduced using a common, but complex example. I submitted a ticket in the github repo for the book with some suggestions to fix this, but until then, lets explore the topic here.

Simple Example

We'll start simple. If you have a struct, and you want to add methods to it, you would do something like this:

struct Container {
    field: i32,
}

impl Container {
    fn foo(&self) {
        ...
    }
}

If you've read the book up to Chapter 10.1, this should make sense to you.

Simple Example Using Generic Type

If your struct contains a generic type on the other hand, your impl MUST also specify a type. Ex:

struct Container<T> {
    field: T,
}

impl Container<[TYPE]> {

}

where [TYPE] is the type that your impl block will be implemented for.

For example, if you were to do this:

struct Container<T> {
    field: T,
}

impl Container<i32> {
    fn foo(&self) {
        println!("I exist!");
    }
}

That means that you can create an instance of your struct using any type, BUT, only instances that use the i32 type will have the foo method.

If we were to create a few instances, we can confirm this:

let inst1 = Container { field: 'c' };
let inst2 = Container { field: 10 };
let inst3 = Container { field: 12.2 };

inst1.foo(); // Won't work - method doesn't exist
inst2.foo(); // Works fine
inst3.foo(); // Won't work - method doesn't exist

These 3 instances are of the same struct, but only inst2 has i32 as the generic type being passed into it when the instance is created, so it is the only instance that will have the foo method.

Another way to say this is that the [TYPE] from above is a matcher. All the methods defined in the impl block will only be attached to instances that match that type.

If this makes sense to you - great! Read on. If not, read it again, because understanding the idea above is the key to understanding the example in the book.

Simple Example Using Custom Generic Type

Because rust allows you to define your own types, like a struct or an enum, the code above is almost exactly the same as the following:

struct Color {
    red: u8,
    green: u8,
    blue: u8,
}

struct Container<T> {
    field: T,
}

impl Container<Color> {
    fn foo(&self) {
        println!("I exist");
    }
}

fn main() {
    let inst1 = Container {
        field: Color { red: 10, green: 20, blue: 30 },
    };
    let inst2 = Container { field: 10 };
    let inst3 = Container { field: 12.2 };

    inst1.foo(); // This will work
    inst2.foo(); // Won't work - method doesn't exist
    inst3.foo(); // Won't work - method doesn't exist
}

Here, we've defined a custom type called Color, and our impl block for our Container struct says that the foo method should only be added to instances where the T (the generic type) is of type Color. This is true for inst1 (where T is of type Color), but not true for inst2 (where T is of type i32) and inst3 (where T is of type f64).

Common beginner mistake in impl block

Now, knowing all that, what happens if we want the methods in the impl block to be available on all instances of our struct, no matter what type it is?

Your first thought may be to do something like this:

struct Container<T> {
    field: T,
}

impl Container<T> {
    fn foo(&self) {
        println!("I exist!");
    }
}

Unfortunately, this won't quite work the way you might expect. This is almost exactly the same as the example above that uses a custom Color type. You are saying that you want foo implemented only where the generic type = T, but you have not defined type T anywhere. The compiler doesn't know that when you wrote impl Container<T>, what you meant was a generic type. It tries to find an actual, concrete definition somewhere in this scope for a type T, and since that doesn't exist, the code will fail to compile.

Note that while the struct Container<T> line does define a generic type called T, this definition's scope is only within that struct's body. That type does NOT exist for the impl definition to use.

impl block matching all types

What you need is a way to tell the compiler that your impl block should match against all types. To do this, you must define a generic type within the impl definition. This looks like the following:

struct Container<T> {
    field: T,
}

impl<T> Container<T> {
    fn foo(&self) {
        println!("I exist!");
    }
}

Here, within the impl definition, we have defined a generic type T, and later specified that this impl block should match any instances that match this generic type, which, without any trait bounds (which you learn about in the following section of the book) is all types. The result is that your foo method will be available on all instances of your struct, no matter what your generic type T ended up being.

Hopefully, this explains why you need to write <T> twice within the impl line - once to define a generic type, and once to match against it.

Rules

While working with generic types in impl definitions, there are a few rules that are important to remember:

Rule 1

The number of matchers in your impl block must be the same as the number of generic type args in your struct definition

Ex:

struct Container<T, V> { }
impl Container<i32, i32> { }

Since there are 2 generic type args in the struct definition, there MUST be 2 in the matcher of the impl block.

This won't work:

struct Container<T, V> { }
impl Container<i32> { }

Neither will this:

struct Container<T, V> { }
impl Container { }

Rule 2

The number of generic args defined in the impl block do NOT need to match the number of generic args defined in the struct.

This works (2 generic args in struct definition, 0 in impl definition):

struct Container<T, V> { }
impl Container<i32, i32> { }

As does this (2 generic args in struct definition, 1 in impl definition):

struct Container<T, V> { }
impl<T> Container<T, i32> { }

As does this (2 generic args in struct definition, 2 in impl definition):

struct Container<T, V> { }
impl<T, V> Container<T, V> { }

Rule 3

The names of the generic args in the impl block do NOT need to match the names of the generic args in the struct.

This works fine, and does exactly the same thing as the above example:

struct Container<T, V> { }
impl<A, B> Container<A, B> { }

Matching against duplicate types

Besides matching on concrete types, you can also match against instances where both generic types are the same. Ex:

struct Container<T, V> { }
impl<X> Container<X, X> { }

Here, we've defined a single generic type in the impl line called X, and have stated that this impl block will only match against instances where both the generic args are of the same type, no matter what that type happens to be. Again - this doesn't mean you can't create an instance where T and V are different types - you can - but the methods in this impl block will not be available on those instances.

Conclusion

The official Rust book is amazing, and introduces a fairly complex language in a very approachable way. This topic is one of the few where the book falls a little short - at least in my opinion. I'm sure that with time, the book will expand on this topic, but until then, I really hope that this article clears things up for people also confused after reading that particular section of the book, like I was when I first read it.

Handling Unix Kill Signals in Rust

Tal — Sat, 20 Feb 2021 20:27:39 +0000

Intro

Like many of you, I am a software developer. For the past few years, I've been working with Python, both at work, and writing small hobby projects at home.

One of the most common things I do with Python is write Linux services/daemons. A linux daemon is a program, in our case written in Python, that runs in a loop, usually by SystemD, and only exits when it receives a kill signal.

A few months ago, I decided to teach myself Rust, and after reading the Rust book (which I highly recommend), and watching lots of youtube videos, I tried to write a Rust Linux daemon.

Part of the process was figuring out how to handle kill signals in Rust, which is very different than how it is handled in Python. I expected this to be relatively easy, but found it to be rather difficult. In this article, we're going to take a look at the signal_hook crate, and the different ways Rust allows us to react to a kill signal. Hopefully, my experience will help ease the journey for some of you.

Linux Kill Signals

The 2 most common kill signals in Linux are SIGINT, which gets sent to your program when you run the program manually, and hit Ctrl+C in your terminal, or SIGTERM, which SystemD sends to your program when you run systemctl stop my_program.

Unlike Python, which throws an ugly traceback when it receives an unhandled kill signal, Rust quietly exits. If your Rust program does not need to do anything special when it terminates, you can probably get away with not doing any kill signal handling at all, but if you need to do any kind of cleanup, you'll likely need to catch these kill signals, and do your cleanup before exiting.

Crate Options

Unlike Python, Rust doesn't have built-in kill signal handling. You'll need to use an external crate to add this functionality. There are 2 main crates that allow you to handle kill signals:

The ctrlc crate is fairly easy to use, but only supports a limited number of kill signals:

SIGINT
SIGTERM (requires enabling the termination feature)

Here, I'll be taking a look at the signal_hook crate. Once we break down the signal_hook crate, the ctrlc crate becomes easy to understand and use as well.

Signal Hook

This may change, but as of now, the crate documentation has 2 examples on the front page - one that is very simple, which we will take a closer look at below, and one that is overly complex, which uses features that are unlikely to be commonly needed, and won't compile without enabling extra features. We'll slowly work our way from the simple example, to a more complex one that resembles the one in the documentation.

Cargo.toml

The first thing you'll want to do is add this to the dependencies section of your Cargo.toml file:

signal-hook = "0.3.4"

While this will work for ALL of our examples, if you want to compile the complex example from the documentation, you'll want your toml file to say this instead:

signal-hook = { version = "0.3.4", features = ["extended-siginfo"] }

Simple Example

This is a slightly modified version of the simple example from the documentation:

use std::io::Error;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::thread;
use std::time;
use signal_hook::flag;

fn main() -> Result<(), Error> {
    // Declare bool, setting it to false
    let term = Arc::new(AtomicBool::new(false));

    // Ask signal_hook to set the term variable to true
    // when the program receives a SIGTERM kill signal
    flag::register(signal_hook::consts::SIGTERM, Arc::clone(&term))?;

    // Do work until the term variable becomes true
    while !term.load(Ordering::Relaxed) {
        println!("Doing work...");
        thread::sleep(time::Duration::from_secs(1));
    }

    // Since our loop is basically an infinite loop,
    // that only ends when we receive SIGTERM, if
    // we got here, it's because the loop exited after
    // receiving SIGTERM
    println!("Received SIGTERM kill signal. Exiting...");

    Ok(())
}

Lets have a look at the different parts. First, we have this:

let term = Arc::new(AtomicBool::new(false));

This line creates a special boolean variable that can be used safely from different threads. It can be set in one thread, by the signal_hook crate, and checked in your main thread.

Next, we have this line:

flag::register(signal_hook::consts::SIGTERM, Arc::clone(&term))?;

This tells signal_hook that we would like to register the SIGTERM kill signal to be monitored, and when we receive this kill signal, to have the term boolean set to true.

Lastly, we have the main loop:

while !term.load(Ordering::Relaxed) { ... }

The way we check if the special boolean we are using is true or false is slightly different than how we check regular booleans. We use the .load() method on it. Because the loop starts out false, and we are waiting for it to turn true, and while loops only run while something is true, we use ! here. All we are saying is that we want the loop to run until the boolean turns true.

To test this program, compile it, run it, and after a few seconds, run:

killall -SIGTERM my_program

where my_program is the name of your program. That's the name you gave it when you ran crate new my_program. It's also the name of your binary under target/debug/ of your project. This will send your program a SIGTERM signal, causing the boolean to get set to true, and the loop to exit. Simple.

Double SIGINT

This is a slightly more complex example. Here, if the user hits Ctrl+C (sending our program the SIGINT kill signal), our program will begin to clean up and try to exit. If the user hits Ctrl+C again, possibly because our cleanup procedure locked up, our program will terminate immediately.

use std::io::Error;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::thread;
use std::time;

// This is just a collection of ints that represent kill signals.
// More specifically, they are the common kill signals used to
// terminate a program
// You can do println!("{:?}", TERM_SIGNALS) to see them
// They are just SIGINT(2), SIGTERM(15) and SIGQUIT(3)
use signal_hook::consts::TERM_SIGNALS;

// Module that sets boolean flags when kill signal is received
use signal_hook::flag;

fn main() -> Result<(), Error> {
    // A special boolean that can be used across threads
    // It will be passed to flag::register, which will
    // set it to true the first time a kill signal is received
    let term_now = Arc::new(AtomicBool::new(false));

    // Register all kill signals
    // Note: You COULD specify other, specific kill signals here
    // rather than the 3 in TERM_SIGNALS. You just need a vector
    // of constants from signal_hook::consts::signal
    for sig in TERM_SIGNALS {
        // When terminated by a second term signal, exit with exit code 1.
        // This will do nothing the first time (because term_now is false).
        flag::register_conditional_shutdown(*sig, 1, Arc::clone(&term_now))?;
        // But this will "arm" the above for the second time, by setting it to true.
        // The order of registering these is important, if you put this one first, it will
        // first arm and then terminate ‒ all in the first round.
        flag::register(*sig, Arc::clone(&term_now))?;
    }

    // Main process that does work until term_now has been set
    // to true by flag::register
    while !term_now.load(Ordering::Relaxed) {
        println!("Doing work...");
        thread::sleep(time::Duration::from_secs(1));
    }

    // If we ended up here, the loop above exited because of a kill signal
    println!("\nReceived kill signal. Wait 10 seconds, or hit Ctrl+C again to exit immediately.");

    // This simulates a long cleanup operation
    // If you wait this long, the program will exit
    // If you hit Ctrl+C again before this is done, flag::register_conditional_shutdown will kill
    // the process without waiting for it to finish. This means double Ctrl+C kills the process
    // immediately
    thread::sleep(time::Duration::from_secs(10));

    println!("Exited cleanly");

    Ok(())
}

This code is actually very similar to the first example, but with one additional part. Now, the term_now bool is used for 2 different purposes.

The first is defined here:

for sig in TERM_SIGNALS {
    flag::register_conditional_shutdown(*sig, 1, Arc::clone(&term_now))?;
    flag::register(*sig, Arc::clone(&term_now))?;
}

As before, the register function will set term_now to true when it receives a kill signal. The new register_conditional_shutdown on the other hand will kill your program, but only if term_now is set to true.

The first time you hit Ctrl+C, register_conditional_shutdown will do nothing because term_now will be false, but register will set term_now to true. The second time you hit Ctrl+C, register_conditional_shutdown will terminate the program no matter what else the program might be working on.

These 2 lines in a for loop will make the double-Ctrl+C work (terminate your program), but you still need your main code to watch for, and react to a kill signal to shut down your program gracefully. As before, we do this with a while loop that runs until term_now becomes true.

Complex Example

Building on the previous examples, the following is a slightly more complex example that reacts differently to different kill signals:

use std::io::Error;
use std::sync::Arc;
use std::sync::atomic::AtomicBool;
use std::thread;
use std::time;
use std::sync::atomic::Ordering;

use signal_hook::flag;
use signal_hook::consts::signal::*;
use signal_hook::consts::TERM_SIGNALS;
use signal_hook::iterator::Signals;

fn main() -> Result<(), Error> {
    // A special boolean that can be used across threads
    // The first time a kill signal is received, it will be set to
    // true by flag::register
    // The second time a kill signal is received, our process will
    // be killed by flag::register_conditional_shutdown
    let term_now = Arc::new(AtomicBool::new(false));

    for sig in TERM_SIGNALS {
        // When terminated by a second term signal, exit with exit code 1.
        // This will do nothing the first time (because term_now is false).
        flag::register_conditional_shutdown(*sig, 1, Arc::clone(&term_now))?;
        // But this will "arm" the above for the second time, by setting it to true.
        // The order of registering these is important, if you put this one first, it will
        // first arm and then terminate ‒ all in the first round.
        flag::register(*sig, Arc::clone(&term_now))?;
    }

    // Our actual work thread
    let t = thread::spawn(move || {
        while !term_now.load(Ordering::Relaxed)
        {
            println!("Doing work...");
            thread::sleep(time::Duration::from_secs(1));
        }

        println!("\nThread exiting...");
    });

    // Create iterator over signals
    let mut signals = Signals::new(TERM_SIGNALS)?;

    // This loop runs forever, and blocks until a kill signal is received
    'outer: loop {
        for signal in signals.pending() {
            match signal {
                SIGINT => {
                    println!("\nGot SIGINT");
                    break 'outer;
                },
                SIGTERM => {
                    println!("\nGot SIGTERM");
                    break 'outer;
                },
                term_sig => {
                    println!("\nGot {:?}", term_sig);
                    break 'outer;
                },
            }
        }
    }

    // Wait for thread to exit
    t.join().unwrap();

    // Cleanup code goes here
    println!("\nReceived kill signal. Wait 10 seconds, or hit Ctrl+C again to exit immediately.");
    thread::sleep(time::Duration::from_secs(10));
    println!("Exited cleanly");

    Ok(())
}

Here, a few things are going on that we are already familiar with. Just like before, we create a new bool that signal_hook will set to true for us when it receives a kill signal.

We also, once again, use flag::register_conditional_shutdown to make sure that a second SIGINT will kill our program immediately.

Something that's new here is this:

// Our actual work thread
let t = thread::spawn(move || {
    while !term_now.load(Ordering::Relaxed)
    {
        println!("Doing work...");
        thread::sleep(time::Duration::from_secs(1));
    }

    println!("\nThread exiting...");
});

Here, we are spawning a new worker thread where our actual work will be done, whatever that happens to be, and moving our term_now variable to this thread, so that the worker thread can monitor the boolean, and know when it's time to exit (when we've received a kill signal).

The worker thread looks very similar to our previous examples' main thread - it runs an infinite while loop that only exits if the boolean signal_hook will set for us becomes true. When it does exit, the statements following the while loop will be executed on its way out.

The next new code in this example is this:

let mut signals = Signals::new(TERM_SIGNALS)?;

This will let us use an iterator to iterate over any incoming signals.

The main example in the signal_hook documentation uses SignalsInfo instead. The main difference is that Signals will simply return the kill signal received, whereas SignalsInfo returns some additional info about every kill signal.

As stated above, using Signals doesn't require anything special, while using SignalsInfo requires the extended-siginfo feature to be enabled in your Cargo.toml, so please be aware.

After that, we have this code:

    'outer: loop {
        for signal in signals.pending() {
            match signal {
                SIGINT => {
                    println!("\nGot SIGINT");
                    break 'outer;
                },
                SIGTERM => {
                    println!("\nGot SIGTERM");
                    break 'outer;
                },
                term_sig => {
                    println!("\nGot {:?}", term_sig);
                    break 'outer;
                },
            }
        }
    }

This is a loop within a loop. The inner loop iterates over any kill signals in queue, while the outer loop is an infinite loop that keeps checking the queue.

When we do receive a kill signal, we can match it against the constants found in signal_hook::consts::signal, like SIGINT and SIGTERM, take action, and break out of both loops.

In order to easily break out of both loops, we give the outer loop a name, and our break statement tells rust that we want to break out of the loop with the given name, rather than the first enclosing loop.

After we are out of the loop, we have this line:

t.join().unwrap();

Because the only way to get out of the loop is by receiving a kill signal, and our worker thread will also see this kill signal, we can assume at this point that our thread is terminating, so here, we simply wait for it to return (finish its cleanup).

Once the thread returns, we can do our own cleanup here:

println!("\nReceived kill signal. Wait 10 seconds, or hit Ctrl+C again to exit immediately.");
thread::sleep(time::Duration::from_secs(10));
println!("Exited cleanly");

This can be whatever you need to do before your program exits.

Because we used flag::register_conditional_shutdown at the beginning, if this cleanup gets stuck, the user has the option of hitting Ctrl+C again in order to terminate our program.

Conclusion

Now that we've slowly worked up from a basic example, to a complex example, hopefully you are ready to read, and understand the example in the signal_hook documentation that uses SignalsInfo, and a few extra features we haven't covered here.

It took me a few days to figure this out - I hope with this guide, you'll be able to get going faster.

If you have any questions, please let me know. I'm still learning Rust, and definitely don't know everything about the signal_hook crate, but I'll try to answer them as best as I can.