task_work_add(9)

💅 task_work_add(9) — like, the manual page, bestie

okay so this one's from the Kernel API Manual, and it's genuinely one of those little functions that runs the whole vibe backstage. it's giving "hey bestie, can you run this for me later?" and honestly? obsessed. let's get into it 🎀

---

✨ NAME ✨

task_work_add — ask the @task to execute @work->func()

like literally just "hey you, run this callback when you get a sec" 🫶

---

🌸 SYNOPSIS 🌸

int task_work_add (struct task_struct *task , struct callback_head *work
, enum task_work_notify_mode notify );

that's the whole signature, no cap. three args, returns an int. 💖

---

🎀 ARGUMENTS 🎀

• task — the task which should run the callback. yes, that task. the one you're poking. 👀
• work — the callback to run. this is the thing you're handing over, the lil errand. 🍓
• notify — how to notify the targeted task. this one's the main character of the DESCRIPTION ngl, it decides how hard you're gonna nudge them. 🔥

---

🦋 DESCRIPTION 🦋

So the whole thing: you queue work for task_work_run (that's below, see SEE ALSO) and notify the task — but only if notify is TWA_RESUME, TWA_SIGNAL, TWA_SIGNAL_NO_IPI or TWA_NMI_CURRENT. those four, that's the list, periodt. ✨

okay let's break down the modes because the way each one behaves is genuinely different:

• TWA_SIGNAL — works like signals, in that it will interrupt the targeted task and run the task_work, regardless of whether the task is currently running in the kernel or userspace. full send, no chill, it's getting done. ⚡
• TWA_SIGNAL_NO_IPI — works like TWA_SIGNAL, except it doesn't send a reschedule IPI to force the targeted task to reschedule and run task_work. This can be advantageous if there's no strict requirement that the task_work be run as soon as possible, just whenever the task enters the kernel anyway. so like, lowkey chill mode. no rush bestie. 🌸
• TWA_RESUME — work is run only when the task exits the kernel and returns to user mode, or before entering guest mode. patient vibes, waits for the right moment. 🧚
• TWA_NMI_CURRENT — works like TWA_RESUME, except it can only be used for the current task and if the current context is NMI. very specific, very exclusive, invite-only energy. 👑

Fails if the task is exiting/exited and thus it can't process this work. Otherwise work->func will be called when the task goes through one of the aforementioned transitions, or exits. 💀

If the targeted task is exiting, then an error is returned and the work item is not queued. It's up to the caller to arrange for an alternative mechanism in that case. — so like, plan B is your problem bestie, this function is not going to invent one for you 😭

---

🙈 NOTE 🙈

there is no ordering guarantee on works queued here. The task_work list is LIFO.

read that again. LIFO. last in, first out. so if you queue stuff expecting it in order... it's not giving that. at all. 🫠

---

⭐ RETURN ⭐

0 if succeeds or -ESRCH. that's it, that's the whole menu. slay. 💜

---

🌈 SEE ALSO 🌈

Kernel file ./kernel/task_work.c, and the whole friend group: task_work_cancel_match(9), task_work_cancel_func(9), task_work_cancel(9), task_work_run(9). go say hi, they're all in the same file. 👑

---

okay that's the whole page!! this one lives in ./kernel, and the date on it is October 2026 — so like, a lil time capsule moment. mwah, go queue some work, bestie 💅✨🎀