Forem: Nirmalya Sengupta

Rust Notes on Temporary values (usage of Mutex) - 4

Nirmalya Sengupta — Thu, 22 Jun 2023 11:56:48 +0000

Preface

Some weeks back, in the discord LetsGoRusty server, a topic of discussion was the behavior of match expression vis-a-vis a lock. The thread of discussion was quite interesting for me. Fellow members of the channel exchanged messages, much to my benefit. After all, I am learning Rust! 😁

In short, the problem was this:

match receiver.lock().unwrap().recv().unwrap() { 
    // ...
}

and

// ...
let message = receiver.lock().unwrap().recv().unwrap();
match message {
    // ....
}

behave differently, Why?

As someone who is learning Rust enthusiastically, and fighting the Borrow Checker valiantly along the way 😃 this question intrigued me. I wanted to find out - to the extent I could - the exact reason behind this behaviour. Whatever I have been able to understand, I have captured in a series of articles (listed below). This is the last and final article of that series.

Build up

Perhaps, it will be easier to understand the background of this article, if the ones just preceding it (in order as below) are referred to:

Explores Method-call expressions and binding. (link)
Explores RAII, OBMR and how these are used in establishing the behaviour of a Mutex (link)
Explores the interplay between the scope of a temporary and match expressions - 3 (link)

What are the main takeaways so far (summary of the earlier articles)

An expression like a.b().c() is called a Method-call expression. It is kind of obvious that c() can be called only when a receiver object exists which implements the method c(). A method/function cannot be called in isolation. The question is, which is the receiver object in that expression, on which c() is available.
Any expression evaluates to a value. So, does a Method-call expression, as well. How we deal with that value is important.
In order to facilitate execution of a Method-call expression, #rustlang compiler brings forth temporary objects as receivers of the methods. The scope - i.e. how long is it available - of these temporaries are governed by a few rules.
The purpose of having a Mutex is to set up a fence around a piece of data. When a thread of execution needs an access to this piece of data, the Mutex must set up a lock around the data, ensuring an exclusive access by this particular thread. While the lock is in place, no other thread can access the data. Therefore, it is important to remove the exclusive lock, just when the current thread of execution is done with it.
Rust employs a technique named OBMR (more commonly known as RAII) to implement the lock by creating temporary object of type MutexGuard and using the scoping rules to ensure its timely destruction (thereby, releasing the lock).
When used in a match expression, the rules of scoping the temporaries determine how the lock is held and released. This is an important observation.

A brief description of the application where it started

The Discord discussion thread, is about a multi-threaded webserver toy application, from the the Rust Book. This application demonstrates - amongst other things - inter-thread communication using Channels. A bunch of workers is looking for jobs to arrive at a channel: when a job arrives, a worker picks it up and executes. This article is not about threads and channels; so we don't go that way. It is sufficient for us to know that the Channel (the receiving end of the channel, to be accurate but that is not important) is held inside a Mutex. Any thread that needs to peep in the channel to see if a job is waiting to be picked up, must acquire the lock!

What is the real issue with the behaviour here?

Well, imagine a queue of jobs. One thread acquires the lock on the queue and picks up a job which is at the mouth of the queue. Once it picks up, it is going to execute the job. During the execution, it must release the lock, so that the next job at the mouth of the queue, may be picked up by another thread. Nothing really very complicated, so far.

But, what if the first thread never releases the lock? In that case, even if jobs accumulate in the queue, other threads - even if free - will remain idle. The first thread, when it is done with the current job, will get a chance to peek again and extract the next job. Only this thread will be working, and in effect, the application will behave as if it is single-threaded.

Explaining the behavior

The code snippet that began the discussion on 'Let's Go Rusty' Discord server, was:

// ...
let message = receiver.lock().unwrap().recv().unwrap();  
match message {                                // <-- match on the bound variable
    Message::NewJob(job) => {
        println!("Worker {} got a new job, executing ..", id);
        job();
    },
    Message::Terminate => {
        println!("Worker {} was told to terminate!", id);
        break;
    }
}
// ...

The point was that the behaviour was different (as outlined earlier) when the first line in the snippet is chaged to this:

// ...
match receiver.lock().unwrap().recv().unwrap() {  // <-- match on the expression
    Message::NewJob(job) => {
        println!("Worker {} got a new job, executing ..", id);
        job();
    },
    Message::Terminate => {
        println!("Worker {} was told to terminate!", id);
        break;
    }
}
// ...

In the second case, the lock is held till the end of the match expression as we have seen in the earlier article. Therefore, while the job() is being done, receiver's channel - the job-queue's head - is locked (the MutexGuard is alive). No other thread can access the receiver's channel during this time. In effect, the application behaves as if it is single threaded.

Expressions `while let` and `match`

The example shared on Discord is almost the same as the sample multi-threaded application that is implemented in the Rust book. The book, also mentions the same problem as described above, but as a slightly different case.

This works as a multi-threaded server alright:

// --snip--

impl Worker {
    fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Job>>>) -> Worker {
        let thread = thread::spawn(move || loop {
            let job = receiver.lock().unwrap().recv().unwrap(); // <==  the lock is released here (tempprary dropped)
            println!("Worker {id} got a job; executing.");
            job();  // <-- do the job and then loop back again
        });

        Worker { id, thread }
    }
}

But, this behaves as a single-threaded server:

// --snip--

impl Worker {
    fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Job>>>) -> Worker {
        let thread = thread::spawn(move || {
            while let Ok(job) = receiver.lock().unwrap().recv() { // <-- lock is not released ...
                println!("Worker {id} got a job; executing.");
                job();
            }                                                     // <-- till here!
        });

        Worker { id, thread }
    }
}

There is no match yet the behaviour is the same as in match receiver.lock().unwrap().recv(). Why?

This is so because Rust compiler translates a while let() = ..... into a match expression!

The while let Ok(Job) = receiver.lock().unwrap().recv() is made into something equivalent to this:

loop {
    match receiver.lock().unwrap().recv() {  // <-- lock is not released
            Ok(job) => job(),
            Err(_) => { break; }
    }                                        // <-- till here!
}

Like earlier, the lock is still held inside the match arm and is not released till the end of the expression, and then it loops!

Conclusion

An idiomatic use of Mutex requires us to understand the important role that a temporary MutexGuard plays of fencing and freeing the data that is under Mutex 's lock. The `MutexGuard 's construction and destruction ensure that the lock is held and released at the appropriate time, so that access to data is not prevented when it is necessary. The rules that govern the scope of a temporary in a Rust expression, is crucial here because the rules ensure how long the MutexGuard lives!

It will be fantastic to hear your comments, on this series. If this benefits someone, I will be happy. I will be happier if someone spots and points out the gaps in my understanding. I am learning and any help is welcome! 😃.

Rust Notes on Temporary values (usage of Mutex) - 3

Nirmalya Sengupta — Wed, 21 Jun 2023 06:50:31 +0000

