10.5 Alignment of poly_ints

poly_int provides various routines for aligning values and for querying misalignments. In each case the alignment must be a power of 2.

‘can_align_p (value, align)’

Return true if we can align value up or down to the nearest multiple of align at compile time. The answer is the same for both directions.

‘can_align_down (value, align, &aligned)’

Return true if can_align_p; if so, set aligned to the greatest aligned value that is less than or equal to value.

‘can_align_up (value, align, &aligned)’

Return true if can_align_p; if so, set aligned to the lowest aligned value that is greater than or equal to value.

‘known_equal_after_align_down (a, b, align)’

Return true if we can align a and b down to the nearest align boundary at compile time and if the two results are equal.

‘known_equal_after_align_up (a, b, align)’

Return true if we can align a and b up to the nearest align boundary at compile time and if the two results are equal.

‘aligned_lower_bound (value, align)’

Return a result that is no greater than value and that is aligned to align. The result will the closest aligned value for some indeterminate values but not necessarily for all.

For example, suppose we are allocating an object of size bytes in a downward-growing stack whose current limit is given by limit. If the object requires align bytes of alignment, the new stack limit is given by:

aligned_lower_bound (limit - size, align)

‘aligned_upper_bound (value, align)’

Likewise return a result that is no less than value and that is aligned to align. This is the routine that would be used for upward-growing stacks in the scenario just described.

‘known_misalignment (value, align, &misalign)’

Return true if we can calculate the misalignment of value with respect to align at compile time, storing the result in misalign if so.

‘known_alignment (value)’

Return the minimum alignment that value is known to have (in other words, the largest alignment that can be guaranteed whatever the values of the indeterminates turn out to be). Return 0 if value is known to be 0.

‘force_align_down (value, align)’

Assert that value can be aligned down to align at compile time and return the result. When using this routine, please add a comment explaining why the assertion is known to hold.

‘force_align_up (value, align)’

Likewise, but aligning up.

‘force_align_down_and_div (value, align)’

Divide the result of force_align_down by align. Again, please add a comment explaining why the assertion in force_align_down is known to hold.

‘force_align_up_and_div (value, align)’

Likewise for force_align_up.

‘force_get_misalignment (value, align)’

Assert that we can calculate the misalignment of value with respect to align at compile time and return the misalignment. When using this function, please add a comment explaining why the assertion is known to hold.