Completion¶

Overview¶

Completion is a Linux kernel synchronization primitive designed for one-shot event notification.

It allows one execution context to wait until another execution context signals that an operation has finished.

Common use cases include:

Many synchronization problems can be expressed as:

Start operation
        ↓
Wait until operation finishes
        ↓
Continue

Traditionally this could be implemented using a wait queue and a completion flag:

bool done;

wait_event(wq, done);

done = true;
wake_up(&wq);

Completion encapsulates this pattern into a dedicated synchronization primitive.

Typical workflow:

init_completion()
        ↓
wait_for_completion()
        ↓
complete()

The waiter blocks until another execution context signals completion.

Completion is designed for one-shot events.

Examples:

Firmware ready
DMA complete
Hardware initialized
Worker started

Unlike wait queues, completion is not intended for repeated event processing.

After:

complete()

or:

complete_all()

the completion object remains in the completed state.

Future waiters return immediately.

Example:

complete();

wait_for_completion();

returns immediately.

To reuse a completion object:

reinit_completion()

must be called.

This resets the completion state and allows future waiters to block again.

Feature	Completion	Wait Queue
Waiting Model	Operation-based	Condition-based
One-shot Event	Excellent	Possible
Repeated Events	Poor	Excellent
State Machine	Poor	Excellent
Initialization Synchronization	Excellent	Acceptable

Completion is commonly used in:

Example:

probe()
    ↓
start hardware
    ↓
wait_for_completion_timeout()
    ↓
continue initialization

Internally, completion is built on top of wait queues.

Kernel definition:

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

Completion can be viewed as:

Wait Queue
        +
Completion State
        =
Completion

Use completion when:

One execution context waits for
another operation to finish.

Use wait queues when:

One execution context waits for
a condition to become true.

Completion provides a lightweight mechanism for operation completion notification.

It is ideal for:

Completion simplifies many synchronization patterns that would otherwise require a wait queue and a separate completion flag.