[Cover image credit: https://pixabay.com/users/engin_akyurt-3656355]

Build up

Perhaps, it will be easier to understand the background of this article, if the ones just preceding it (in the series) are referred to:

Rust Notes on Temporary values (usage of Mutex) - 1 (link)

Explores Method-call expressions and binding.
Rust Notes on Temporary values (usage of Mutex) - 2 (link)

Explores RAII, OBMR and how these are used in establishing the behaviour of a Mutex

Mutex is used to fence a piece of data. Any access to this data, is preceded by acquiring a lock on it. Releasing this lock is crucial, because unless that happens, subsequent access to this data will be impossible. In the preceding article, we have briefly seen how a combination of RAII (or OBMR) and Scoping rules of Rust, makes this very straightforward. However, are there cases where the lock is held for longer than we expect?

Revisiting accessing the fenced data

We have seen this snippet earlier.

use std::sync::Mutex;
fn main() {
    let a_mutex = Mutex::new(5);
    let stringified = a_mutex.lock().unwrap().to_string(); // multiple transformations here!    
    println!("stringified -> {:?}", stringified);
    println!("Mutex itself -> {:?}", a_mutex);
    println!("Good bye!");
}

a_mutex.lock().unwrap().to_string(): In that expression, multiple steps are taking place:

Lock is obtained from a_mutex. An unnamed MutexGuard object is produced.
The MutexGuard is unwrapped and its internal i32 ( value of '5') is made available (through a mechanism of deref but that is not important here)
The to_string() method available on i32 is called.
A stringified representation of numeric '5' is produced. This is the final value of the expression.
Then the expression is complete and the statement ends. Unnamed MutexGuard goes out of scope and hence, dropped. The lock is released.

This stringified representation is assigned to (bound to) stringified.

Importantly, just before that ;, the scope of unnamed MutexGuard ends, and it is dropped, thereby releasing the lock. That is as well, because once we call to_string(), our objective has been fulfilled.

Can we force the guard to stay open for longer?

The MutexGuard is dropped when the statement ends. What if we want the guard to exist, till we want?

We have already seen this:

use std::sync::Mutex;

fn main() {
    let a_mutex = Mutex::new(5);
    let guard = a_mutex.lock().unwrap(); // <-- 'guard' is of type `MutexGuard`
    println!("guard -> {:?}", guard);
    println!("Mutex itself -> {:?}", a_mutex);

    // An attempt to acquire the lock again.
    let w = a_mutex.try_lock().unwrap();
    println!("Good bye!");
}

The output clearly shows that the mutex is in a locked state and an attempt to acquire the lock again is disallowed:

guard -> 5
Mutex itself -> Mutex { data: <locked>, poisoned: false, .. }
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: "WouldBlock"', src/main.rs:37:32
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Why? Because the MutexGuard has not gone out of scope. It is now bound to a variable guard; therefore it is not temporary anymore. In fact the MutexGuard's scope now spans till the end of the block, i.e. end of main in this case.

Clearly, the scope of MutexGuard ends when we operate directly on it by calling a method on value it is guarding but not when we bind it to a variable, and then operate on it. Does any other case exist, where the scope is extended?

Making use of `match` expression

lock() returns a LockResult; therefore, we can match on it:

use std::sync::Mutex;
fn main() {


    let a_mutex = Mutex::new(5);
    let stringified = match a_mutex.lock() { // <--- scope begins

        Ok(guard) => {
            let v = guard.to_string();
            println!("Mutex itself on a match arm -> {:?}", a_mutex);
            v
        }, 

        Err(e) => panic!("We don't expect it here {}!", e.get_ref()) // 'e' carries the guard inside it
    }; // <-- scope ends

    println!("stringified -> {:?}", stringified);
    println!("Mutex itself after guard is released -> {:?}", a_mutex);
    println!("Good bye!");
}

The output confirms that the lock is released, but after the entire match expression, ends:

Mutex itself while guard is alive, on a match arm -> Mutex { data: <locked>, poisoned: false, .. }
stringified -> "5"
Mutex itself after guard is released -> Mutex { data: 5, poisoned: false, .. }
Good bye!

So, the temporary here is being held inside the arm. Let us go a bit further.

In this case:

 use std::sync::Mutex;
fn main() {
    let a_mutex = Mutex::new(5);

    let stringified = a_mutex.lock().unwrap().to_string(); // <-- MutexGuard's scope ends heres
    println!("stringified -> {:?}", stringified);
    println!("Mutex itself after guard is released -> {:?}", a_mutex);
    println!("Good bye!");
}

The lock is released at the end of the statement ( conceptually, when ; is reached ).

But, not in this case:

 use std::sync::Mutex;
fn main() {

    let a_mutex = Mutex::new(5);
    let stringified = match a_mutex.lock().unwrap().to_string().as_str() {

        s @ "5" => {
            println!("We have received a five!");
            println!("Mutex itself while guard is alive, on a match arm -> {:?}", a_mutex);
            s.to_owned()
        },
        _ => "Not a five".to_owned()
    };  // <-- lock is released here!

    println!("stringified -> {:?}", stringified);
    println!("Mutex itself after guard is released -> {:?}", a_mutex);
}

Note: That .as_str() is required for idiomatically *match*ing String literals. It has got nothing to do with the core discussion here. The basic point remains the same: how long is the lock being acquired and held?

The scoping rules come into play. The expression that follows a match is called a Scrutinee Expression. In case a scrutinee expression generates a temporary value (viz., MutexGuard) it is not dropped till the end of scope of match expression. As a consequence, the lock is held, till the match expression comes to an end.

This has implications which may not be obvious. For example, what happens in this case?

use std::sync::Mutex;
fn main() {

    let a_mutex = Mutex::new(5);
    let stringified = match a_mutex.lock().unwrap().to_string().as_str() {

        s @ "5" => {
            println!("Mutex itself while guard is alive, on a match arm -> {:?}", a_mutex);
            // the lock is held here..
            let p = do_some_long_calculation(); // Example function, not implemented
            // the lock is still held here..
            let q = make_a_network_call(&p);    // Example function, not implemented
            s.to_owned() + q
        },
        _ => "Not a five".to_owned()
    };  // <-- lock is released here!

    println!("stringified -> {:?}", stringified);
    println!("Mutex itself after guard is released -> {:?}", a_mutex);
}

Executing functions, which take time to finish, will effectively prevent the lock from being released. If someone else is waiting for the lock (may be, another thread), tough luck!

Before we close, let's contrast the code above, with the code below:

use std::sync::Mutex;
fn main() {
    let a_mutex = Mutex::new(5);

    let unfenced = a_mutex.lock().unwrap().to_string(); // <-- MutexGuard goes out of scope

    let stringified = match unfenced.as_str() { // like earlier, ignore the as_str() function

        s @ "5" => {
            println!("We have received a five!");
            println!("Mutex itself while guard is alive, on a match arm -> {:?}", a_mutex);
            s.to_owned()
        },
        _ => "Not a five".to_owned()
    };

    println!("stringified -> {:?}", stringified);
    println!("Mutex itself after guard is released -> {:?}", a_mutex);
    println!("Good bye!");
}

Main Takeaways

In order to extend a temporary value's scope, it is bound to a variable using the let statement.
In case of MutexGuard, a let statement forces the guard to exist for longer (depends on the scope of the let variable). While the guard exists, the lock on the innter piece of data remains acquired.
In case using match expression that works on a temporary, the scope extends till the end of the match expression.
Because an arm of a match can execute arbitrary logic, the lock can be held for longer than expected or even, necessary. This is an important observation.

Acknowledgements

In my quest to understand the behaviour of the compiler in this case, I have gone through a number of articles / blogs / explanations. I will be unfair and utterly discourteous on my part, if I don't mention the some of them. This blog stands on the shoulders of those authors and elaborators:

My specific question on stackoverflow and fantastic answers given by Chayim Friedman, masklinn, and paul.
This stackoverflow QnA On, how the lock should be treated, in order to make use of the value tucked inside the mutex.
This post has been extremely valuable for me to understand the issue of interplay between Place Context and Value Context! Thank you Lukas Kalberbolt. A great question is posed by AnimatedRNG.

Rust Notes on Temporary values (usage of Mutex) - 2

Nirmalya Sengupta — Fri, 16 Jun 2023 04:26:57 +0000

[Cover image credit: https://pixabay.com/users/engin_akyurt-3656355]

Build up

In this article (first in the series), I have elaborated the understanding of temporary objects / variables in an expression, their scopes and behaviour.

This article is a continuation of the same topic, but it explores a much-used (and very crucial in multi-threaded context) type in Rust programming: the Mutex .

Quick definition for the context

The concept of a Mutex (Mutual Exclusion) is ages old. The idea is to ensure that only one thread of execution can access and modify a piece of data in memory, it must be locked first and unlocked, post-modification. All threads must govern themselves by checking for the lock's availabilty before going ahead with the modification; if the lock is not avaiable (meaning, some other thread is in the middle of modifying the data beind the lock), it must not gatecrash but wait, patiently.The Rust bool's chapter on Mutex is a recommended read.

Mutex in Rust

The crucial and tricky thing about a Mutex is about when to put in the lock around the inner data (rememember: a lock's existence is jutsified because it is guarding some piece of data in memory) and when to lift it. The sequecnce of acquiring and releasing the lock extremely important. Before we try to understand the way it is done in Rust, we should get familiarized with a term: RAII.

RAII

RAII stands for, rather too predictably, Resource Acquisition Is Initialization (phew!). C++ experts are quite familiar with it. I will not delve deep into this topic - other detailed descriptions like this, this and this and several others - exist for a deeper understanding.

Put very simply, RAII is a mechanism which stipulates that any access to a computing resource (viz., memory,file, DB Connection etc.) must be preceded by its construction. While this sounds kind of given, the subsequent part is what is important: the access to resource is denied after the destruction of the resource. In other words, the resource is available strictly between its creation and demise.The duration between these two stages of life, is determined by the scoping rules.

OBRM

I have come across this term while tinkering with Rust. OBRM stands for O*wnership *B*ased *R*esource *M*anagament (you don't like the acronym? I don't, either 😃 ). Again, I will not delve into this either (I find these 2 good videos by #letsgorusty here and here, quite explanatory). The main understanding is this: acquisition and release of resources are governed by the *Ownership rules of Rust. Put simply, when the object (say, a constructed struct) that holds the resource is destroyed ( *Drop*ped ), the resource is released too. Automatically! The language ensures this behavior!

My objective is to elucidate how this idiom is used in Rust's handling of Mutex.

Experiments and observations

We hold a simple i32 value inside a Mutex, then operate on it, observe the behavior of the code and convince ourselves why the behavior is that way!

use std::sync::Mutex;
fn main() {
let a_mutex = Mutex::new(5);         // Just an i32 value inside a mutex
    let guard = a_mutex.lock().unwrap(); // <-- 'guard' is of type `MutexGuard`
    println!("guard -> {:?}", guard);
    println!("Mutex itself -> {:?}", a_mutex);
    println!("Good bye!");
}

The output is:

guard -> 5
Mutex itself -> Mutex { data: <locked>, poisoned: false, .. }
Good bye!

Inside itself, the Mutex is holding its own data in a Locked state. Then the program ends, and the lock is released. But, where is that MutexGuard coming from?

Here's what the rust-lang documentation says, of the lock method:

It returns a LockResult, which when transformed using an unwrap() like in the code above, produces a MutexGuard which is guarding an i32 (the type T) in this case.

What it we try to acquuire the lock again, on the same a_mutex?

use std::sync::Mutex;
fn main() {
    let a_mutex = Mutex::new(5);
    let guard = a_mutex.lock().unwrap(); // <-- 'guard' is of type `MutexGuard`
    println!("guard -> {:?}", guard);
    println!("Mutex itself -> {:?}", a_mutex);

    // An attempt to acquire the lock again.
    let w = a_mutex.lock().unwrap();
    println!("Good bye!");
}

This time, the output is:

guard -> 5
Mutex itself -> Mutex { data: <locked>, poisoned: false, .. }

The program never terminates (it cannot even say 'Good Bye')! Why? This is what the documentation says:

The exact behavior on locking a mutex in the thread which already holds the lock is left unspecified. However, this function will not return on the second call (it might panic or deadlock, for example).

In our case, we made a second call, on a mutex, in the same thread (the main thread here, there is only one)!

Mutex has a helpful alternative, in the form of Mutex::try_lock(), which allows us to attempt to acquire the lock, knowing that we may fail.

use std::sync::Mutex;

fn main() {
    let a_mutex = Mutex::new(5);
    let guard = a_mutex.lock().unwrap(); // <-- 'guard' is of type `MutexGuard`
    println!("guard -> {:?}", guard);
    println!("Mutex itself -> {:?}", a_mutex);

    // An attempt to acquire the lock again.
    let w = a_mutex.try_lock().unwrap();
    println!("Good bye!");
}

This time, the output is:

guard -> 5
Mutex itself -> Mutex { data: <locked>, poisoned: false, .. }
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: "WouldBlock"', src/main.rs:37:32
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

The error message is quite explanatory. The attempt to acquire the lock again, fails because the it will have caused a forever blocking and therefore, non-termination of the program as we have seen eariler.

The point of interest is this part from rust-lang documentation:

This function will block the local thread until it is available to acquire the mutex. Upon returning, the thread is the only thread with the lock held. An RAII guard is returned to allow scoped unlock of the lock. When the guard goes out of scope, the mutex will be unlocked.

The type of this RAII guard is MutexGuard, (my comment on the code-snippet). What is its purpose in life?

Again, rust-lang documentation tells us in comforting details:

An RAII implementation of a “scoped lock” of a mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
The data protected by the mutex can be accessed through this guard via its Deref and DerefMut implementations.
This structure is created by the lock and try_lock methods on Mutex.

The key portion, in our context, is this: "When this structure is dropped (falls out of scope), the lock will be unlocked".

In search of the 'Scope'

Let us try and find out what is the scope of the guard.

fn main() {
    use std::sync::Mutex;

    let a_mutex = Mutex::new(5);

    {   // <-- Beginning of scope
        let guard = a_mutex.lock().unwrap(); // <-- 'guard' is of type `MutexGuard`
        println!("guard -> {:?}", guard);
    }   // <-- End of scope`

    println!("Mutex itself -> {:?}", a_mutex);
    println!("Good bye!");
}

The output is quite as expected.

guard -> 5
Mutex itself -> Mutex { data: 5, poisoned: false, .. }
Good bye!

Don't miss the fact that Mutex { data: 5, poisoned: false, .. } indicates the absence of the lock being held, as opposed to the output that we have seen earlier: Mutex { data: <locked>, poisoned: false, .. }. The following achieves the same effect, for the same reason:

fn main() {
    use std::sync::Mutex;

    let a_mutex = Mutex::new(5);
    let guard = a_mutex.lock().unwrap(); // <-- 'guard' is of type `MutexGuard`
    println!("guard -> {:?}", guard);
    drop(guard);  // <-- Dropping manually!

    println!("Mutex itself -> {:?}", a_mutex);
    println!("Good bye!");
}

The output is exactly the same as the precding output ( no lock ).

We establish then, that when the guard is dropped, the lock is released automatically, as per the premise of RAII (or OBRM, if you like). But, when is it constructed exactly?

Let's be a bit adventurous and peep into the implementation of std::sync::Mutex.rs:

#[stable(feature = "rust1", since = "1.0.0")]
    pub fn lock(&self) -> LockResult<MutexGuard<'_, T>> {
        unsafe {
            self.inner.lock();
            MutexGuard::new(self)
        }
    }

Let's ignore everything except, the return type and the call to MutexGuard::new(self). Even without much knowledge about the internals, it is quite clear that when Mutex::lock() returns, it carries with itself, freshly built MutexGuard object. Just before that happens, a lock resource (Operating System resource) has been obtained. The initialization has guaranteed the acquisition!

How about release of the lock? Again, peeping into the source of std::sync::Mutex.rs:

#[stable(feature = "rust1", since = "1.0.0")]
impl<T: ?Sized> Drop for MutexGuard<'_, T> {
    #[inline]
    fn drop(&mut self) {
        unsafe {
            self.lock.poison.done(&self.poison);
            self.lock.inner.unlock();
        }
    }
}

The key point for us is that self.lock.inner.unlock() statement. As the MutexGuard is dropped, the lock is released!

Therefore, the scope in which a MutexGuard remains valid, follows the idiom of RAII!

The temporary MutexGuard

The preceding article in this series discusses the concept of temporary variable. One of the takeaways from that is the presence of a receiver, which is temporarily produced to complete the method-call expression.

The concept of this temporary object is applicable in the case of MutexGuard here too. And, following the scoping rules of a temporary, the MutexGuard ceases to exist at the end of the statement.

fn main() {

    use std::sync::Mutex;

    let a_mutex = Mutex::new(5);
    let guard = a_mutex.lock().unwrap().to_string(); // <-- 'guard' is of type `String`

    println!("Mutex itself -> {:?}", a_mutex); // <-- MutexGuard is not being held
    println!("guard -> {:?}", guard);

    // An attempt to acquire the lock again.
    let w = a_mutex.try_lock().unwrap();
    println!("Good bye!");
}

Nothing surprising about the output:

guard -> "5"
Mutex itself -> Mutex { data: 5, poisoned: false, .. }
Good bye!

Notice the absence of any data: <locked> in the Mutex. When the preceding statement ends - yielding the stringified representation of value '5' - the tempoary MutexGuard

reaches the end of its scope,
is dropped, and therefore
releases the lock (re: RAII)

We have read the value that is fenced in by the Mutex and have trodden in the world of expressions along with temporary objects. In the next article in this series, we explore more about how the scope of the temporaries is affected by the body of an expression.

Main Takeaways

Mutex follows the idiom of RAII (or OBRM) for ensuring that access to the value it is guarding, cannot be breached.
Mutex.lock() produces a temporary MutexGuard whose construction and destruction ( Drop ), acquires and releases the lock, in that order.
Because it is a temporary object, the MutexGuard is dropped at the end of the statement that creates it, unless it scope is expanded by other means (that is not a part of this article though).

Rust Notes on Temporary values (usage of Mutex) - 1

Nirmalya Sengupta — Wed, 14 Jun 2023 04:20:53 +0000

[Cover image credit: https://pixabay.com/users/engin_akyurt-3656355]

The build up

Just like other enthusiastic Rust newbies, I am trying to trek through the difficult terrain of Rust's Borrow-checker, with excitement, mixed with trepidation. Many times, I fall foul of the compiler, because I am careless or I lose sight of the obvious. But, some other times, compiler's reprimands baffle me, to no end.

One such case is of compiler flagging: temporary values getting freed at the end of the statement!

A method-call expression like:

a.b().c().d;

is so common in a program that one tends to write it, almost by reflex. Yet, some times the compiler derails the line of thought, unexpectedly, pointing out release of a temporary variable, that one hasn't even mentioned.

I had decided to understand the whys and the wherefores of this particular problem, to reasonably good extent. At least, I should know how to avoid those. This is a digest of that exploration.

Simulate the error

An Employee has an id ( i32 ). It implements a get_details() method.

This method, intentionally, returns a new Details Object (the reason behind this, will be clearer later). The object initializes the name field with a String constant, which it owns!

#[derive(Debug)]
struct Employee {
    id: i32
}

#[derive(Debug)]
struct Details {
    emp_id: i32,
    name: String
}

impl Employee {
    pub fn get_details(&self) -> Details {
        Details { emp_id: self.id, name: String::from("Nirmalya") }
    }
}

impl Details {
    pub fn get_name( &self ) -> String {
        self.name
    }
}

fn main() {

    let e = Employee { id: 10 };
    let n = e.get_details().get_name();
    println!("Employee name: {}", n);     

}

The compiler frowns, expectedly ...

error[E0507]: cannot move out of `self.name` which is behind a shared reference
  --> src/main.rs:31:9
   |
31 |         self.name
   |         ^^^^^^^^^ move occurs because `self.name` has type `String`, which does not implement the `Copy` trait

We are not allowed to 'move' the name here; the &self parameter is prohibiting it. The move requires the Details to be modified. The get_details() method taken in an immutable reference: &self. After the method returns, self.name cannot remain uninitialized.

We cannot move but we can possibly share a reference then?

impl Details {
    pub fn get_name( &self ) -> &String {  // String is replaced with &String
        &self.name
    }
}

The compiler finds the temporary which is freed prematurely, this time.

error[E0716]: temporary value dropped while borrowed
  --> src/main.rs:41:13
   |
41 |     let n = e.get_details().get_name();
   |             ^^^^^^^^^^^^^^^           - temporary value is freed at the end of this statement
   |             |
   |             creates a temporary value which is freed while still in use
42 |
43 |     println!("Employee name: {}", n);     
   |                                   - borrow later used here
   |
help: consider using a `let` binding to create a longer lived value
   |
41 ~     let binding = e.get_details();
42 ~     let n = binding.get_name();
   |

For more information about this error, try `rustc --explain E0716`.

So, changing the body and return type of Details::get_details() is causing an otherwise harmelss method-call expression to fail.

But why? Let's find out more about this.

Elaboration

A binding comes into existence with the let statement: e is bound to and thereby is owning an Employee struct(ure).

let e = Employee { id: 10 };

We are trying get an access to the Employee's name. This name is not a part of Employee but of a different object of type Details.

let n = e.get_details().get_name();

What get_details() produces is a Details object. We are calling get_name() on it. What's there to complain about?

Well, the get_name() is returning a reference to a member variable of Details. For this reference to remain valid (pointing to some place which is initialized with some known value), Details has to keep existing. But, till when? The answer lies in establishing its scope.

Expresssions and Scopes

This is a method-call expression:

e.get_details().get_name();

get_details() is a direct method on the type Employee. Here, e is called the receiver of method-call.

get_name() is a direct method on the type Details. But, where is the receiver of this method-call? Taking a closer look, we find that an unnamed object of type Details has been made available - temporarily - so that we can call the method. Our intention is to be able to get hold of what get_name() returns. We don't really care about this faceless helper object, though.

The key understanding here, is that get_name() returns a reference. It refers to a field of Details object. If and when this (temporary) Details object ceases to exist (or Drop-ped, if you like), the reference is invalidated.

By the rule of scope of such temporaries (more here), they can live till the end of the statement that contains the call that produces it. Interpeting this vis-a-vis our example, by the time the whole expression is evaluated and the statement ends, the faceless Details object has gone out of existence. Therefore, it is illegal to hold a reference to a field that it owns. So, n cannot be assigned to.

This explains the complaint from the compiler, shown above.

Going a little further

One way, not to let the faceless Details object go, is to bind it to a memory location.

fn main() {
    let e = Employee { id: 10 };
    let intermediate_d = e.get_details(); // <--- Binding!
    let n = intermediate_d.get_name();    // <--- Method call expression
    println!("Employee name: {}", n);     
}

In this case, the compiler is happy and waves us ahead. But, why exactly?
Because we have bound the hitherto faceless Details object to intermediate_d, its scope has now been extended to the end of the block it belongs to (in this case, the end of the body of function, i.e.,main()). Thus, getting hold of the name inside it, is not illegal anymore.

This was what the ever helpful Rust compiler suggested in the error message, shown earlier! 👌 🌟

Interestingly, the following code is flagged as alright, by the compiler.

fn main() {
    let e = Employee { id: 10 };
    let n = e.get_details().get_name().len(); // <-- expression produces a value.
    println!("Employee name: {} chars long", n);     
}

In this case, the length of the name is what we hold in n. The faceless Details object, goes away by the end of the statement, but it doesn't matter. We are not holding any reference to Details.name anyway.

Even this works, but for a slightly different reason:

impl Details {
    pub fn get_name( &self ) -> String {
        self.name.to_owned()  // <-- Not a reference, but a cloned value, unassociated with `self.name`
    }
}
// ........
fn main() {
    let e = Employee { id: 10 };
    let n = e.get_details().get_name();
    println!("Employee name: {}", n);     
}

Because get_name returns a value that is owned by - and not referred to by - the caller, the non-existence of the faceless Details object is immaterial here. n is bound to a fresh replica of what was held by Details.name. Its scope extends till the end of the block; in this case, the end of body of function, i.e., main().

Main Takeaways

Method chains are Method-call expressions. Like every expression, they evaluate to a value.
Every dot ( . ) operation is a method/function, which operates on an object, called the 'Receiver' according to the Book (rust book). The receiver's type must have that method defined on itself.
In some cases, in order to determine the intended receiver, the compiler follows the references along the expression and produces temporary objects as receivers. The scope of these temporary objects extends up to the end of the statement they are contained in (not exactly, but let's continue till subsequent articles on this topic). Therefore, the compiler considers any attempt to access these temporary objects through references, after the statement, as illegal.
The simplest way to avoid this, is to declare local variables to bind to these temporary objects. The helpful compiler even hints at this, along with the error message.

Acknowledgements

In my quest to understand the behaviour of the compiler in this case, I have gone through a number of articles / blogs / explanations. I will be unfair and utterly discourteous on my part, if I don't mention at least, some of them. This blog stands on the shoulders of those authors and elaborators:

https://fasterthanli.me/articles/a-rust-match-made-in-hell from one of the most readable and elucidative take on all things Rust, by Amos ( @fasterthanlime ).
A brief yet illuminative answer by Sven Marnach on Stackoverflow.
An useful question on Stackoverflow by Bosh and fantastic answer by Jim Blandy. This answer has brought forth that Aha moment for me but the discussion trail itself is very helpful (thanks everyone else, in that ticket).
The chapter on Destruction in the Rust wiki and a bit of my own expeimentation
An old but quite useful explanation of scoping; recommended!
Of course, the relevant pages of The Rust Wiki, an excellent aid for a newbie like me.
My companion book by Jim Blandy (again!), Jason Orendorff, Leonora Tindall

Random Rust Notes - 4

Nirmalya Sengupta — Sat, 29 Apr 2023 17:25:34 +0000

[Cover image credit: https://pixabay.com/users/engin_akyurt-3656355]

This blog is a collection of notes of key learnings / understandings / Aha moments, as I am kayaking through demanding yet exciting waters, of Rust ( #rustlang ). If you happen to find defects in the code or gaps in my understanding, please correct me. I will remain thankful.

The topic of this particular notes: scoped_threads in Rust.

A brief on spawned threads

Using the standard library, whenever a thread is launched - spawn-ed - a unit of execution - - with an associated piece of logic - is created. Underneath, the library, OS facilities and hardware work together to run that unit of execution , separately from the unit of execution that launched it. This is at the core of threading - a bit simplistic, I agree - concept. One is the parent thread and it launches a child thread, as is commonly understood.

Naturally, the child thread will finish its job at some point in time. The parent thread may need to know if and when that happens (let us keep away from the aspect of cancellation of the child thread for the time being). A mechanism must exist for it to be able to do that. This mechanism takes the form of a handle (programmer-speak). Using this handle, the parent thread waits for the child thread to join the former and then, the flow of execution continues.

So, we need a handle

pub fn start_as_free(&self) -> JoinHandle<()> {
        let message_collector_handle = thread::spawn(move || { () });
        message_collector_handle
    }

Here's a skeleton code: a thread is spawn-ed and its handle is returned to the caller (the parent thread). For a better understanding of what that JoinHandle is, here's the standard library's documentation. JoinHandle is a structure of type std::thread::JoinHandle. One of its implementation functions is named join, pub fn join(self) -> Result<T>. This is the mechanism available to the parent thread, to wait for the child thread to finish. From the standard library's documentation:

Now, a scoped thread

Instead of spawning a free-running thread as shown above, a parent thread may launch a scoped thread. A scoped thread, is built in a way which ensures that the function in which it is launched will finish only when the threads launched inside it are also finished. This is a key aspect because a scoped thread cannot live beyond the demarcation laid out by its parent thread. Therefore, the parent thread may share its own data structures with the child thread, secure in the understanding that all the changes (if any) done to these data structures by the child thread, are guaranteed to be visible to the parent.

From the standard library's documentation:

pub struct ScopedJoinHandle<'scope, T>(_);

So, ScopedJoinHandle is a structure, much like its elder sibling JoinHandle (elder, because it preexists). And, sure enough, it has a join() function as well. But with a twist!

Difference between spawning steps

A standard, your-friendly-companion-thread is spawned thus:

 let message_collector_handle = thread::spawn(move || { () });

A scoped, strictly-watched-and-controlled thread, is spawned thus:

let message_collector_handle = thread::scope (|current_scope| 
                               {
                                  current_scope.spawn(|| { Ok(()) });
                               }

Something special is happening in std::hread::scope() . From standard library's documentation:

pub fn scope<'env, F, T>(f: F) -> T
where
    F: for<'scope> FnOnce(&'scope Scope<'scope, 'env>) -> T,

So, the scope function takes in a closure as a parameter, which in turn takes in a Scope (with uppercase 'S') value as a paremeter.

What is that Scope? It is a struct! From the standard library's documentation:

pub struct Scope<'scope, 'env: 'scope> { /* private fields */ }

And, as expected, this struct implements a spawn function:

pub fn spawn<F, T>(&'scope self, f: F) -> ScopedJoinHandle<'scope, T>where
    F: FnOnce() -> T + Send + 'scope,
    T: Send + 'scope,

Let us not get lost in that crowd of symbols. The key understanding:

thread::scope takes in a closure. This closure, in turn, takes in a Scope value. Inside the closure, a thread is spawned: Scope::spawn(). This spawn() call returns a ScopedJoinHandle.
The return value of type ScopedJoinHandle is valid as long as the parameters are valid. Put another way, the return value (remember, this is a struct ) cannot live even when the Scope (the struct, starts with an uppercase 'S'!) doesn't.

An example makes it clearer, hopefully!

Let's watch these two functions, being compiled:

pub fn start_as_scoped(&self) -> ScopedJoinHandle<Result<(),String>>{
        let message_collector_handle = thread::scope (|current_scope| {
                    current_scope.spawn(|| { Ok(()) })              
                });

        message_collector_handle    
    }

// Here's our old friend, std::thread::JoinHandle
pub fn start_as_free(&self) -> JoinHandle<()> {
        let message_collector_handle = thread::spawn(move || { () });

  message_collector_handle
}

The compiler is watchful, yet helpful:

error: lifetime may not live long enough
  --> src/main.rs:30:21
   |
29 |         let message_collector_handle = 
                thread::scope (|current_scope| {                                            
                                -------------- return type of closure is ScopedJoinHandle<'2, Result<(), String>>
   |                            |
   |                            has type `&'1 Scope<'1, '_>`
30 |                     current_scope.spawn(|| { Ok(()) })
   |                     ^^^^  returning this value requires that `'1` must outlive `'2`

Hmm! We cannot return the ScopedJoinHandle in a manner as we could, for its sibling, JoinHandle .

But, why?

Without getting into the details of lifetime, we can analyse it intuitively.

The ScopedJoinHandle cannot live beyond the lifetime of the current_scope. Put in a different way, we cannot let the ScopedJoinHandle
return from the function, because that will mean that some other thread will be able to join the thread launched under the watchful eyes of
current_scope. But that is disallowed. The standard library's documentation makes that very clear:

All threads spawned within the scope that haven’t been manually joined will be automatically joined before this function returns.

This means, that either we explicitly join the thread before leaving the scope or thread will be implicitly join-ed by Rust runtime, when the current_scope is dropped.

This compiles:

 pub fn start_as_scoped(&self) -> i32 {
        let message_collector_handle = thread::scope (|current_scope| {
           current_scope.spawn(|| { 42 }).join()    // <---- join() before leaviing the current_scope>    
         });


        match message_collector_handle {
            Ok(x) => x,
            Err(_) => -1 // We could have returned a String, by modifying the return type of the function to Result<T,E>
        }

    }

Key takeaways

A thread which is spawned inside a scope, must end before scope ends.
Such a thread's handle cannot outlive the overarching scope.
Such a thread must be join-ed explicitly or those will be join-ed implicitly, at runtime. And, inside the scope!!

NB: Standard library's documentation on Scoped threads, is elaborate and worth a good reading!

Random Rust Notes - 3

Nirmalya Sengupta — Sat, 22 Apr 2023 17:12:09 +0000

[Cover image credit: https://pixabay.com/users/engin_akyurt-3656355]

This blog is a collection of notes of key learnings / understandings / Aha moments, as I am kayaking through demanding yet exciting waters, of Rust (#rustlang). If these help someone, I will be happy of course. OTOH, if someone happens to find defects in the code or gaps in my understanding, please correct me. I will remain thankful.

As a part of a personal project, I am in the middle of learning how to use channels to communicate between two threads. This is quite a common topic. Many people seem to have questions around this topic. Many answers / explanations are available.

These are my notes, though.

Takeaways from the previous note

The previous note is here (for a quick recap, in cases needed)

Using channels, multiple producers can send messages to a single consumer.
Each such producer must have its own copy of the sender-end of the channel. clone the sender-end for this.
Channels are unidirectional and FIFO in structure; therefore, every producer's messages to the consumer reach in the same order in which they are despatched.
Multiple producers messages may reach in any random order, though.

What is it that I am modeling (recap helps)

An in-memory dashboard, which
- Works as a collector of events generated by a number of event-generators
- Informs a viewer of the events as they are arriving and being collected
- Dumpts a chronicle of the events that it receives before terminating
Each event generator is modeled as a thread that pushes the events and then terminates
An event inquirer - another thread itself - which registers itself with the dashboard, so that the dashboard can keep informing it of the events as they arrive

All communications between various threads, happen through channels and are based on an application-specific protocol, implemented as an Enumeration. Enumumerations help in ensuring that channels are bound to a particular type.

The dashboard is modeled as a struct. It has a lifecycle:

Created using a conventional new() function
Prepared with a ready() function
Nudged to receive, events from producers (separate threads, outside the struct) with a start() function
Brought to an end, by a stop() function

Having a lifecycle like this, helps in desigining and implementing, a clean, predictable and testable behaviour.

Key observations

The dashboard is built as a black-box like entity. It is created, used and destroyed using its APIs. Therefore, some other thread - may be the main thread - is expected to bring it forth and let it go, when done.
The dashboard doesn't know how many event producers are alive, at a given point in time. The receiving end is with the dashboard and the sending ends are with the event producers (remember, Sending ends need cloning). So, the dashboard waits till all the sending ends have gone out of existence ( dropped in Rust parlance), which is when the receiver in Dashboad, returns with an error. This is how the dashboard knows when not to expect any further events.
There are more than one channels, Obviously, distributing the sending and receiving ends has to be carefully and correctly done.
Receivers cannot be shared between threads, like the way Senders can be. Therefore, to share the receivers, one needs to wrap those in some kind mutually exclusive data structure and then shared. This mutual exclusion is important to ensure that one of the threads accesses it at a given point in time.

Random Rust Notes - 2

Nirmalya Sengupta — Mon, 17 Apr 2023 16:48:28 +0000

[Cover image credit: https://pixabay.com/users/engin_akyurt-3656355/]

These are my notes, though.

Takeaways from the previous note

The previous note is here (for a quick recap, in cases needed)

A channel is created with two ends: one used for sending and other for receiving. While creating a channel, we specify the type of data that will pass through it, when the program runs.
One thread gets ownership of the end that sends; the other thread gets ownership of the end that receives.
The channel is always unidirectional, from the sending end to the receiving end. No Request-Response style inter-thread communication is possible, using a single channel.
Any of the two ends may decide to stop working, independent of the other. No handshaking and Good-Bye is necessary. The thread that holds the sending end, may decide on its own, if and when to stop sending; similarly, for the thread that holds the receving end.
If one of the ends becomes non-operational, the other end receives an error. This behaviour is captured by the return type of send() and receive() functions.

The case of many senders (MPSC)

For those who remember the famous *Producer-Cconsumer * problem from the textbooks (for me, a few decades ago 😁 ) - here's a wikipedia page for a quick reference - the mechanism of channels should seem familiar. The thread that sends data into the channel, is the producer thread; the other thread which reads from the same channel, is the consumer thread.

With only two threads, there is one producer and one consumner, commonly referred to as SPSC. What if there are multiple producers, a case of MPSC?

Obviously, each thread (a producer) has to have access to the sending end of the channel. Put even more simply, every thread has to have a sender for itself.

Referring to the code snippet in the previous note, we have:

    // ... continuing in current thread, let's call it one_thread
    let (sender, receiver) = channel::<Conversation>();

    let another_thread =  // another thread starts here ...
        thread::spawn(move || { 
         let a_message = Conversation::Hello;
         sender.send(a_message).unwrap();

         let another_message = Conversation::HowAreYou;
         sender.send(another_message).unwrap();

     }) // another_thread ends here

     // ... continue in one_thread

     let receipt_of_hello = receiver.recv().unwrap(); // message 'Hello' is here
     let receipt_of_how_are_you = receiver.recv.unwrap(); // message 'HowAreYou' is here
     // .. go on and do the rest

Because of the move , the ownership of sender is transferred to closure above. another_thread then runs the closure. This easy arrangement is not an option, when there is yet_another_thread. The ownership of sender cannot be transferred to the closure for yet_another_thread, as well. What do we do?

We simply duplicate the sender and pass one each to the closures. The above code takes the form:

    // ... continuing in current thread, let's call it one_thread
    let (sender, receiver) = channel::<Conversation>();

    let another_sender = sender.clone();

    let another_thread =  // another thread starts here ...
        thread::spawn(move || { 
         let a_message = Conversation::Hello;
         another_sender.send(a_message).unwrap();

         let another_message = Conversation::HowAreYou;
         sender.send(another_message).unwrap();

     }) // another_thread

    let yet_another_sender = sender.clone();

    let yet_another_thread =  // another thread starts here ...
        thread::spawn(move || { 
         let a_message = Conversation::Hello;
         yet_another_sender.send(a_message).unwrap();

         let another_message = Conversation::HowAreYou;
         sender.send(another_message).unwrap();

     }) // yet_another_thread

     // ... continue in one_thread

     let receipt_of_hello = receiver.recv().unwrap(); // message 'Hello' is here
     let receipt_of_how_are_you = receiver.recv.unwrap(); // message 'HowAreYou' is here
     // .. go on and do the rest

Obviously, such an arrangement is applicable to more than two producers also. We just need as many duplicates of sender.


for i in 0..5 {  // '5' could have been, say '1000'!
    let duplicate_sender = sender.clone();

    // another thread starts here; we are 
        thread::spawn(move || { 
         let a_message = Conversation::Hello;
         duplicate_sender.send(a_message).unwrap();

         let another_message = Conversation::HowAreYou;
         duplicate_sender.send(another_message).unwrap();

     }) // another_thread

}

Multiple producers done, what about single consumer?

The channel is unidirectional. Producers send messages in the direction of the Consumer. The consumer has to keep waiting for the messages to arrive, until the recv() returns an error indicating that all producers are done with their action (refer to the previous note). Almost intuitively, a consumer is a loop:

while let Ok(message_received) = receiver.recv() {
         println!("Message received: {:?}",message_received);
}

A Rust playground is here.

A crucial understanding is about the order in which the consumer receives the messages. The channel is FIFO for every Producer -> Consumer, but not for all Producers -> Consumer. If producer-1 sends 2 messages (say, m-1-1 and m-1-2) and producer-2 sends 2 messages (say, m-2-1- and m-2-2) to the same consumer, then the order in which the messages reach can be:

m-1-1, m-2-1-, m-2-2, m-1-2, or
m-1-1, m-1-2, m-2-1, m-2-2 , but
m-1-1 always reaches before m-1-2 and m-2-1 always reaches before m-2-2-

Takeaways

Using channels, multiple producers can send messages to a single consumer.
Each such producer must have its own copy of the sender-end of the channel. clone the sender-end for this.
Channels are unidirectional and FIFO in structure; therefore, every producer's messages to the consumer reach in the same order in which they are despatched.
Multiple producers' messages may reach in any random order, though.

Random Rust Notes - 1

Nirmalya Sengupta — Mon, 17 Apr 2023 12:27:00 +0000

[Cover image credit: https://pixabay.com/users/engin_akyurt-3656355/]

This blog is a collection of notes of key learnings / understandings / Aha moments, as I am kayaking through demanding yet exciting waters, of Rust (#rustlang). If these help someone, I will be happy of course. OTOH, if someone happens to find defects in the code or gaps in my understanding, please correct me. I will remain thankful.

Using channels to communicate between threads

These are my notes, though. Here goes:

Channels provide mechanism for any two threads to communicate asynchrounously. It is unidirectional in structure and behaviour. Every channel has (at least) a Sender and a Receiver. The names indicate which end of the channel is occupied by which.
If we can set up a channel in such a way, that one thread gets hold of the sending end (in other words, is the Sender) and the other thread gets hold of the receiving end (in other words, is the Receiver), then they can converse.
Using std::sync::mpsc crate, the pattern to create a channel is:
let (sender, receiver) = channel::<Conversation>();

Conversation is an enum. The messages that are sent over the channel, are of type Conversation. Almost every example I have come across on the 'Net, uses i32 or &str, but such an enum is contextually more meaningful (in my view 😁 ). Thus, the name.

In keeping with the norms followed in tramission of signals, senders are named as tx and receivers, as rx. Many blogs/dicsussions use these. Doesn't matter, does it? tx == sender and rx == receiver!
Two threads are going to converse. Therefore, one thread has to have access to the sender and the other thread, obviously, gets the receiver.

Channels are unidirectional

A channel is unidirectional: the messages always go from the sending side to the receiving side. In other words, the thread holding the sender, begins the conversation by sending a message; the thread holding the receiver, takes action on the receipt of the message.
A key understanding is that the receiver does not respond to the message through the same channel. These channels are not bi-directional and hence, cannot be used for a Request-Response model.

How do two threads make use of the channel?

Create the channel first. Now, we have the sender and the receiver.
The act of creation must happen on some thread. After all, we are executing a piece of code, on some existing thread!

    // ... continuing in current thread, let's call it one_thread
    let (sender, receiver) = channel::<Conversation>();

    let another_thread =  // another thread starts here ...
        thread::spawn(move || { 
         let a_message = Conversation::Hello;
         sender.send(a_message).unwrap();

         let another_message = Conversation::HowAreYou;
         sender.send(another_message).unwrap();

     }) // another_thread ends here

     // ... continue in one_thread

     let receipt_of_hello = receiver.recv().unwrap(); // message 'Hello' is here
     let receipt_of_how_are_you = receiver.recv.unwrap(); // message 'HowAreYou' is here
     // .. go on and do the rest

The order in which another_thread is sending the messages, is the order in which the receiver is receiving them. This is because the channel is FIFO in structure and behaviour. This is an important observation, because what if there are more than one senders? More about it later.

How do threads know when to stop?

An ongoing conversation stops, when one of the participants stops. Therefore, if either the Sender stops or the Receiver stops, the other side must have to know. This is important to understand.
Significantly, neither of std::sync::mpsc::{Receiver,Sender} provides any mechanism to stop sending or receiving. But, they are dropped, meaning they cease to exist, perhaps because the scope in which they are defined, comes to an end.
We note that the sending side (one_thread above) and the receiving side (another_thread above) are completely disconnected (naturally, one argues, because they are threads). Neither of the two is aware of the continued existence of the other side. Unless the channel through which they are communicating offers help!
To help, the channel specifies this: if a sender fails to send - in other words, the act of sending returns with an error - the sender comes to know that the receiver has become non-existent (no point sending any more). Similarly, if the sender goes out existence (viz. being dropped perhaps), the receiver is handed an error (nothing is going to arrive any further). Based on this, the threads can decide how to deal with a disconnection from one another.
Because the action of send/receive may return with an error, the retrun type of of these functions is a Result.
A call to send() returns a Result<(),SendError>. A call to receive() returns a Result<Conversation,RecvError> . Of course, that Conversation is my example type. It can be any valid type (generically speaking, Result<T,RecvError>).
This Result<..> explains the use of unwrap() in the code snippet, above.

Takeaways

A channel is created with two ends: one used for sending and other for receiving. While creating a channel, we specify the type of data that will pass through it, when the program runs.
One thread gets ownership of the end that sends; the other thread gets ownership of the end that receives.
The channel is always unidirectional, from the sending end to the receiving end. No Request-Response style inter-thread communication is possible, using a single channel.
Any of the two ends may decide to stop working, independent of the other. No handshaking and Good-Bye is necessary. The thread that holds the sending end, may decide on its own, if and when to stop sending; similarly, for the thread that holds the receving end.
If one of the ends becomes non-operational, the other end receives an error. This behaviour is captured by the return type of send() and recv() functions.

Why am I learning Rust?

Nirmalya Sengupta — Tue, 04 Apr 2023 07:00:00 +0000

The Build-up

I met Debasis Basu (LinkedIn) at a social event, a few weeks ago.

Debasis is a childhood friend. We studied at the same residential high-school and spent six of our formative years together: a brilliant student (much better than I have been 😁) and an excellent sportsperson (again, much ahead of me 😞), Debasis has had an outstanding career for over 35 years, after graduating from IIT, Kharagpur, India. A keen observer of the goings-on, in the technology industry, Debasis has this habit of putting me off-guard, by asking relevant, pointed and interesting questions. I fumble but then, I become aware of gaps between what I know and what I think I know.

This time, too, Debasis threw a seemingly simple question at me: why are you learning Rust? What is it that you can do using Rust, that you cannot do using say, 'C'?

I put up a brave face, thought on my feet and mumbled something. It quickly became obvious to me, that my effort did not leave any much effect on him. He looked plainly unimpressed.

Later, I played the conversation in my mind. If I could not tell Debasis - who has (more than) the requisite background and was genuinely all ears - reasonably convincingly why I was learning Rust, what chance did I have to tell someone else, having much less attention to and much less time for, what I had to say? More importantly, did I ever tell myself why would I like to learn Rust?

So, I decided to put together my thoughts into a more coherent form, but I will begin with a quote I have remained very, very fond of:

A language that doesn't affect the way you think about programming, is not worth knowing.

-- Alan Perlis

Learning a new language makes me think differently from what I am used to

Rust is a systems programming language. I have developed non-trivial software using 'C' in the first decade and a half of my career. That was my first - and so far, last - fortuitous association with what is called systems programming. A compact language, having 32 keywords, 'C' propounded a philosophy of doing a lot by saying a little. Being a low_level language, it provided powerful constructs that allowed me - the programmer - to go very near to the world where the machine ruled. The fall-out was a huge responsibility on me to be 'right' along the entire flow from very near to the user application to very near to the machine. The price to pay for being inattentive could be disatrous. The power was intoxicating for a programmer and the responsibility was unnerving. The long nights spent in following a wayward pointer are still etched in my mind.

Rust brings in a different philosophy. The Rust compiler has strict rules and it employs them ruthlessly. Armed with these rules, it tries to foresee where my code can go wrong when it runs, even when I haven't been careful. This changes the game altogether. The compiler can see what I - the programmer - have possibly failed to see and then, by throwing compile-time errors, the compiler refuses to let me move ahead. Thus, to satisfy the compiler, I am forced to consider implications of my code while writing it:

is a variable associated with right data type througout its usage?
is a pointer dangling dangerously?
is a piece of memory being used incautiously by two threads? and such.

The important point is that the compiler doesn't let me proceed with such vulnerabilities. Consequently, in order to run my program, I have to think the way the compiler is thinking. This forced co-thinking with a very smart and powerful compiler has its benefits: I am made to think more precisely than I am used to. It helps sharpen my programming thinking.

I feel welcome. Yes, that matters.

From the very first time I stepped in the world of Rust, I felt that folks in the community were all extending a helping hand. Documentations were crisp and clear. Tutorials were meant to coach me and not just to take me to quick end of an example. Exercises were usefully graded, with appropriate hints to assist. Videos (on youtube) varied from simple features to complex concepts, without being patronizing.

Now, one may raise the eyebrow and wonder how do all these make Rust special? Are proponents and practitioners of other, newer languages any different?

Well, I will be honest. I cannot knowledgeably comment on how is the state of affairs with long list of other languages. I know and professionally work (have worked) with a few of them. I have dabbled with a couple of others. Thus, the background with which I say this, is quite limited.

It is not that I decided to jump into Rust without any consideration. I had been watching Rust from the fence for some time. I have spent time watching video clips, listening to podcasts and of course, reading blogs as well as discussion-threads in 'Stackoverflow' and 'reddit'. Like I mentioned earlier, Rust indeed has many quirks, some of which are quite inscrutable at the beginning. At times, this is definitely frustrating.

Countless enthusiastic newbies like me threw (and are throwing) in questions, ranging from eye-opener-types to eye-rolling-in-socket-types. However, I didn't find responses which were dismissive in nature and in tone. One may argue that the sample-set is too small, but I did sense the care and the wardship of the Rust experts who proffered their responses. It was as if they knew that the language brought in approaches which, a large swath of mainstream programmers hadn't heard about, let alone being comfortable. These programmers needed calming hands on their shoulders while they joined the community.

Praising by practitioners, backing by biggies

Even though large corporations of the world of software are not particularly loved for their large-heartedness 😉, it is undeniable that their endorsement of a technology matters. A programming language's uptake gets a shot in the arm, when they announce their support, contribute to the effort and in the process, keep generations of programmers enthused. Java, Javascript (nodeJS to be a little more accurate), Swift etc. good examples.

Rust has made some of the biggies interested and that is a good news. Amazon,, Microsoft and Cloudflare have endorsed it and have put up production versions of some of their offerings.

Several publicly available datasets indicate that Rust has a significant following and the trend doesn't seem to wane.

TIOBE Index confirms the upward trend, but Rust decidedly has a long distance to cover.

Redmonk suggests in its June'2022 report that "it seems increasingly clear that the hypothesis of a temporary equilibrium of programming language usage is supported by the evidence". If this indeed is the case, Rust has a steep upwards climb ahead, from its current position of 19 out of 20.

According to statisticstimes.com, Rust is showing slow yet steady progress upwards in popularity in countries like US, Germany, France, UK and in India!

So, there's something going on with Rust. Will it sustain (or accelerate) its current rate of adoption? Time will tell.

So, where do I find myself?

Well, I am not a soothsayer. I cannot and certainly don't want to, predict the fate of Rust. I feel that Rust very unlikely to dethrone Python or Javascript based on number of deployed applications. It is also unlikely to challenge Java (and other JVM based languages) for enterprise-focused, large, server-side application, meaningfully. It will possibly remain a niche language, used for specific purposes and by a smaller segment of the tech-industry. Having said that, I also feel that these specific, niche areas will only increase in number. Hopefully, the time and effort that I am investing in learning and mastering Rust, will not go in vain.

So, this is all that I have to say to Debasis 🤗.

I have steadfastly kept away from the technical features of Rust, their power and their usage-patterns and the cautionary steps which the experts remind the new entrants. Debasis was not interested about those in any case and this blog is primarily meant to give a compact and honest answer to the question he posed, during a sumptuous dinner in Kolkata, India.

Product Owners, the Technical debt matters to you too!

Nirmalya Sengupta — Mon, 02 Jan 2023 13:31:20 +0000

Attribution: Cover Image by iconicbestiary on Freepik

TL;DR

Technical Debt, is unavoidable in the life of a successful software. A l-o-t has been (and still being) discussed on this and many have spoken about its nature, the risk it poses and ways to deal with it. However, an overwhelming number of these, explains it from the PoV of the Engineering (or Development) team. Here's my attempt to expound the topic for the Business team: how they should see this inseparable part of software.

Preface

The topic of Technical debt - colloquially, Tech-debt - is perhaps one of the most common topics that the we, in the business of developing software, love to discuss, if not to embroil ourselves in. In a street-lingo précis, Tech-debt represents a bunch of TODOs in the software that exists in the code, database, configuration, deployment strategy etc. These come into existence primarily because the Business side (Product Owners/Stakeholders/Sponsors) wants the software to be usable soon, and the ENGineering side (Developers/QA/Devops) complies, leaving spots of uncleanliness (software-wise, please) behind, as a show of pragmatism. These spots carry cost (of clean up), which one may or may not want to pay forthwith. This is because, as in a financial debt, carrying a Tech-debt for some benefit now, and paying the increased technical due later, may make perfect business sense.

In general, people agree that such a debt is going to bite as some point in time. But, if it can be absorbed in some way or the other - without having any ruinous effect on the software and therfore, the business - there is nothing really grossly wrong about it. After all, if a stakeholder - who pays for what is being built and going to be used - decides to view it as an unavoidable cost measured against other benefits, there is nothing really to complain.

Myriads of friendly discussions, verbal fisticuffs, compelling presentations, persuasive video-clips and serious research on the topic later, why do I write about this topic again? More to the point, is there anything that I am going to add to it, really?

Well, a very large proportion of the available materials on Tech-debt treats the subject from the development team's side. My intention is to bring to the Product owners, Stakeholders, or Sponsors, the aspect of Tech-debt and the cost associated with it! It is my considered opinion that those who put in money to have the software built and then sell, must understand where and how, the debt hurts. I am addressing them in second person, in this blog. It is their attention that I am drawing, in this article.

Note: I am not to going elaborate on what is Technical debt, how does a piece of software accrue this unavoidable yet unwelcome payable and how is a DEV team supposed to deal with it. Tons of very good materials reside on the 'Net which explain, elaborate and exemplify these aspects. If you are interested to know first-hand or know more, I have included a links to a bunch at the end of this article.

The murmur

To begin with, trust your DEV team; especially the seniors. They are much likely to sense when things are gradually becoming difficult to ignore. If they are mentioning this in discussions and reviews, pay attention.

To be fair, any dyed-in-the-wool software developer, feels very happy to see a well-built software being shipped and used. That an user (internal or external) finds the software useful, is what developers love to hear. There is perhaps no better incentive than this.

When a growing Tech-debt is discomfiting them, and they are expressing it, take that as a good sign. What they are telling you, is that they care for what they are building and that is what you want to be built. Your inattention can be taken in as your disregard for the quality of what you are paying for. The developers can see through this very quickly. And, after some time, they will begin to care less for what they build. The fallout will be borne by you and your users.

This [report ](Tech debt: Reclaiming tech equity | McKinsey from year 2020, from McKinsey & Company, says that CIOs believe that Tech-debt is increasing and a vast majority of them spend less than 20% of their budget to stave it off.

The velocity

As your paying customers increase in number, they expect predictable behaviour from the software. At the same time, your sales team acquires new customers too. While existing and popular features cannot falter, new features have to be added as well. The balance is crucial. More often than not, the velocity is measured by number of features shipped. However, if the software has been built keeping N simultaneous users in mind, to keep it running for N + m users, requires work, even if - for argument's sake - no new feature is added. Perhaps the Customer Support team is engaged with the ENG team, in the very useful and necessary effort to settle the new users. Perhaps your Business Analytics team is asking for some set of data, unavailable so far and the ENG team is busy preparing for it. The reduced velocity - meaning, new features are not rolling out as rapidly as you expect - doesn't mean that the ENG team is sluggish. On the contrary, they are helping the business be in the current, steady state. Under the hood, they are taking considerable effort to keep the Tech-debt as low as possible. It is worthwhile for you to bear in mind, that even though the Business sees slower newer features, the business assumes no brittleness in the existing features either. And, latter consumes what is called your ENG team's bandwidth. That, in turn, affects velocity.

The Internal quality

Users judge the quality of a software primarily by the outward manifestation of it: ease of use, intuitiveness, completeness etc. These form the external quality of the software and bring in and/or retain paying customers. However, how well the software deals with further, upcoming and inevitable changes depends on its internal quality. In plain terms, the internal quality is the property which determines the velocity (see above); for example:

How quickly are customer-support issues resolved (remember, this may mean a release, a GA if you like, is faltering)?
How easily can 3rd party software be integrated (remember, not all inputs to the software will come through an web-page and your business' organic expansion may depend on ease of such integrations)
How frequently are released versions reported back with something broken (remember, the older the broken behaviour is, the higher is the cost of fixing it)
How frequently are main DB (Tables / Collections / Documents etc.) modified for implementing quick changes or fixes?
How long does it take for new entrants in the team to get going

etc.

The larger the unpaid Tech-debt, the higher is the chance that the software's internal quality is compromised. It is in the interest of the business to help keep the level of internal quality, high.

Martin Fowler - in his signature lucid style - has written about the internal quality and its implications on the cost of software. If you are a sponsor of non-trivial, money-earning software, I encourage you to read it; especially the point of cruft_ which according to me, soon becomes a sludge, if left unattended for too long.

The Roadmap

The Roadmap lays out the plan of gradual transformation of the software being built, in keeping with what the Business needs. Almost always (in my experience), the milestones along these roadmaps, tend to focus on the newer things: everyone wants to watch the software flourish (what is a better word here?). Objectively speaking, there is nothing wrong with that view, but it is incorrect - and provenly detrimental in the longer run - to overlook the importance of consolidation of the internals of the software, before and while, we march forward. The DEV team is in the best position to have a sense of extent of (a) necessary consolidation and (b) the effort to undertake that.

As an aside, the roadmap is liable to change any time, for a number of reasons. Like Kevlin Henney so pithily says in Six Impossible Things:

If I only have one road, I don't really need a roadmap.

Think of it this way: if the product's roadmap is susceptible to unforeseen changes in the prevailing business condition, then the structure behind the software is susceptible to unforeseen changes in the roadmap too. The question is how well can the existing version absorb these changes, without any adverse aftermath. This is where the quality of the software matters: the lesser the accumulated Tech-debt, the more is the inner resilience. And, of course, the level of craftsmanship of your DEV team is a very important factor too.

The cost

That an useful software - meaning, in this case, having happy and paying users - is going to evolve is a well-known tenet in the world of software programming. In fact, the demand to evolve is an indication that the software is doing well and that, your business is benefited by it. A steadily evolving software is a result of not only great and appropriate design (high quality, refer above) but also - and, this is important - better understanding of how is it supposed to work. As your Business team is understanding the prevailing and upcoming environment better, your ENG team too, is understanding what must be done, undone and redone, better. The act and benefit of discovery are applicable equally to both the teams. The Business team decides what additions and modifications must be done to the software, and the ENG team:

Realizes what should have been done in the past
Confirms what should be done now, and
Suspends what will have to be done later

to the software.

(2) is what the Business team is interested in, because while it carries a cost (time and effort) , it also offers immediate benefit (better features, happier users, more business). The ENG team, however, has to decide the extent of necessary reparative measures (ENG Team loves to refer to this as Refactoring) owing to (1) as well as how much should be left for (3). What is important for you to understand is this:

Things that ENG team decides not to do now, add to the Tech-debt
For every successive (3), the debt mounts

The truth is that some Tech-debt will always remain in a live, useful and continually changing software, and not all of them will be (should be) serviced perhaps. However, what must not escape your radar as the Product owner / Stakeholder / Sponsor, is that the accumulating debt should not reach a level where servicing the debt is a Sisyphean task, economically speaking. Both the velocity and quality will suffer.

The team

Professional and sincere software programmers (your ENG team is comprised of them), want to do a good job. They tend to leave code in a better shape than it had been in the past (Boy scout rule). This is their craft and they take pride in it. Mounting Tech-debt and woes originating from organisational disregard of it, affects their productivity and morale, and dents their pride. The quality of the software suffers, inevitably and worse, silently. A survey made by Stepsize in 2021 reveals that 52% of developers believe that Tech-debt negatively impacts a team's morale and 66% believe that they would ship 100% faster if they had a process for servicing the debt.

There is another aspect that needs a mention. New joinees in the ENG team get going faster if the software (including primary codebase, scripts, database schema, documentation, automated tests etc.) carry less Tech-debt. Much of the Tech-debt are left as assumptions, generally shared amongst the members of the team. People leaving ENG team is a regular affair. A software with much reduce Tech-debt has much less chance of being orphaned.

I am a software programmer with ~3 decades of experience, having learnt through many successes I have influenced or caused, and many failures and mistakes I have made. I work as a platform technologist with a consortium of consultants: Swanspeed Consulting.

Digital Clock using Rust (toy project)

Nirmalya Sengupta — Thu, 15 Dec 2022 16:01:48 +0000

Attribution: Cover image by Image by rawpixel.com on Freepik

I am a Rust newbie. Like many other Rust (#rustlang) learners, I am also cutting my teeth on the language by paging through the Rust book (Link) and the one from Oreilly (Link), solving small puzzles, writing code snippets, and rummaging through a host of helpful blog-posts, as well as questions/answers on Stackoverflow and Rust users' group (Link).

On one such evening, while wandering through Youtube, I had come across this particular video (Link) by (Andy Thomason). In the video, Andy codes online, and takes us through a small application which brings up a digital clock on the screen. I found that quite interesting, especially the way he modeled the arms of the digits (code is here). The code was wonderfully concise and posed no problem for a newbie like me to follow.

I thought I will take this idea further, primarily to strengthen my Rust skills. My intention has been to emulate a few things while writing this toy application:

To model a 7-Led BCD decoder for each digit
To use special ASCII characters to represent each Led and adopt ANSI Escape Sequences for cursor positioning and drawing on a text - xterm, in my case - terminal (note: Andy did the same, I just followed his footsteps)
To behave as if the clock's ticks are coming in as external signals, as opposed to sleeping between two successive calls to get current time
To trap a CTRL-C command (that stops the application) and ensure that the cursor is back to its regular blinking behaviour

Note: Let me repeat that all the above are emulations, an attempt to highlight the core behaviour; no hardware is interfaced with the toy application I have written.

BCD for each digit

For a realistic clock ( HH:MM:SS ) to appear on the screen, 6 digits are needed, namely H, H, M, M, S, S. Each of these digits is supposed to be a 7-segment display unit.

(Source: https://en.wikipedia.org/wiki/Seven-segment_display)

For a digit to be visible, several of these segments - also called LEDs (or LCDs) - should glow and other should remain unlit. The LEDs are numbered - lettered, to be more accurate - thus:

Source: https://en.wikipedia.org/wiki/Seven-segment_display

Each digit can be one of the 10 values, namely '0' to '9'. For example, for displaying digits '6', '0' and '2', the LEDs should light up as below:

Source: https://www.electricaltechnology.org/2018/05/bcd-to-7-segment-display-decoder.html

The following table shows, the input signal combinations vs the corresponding LED-borne digits:

The point is that using a 4-bit input set - referred to as Binary Coded Decimals (BCD) - all the 10 digits can be displayed. (the truth-table is in the README).

I have modeled:

every LED as a struct :

// Datatype that captures a Led
pub struct Led {
    name: String,
    show_character: String,
    hide_character: String ,
    light_status: bool,
    on_receiving_next_signal: fn(&u8) -> bool // Closure that evaluates a BCD-signal, before deciding what the light_status should become
}

A BCD signal as an u8 (unsigned 8-bit):

pub struct Nibbles(pub u8);

The 4 most-significant-bits (MSB) of this u8 are ignored always and the 4 least-significant-bits (LSB) represent the BCD for each of 10 digits. Moreover, 4 LSB combinations which represent values '10' to '15' are ignored as well (the truth-table is in the README).

Logic to determine if the LED should be lit

Using Karnaugh Map, the minimal boolean signal combination is arrived at, for every LED. For example, based on the table above, the boolean logic that leads to a lit or unlit LED 'a' is this:

const LED_A_GATE_LOGIC: fn(&u8) -> bool = | input: &u8 | {
    // 8-bits and BCD (MSBs start from leftmost)
    // 0       0       0       0       A       B      C      D
    // Using karnaugh Map and don't care conditions: A + C + B.D + ~B.~D

    (input & 0b00001000 == 0x08)              // *nibble_a == 1u8
        || (input & 0b00000010 == 0x02)       // *nibble_c == 1u8
        || (input & 0b00000101 == 0x05)       // (*nibble_b == 1u8 && *nibble_d == 1u8)
        || (input & 0b00000101 ==  0x00)      // (*nibble_b == 0u8 && *nibble_d == 0u8)
};

While constructing any specific LED, the logic is passed on as a closure. By defining them as const, I find it easier to read, test and if necessary, modify them:

pub fn new(name: &str, displayChar: &str, hide_character: &str, evaluator: fn(&u8) -> bool) -> Led {
        Led {
            name: name.to_string(),
            show_character: displayChar.to_string(),
            hide_character: hide_character.to_string(),
            light_status: false,
            on_receiving_next_signal: evaluator
        }
    }

Every LED has a show_character and a hide_character to represent its display in the lit and unlit mode. I have used special ASCII characters to help show a LED on the terminal. For example, for LED 'a', it is "━━━━" and for LED 'b', it is " ┃": the space prefixed is for easier positioning on the screen. The section below exemplifies this.

At the call-site of calling the constructor of LED 'a':

Led::new("a", "━━━━", "    ", LED_A_GATE_LOGIC /* closure as a const */);

Data and Code structure

This is the easier part. Using regular OO technique:

A DisplayUnit is composed of 7 LEDs of its own and is responsible for constructing those
A ScreenClock is composed of 6 DisplayUnits and is responsible for constructing those

A DisplayUnit is a struct:

pub struct DigitDisplayUnit {
    // TODO: These leds should be in a map, identifiable  by the letter associated
    led_a: Led,
    led_b: Led,
    led_c: Led,
    led_d: Led,
    led_e: Led,
    led_f: Led,
    led_g: Led,
}

impl DigitDisplayUnit {
    pub fn new() -> DigitDisplayUnit {
        let leda = Led::new("a", "━━━━", "    ", LED_A_GATE_LOGIC);
        let ledb = Led::new("b", " ┃", "  ",     LED_B_GATE_LOGIC);
       // ...

        DigitDisplayUnit {
            led_a: leda,
            led_b: ledb,
            // ..
        }
    }

So, to create a ScreenClock, we do this:

pub struct ScreenClock {
    top_left_row: u8,
    top_left_col: u8,
    display_units: [DigitDisplayUnit;6],
}

impl ScreenClock {
    pub fn new( start_at_row: u8, start_at_col: u8 ) -> ScreenClock {

        // From left to right, on the display panel!
        let digital_display_unit0 = DigitDisplayUnit::new(); // h_ of hh
        let digital_display_unit1 = DigitDisplayUnit::new(); // _h of hh
        let digital_display_unit2 = DigitDisplayUnit::new(); // m_ of mm
        let digital_display_unit3 = DigitDisplayUnit::new(); // _m of mm
        let digital_display_unit4 = DigitDisplayUnit::new(); // s_ of ss
        let digital_display_unit5 = DigitDisplayUnit::new(); // _s of ss


        ScreenClock {
            top_left_row: start_at_row,
            top_left_col: start_at_col,
            display_units: [
                digital_display_unit0,
                digital_display_unit1,
                digital_display_unit2,
                digital_display_unit3,
                digital_display_unit4,
                digital_display_unit5,
            ]
        }
    }
// ... rest of it

Once the skeleton is in place, solution becomes apparent to one:

Decide the position of the clock on the screen (row / column)
Create a ScreenClock ( refer to the constructor new)
Every second on the system's own date/time -- Pass the current hour/minute/second readings to ScreenClock -- Refresh the ScreenClock (i.e. produce the LEDs on the screen)

On the left, this digital clock and on the right, Unix date command's output, on my Ubuntu 22.10 laptop, with terminal type xterm-256color :

Respond to a tick

The simplest way to get the current system time every second is to use Local::now() from the chrono:: crate, after a second's duration and sleeping in between. However, my intention has been to implement a behaviour of reaction: let a nudge arrive at a second's frequency indicating that a second has elapsed and then, the current time be read again. This way there is no enforced sleeping.

It turns out that crossbeam:: crate has exactly the facility that I need, a function named tick:

crossbeam_channel::channel
pub fn tick(duration: Duration)

This is how I set it up:

let notification_on_next_second = tick(Duration::from_secs(1));

Whenever a tick arrives, the application reads the current time and uses that to drive the digital boolean logic, which lights up the LEDs as needed.

Trap CTRL-C to restore the cursor

At the beginning, the application hides the cursor by issuing a ANSI Escape sequence, thus:

print!("\x1b[?25l");

When the user terminates the program by pressing CTRL-C, I need to restore the blinking cursor; a well-behaved DigitalClock must do that. Some kind of signal handler is required, so that just before it exits, the application issues the complementary ANSI escape sequence that restores the cursor. This time, the standard library provides the handler facility, aptly named: ctrlc:

fn notify_me_when_user_exits() -> Result<Receiver<u8>, ctrlc::Error> {
    let (sender, receiver) =  bounded(8);
    ctrlc::set_handler(move || {
        print!("\x1b[?25h");  // Restore the hidden cursor!
        let _ = sender.send(0xFF);
    })?;

    Ok(receiver)
}

That little closure, named ctrlc::set_handler does the job. It makes use of a facility that crossbeam_channel::bounded(n) provides. Upon trapping the CTRL-C, the closure issues an appropriate ANSI Escape sequence, and sends a 0xFF (an arbitrary value, not used) in the channel.

Handling two non-deterministic asynchronous inputs

The main thread sets itself up for two inputs:

A periodic tick: when it arrives, current time is picked up and the DigitalClock displays the digits
An intimation by the user to exit: when it arrives, the handler gets into action, keeps the house as it were and leaves.

Thus, a structure is required to respond to either of these two inputs which can arrive in an unforeseen order; as if, the application is passively waiting for either of two interrupts and then reacting to the one that arrives first.

While strolling through rust-cli (handbook), I have come across a nifty arrangement of select! macro. This macro sits perfectly at the receiving end of a (bi-ended) channel and executes logic associated with the receipt of data through that channel. Structurally, it caters to multiple such receiving ends but responds to any one of them at a given point in time:, much like its homographic elder cousin named select() Unix system call:

select! {
            recv(notification_on_next_second) -> _ => {
                let time = read_clock_now()      // Current HH:MM:SS as a string
                .chars()                         // An iterator of characters it contains
                .filter( | c  | c != &':')       // Scrape the ':' character from the middle
                .map(| c | c as u8 - '0' as u8)  // Get the numeric digit from ascii digit
                .collect();

                screen_clock
                .on_next_second(
                    hr_and_min_and_sec[0],
                    hr_and_min_and_sec[1],
                    hr_and_min_and_sec[2],
                    hr_and_min_and_sec[3],
                    hr_and_min_and_sec[4],
                    hr_and_min_and_sec[5]
                )
                .refresh();

                print!("\x1b[7A");
            }

            recv(notification_on_user_exiting) -> _ => {
                println!("Goodbye!");
                break;
            }
        }

The complete code is here.

There it is, a simple application that makes use of some Rust facilities, idioms and techniques that I have managed to learn so far. It is not optimized for memory and speed and certainly, the code can be improved at few places, I know. Yet, I would love to hear from Rustaceans if and where do they think,the design can be cleaner and Rust's features can be adopted better. Educate me.

Aspiring to be a sparring partner of CTOs

Nirmalya Sengupta — Sun, 14 May 2017 08:46:40 +0000

Forem: Nirmalya Sengupta

Rust Notes on Temporary values (usage of Mutex) - 4

Preface

Build up

What are the main takeaways so far (summary of the earlier articles)

A brief description of the application where it started

What is the real issue with the behaviour here?

Explaining the behavior

Expressions while let and match

Conclusion

Rust Notes on Temporary values (usage of Mutex) - 3

Build up

Revisiting accessing the fenced data

Can we force the guard to stay open for longer?

Making use of match expression

Main Takeaways

Acknowledgements

Rust Notes on Temporary values (usage of Mutex) - 2

Build up

Quick definition for the context

Mutex in Rust

RAII

OBRM

Experiments and observations

In search of the 'Scope'

The temporary MutexGuard

Main Takeaways

Rust Notes on Temporary values (usage of Mutex) - 1

The build up

Simulate the error

Elaboration

Expresssions and Scopes

Going a little further

Main Takeaways

Acknowledgements

Random Rust Notes - 4

A brief on spawned threads

So, we need a handle

Now, a scoped thread

Difference between spawning steps

An example makes it clearer, hopefully!

But, why?

Key takeaways

Random Rust Notes - 3

Takeaways from the previous note

What is it that I am modeling (recap helps)

Key observations

Random Rust Notes - 2

Takeaways from the previous note

The case of many senders (MPSC)

Multiple producers done, what about single consumer?

Takeaways

Random Rust Notes - 1

Using channels to communicate between threads

Channels are unidirectional

How do two threads make use of the channel?

How do threads know when to stop?

Takeaways

Why am I learning Rust?

The Build-up

Learning a new language makes me think differently from what I am used to

I feel welcome. Yes, that matters.

Praising by practitioners, backing by biggies

So, where do I find myself?

Product Owners, the Technical debt matters to you too!

TL;DR

Preface

The murmur

The velocity

The Internal quality

The Roadmap

The cost

The team

More reading:

Digital Clock using Rust (toy project)

BCD for each digit

Logic to determine if the LED should be lit

Data and Code structure

Respond to a tick

Trap CTRL-C to restore the cursor

Expressions `while let` and `match`

Making use of `match` expression