c/language/restrict

Each individual type in the C has several qualified versions of that type, corresponding to one, two, or all three of the, , and, for pointers to object types, restrict qualifiers. This page describes the effects of the restrict qualifier.

Only a pointer to an  may be restrict-qualified; in particular, the following are erroneous:



Restrict semantics apply to lvalue expressions only; for example, a cast to restrict-qualified pointer or a function call returning a restrict-qualified pointer are not lvalues and the qualifier has no effect.

During each execution of a block in which a restricted pointer is declared (typically each execution of a function body in which  is a function parameter), if some object that is accessible through  (directly or indirectly) is modified, by any means, then all accesses to that object (both reads and writes) in that block must occur through  (directly or indirectly), otherwise the behavior is undefined:

If the object is never modified, it may be aliased and accessed through different restrict-qualified pointers (note that if the objects pointed to by aliased restrict-qualified pointers are, in turn, pointers, this aliasing can inhibit optimization).

Assignment from one restricted pointer to another is undefined behavior, except when assigning from a pointer to an object in some outer block to a pointer in some inner block (including using a restricted pointer argument when calling a function with a restricted pointer parameter) or when returning from a function (and otherwise when the block of the from-pointer ended):

Restricted pointers can be assigned to unrestricted pointers freely, the optimization opportunities remain in place as long as the compiler is able to analyze the code:

In a function declaration, the keyword may appear inside the square brackets that are used to declare an array type of a function parameter. It qualifies the pointer type to which the array type is transformed:

Usage patterns
There are several common usage patterns for restrict-qualified pointers:

File scope
A file-scope restrict-qualified pointer has to point into a single array object for the duration of the program. That array object may not be referenced both through the restricted pointer and through either its declared name (if it has one) or another restricted pointer.

File scope restricted pointers are useful in providing access to dynamically allocated global arrays; the restrict semantics make it possible to optimize references through this pointer as effectively as references to a static array through its declared name:

Function parameter
The most popular use case for restrict-qualified pointers is the use as function parameters.

In the following example, the compiler may infer that there is no aliasing of modified objects, and so optimize the loop aggressively. Upon entry to f, the restricted pointer a must provide exclusive access to its associated array. In particular, within f neither b nor c may point into the array associated with a, because neither is assigned a pointer value based on a. For b, this is evident from the const-qualifier in its declaration, but for c, an inspection of the body of f is required:

Note that it is permitted for c to point into the array associated with b. Note also that, for these purposes, the "array" associated with a particular pointer means only that portion of an array object which is actually referenced through that pointer.

Note that in the example above, the compiler can infer that a and b do not alias because b's constness guarantees that it cannot become dependent on a in the body of the function. Equivalently, the programmer could write, in which case the compiler can reason that objects referenced through b cannot be modified, and so no modified object can be referenced using both b and a. If the programmer were to write , the compiler would be unable to infer non-aliasing of a and b without examining the body of the function.

In general, it is best to explicitly annotate all non-aliasing pointers in a function's prototype with.

Block scope
A block scope restrict-qualified pointer makes an aliasing assertion that is limited to its block. It allows local assertions that apply only to important blocks, such as tight loops. It also makes it possible to convert a function that takes restrict-qualified pointers into a macro:

Struct members
The scope of the aliasing assertion made by a restrict-qualified pointer that is a member of a struct is the scope of the identifier used to access the struct.

Even if the struct is declared at file scope, when the identifier used to access the struct has block scope, the aliasing assertions in the struct also have block scope; the aliasing assertions are only in effect within a block execution or a function call, depending on how the object of this struct type was created:

Example
code generation example; compile with -S (gcc, clang, etc) or /FA (visual studio)

Possible output: