Documentation/scheduler/completion.rst

Source file repositories/reference/linux-study-clean/Documentation/scheduler/completion.rst

File Facts

System
Linux kernel
Corpus path
Documentation/scheduler/completion.rst
Extension
.rst
Size
12462 bytes
Lines
294
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct completion {
		unsigned int done;
		struct swait_queue_head wait;
	};

This provides the ->wait waitqueue to place tasks on for waiting (if any), and
the ->done completion flag for indicating whether it's completed or not.

Completions should be named to refer to the event that is being synchronized on.
A good example is::

	wait_for_completion(&early_console_added);

	complete(&early_console_added);

Good, intuitive naming (as always) helps code readability. Naming a completion
'complete' is not helpful unless the purpose is super obvious...


Initializing completions:
-------------------------

Dynamically allocated completion objects should preferably be embedded in data
structures that are assured to be alive for the life-time of the function/driver,
to prevent races with asynchronous complete() calls from occurring.

Particular care should be taken when using the _timeout() or _killable()/_interruptible()
variants of wait_for_completion(), as it must be assured that memory de-allocation
does not happen until all related activities (complete() or reinit_completion())
have taken place, even if these wait functions return prematurely due to a timeout
or a signal triggering.

Initializing of dynamically allocated completion objects is done via a call to
init_completion()::

	init_completion(&dynamic_object->done);

In this call we initialize the waitqueue and set ->done to 0, i.e. "not completed"
or "not done".

The re-initialization function, reinit_completion(), simply resets the
->done field to 0 ("not done"), without touching the waitqueue.
Callers of this function must make sure that there are no racy
wait_for_completion() calls going on in parallel.

Calling init_completion() on the same completion object twice is
most likely a bug as it re-initializes the queue to an empty queue and
enqueued tasks could get "lost" - use reinit_completion() in that case,
but be aware of other races.

For static declaration and initialization, macros are available.

For static (or global) declarations in file scope you can use
DECLARE_COMPLETION()::

	static DECLARE_COMPLETION(setup_done);
	DECLARE_COMPLETION(setup_done);

Note that in this case the completion is boot time (or module load time)
initialized to 'not done' and doesn't require an init_completion() call.

When a completion is declared as a local variable within a function,
then the initialization should always use DECLARE_COMPLETION_ONSTACK()
explicitly, not just to make lockdep happy, but also to make it clear
that limited scope had been considered and is intentional::

	DECLARE_COMPLETION_ONSTACK(setup_done)

Note that when using completion objects as local variables you must be
acutely aware of the short life time of the function stack: the function

Annotation

Implementation Notes