linux-imx

/* SPDX-License-Identifier: GPL-2.0 */

#ifndef _LINUX_CLOSURE_H

#define _LINUX_CLOSURE_H

​

#include <linux/llist.h>

#include <linux/sched.h>

#include <linux/sched/task_stack.h>

#include <linux/workqueue.h>

​

/*

 * Closure is perhaps the most overused and abused term in computer science, but

 * since I've been unable to come up with anything better you're stuck with it

 * again.

 *

 * What are closures?

 *

 * They embed a refcount. The basic idea is they count "things that are in

 * progress" - in flight bios, some other thread that's doing something else -

 * anything you might want to wait on.

 *

 * The refcount may be manipulated with closure_get() and closure_put().

 * closure_put() is where many of the interesting things happen, when it causes

 * the refcount to go to 0.

 *

 * Closures can be used to wait on things both synchronously and asynchronously,

 * and synchronous and asynchronous use can be mixed without restriction. To

 * wait synchronously, use closure_sync() - you will sleep until your closure's

 * refcount hits 1.

 *

 * To wait asynchronously, use

 *   continue_at(cl, next_function, workqueue);

 *

 * passing it, as you might expect, the function to run when nothing is pending

 * and the workqueue to run that function out of.

 *

 * continue_at() also, critically, requires a 'return' immediately following the

 * location where this macro is referenced, to return to the calling function.

 * There's good reason for this.

 *

 * To use safely closures asynchronously, they must always have a refcount while

 * they are running owned by the thread that is running them. Otherwise, suppose

 * you submit some bios and wish to have a function run when they all complete:

 *

 * foo_endio(struct bio *bio)

 * {

 *  closure_put(cl);

 * }

 *

 * closure_init(cl);

 *

 * do_stuff();

 * closure_get(cl);

 * bio1->bi_endio = foo_endio;

 * bio_submit(bio1);

 *

 * do_more_stuff();

 * closure_get(cl);

 * bio2->bi_endio = foo_endio;

 * bio_submit(bio2);

 *

 * continue_at(cl, complete_some_read, system_wq);

 *

 * If closure's refcount started at 0, complete_some_read() could run before the

 * second bio was submitted - which is almost always not what you want! More

 * importantly, it wouldn't be possible to say whether the original thread or

 * complete_some_read()'s thread owned the closure - and whatever state it was

 * associated with!

 *

 * So, closure_init() initializes a closure's refcount to 1 - and when a

 * closure_fn is run, the refcount will be reset to 1 first.

 *

 * Then, the rule is - if you got the refcount with closure_get(), release it

 * with closure_put() (i.e, in a bio->bi_endio function). If you have a refcount

 * on a closure because you called closure_init() or you were run out of a

 * closure - _always_ use continue_at(). Doing so consistently will help

 * eliminate an entire class of particularly pernicious races.

 *

 * Lastly, you might have a wait list dedicated to a specific event, and have no

 * need for specifying the condition - you just want to wait until someone runs

 * closure_wake_up() on the appropriate wait list. In that case, just use

 * closure_wait(). It will return either true or false, depending on whether the

 * closure was already on a wait list or not - a closure can only be on one wait

 * list at a time.

 *

 * Parents:

 *

 * closure_init() takes two arguments - it takes the closure to initialize, and

 * a (possibly null) parent.

 *

 * If parent is non null, the new closure will have a refcount for its lifetime;

 * a closure is considered to be "finished" when its refcount hits 0 and the

 * function to run is null. Hence