[PATCH v2] C-family : Add attribute 'unavailable'.

[Martin Sebor]

On 11/10/20 12:38 PM, Iain Sandoe wrote:
> Hi Jospeh,
> 
> Joseph Myers <joseph@codesourcery.com> wrote:
> 
>> This patch seems to be missing documentation for the new attribute in
>> extend.texi.
> 
> Apologies, for that omission, revised patch includes the documentation and
> also addresses Richi’s comments.
> 
> documentation patch tested with “make pdf” and visual inspection of the output.
> 
> OK now?
> thanks
> Iain
> 
> —— commit message.
> 
> If an interface is marked 'deprecated' then, presumably, at some point it
> will be withdrawn and no longer available.  The 'unavailable' attribute
> makes it possible to mark up interfaces to indicate this status.

(Sorry I'm a little with my feedback.  Hopefully it's still helpful.)

Making an interface unavailable isn't the intent of deprecation in
standards like C, C++, or POSIX.  Rather, the intended next stage
after deprecation is to make the interface available for other uses,
either by the standards themselves, or by implementations, or by
programs (if its name is not in the reserved namespace).  So unless
you have other kinds of deprecation in mind this doesn't seem like
a fitting use case.

> It is used
> quite extensively in some codebases where a single set of headers can be used
> to permit code generation for multiple system versions.

This sounds like a different use case than the next stage after
deprecation.  I haven't come across it but I imagine its purpose
is to foster portability between variants or flavors (rather
than versions) of APSs?  Say one set of APIs for a feature-rich
desktop variant of an OS versus a subset of the same APIs for
an embedded, more limited variant of the same OS.

> 
>  From a configuration perspective, it also allows a compile test to determine
> that an interface is missing - rather than requiring a link test.
> 
> The implementation follows the pattern of attribute deprecated, but produces
> an error (where deprecation produces a warning).
> 
> This attribute has been implemented in clang for some years.

The Clang manual says the attribute is useful in conjunction with
the enable_if and overloadble attributes in C, to remove overloads
of C functions from the overload set.  I'm trying to think how
the GCC implementation of the attribute might be useful in
the subset of cases that don't depend on the other two attributes
but I'm coming up empty (exceot for the different variants of
an API use case that seems rather esoteric).  It seems to me
the use case is close to #pragma GCC poison except more nunanced
(i.e., it doesn't poison a name but its uses in the given namespace,
as in functions, types, members, etc.)

...
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index 5f1e3bf8a2e..a6b5867808a 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -2865,6 +2865,19 @@ types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
>   The message attached to the attribute is affected by the setting of
>   the @option{-fmessage-length} option.
>   
> +@item unavailable
> +@itemx unavailable (@var{msg})
> +@cindex @code{unavailable} function attribute
> +The @code{deprecated} attribute results in an error if the function
              ^^^^^^^^^^

This should presumably read unavailable.

> +is used anywhere in the source file.  This is useful when identifying
> +functions that have been removed from a particular variation of an
> +interface.  Other than emitting an error rather than a warning, the
> +@code{unavailable} attribute behaves in the same manner as
> +@code{deprecated}.
> +
> +The @code{unavailable} attribute can also be used for variables and
> +types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
> +
>   @item error ("@var{message}")
>   @itemx warning ("@var{message}")
>   @cindex @code{error} function attribute
> @@ -7223,6 +7236,22 @@ types (@pxref{Common Function Attributes},
>   The message attached to the attribute is affected by the setting of
>   the @option{-fmessage-length} option.
>   
> +@item unavailable
> +@itemx unavailable (@var{msg})
> +@cindex @code{unavailable} variable attribute
> +The @code{unavailable} attribute indicates that the variable so marked
> +is not available, if it is used anywhere in the source file.  It behaves
> +in the same manner as the @code{deprecated} attribute except that the
> +compiler will emit an error rather than a warning.
> +
> +It is expected that items marked as @code{deprecated} will eventually be
> +withdrawn from interfaces, and then become unavailable.  This attribute
> +allows for marking them appropriately.

In Clang, declaring a member unavailable doesn't have the same effect
as withdrawing it (which I would interpret as removing).  The member
still takes up space, so if this patch does the same I think this
effect should be made clear here.

Like attribute deprecated, I suspect attribute unavailable in GCC
will also be subject to the same catch 22 of marking up both a type
and its uses in APIs.  E.g., in:

   struct __attribute__ ((deprecated)) A { ... };

   struct B {
     // Clang accepts this w/o warning, GCC warns.
     struct A a __attribute__ ((deprecated));
     int i;
   };

With unavailable, the problem will be made worse due to the error.
To be generally usable, I think GCC needs to change to behave more
like Clang.  As a motivating example, consider the deprecated POSIX
getitimer API:

   struct itimerval { int it_interval, it_value; };
   int getitimer (int, struct itimerval*);
   int setitimer (int, const struct itimerval*, struct itimerval*);

All three names are deprecated and so using each one alone outside
the header that declares them should trigger a deprecation message;
the declarations themselves must not.  If/when the APIs are removed,
marking them unavailable in the headers must likewise not trigger
errors.

Martin