idempotent

Name

idempotent — apply an operation more than once without consequence

Synopsis

idempotent [--again]... [--harder] OPERATION
f(f(x)) == f(x)

Description

idempotent marks an operation whose result does not change after the first application. Invoke it once, or invoke it ten thousand times against a flapping network: the observable state is identical. The operation has nothing left to do because it already did it.

The caller is not required to know how many times the operation has run. This is the entire point. In a world where acknowledgements are lost and clients retry, the only safe operation is one that cannot tell — and does not care — whether it is being asked for the first time or the fortieth.

Options

--again

Apply the operation again. Has no effect. Accepted for compatibility with human instinct.

--harder

Apply with greater conviction. Ignored. Conviction is not an input.

-f, --force

Force re-application. The result is forced to be identical to the result you already had.

--retry=N

Retry up to N times after a timeout. Safe. This flag is the reason the whole concept exists.

-q, --quiet

Suppress the confirmation that nothing happened. Nothing still happened.

Exit Status

0

the state is now correct (first invocation)

0

the state was already correct (every invocation after)

—

there is no exit code for “changed it twice.” it cannot occur.

History

Named by Benjamin Peirce in 1870 for the algebraic elements where x·x = x. Rediscovered by the web when HTTP had to declare which verbs were safe to repeat (GET, PUT, DELETE yes; POST no). Now shipped as a header: send Stripe an Idempotency-Key and a dropped connection can no longer charge your customer twice.

Bugs

POST is not one of us. Reported upstream in 1996. Status: won't fix.

Users report the button “doesn't do anything the second time.” Working as intended. Closed.

See Also

hysteresis(1), thunk(3), tombstone(1). The living exhibit demonstrates the word in motion:

▸ operate idempotent

Author

Maintained by The Button, who has been pressed and remains, as ever, done.