]>
Commit | Line | Data |
---|---|---|
1 | .. | |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. _alignment-of-poly_ints: | |
7 | ||
8 | Alignment of poly_ints | |
9 | ********************** | |
10 | ||
11 | ``poly_int`` provides various routines for aligning values and for querying | |
12 | misalignments. In each case the alignment must be a power of 2. | |
13 | ||
14 | :samp:`can_align_p ({value}, {align})` | |
15 | Return true if we can align :samp:`{value}` up or down to the nearest multiple | |
16 | of :samp:`{align}` at compile time. The answer is the same for both directions. | |
17 | ||
18 | :samp:`can_align_down ({value}, {align}, &{aligned})` | |
19 | Return true if ``can_align_p`` ; if so, set :samp:`{aligned}` to the greatest | |
20 | aligned value that is less than or equal to :samp:`{value}`. | |
21 | ||
22 | :samp:`can_align_up ({value}, {align}, &{aligned})` | |
23 | Return true if ``can_align_p`` ; if so, set :samp:`{aligned}` to the lowest | |
24 | aligned value that is greater than or equal to :samp:`{value}`. | |
25 | ||
26 | :samp:`known_equal_after_align_down ({a}, {b}, {align})` | |
27 | Return true if we can align :samp:`{a}` and :samp:`{b}` down to the nearest | |
28 | :samp:`{align}` boundary at compile time and if the two results are equal. | |
29 | ||
30 | :samp:`known_equal_after_align_up ({a}, {b}, {align})` | |
31 | Return true if we can align :samp:`{a}` and :samp:`{b}` up to the nearest | |
32 | :samp:`{align}` boundary at compile time and if the two results are equal. | |
33 | ||
34 | :samp:`aligned_lower_bound ({value}, {align})` | |
35 | Return a result that is no greater than :samp:`{value}` and that is aligned | |
36 | to :samp:`{align}`. The result will the closest aligned value for some | |
37 | indeterminate values but not necessarily for all. | |
38 | ||
39 | For example, suppose we are allocating an object of :samp:`{size}` bytes | |
40 | in a downward-growing stack whose current limit is given by :samp:`{limit}`. | |
41 | If the object requires :samp:`{align}` bytes of alignment, the new stack | |
42 | limit is given by: | |
43 | ||
44 | .. code-block:: c++ | |
45 | ||
46 | aligned_lower_bound (limit - size, align) | |
47 | ||
48 | :samp:`aligned_upper_bound ({value}, {align})` | |
49 | Likewise return a result that is no less than :samp:`{value}` and that is | |
50 | aligned to :samp:`{align}`. This is the routine that would be used for | |
51 | upward-growing stacks in the scenario just described. | |
52 | ||
53 | :samp:`known_misalignment ({value}, {align}, &{misalign})` | |
54 | Return true if we can calculate the misalignment of :samp:`{value}` | |
55 | with respect to :samp:`{align}` at compile time, storing the result in | |
56 | :samp:`{misalign}` if so. | |
57 | ||
58 | :samp:`known_alignment ({value})` | |
59 | Return the minimum alignment that :samp:`{value}` is known to have | |
60 | (in other words, the largest alignment that can be guaranteed | |
61 | whatever the values of the indeterminates turn out to be). | |
62 | Return 0 if :samp:`{value}` is known to be 0. | |
63 | ||
64 | :samp:`force_align_down ({value}, {align})` | |
65 | Assert that :samp:`{value}` can be aligned down to :samp:`{align}` at compile | |
66 | time and return the result. When using this routine, please add a | |
67 | comment explaining why the assertion is known to hold. | |
68 | ||
69 | :samp:`force_align_up ({value}, {align})` | |
70 | Likewise, but aligning up. | |
71 | ||
72 | :samp:`force_align_down_and_div ({value}, {align})` | |
73 | Divide the result of ``force_align_down`` by :samp:`{align}`. Again, | |
74 | please add a comment explaining why the assertion in ``force_align_down`` | |
75 | is known to hold. | |
76 | ||
77 | :samp:`force_align_up_and_div ({value}, {align})` | |
78 | Likewise for ``force_align_up``. | |
79 | ||
80 | :samp:`force_get_misalignment ({value}, {align})` | |
81 | Assert that we can calculate the misalignment of :samp:`{value}` with | |
82 | respect to :samp:`{align}` at compile time and return the misalignment. | |
83 | When using this function, please add a comment explaining why | |
84 | the assertion is known to hold. |