Skip to contentSkip to conversation

_Generic.3: New page documenting _Generic()

PATCH Superseded Alejandro Colomar 2 participants 10 messages Aug 20, 2022 – Sep 9, 2022 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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.

Cc JeanHeyd Meneide <[email protected]>
Cc "G. Branden Robinson" <[email protected]>
Cc Ingo Schwarze <[email protected]>

---

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
new file mode 100644
index 000000000..7c88a6975
@@ -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
#1 lore raw

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.

Cc JeanHeyd Meneide <[email protected]>
Cc "G. Branden Robinson" <[email protected]>
Cc Ingo Schwarze <[email protected]>

---

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
new file mode 100644
index 000000000..3e1c159ab
@@ -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
#2 lore raw

* 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

#3 lore raw

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 _Generic expand 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 _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?

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/>
#4 lore raw
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/>
#5 lore raw
In reply to Florian Weimer

Hi Florian,

Quoted 11 lines · Florian Weimer

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.

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/>
#6 lore raw
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 _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.

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_t as 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/>
#7 lore raw
In reply to Florian Weimer

Hi Florian,

Quoted 11 lines · Florian Weimer

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.

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
index f3daf98c1..3bd5f306c 100644
@@ -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/>
#8 lore raw
Quoted 2 lines · Alejandro Colomar

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.

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.

#9 lore raw
In reply to Alejandro Colomar
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 _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.

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 +6 -6
index f3daf98c1..3bd5f306c 100644
@@ -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/>