[cfe-dev] [RFC] Handling implementation limits

[Aaron Ballman via cfe-dev]

On Wed, Jan 1, 2020 at 11:16 AM Mark de Wever <koraq at xs4all.nl> wrote:
>
> This RFC asks the community for its interest in centralizing Clang's
> implementation limits and how you feel about the proposed approach.

Thank you for looking into this, I think something along these lines
could be valuable both for internal development purposes as well as
for our users. I'm generally supportive of the idea.

> Abstract
> ========
>
> At the moment the implementation limits of the Clang compiler are hidden
> in magic numbers in the code. These numbers sometimes differ between the
> frontend and the backend. They are not always properly guarded by compiler
> warnings, instead they trigger assertion failures.
>
> This proposal suggests a TableGen based solution to better maintain these
> limits. This solution will be able to generate a header and documentation
> of these limits. The latter is required by the C++ standard [implimits].

It's also required by the C standard where they have Implementation
Limits clauses that detail situations where the implementation may
place limits on constructs.

> The problem
> ===========
>
> The proposal tries to solve 2 issues:
> * Implementation limits are not always clear and duplicated in the source.
> * Document C++ Implementation quantities  is required by the C++ standard
>   [implimits].

Do you anticipate also trying to cover the C standard implementation
limits as well? I think it would make sense to do so -- there should
be a large amount of overlap between the C limits and the C++ limits.

~Aaron

> Unclear limits
> --------------
>
> The compiler has several limitations often 'hidden' as the width of a
> bit-field in a structure. This makes it hard to find these limits. Not
> only for our users but also for developers. While looking at a proper
> limit for the maximum width of a bit-field in the frontend I discovered
> it didn't matter what the frontend picked, the backend already had a
> limit [D71142]. To fix this issue the frontend and backend should have
> the same limit. To avoid duplicating the value it should be in a header
> available to the frontend and backend.
>
> Since the values are often stored in a bit-field there is no standard way
> to get the maximum value. This means the limit needs a small helper
> function to get the value, for example [D63975] uses
> `getMaxFunctionScopeDepth()`.
>
>
> Standard conformance
> --------------------
>
> This is rather simple the C++ standard Annex B states:
>    Because computers are finite, C++ implementations are inevitably
>    limited in the size of the programs they can successfully process.
>    Every implementation shall document those limitations where known.
>
> Currently this documentation is not available.
>
>
> The proposed solution
> =====================
>
> In order to solve this issue I created a proof-of-concept solution
> [D72053]. It contains a new file
> clang/include/clang/Basic/ImplementationQuantities.td with two TableGen
> generators which create:
> * An inc file with a set of constants containing the limits. This file
>   $BUILD_DIR/tools/clang/include/clang/Basic/ImplementationQuantities.inc
>   is included in the header
>   clang/include/clang/Basic/ImplementationQuantities.h.
> * The document clang/docs/ImplementationQuantities.rst
>   This document documents the limits of Clang. These limits include, but
>   are not limited to the quantities in [implimits].
>
> The quantity limit has the following possible types:
> * The quantity is limited by the number of bits in a bit-field. TableGen
>   generates two constants:
>   * FieldNameBits, the number of bits in the bit-field.
>   * MaxFieldName, the maximum value of the bit-field. (This assumes all
>     bit-fields can be stored in an unsigned.)
> * The quantity is limited by a value. TableGen generates one constant:
>   * MaxFieldName, the maximum value of the field.
> * The quantity's limit is determined by a compiler flag. TableGen
>   generates one constant:
>   * FieldNameDefault, the default value of the compiler flag.
> * The quantity's limit cannot be expressed in a number. For example it
>   depends on the stack size or available memory of the system. In this
>   case TableGen generates no constant, only documentation.
>
> For all types documentation is generated. The documentation shows the
> description of the limit and the limit implemented in Clang. If the
> recommended value is not 0 it is a value described in the C++ Standard. In
> this case the recommended value is shown in the documentation.
>
>
> Questions
> =========
>
> * If this proposal is accepted how to we make sure the document is updated
>   before releasing a new version of clang?
> * The compiler flag limits are also documented in the UserManual. This means
>   these limits are still duplicated. Do we want to let the UserManual also be
>   generated and use the values here or just keep the duplication?
>
>
> Bikeshed
> ========
>
> I picked IQ for the namespace of the quantities since it's short and not
> often used in the codebase so it's easy greppable.
>
>
> [implimits] http://eel.is/c++draft/implimits
> [D63975] https://reviews.llvm.org/D63975
> [D71142] https://reviews.llvm.org/D71142
> [D72053] https://reviews.llvm.org/D72053
>
>
> Kind regards,
> Mark de Wever