_Generic.3: New page documenting _Generic()
PATCH 1/1 _Generic.3: New page documenting _Generic()
Also add a hint of how intmax(3) and other functions using [u]intmax_t types could be better defined by ISO C, by requiring that they're implemented as type-generic macros, to avoid having problems with the ABI.
---
Hi,
This page is one of the first using true-case page title, and the first one using the new Linux man-pages 4th .TH argument.
I always forget about the syntax details of using _Generic(), since it's different to anything else (why didn't they just use switch-case syntax??!).
I hope this is useful for others as it is for me.
Cheers,
Alex
man3/_Generic.3 | 69 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 man3/_Generic.3
man3/_Generic.3 new file +69 -0
@@ -0,0 +1,69 @@ +.\" Copyright (C) 2022 Alejandro Colomar <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH _Generic 3 2022-08-20 "Linux man-pages (unreleased)" "Linux Programmer's Manual" +.SH NAME +_Generic \- type-generic selection +.SH SYNOPSIS +.nf +.BR _Generic( \fIexpression\fP ", type1: " e1 ", " "... /*" \ +", default: " "e */" ); +.fi +.SH DESCRIPTION +.BR _Generic () +evaluates the path of code under the type selector +that is compatible with the type of the controlling +.IR expression , +or +.B default: +if no type is compatible. +.PP +.I expression +is not evaluated. +.PP +This is especially useful for writing type-generic macros, +that will behave differently depending on the type of the argument. +.SH STANDARDS +C11 and later. +.SH EXAMPLES +The following program demonstrates how to write +a replacement for the standard +.BR imaxabs (3) +function, which being a function can't really provide what it promises: +seamlessly upgrading to the widest available type. +.PP +.\" SRC BEGIN (_Generic.c) +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> + +#define my_imaxabs(j) _Generic \e +((intmax_t) 0, \e + \e + int: \e + abs(j), \e + \e + long: \e + labs(j), \e + \e + long long: \e + llabs(j) \e + \e + /* long long long: */ \e + /* lllabs(j) */ \e +) + +int +main(void) +{ + short a; + + a = \-42; + printf("imaxabs(%d) == %jd\en", a, my_imaxabs(a)); + + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END
Signature · 1 line
2.37.2
PATCH v2 1/1 _Generic.3: New page documenting _Generic()
Also add a hint of how intmax(3) and other functions using [u]intmax_t types could be better defined by ISO C, by requiring that they're implemented as type-generic macros, to avoid having problems with the ABI.
---
v2:
- Use a type that really needs to be converted to (intmax_t).
- Compatc _Generic().
man3/_Generic.3 | 60 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 man3/_Generic.3
man3/_Generic.3 new file +60 -0
@@ -0,0 +1,60 @@ +.\" Copyright (C) 2022 Alejandro Colomar <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH _Generic 3 2022-08-20 "Linux man-pages (unreleased)" "Linux Programmer's Manual" +.SH NAME +_Generic \- type-generic selection +.SH SYNOPSIS +.nf +.BR _Generic( \fIexpression\fP ", type1: " e1 ", " "... /*" \ +", default: " "e */" ); +.fi +.SH DESCRIPTION +.BR _Generic () +evaluates the path of code under the type selector +that is compatible with the type of the controlling +.IR expression , +or +.B default: +if no type is compatible. +.PP +.I expression +is not evaluated. +.PP +This is especially useful for writing type-generic macros, +that will behave differently depending on the type of the argument. +.SH STANDARDS +C11 and later. +.SH EXAMPLES +The following program demonstrates how to write +a replacement for the standard +.BR imaxabs (3) +function, which being a function can't really provide what it promises: +seamlessly upgrading to the widest available type. +.PP +.\" SRC BEGIN (_Generic.c) +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> + +#define my_imaxabs(j) _Generic((intmax_t) 0, \e + int: abs(j), \e + long: labs(j), \e + long long: llabs(j) \e + /* long long long: lllabs(j) */ \e +) + +int +main(void) +{ + off_t a; + + a = \-42; + printf("imaxabs(%jd) == %jd\en", (intmax_t) a, my_imaxabs(a)); + + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END
Signature · 1 line
2.37.2
* Alejandro Colomar:
Quoted 9 lines
+.SH EXAMPLES
man3/_Generic.3 new file +8
-0+The following program demonstrates how to write +a replacement for the standard +.BR imaxabs (3) +function, which being a function can't really provide what it promises: +seamlessly upgrading to the widest available type. +.PP +.\" SRC BEGIN (_Generic.c) +.EX
man3/_Generic.3 line 47
Quoted 10 lines
man3/_Generic.3 new file +10
-0+#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> + +#define my_imaxabs(j) _Generic((intmax_t) 0, \e + int: abs(j), \e + long: labs(j), \e + long long: llabs(j) \e + /* long long long: lllabs(j) */ \e +)
The macro name does not really match what the function does. It's a type-generic abs function, not related to the max function or intmax_t.
Note that this approach does not really work that well in practice because macros using _Generic expand all the alternatives (in current implementations; doing this differently requires deviating from the layered implementation strategy suggested in the C standard). This means that _Generic-using macros can only be nested maybe three or four levels deep, depending on the number of _Generic alternatives on each level. For <tgmath.h>, this is really not enough, so a high-quality implementation of <tgmath.h> using _Generic is not feasible. GCC provides __builtin_tgmath, which is designed in such a way that when used in a macro, the macro argument is only expanded once.
Maybe mention this under BUGS?
C++ templates do not suffer from this particular problem.
Thanks,
Florian
Hi Florian,
Quoted 16 lines · Florian Weimer
* Alejandro Colomar:
Quoted 14 lines
+.SH EXAMPLES
man3/_Generic.3 new file +13
-0+The following program demonstrates how to write +a replacement for the standard +.BR imaxabs (3) +function, which being a function can't really provide what it promises: +seamlessly upgrading to the widest available type. +.PP +.\" SRC BEGIN (_Generic.c) +.EX +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> + +#define my_imaxabs(j) _Generic((intmax_t) 0, \e
Quoted 8 lines
man3/_Generic.3 line 47
Quoted 5 lines
man3/_Generic.3 new file +5
-0+ int: abs(j), \e + long: labs(j), \e + long long: llabs(j) \e + /* long long long: lllabs(j) */ \e +)The macro name does not really match what the function does. It's a type-generic abs function, not related to the max function or
intmax_t.
No, it's not a type-generic function, per the usual definition of "type-generic function". It doesn't depend on the input type. The selector is fixed. It's actually more or less like switch-case-ing on a compile-time constant. BTW, I could improve it to be INTMAX_C(0).
It behaves the same as the standard imaxabs(3):
The input is converted to intmax_t before being passed to the function (i.e., __int128 would be truncated to intmax_t), and the output is of type intmax_t. (Or, actually, the underlying type behind intmax_t.)
Quoted 3 lines
Note that this approach does not really work that well in practice because macros using
_Genericexpand all the alternatives
Yeah, it expands all, instead of behaving like a lot of #if's. Maybe #if's would be better for a libc, but _Generic() could be good enough for some implementations, or could be good for a user that doesn't want to use the broken-by-design standard imaxabs(3).
Quoted 3 lines
(in current
implementations; doing this differently requires deviating from the layered implementation strategy suggested in the C standard).
The standard is broken in this regard. My hint is to fix the standard, not to fix libc. Although glibc might benefit from deviating from the standard for good here.
The problem is in emitting linker code for a function whose type is expected to change in the future. A macro is free from ABI problems by not emitting any linker code.
BTW, as a very-long term suggestion improvement for libc and ISO C, functions should be emitted only for fixed width integer types, like
abs32(), abs64(), abs128(), ...
If only fixed-width function identifiers existed (instead of labs() and llabs(), ...), ABI stability would be less problematic than it is right now.
Quoted 8 lines
This
means that _Generic-using macros can only be nested maybe three or four levels deep, depending on the number of_Genericalternatives on each level. For <tgmath.h>, this is really not enough, so a high-quality implementation of <tgmath.h> using_Genericis not feasible. GCC provides__builtin_tgmath, which is designed in such a way that when used in a macro, the macro argument is only expanded once.> Maybe mention this under BUGS?
I'm not sure I understand the bug. The code is expanded, but it's not evaluated, right?
I.e., AFAIK, my_imaxabs(++x) would only do the ++ once, right? Is that what you were suggesting?
Otherwise, please send a patch for BUGS. It might help.
Quoted 6 lines
C++ templates do not suffer from this particular problem.
Thanks,
Florian
Thanks for the review!!
Cheers,
Alex
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>
Quoted 1 line · Alejandro Colomar
I.e., AFAIK,
my_imaxabs(++x)would only do the ++ once, right? Is that what you were suggesting?
If that's what you meant, the macro seems safe:
$ cat imaxabs.c #include <stdint.h> #include <stdio.h> #include <stdlib.h>
#define my_imaxabs(j) _Generic(INTMAX_C(0), \
long: labs(j), \
long long: llabs(j) \
/* long long long: lllabs(j) */ \)
int
main(void)
{
off_t a;
a = (intmax_t) -1;
printf("imaxabs(%jd) == %jd\n", (intmax_t) -2, my_imaxabs(--a));
exit(EXIT_SUCCESS);
}$ cc -Wall -Wextra imaxabs.c $ ./a.out imaxabs(-2) == 2
Cheers,
Alex
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>
Hi Florian,
Quoted 11 lines · Florian Weimer
Note that this approach does not really work that well in practice because macros using
_Genericexpand all the alternatives (in current implementations; doing this differently requires deviating from the layered implementation strategy suggested in the C standard). This means that _Generic-using macros can only be nested maybe three or four levels deep, depending on the number of_Genericalternatives on each level. For <tgmath.h>, this is really not enough, so a high-quality implementation of <tgmath.h> using_Genericis not feasible. GCC provides__builtin_tgmath, which is designed in such a way that when used in a macro, the macro argument is only expanded once.
Quoted 3 lines
Maybe mention this under BUGS?
C++ templates do not suffer from this particular problem.
Ahh, I get it now. You mean that the preprocessed code could grow exponentially, even if the assembly code is safe from such bloat, right?
Yeah, probably that should go into CAVEATS.
Would you mind sending a patch?
Anyway, if the standard defined intmax_t as a macro, it should probably not specify how that macro is implemented; this is just a simple suggestion, but a builtin of course would be better.
Cheers,
Alex
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>
Quoted 20 lines · Alejandro Colomar
Hi Florian,
Quoted 11 lines · Florian Weimer
Note that this approach does not really work that well in practice because macros using
_Genericexpand all the alternatives (in current implementations; doing this differently requires deviating from the layered implementation strategy suggested in the C standard). This means that _Generic-using macros can only be nested maybe three or four levels deep, depending on the number of_Genericalternatives on each level. For <tgmath.h>, this is really not enough, so a high-quality implementation of <tgmath.h> using_Genericis not feasible. GCC provides__builtin_tgmath, which is designed in such a way that when used in a macro, the macro argument is only expanded once.Quoted 3 lines
Maybe mention this under BUGS?
C++ templates do not suffer from this particular problem.
Quoted 7 lines
Ahh, I get it now. You mean that the preprocessed code could grow exponentially, even if the assembly code is safe from such bloat, right?
Yeah, probably that should go into CAVEATS.
Would you mind sending a patch?
Anyway, if the standard defined
intmax_tas a macro, it should probably
s/intmax_t/imaxabs()/
Quoted 6 lines
not specify how that macro is implemented; this is just a simple suggestion, but a builtin of course would be better.
Cheers,
Alex
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>
Hi Florian,
Quoted 11 lines · Florian Weimer
Note that this approach does not really work that well in practice because macros using
_Genericexpand all the alternatives (in current implementations; doing this differently requires deviating from the layered implementation strategy suggested in the C standard). This means that _Generic-using macros can only be nested maybe three or four levels deep, depending on the number of_Genericalternatives on each level. For <tgmath.h>, this is really not enough, so a high-quality implementation of <tgmath.h> using_Genericis not feasible. GCC provides__builtin_tgmath, which is designed in such a way that when used in a macro, the macro argument is only expanded once.
Quoted 3 lines
Maybe mention this under BUGS?
C++ templates do not suffer from this particular problem.
Heh, I don't know how this didn't oocur to me before. Well, maybe it's because it's non-standard (but the standard might very well benefit from adding this, IMO).
An always_inline function with no extern definition behaves as if it were a macro (trying to take a pointer to it, or something that needs a linker symbol, will result in linker errors, which is not the most readable error, but good enough), in the sense that it doesn't have ABI issues, but has the benefit of not creating code exponentially.
Cheers,
Alex
---
man3/_Generic.3 +13 -6
@@ -30,7 +30,9 @@ C11 and later. The following program demonstrates how to write a replacement for the standard .BR imaxabs (3) -function, which being a function can't really provide what it promises: +function, which being an +.I extern +function can't really provide what it promises: seamlessly upgrading to the widest available type. .PP .\" SRC BEGIN (_Generic.c)
@@ -39,11 +41,16 @@ seamlessly upgrading to the widest available type. #include <stdio.h> #include <stdlib.h> -#define my_imaxabs(j) _Generic(INTMAX_C(0), \e - long: labs(j), \e - long long: llabs(j) \e - /* long long long: lllabs(j) */ \e -) +[[gnu::always_inline]] +inline intmax_t +my_imaxabs(intmax_t j) +{ + return _Generic(j, + long: labs(j), + long long: llabs(j) + /* long long long: lllabs(j) */ + ) +} int main(void)
Signature · 2 lines
Alejandro Colomar <http://www.alejandro-colomar.es/>
Quoted 2 lines · Alejandro Colomar
An
always_inlinefunction with no extern definition behaves as if it were a macro (trying to take a pointer to it, or something that needs a linker symbol, will result in linker errors, which is not the most readable error, but good enough), in the sense that it doesn't have ABI issues, but has the benefit of not creating code exponentially.
Although of course not being able to take pointers to it is a problem for libc. The macro with _Generic has the same issue. libc seems to need preprocessor #if.
Quoted 58 lines · Alejandro Colomar
Hi Florian,
Quoted 11 lines · Florian Weimer
Note that this approach does not really work that well in practice because macros using
_Genericexpand all the alternatives (in current implementations; doing this differently requires deviating from the layered implementation strategy suggested in the C standard). This means that _Generic-using macros can only be nested maybe three or four levels deep, depending on the number of_Genericalternatives on each level. For <tgmath.h>, this is really not enough, so a high-quality implementation of <tgmath.h> using_Genericis not feasible. GCC provides__builtin_tgmath, which is designed in such a way that when used in a macro, the macro argument is only expanded once.Quoted 3 lines
Maybe mention this under BUGS?
C++ templates do not suffer from this particular problem.
Heh, I don't know how this didn't oocur to me before. Well, maybe it's because it's non-standard (but the standard might very well benefit from adding this, IMO).
An
always_inlinefunction with no extern definition behaves as if it were a macro (trying to take a pointer to it, or something that needs a linker symbol, will result in linker errors, which is not the most readable error, but good enough), in the sense that it doesn't have ABI issues, but has the benefit of not creating code exponentially.Cheers,
Alex
---
man3/_Generic.3 +6
-6@@ -30,7 +30,9 @@ C11 and later. The following program demonstrates how to write a replacement for the standard .BR imaxabs (3) -function, which being a function can't really provide what it promises: +function, which being an +.I extern +function can't really provide what it promises: seamlessly upgrading to the widest available type. .PP .\" SRC BEGIN (_Generic.c)@@ -39,11 +41,16 @@ seamlessly upgrading to the widest available type. #include <stdio.h> #include <stdlib.h> -#define my_imaxabs(j) _Generic(INTMAX_C(0), \e - long: labs(j), \e - long long: llabs(j) \e - /* long long long: lllabs(j) */ \e -) +[[gnu::always_inline]] +inline intmax_t +my_imaxabs(intmax_t j)
man3/_Generic.3 seamlessly upgrading to the widest available type. · line 56
Quoted 10 lines
man3/_Generic.3 +7
-0+{ + return _Generic(j, + long: labs(j), + long long: llabs(j) + /* long long long: lllabs(j) */ + ) +} int main(void)
Huh, although this goes back again to macros, and potentially exponential code, I think it's quite clean and minimal, and has the benefit that it allows one to take pointers:
$ cat gen.c #include <stdint.h> #include <stdio.h> #include <stdlib.h>
#define my_imaxabs _Generic(INTMAX_C(0), \
long: labs, \
long long: llabs \
/* long long long: lllabs */ \)
int
main(void)
{
off_t a;
a = -42;
printf("imaxabs(%jd) == %jd\n", (intmax_t) a, my_imaxabs(a));
printf("&imaxabs == %p\n", &my_imaxabs);
printf("&labs == %p\n", &labs);
printf("&llabs == %p\n", &llabs);
exit(EXIT_SUCCESS);
}$ cc -Wall -Wextra gen.c $ ./a.out imaxabs(-42) == 42 &imaxabs == 0x7ff5aa2407a0 &labs == 0x7ff5aa2407a0 &llabs == 0x7ff5aa2407b0
Nice experiment :)
Cheers,
Alex
Signature · 1 line
<http://www.alejandro-colomar.es/>