fn write_first_in_line(msg: Message) {
    let msg_str: &str = msg.str();
    
    if let Err(err) = utils::try_write(&msg_str, msg.output_kind()) {
        let mut queue_guard = QUEUE.lock();
        queue_guard.insert(0, Message::error(format!(
            "comfy_print::blocking_write_first_in_line(): Failed to print first message in queue, it was pushed to the front again.\n\
            Error: {err}\n\
            Message: {msg_str}")));
        
        queue_guard.insert(1, msg);
    }
}

Here we try to write to the desired output. If that fails, we insert an error message in front of the queue, then the original message afterward.

Trying again is unlikely to yield any results, so we shouldn't do anything else.

We'll try again next time comfy_print! is called.

fn check_thread() {
    let Some(mut thread_guard) = ACTIVE_THREAD.try_lock()
        else { return; };
    
    let is_printing = thread_guard.as_ref().is_some_and(|handle| !handle.is_finished());
    if is_printing { // We already pushed our msg to the queue and there's already a thread printing it, so we can return.
        return;
    }
    
    match thread::Builder::new().spawn(print_until_empty) {
        Ok(ok) => {
            *thread_guard = Some(ok);
            drop(thread_guard);
        },
        Err(err) => { // We couldn't create a thread, we'll have to block this one
            drop(thread_guard);
            
            let mut queue_guard = QUEUE.lock();
            queue_guard.insert(0, Message::error(format!(
                "comfy_print::queue_then_check_thread(): Failed to create a thread to print the queue.\n\
                Error: {err}.")));
            
            drop(queue_guard);
            print_until_empty();
        }
    }
}

There's a lot going on here so let's divide into smaller steps:

let Some(mut thread_guard) = ACTIVE_THREAD.try_lock()
    else { return; };

let is_printing = thread_guard.as_ref().is_some_and(|handle| !handle.is_finished());
if is_printing { // We already pushed our msg to the queue and there's already a thread printing it, so we can return.
    return;
}

First, by trying to acquire the lock, we perform a non-blocking operation that tells us if there's another thread already using it. If that's the case, we can assume that the other thread is also about to start printing the queue. We can stop here.

If we did acquire the lock, we can check if there's anything there, and if the handle inside belongs to a thread that's already finished.

If the handle exists and it's not finished, then it means the other thread is actively printing the queue, so we can return.

match thread::Builder::new().spawn(print_until_empty) {

Here we try spawning a new thread, requesting that it executes the function fn print_until_empty().

Ok(handle) => {
    *thread_guard = Some(handle);
    drop(thread_guard);
},

If spawning succeeds, we insert the handle in our static Mutex, other threads will check it to see if they can take the responsibility of printing.

As usual, we also immediately release the lock that we are holding.

Err(err) => {
    drop(thread_guard);
    
    let mut queue_guard = QUEUE.lock();
    queue_guard.insert(0, Message::error(format!(
        "comfy_print::queue_then_check_thread(): Failed to create a thread to print the queue.\n\
        Error: {err}.")));
    
    drop(queue_guard);
}

If, for whatever reason, spawning the thread fails, we have a new error message to print.

Once again, before acquiring a lock on the queue, we release the lock referencing the handle, then insert the error message in front of the queue.

We return now and hope that the user calls print again, which would read the queue and attempt to print all the stored messages.

fn print_until_empty() {
    const MAX_RETRIES: u8 = 50;
    let mut retries = 0;
    
    loop {
        let mut queue_guard = QUEUE.lock();
        
        if queue_guard.len() <= 0 {
            drop(queue_guard);
            break;
        }
        
        let msg = queue_guard.remove(0);
        let msg_str: &str = msg.str();
        let output_kind = msg.output_kind();
        drop(queue_guard); // unlock the queue before blocking stdout/err

        let write_result = utils::try_write(&msg_str, output_kind);
        
        if let Err(err) = write_result {
            let mut queue_guard = QUEUE.lock();
            queue_guard.insert(0, Message::error(format!(
                "comfy_print::write_until_empty(): Failed to print first message in queue.\n\
                Error: {err}\n\
                Message: {msg_str}\n\
                Target output: {output_kind:?}")));
            
            queue_guard.insert(1, msg);
            drop(queue_guard);
            
            retries += 1;
            if retries >= MAX_RETRIES {
                break;
            }
        }

        thread::yield_now();
    }
}

This is the function that actually prints the queue, let's break it into smaller steps.

const MAX_RETRIES: u8 = 50;
let mut retries = 0;

For starters, we have an arbitrary integer that defines the maximum number of retries in case a print operation fails, and the local integer retries to count the attempts.

let mut queue_guard = QUEUE.lock();

if queue_guard.len() <= 0 {
    drop(queue_guard);
    break;
}

Inside the loop, we lock the queue, then stop if it's empty, as that would mean our job is done.

let msg = queue_guard.remove(0);
let msg_str: &str = msg.str();
let output_kind = msg.output_kind();
drop(queue_guard); // unlock the queue before blocking stdout/err

We pop the front element out of the queue, then immediately release the lock.

Releasing the lock here also ensures we don't hold two locks at once, as we are about to lock the output stream.

let write_result = utils::try_write(&msg_str, output_kind);

if let Err(err) = write_result {
    let mut queue_guard = QUEUE.lock();
    queue_guard.insert(0, Message::error(format!(
        "comfy_print::write_until_empty(): Failed to print first message in queue.\n\
        Error: {err}\n\
        Message: {msg_str}\n\
        Target output: {output_kind:?}")));
    
    queue_guard.insert(1, msg);
    drop(queue_guard);
    
    retries += 1;
    if retries >= MAX_RETRIES {
        break;
    }
}

thread::yield_now();

If writing to output fails, we'll insert an error message in front of the queue, then the original message afterward.

However, since we are guaranteed to not be in the main thread, we can hold the print responsibility for a bit longer, we'll keep trying to print up to MAX_RETRIES.

Regardless of the print result, at the end of each iteration we call thread::yield_now(); this will give other threads a chance to hopefully un-screw the output stream, while also allowing more messages to join the queue.