defined in the feature test macro example__cpp_lib_freestanding in favor of __STDC_HOSTED__<compare>source_location addition
Branching from P0829R4. This "omnibus" paper is still the direction I am aiming for. However, it is too difficult to review. It needs to change with almost every meeting. Therefore, it is getting split up into smaller, more manageable chunks.
Limiting paper to <version>, blanket wording, and freestanding facilities already in the working draft.
This paper is the first of many smaller papers adding facilities to the C++ freestanding library. This paper in particular will be updating the editorial technique for declaring facilities as freestanding and adjusting feature test macros. This update will make it easier to mark headers as partially freestanding. This wording change will make it easier to mark in-flight proposals as freestanding, without causing a major blocking point in the standardization process.
Many existing facilities in the C++ standard library could be used without trouble in freestanding environments. This series of papers will specify the maximal subset of the C++ standard library that does not require an OS or space overhead.
For a more in depth rationale, see P0829.
This paper is going to add blanket wording to make it easier to mark things freestanding, and it will retrofit the existing freestanding facilities. It also includes a non-normative note that should allow implementers to use existing no-exception builds of their libraries as an implementation-defined extensions, with a fair number of qualifications. Here's that note, reproduced so that it can be debated more effectively:
There are two intentional design changes in this paper. The first is giving implementers freedom to include facilities in a freestanding implementation beyond those required in the specification, so long as the additional facilities meet the same requirements as for hosted implementations. The second is marking feature test macros for hosted facilities as being optional.
This paper grants implementations the freedom to include more than just the facilities that are marked //freestanding. There will be platforms where, for example, floating point is both available and frequently used (e.g. GPU environments). On those platforms, it is desirable for implementations to provide many of the <cmath> and <complex> facilities. We must be careful here though, as we don't want to allow divergence of implementation, and we want to be able to add facilities to the required subset of freestanding. To permit both vendor extension and future freestanding growth, this paper will require that additionally included facilities must meet the same requirements as for a hosted implementation.
This paper does not need a direct feature test macro. Users can already detect whether an implementation is hosted or freestanding by testing the __STDC_HOSTED__ macro [cpp.predefined].
The library feature macros have been partitioned into those that must be present in both freestanding and hosted mode, and those that only need to be present in hosted mode. If the implementation provides more than the minimal freestanding subset, then the implementation should also provide the corresponding feature test macros. This "should" is left as Quality-of-Implementation though, as nothing binds the individual feature test macros to specific sections of wording.
Example of a freestanding user detecting the presence of an optional feature:
#if defined(__cpp_lib_addressof_constexpr) && __cpp_lib_addressof_constexpr >= 201603
#include <memory>
template <class T>
constexpr std::decay_t<T>* my_addressof(T && arg) {
return std::addressof(std::forward<T>(arg));
}
#else
template <class T>
constexpr std::decay_t<T>* my_addressof(T && arg) {
return &arg;
}
#endif
The wording adds an editorial technique for freestanding-only macros. This paper does not use the technique, but future papers dealing with freestanding will need this facility for their feature test macros.
The following changes are relative to N4849 from the Pre-Prague 2020 mailing.
Add a new subclause [freestanding.membership], under [conventions] and after [objects.within.classes]:Change in [compliance] paragraph 3:?.?.?.? Freestanding membership [freestanding.membership]
Freestanding implementations have several declarations and macro definitions that shall meet the same requirements as for a hosted implementation unless otherwise specified.[ Note: Throwing a standard library provided exception is not observably different from terminate() if the implementation doesn't unwind the stack during exception handling ([except.handle#9]) and the user's program contains no catch blocks. -end note]In the associated header synopsis for such declarations and macro definitions, the items are followed with a comment that ends with freestanding.[ Example:#define E2BIG see below // freestanding-end example]Freestanding implementations have several headers that shall meet the same requirements as for a hosted implementation unless otherwise specified.The synopsis for these headers start with a comment that ends with freestanding.[ Example:// freestanding namespace std {-end example]Freestanding implementations have some macro definitions that shall not be present on hosted implementations.In the associated header synopsis for such macro definitions, the items are followed with a comment that ends with freestanding only.[ Example:#define __cpp_lib_freestanding 202001L // freestanding only-end example]Deduction guides for freestanding class templates shall be implemented in freestanding implementations.Freestanding class templates are class templates that are implemented (partially or fully) in freestanding implementations.The containing namespace of each freestanding declaration shall be provided in a freestanding implementation.Freestanding declarations are non-namespace declarations that are implemented (partially or fully) in a freestanding implementation
Add a paragraph to [compliance]:
Instructions to the editor:A freestanding implementation may optionally provide an implementation-defined set of additional facilities from the C++ standard library, beyond those required for freestanding implementations.All additional facilities provided beyond those required for a freestanding implementation shall meet the requirements for a hosted implementation.
Change in [version.syn]:??? Header <cstdlib> synopsis [cstdlib.syn]
namespace std { using size_t = see below; // freestanding using div_t = see below; using ldiv_t = see below; using lldiv_t = see below; } #define NULL see below // freestanding #define EXIT_FAILURE see below #define EXIT_SUCCESS see below #define RAND_MAX see below #define MB_CUR_MAX see below namespace std { // Exposition-only function type aliases extern "C" using c-atexit-handler = void(); // exposition only extern "C++" using atexit-handler = void(); // exposition only extern "C" using c-compare-pred = int(const void*, const void*); // exposition only extern "C++" using compare-pred = int(const void*, const void*); // exposition only // [support.start.term], start and termination [[noreturn]] void abort() noexcept; // freestanding int atexit(c-atexit-handler* func) noexcept; // freestanding int atexit(atexit-handler* func) noexcept; // freestanding int at_quick_exit(c-atexit-handler* func) noexcept; // freestanding int at_quick_exit(atexit-handler* func) noexcept; // freestanding [[noreturn]] void exit(int status); // freestanding [[noreturn]] void _Exit(int status) noexcept; [[noreturn]] void quick_exit(int status) noexcept; // freestanding char* getenv(const char* name); int system(const char* string); // [c.malloc], C library memory allocation void* aligned_alloc(size_t alignment, size_t size); void* calloc(size_t nmemb, size_t size); void free(void* ptr); void* malloc(size_t size); void* realloc(void* ptr, size_t size); double atof(const char* nptr); int atoi(const char* nptr); long int atol(const char* nptr); long long int atoll(const char* nptr); double strtod(const char* nptr, char** endptr); float strtof(const char* nptr, char** endptr); long double strtold(const char* nptr, char** endptr); long int strtol(const char* nptr, char** endptr, int base); long long int strtoll(const char* nptr, char** endptr, int base); unsigned long int strtoul(const char* nptr, char** endptr, int base); unsigned long long int strtoull(const char* nptr, char** endptr, int base); // [c.mb.wcs], multibyte / wide string and character conversion functions int mblen(const char* s, size_t n); int mbtowc(wchar_t* pwc, const char* s, size_t n); int wctomb(char* s, wchar_t wchar); size_t mbstowcs(wchar_t* pwcs, const char* s, size_t n); size_t wcstombs(char* s, const wchar_t* pwcs, size_t n); // [alg.c.library], C standard library algorithms void* bsearch(const void* key, const void* base, size_t nmemb, size_t size, c-compare-pred* compar); void* bsearch(const void* key, const void* base, size_t nmemb, size_t size, compare-pred* compar); void qsort(void* base, size_t nmemb, size_t size, c-compare-pred* compar); void qsort(void* base, size_t nmemb, size_t size, compare-pred* compar); // [c.math.rand], low-quality random number generation int rand(); void srand(unsigned int seed); // [c.math.abs], absolute values int abs(int j); long int abs(long int j); long long int abs(long long int j); float abs(float j); double abs(double j); long double abs(long double j); long int labs(long int j); long long int llabs(long long int j); div_t div(int numer, int denom); ldiv_t div(long int numer, long int denom); // see [library.c] lldiv_t div(long long int numer, long long int denom); // see [library.c] ldiv_t ldiv(long int numer, long int denom); lldiv_t lldiv(long long int numer, long long int denom); }
__cpp_lib_atomic_flag_test__cpp_lib_atomic_float__cpp_lib_atomic_is_always_lock_free__cpp_lib_atomic_ref__cpp_lib_atomic_value_initialization__cpp_lib_atomic_wait__cpp_lib_bit_cast__cpp_lib_bitops__cpp_lib_bool_constant__cpp_lib_bounded_array_traits__cpp_lib_byte__cpp_lib_char8_t__cpp_lib_concepts__cpp_lib_destroying_delete__cpp_lib_endian__cpp_lib_hardware_interference_size__cpp_lib_has_unique_object_representations__cpp_lib_int_pow2__cpp_lib_integral_constant_callable__cpp_lib_is_aggregate__cpp_lib_is_constant_evaluated__cpp_lib_is_final__cpp_lib_is_invocable__cpp_lib_is_layout_compatible__cpp_lib_is_nothrow_convertible__cpp_lib_is_null_pointer__cpp_lib_is_pointer_interconvertible__cpp_lib_is_swappable__cpp_lib_launder__cpp_lib_logical_traits__cpp_lib_remove_cvref__cpp_lib_result_of_sfinae__cpp_lib_source_location__cpp_lib_three_way_comparison__cpp_lib_transformation_trait_aliases__cpp_lib_type_identity__cpp_lib_type_trait_variable_templates__cpp_lib_uncaught_exceptions__cpp_lib_void_t
Please add a // freestanding comment to all entities in [atomics.syn] other than atomic_signed_lock_free and atomic_unsigned_lock_free
On hosted implementations ([compliance]), aAt least one signed integral specialization of the atomic template, along with the specialization for the corresponding unsigned type ([basic.fundamental]), is always lock-free.
Thanks to Brandon Streiff, Joshua Cannon, Phil Hindman, and Irwan Djajadi for reviewing P0829.
Thanks to Odin Holmes for providing feedback and helping publicize P0829.
Thanks to Paul Bendixen for providing feedback while prototyping P0829.
Similar work was done in the C++11 timeframe by Lawrence Crowl and Alberto Ganesh Barbati in N3256.