C Reference ยท Keywords and Statements
The restrict qualifier
Reference for the C restrict pointer qualifier: the no-aliasing promise, how it enables optimization, standard functions that use it, and the undefined behavior.
restrict is a promise you make to the compiler about a pointer: during the lifetime of that pointer, the object it points to is accessed only through that pointer (or pointers derived from it) whenever the object is modified. Knowing there is no aliasing lets the compiler keep values in registers, reorder loads and stores, and vectorize loops.
The keyword changes no behavior of correct code. It only permits faster code, and it makes your program undefined if the promise is broken. The standard library uses it to express contracts: memcpy has restrict parameters, memmove does not.
void add(int n, int *restrict out, const int *restrict a, const int *restrict b);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
type *restrict name
| Part | Description |
|---|---|
restrict |
Qualifier written after the *. It can qualify only pointers to object types (not function pointers). |
The following broken call is shown read-only because it is undefined behavior:
int buf[5] = {1, 2, 3, 4, 5}; add(4, buf + 1, buf, buf); /* out overlaps a and b: undefined */
Undefined behavior: modifying an object through a restrict pointer while another pointer (restrict or not) not derived from it accesses the same object during the pointer's lifetime. The compiler is free to produce code that gives the wrong result.
Usage notes
- Only matters if something is written. Two restrict pointers may point into the same array when the program only reads through them.
- Promise is yours to keep. The compiler cannot check it.
-fsanitize=undefineddoes not catch it either; careful reasoning and tests do. - Scope of the promise: for a function parameter, the duration of the function call.
- Typical wins: numeric loops, image and signal processing, copy routines. The gain can be large when the compiler could not otherwise prove independence, and zero when it already could.
- Use it in headers as documentation:
restricttells the caller "do not pass overlapping buffers". - C only. C++ has no standard
restrict; compilers offer__restrictas an extension. - Added in C99. In C89 mode GCC accepts
__restrict__. constandrestrictcombine:const char *restrict srcmeans a read-only, non-aliased source.