qthread_disable_shepherd(3)

qthread_disable_shepherd 💅

okay so this is a libqthread joint, from the <qthread.h> cinematic universe, and it's literally all about telling a shepherd "bestie, take a nap" or "bestie, wake UP" 🎀

✨ NAME ✨

qthread_disable_shepherd, qthread_enable_shepherd — turn a shepherd off or on for thread scheduling 🐑

🌸 SYNOPSIS 🌸

#include <qthread.h>

int
qthread_disable_shepherd (qthread_shepherd_id_t shep);

void
qthread_enable_shepherd (qthread_shepherd_id_t shep);

🦋 DESCRIPTION 🦋

So these two functions are the on/off switch for shepherds, no cap. Every shepherd starts out in the enabled state, like, from birth. Iconic behavior honestly.

A disabled shepherd cannot execute threads, periodt. So what happens to all the threads hanging out there? They get actively migrated away 💨. And the migration decision is based on two things:

• the distance (how far away the other shepherds are)
• an estimate of "busyness", which comes from the shepherd's active queue length

The way that disabling a shepherd hits thread-placement decisions immediately but the shepherd itself might still be chugging along on its current thread until that thread either blocks, yields, or exits — it's giving "finishing my plate before I leave the table" 🍽️.

Once that thread finally stops executing, the disabled shepherd doesn't run anything new. Instead it monitors its queue and, rather than execute runnable threads, it migrates runnable threads to nearby shepherds. It's basically a little matchmaker for threads. So selfless. 🫶

And then when a shepherd gets re-enabled? It becomes available to run threads again, like nothing ever happened. The comeback era. 👑

💖 RETURN VALUE 💖

On success, the specified shepherd is marked as disabled and the value QTHREAD_SUCCESS is returned. Slay. ✨

On failure, an error code is returned instead. Not slay. 😭

💀 ERRORS 💀

• QTHREAD_NOT_ALLOWED — the first shepherd, shepherd 0, cannot be disabled. Sorry bestie, shepherd 0 is the main character and main characters don't get benched. 🙈

fr fr, do not try to disable shepherd 0. It said no. It meant no. 🎀

libqthread · NOVEMBER 2009 — mwah, that's the version and the date, and this page is qthread_disable_shepherd(3) 💜 bye bestie, go schedule something responsibly 🌈