[PATCH] _Generic.3: New page documenting _Generic()

[PATCH] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

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.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: JeanHeyd Meneide <wg14@soasis.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Ingo Schwarze <schwarze@usta.de>
---

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

diff --git a/man3/_Generic.3 b/man3/_Generic.3
new file mode 100644
index 000000000..7c88a6975
--- /dev/null
+++ b/man3/_Generic.3
@@ -0,0 +1,69 @@
+.\" Copyright (C) 2022 Alejandro Colomar <alx.manpages@gmail.com>
+.\"
+.\" 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
-- 
2.37.2

[PATCH v2] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

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.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: JeanHeyd Meneide <wg14@soasis.org>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Ingo Schwarze <schwarze@usta.de>
---

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

diff --git a/man3/_Generic.3 b/man3/_Generic.3
new file mode 100644
index 000000000..3e1c159ab
--- /dev/null
+++ b/man3/_Generic.3
@@ -0,0 +1,60 @@
+.\" Copyright (C) 2022 Alejandro Colomar <alx.manpages@gmail.com>
+.\"
+.\" 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
-- 
2.37.2

Re: [PATCH v2] _Generic.3: New page documenting _Generic()

[Florian Weimer]

* Alejandro Colomar:

> +.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
> +)

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

Re: [PATCH v2] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3660 bytes --]

Hi Florian,

On 8/23/22 09:58, Florian Weimer wrote:
 > * Alejandro Colomar:
 >
 >> +.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
 >> +)
 >
 > 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.)

 >
 > 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).

 > (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.

 >  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.

 >
 > C++ templates do not suffer from this particular problem.
 >
 > Thanks,
 > Florian
 >
Thanks for the review!!

Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 797 bytes --]

On 8/23/22 15:16, Alejandro Colomar wrote:
> 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

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1376 bytes --]

Hi Florian,

On 8/23/22 09:58, Florian Weimer wrote:

> 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.


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

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1507 bytes --]

On 8/23/22 15:32, Alejandro Colomar wrote:
> Hi Florian,
> 
> On 8/23/22 09:58, Florian Weimer wrote:
> 
>> 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.
> 
> 
> 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()/

> not specify how that macro is implemented; this is just a simple 
> suggestion, but a builtin of course would be better.
> 
> Cheers,
> 
> Alex
> 

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2582 bytes --]

Hi Florian,

On 8/23/22 09:58, Florian Weimer wrote:
> 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.


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

---

diff --git a/man3/_Generic.3 b/man3/_Generic.3
index f3daf98c1..3bd5f306c 100644
--- a/man3/_Generic.3
+++ b/man3/_Generic.3
@@ -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)




-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 580 bytes --]

On 9/4/22 23:16, Alejandro Colomar wrote:
> 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.

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] _Generic.3: New page documenting _Generic()

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3808 bytes --]

On 9/4/22 23:16, Alejandro Colomar wrote:
> Hi Florian,
> 
> On 8/23/22 09:58, Florian Weimer wrote:
>> 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.
> 
> 
> 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
> 
> ---
> 
> diff --git a/man3/_Generic.3 b/man3/_Generic.3
> index f3daf98c1..3bd5f306c 100644
> --- a/man3/_Generic.3
> +++ b/man3/_Generic.3
> @@ -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)
> 

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


-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]