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

[Joseph Myers]

On Mon, 21 Dec 2020, Iain Sandoe wrote:

> Hi Joseph,
> 
> Nathan has approved this from the C++ perspective (and Martin said that his
> comments were  "not necessarily to object to the idea behind the attribute but
> to draw attention to the fact that it's not suitable for standard APIs.”)
> 
> So, I wonder, do you have more comments on the revised patch, or is this
> now OK for master?

If  
is the current version, one of the three copies of the attribute 
documentation (the one for it as a function attribute) starts with "The 
@code{deprecated} attribute results in an error", when it should refer to 
@code{unavailable} not @code{deprecated}.  I don't have further comments 
beyond that.

-- 
Joseph S. Myers
jos...@codesourcery.com

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

[Iain Sandoe]

Hi Joseph,

Nathan has approved this from the C++ perspective (and Martin said that his
comments were  "not necessarily to object to the idea behind the attribute  
but

to draw attention to the fact that it's not suitable for standard APIs.”)

So, I wonder, do you have more comments on the revised patch, or is this
now OK for master?

(reiterating, that we are not inventing something new here - but rather  
trying

 to achieve compatibility with implementations that already have the 
attrinbute).

thanks
Iain

Iain Sandoe  wrote:



Martin Sebor  wrote:


On 11/29/20 6:56 PM, Iain Sandoe wrote:



Martin Sebor via Gcc-patches  wrote:

On 11/10/20 12:38 PM, Iain Sandoe wrote:

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

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.

coming at things from the standards perspective .. perhaps.
.. however, in the first set of cases above, one never needs to indicate
 unavailability  since the entity never becomes unavailable, it changes
 meaning.
In practice, we don’t have markup of keywords etc. to indicate this (such
deprecation has been handled specifically in the FEs).
The practical (and actual) use of these attributes is in describing the  
lifecycle

of system APIs.
In that context, one could see it being used to describe APIs withdrawn  
in, say,
a Posix standard (as implemented by a given system or according to  
specific

compile-time flags).


Just for the sake of clarity, to make sure we are both talking about
the same thing, the term POSIX uses for "withdrawn" when referring
to APIs is removed.  Withdrawn is a term that ISO tends to apply to
whole standards.  For example, ISO 9945:2003 AKA SUSv3 is a withdrawn
revision of POSIX (likewise, C99 and C11 are withdrawn revisions of
C).

With that, the APIs that have been removed in recent POSIX versions
would not be appropriately described by the attribute, either on
paper, in the POSIX spec (if the hypothetical case when the attribute
was specified the C standard), or in implementations.  The APIs simply
don't exist and so are open to use by programs (unless they are in
the reserved namespace), or by implementations as extensions.
The latter typically means that the APIs are defined (i.e., can
continue to be linked to by legacy applications) but not declared
in the system's header so they can be defined by programs.  Declaring
removed APIs with the unavailable attribute would prevent that and so
would not be conforming.

An example from C (not yet POSIX) is the gets() function that was
removed in C11 (it's still SUSv4).  It's only declared in 
when targeting older versions of C and C++.  Because in more recent
versions of the standards gets is not a reserved name it's valid
for programs to declare symbols named gets (of any kind).  So
declaring gets in  with attribute unavailable would be
nonconforming.

My point here is not necessarily to object to the idea behind
the attribute but to draw attention to the fact that it's not
suitable for standard APIs.


I understand (and have no disagreement with) that this is not a facility
that could be used as an enforcement of standard’s compliance.



However, imagine that you are a system integrator, and you have a
system which supports the API of SUSv3 and some of the additions of
later systems; let’s say you want to help your users avoid use of APIs
which would be unavailable on a SUSv3 system

You could mark up your implementation’s headers such that when presented
with some compile flags, it made the toolchain emit an error if the user
attempted to use APIs that are not present in SUSv3.

This is not actually a completely inane goal - despite that SUSv3 is  
retired -

in reality (AFAICS) there is only one system that’s qualified to UNIX7.


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.
In the case of Darwin, the compilers are capable of targeting multiple  
versions
of the system (one doesn’t need a separate GCC or clang to target each  
version,
ther

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

[Iain Sandoe]

Hi Martin,

Martin Sebor  wrote:


On 11/29/20 6:56 PM, Iain Sandoe wrote:



Martin Sebor via Gcc-patches  wrote:

On 11/10/20 12:38 PM, Iain Sandoe wrote:

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

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.

coming at things from the standards perspective .. perhaps.
.. however, in the first set of cases above, one never needs to indicate
  unavailability  since the entity never becomes unavailable, it changes
  meaning.
In practice, we don’t have markup of keywords etc. to indicate this (such
deprecation has been handled specifically in the FEs).
The practical (and actual) use of these attributes is in describing the  
lifecycle

of system APIs.
In that context, one could see it being used to describe APIs withdrawn  
in, say,
a Posix standard (as implemented by a given system or according to  
specific

compile-time flags).


Just for the sake of clarity, to make sure we are both talking about
the same thing, the term POSIX uses for "withdrawn" when referring
to APIs is removed.  Withdrawn is a term that ISO tends to apply to
whole standards.  For example, ISO 9945:2003 AKA SUSv3 is a withdrawn
revision of POSIX (likewise, C99 and C11 are withdrawn revisions of
C).

With that, the APIs that have been removed in recent POSIX versions
would not be appropriately described by the attribute, either on
paper, in the POSIX spec (if the hypothetical case when the attribute
was specified the C standard), or in implementations.  The APIs simply
don't exist and so are open to use by programs (unless they are in
the reserved namespace), or by implementations as extensions.
The latter typically means that the APIs are defined (i.e., can
continue to be linked to by legacy applications) but not declared
in the system's header so they can be defined by programs.  Declaring
removed APIs with the unavailable attribute would prevent that and so
would not be conforming.

An example from C (not yet POSIX) is the gets() function that was
removed in C11 (it's still SUSv4).  It's only declared in 
when targeting older versions of C and C++.  Because in more recent
versions of the standards gets is not a reserved name it's valid
for programs to declare symbols named gets (of any kind).  So
declaring gets in  with attribute unavailable would be
nonconforming.

My point here is not necessarily to object to the idea behind
the attribute but to draw attention to the fact that it's not
suitable for standard APIs.


I understand (and have no disagreement with) that this is not a facility
that could be used as an enforcement of standard’s compliance.



However, imagine that you are a system integrator, and you have a
system which supports the API of SUSv3 and some of the additions of
later systems; let’s say you want to help your users avoid use of APIs
which would be unavailable on a SUSv3 system

You could mark up your implementation’s headers such that when presented
with some compile flags, it made the toolchain emit an error if the user
attempted to use APIs that are not present in SUSv3.

This is not actually a completely inane goal - despite that SUSv3 is  
retired -

in reality (AFAICS) there is only one system that’s qualified to UNIX7.


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.
In the case of Darwin, the compilers are capable of targeting multiple  
versions
of the system (one doesn’t need a separate GCC or clang to target each  
version,
there is a -mmacosx-version-min= flag that allows the target version to  
be specified

on the command line).
Rather than install many versions of headers (and libraries) for all the  
system
versions, the designers elected to have one copy with markup that  
describes the

availability of APIs.
the lifecycle is typically:
introduced from version P.Q (ergo, unavailable before that)
perhaps deprecated at version R.S (ergo the user should be warned)
withdrawn at version X.Y (and unavailable thereafter).
The headers contain mac

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

[Martin Sebor via Gcc-patches]

On 11/29/20 6:56 PM, Iain Sandoe wrote:

Hi Martin,

Martin Sebor via Gcc-patches  wrote:


On 11/10/20 12:38 PM, Iain Sandoe wrote:



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



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.


coming at things from the standards perspective .. perhaps.

.. however, in the first set of cases above, one never needs to indicate
   unavailability  since the entity never becomes unavailable, it changes
   meaning.

In practice, we don’t have markup of keywords etc. to indicate this (such
deprecation has been handled specifically in the FEs).

The practical (and actual) use of these attributes is in describing the 
lifecycle

of system APIs.

In that context, one could see it being used to describe APIs withdrawn 
in, say,

a Posix standard (as implemented by a given system or according to specific
compile-time flags).


Just for the sake of clarity, to make sure we are both talking about
the same thing, the term POSIX uses for "withdrawn" when referring
to APIs is removed.  Withdrawn is a term that ISO tends to apply to
whole standards.  For example, ISO 9945:2003 AKA SUSv3 is a withdrawn
revision of POSIX (likewise, C99 and C11 are withdrawn revisions of
C).

With that, the APIs that have been removed in recent POSIX versions
would not be appropriately described by the attribute, either on
paper, in the POSIX spec (if the hypothetical case when the attribute
was specified the C standard), or in implementations.  The APIs simply
don't exist and so are open to use by programs (unless they are in
the reserved namespace), or by implementations as extensions.
The latter typically means that the APIs are defined (i.e., can
continue to be linked to by legacy applications) but not declared
in the system's header so they can be defined by programs.  Declaring
removed APIs with the unavailable attribute would prevent that and so
would not be conforming.

An example from C (not yet POSIX) is the gets() function that was
removed in C11 (it's still SUSv4).  It's only declared in 
when targeting older versions of C and C++.  Because in more recent
versions of the standards gets is not a reserved name it's valid
for programs to declare symbols named gets (of any kind).  So
declaring gets in  with attribute unavailable would be
nonconforming.

My point here is not necessarily to object to the idea behind
the attribute but to draw attention to the fact that it's not
suitable for standard APIs.


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.


In the case of Darwin, the compilers are capable of targeting multiple 
versions
of the system (one doesn’t need a separate GCC or clang to target each 
version,
there is a -mmacosx-version-min= flag that allows the target version to 
be specified

on the command line).

Rather than install many versions of headers (and libraries) for all the 
system
versions, the designers elected to have one copy with markup that 
describes the

availability of APIs.

the lifecycle is typically:

introduced from version P.Q (ergo, unavailable before that)
perhaps deprecated at version R.S (ergo the user should be warned)
withdrawn at version X.Y (and unavailable thereafter).

The headers contain macros that are expanded according to the version
for which the code is being compiled - to produce deprecation warnings or
unavailability errors if such APIs are *used* in the code.


I see.  That seems like a Darwin-specific use case, or one that may
be suitable for proprietary APIs not covered by the three language
standards (C, C++, or POSIX) where the attribute could only be used
this way as a non-conforming extension.  I suppose it might also be
applicable in the case of Linux distributions whose vendors support
multiple versions simultaneously, although I haven't come across
this use case.



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 

Re: PING^1 Re: [PATCH v2] C-family : Add attribute 'unavailable'.

[Nathan Sidwell]

On 11/27/20 3:49 PM, Iain Sandoe wrote:

Hi

I believe this version addressed Joseph’s and Richard’s comment, but it
C++ review.


ok.  Found a doc nit though ...



+@item unavailable
+@itemx unavailable (@var{msg})
+@cindex @code{unavailable} function attribute
+The @code{deprecated} attribute results in an error if the function
...^^  unavailable


--
Nathan Sidwell

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

[Iain Sandoe]

Hi Martin,

Martin Sebor via Gcc-patches  wrote:


On 11/10/20 12:38 PM, Iain Sandoe wrote:



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



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.


coming at things from the standards perspective .. perhaps.

.. however, in the first set of cases above, one never needs to indicate
  unavailability  since the entity never becomes unavailable, it changes
  meaning.

In practice, we don’t have markup of keywords etc. to indicate this (such
deprecation has been handled specifically in the FEs).

The practical (and actual) use of these attributes is in describing the  
lifecycle

of system APIs.

In that context, one could see it being used to describe APIs withdrawn in,  
say,

a Posix standard (as implemented by a given system or according to specific
compile-time flags).


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.


In the case of Darwin, the compilers are capable of targeting multiple  
versions
of the system (one doesn’t need a separate GCC or clang to target each  
version,
there is a -mmacosx-version-min= flag that allows the target version to be  
specified

on the command line).

Rather than install many versions of headers (and libraries) for all the  
system
versions, the designers elected to have one copy with markup that describes  
the

availability of APIs.

the lifecycle is typically:

introduced from version P.Q (ergo, unavailable before that)
perhaps deprecated at version R.S (ergo the user should be warned)
withdrawn at version X.Y (and unavailable thereafter).

The headers contain macros that are expanded according to the version
for which the code is being compiled - to produce deprecation warnings or
unavailability errors if such APIs are *used* in the code.

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


Hopefully, the description above clarifies the intent.

It is possible, even likely, that the implementations in clang have  
additional

capabilities above those implemented in this first cut - and perhaps we might
adopt some of those in follow-on work.

however the immediate use-case is the hundreds of instances where APIs
are marked up in the manner I’ve outlined above.


+@cindex @code{unavailable} function attribute
+The @code{deprecated} attribute results in an error if the function

^^

This should presumably read unavailable.


yes, good catch


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


The intent is to match the behaviour of clang sufficiently closely that GCC  
can

make more effective use of the system headers on Darwin platforms (and, of
course, allow for the same kind of life cycle markup on other platforms).


Like attribute

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

[Martin Sebor via Gcc-patches]

On 11/10/20 12:38 PM, Iain Sandoe wrote:

Hi Jospeh,

Joseph Myers  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));
i

PING^1 Re: [PATCH v2] C-family : Add attribute 'unavailable'.

[Iain Sandoe]

Hi

I believe this version addressed Joseph’s and Richard’s comment, but it
C++ review.

thanks
Iain



Iain Sandoe  wrote:


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

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.

gcc/c-family/ChangeLog:

* c-attribs.c (handle_unavailable_attribute): New.

gcc/c/ChangeLog:

* c-decl.c (enum deprecated_states): Add unavailable state.
(merge_decls): Copy unavailability.
(quals_from_declspecs): Handle unavailable case.
(start_decl): Amend the logic handling suppression of nested
deprecation states to include unavailability.
(smallest_type_quals_location): Amend comment.
(grokdeclarator): Handle the unavailable deprecation state.
(declspecs_add_type): Set TREE_UNAVAILABLE from the decl specs.
* c-tree.h (struct c_declspecs): Add unavailable_p.
* c-typeck.c (build_component_ref): Handle unavailability.
(build_external_ref): Likewise.

gcc/cp/ChangeLog:

* call.c (build_over_call): Handle unavailable state in addition to
deprecation.
* class.c (type_build_ctor_call): Likewise.
(type_build_dtor_call): Likewise.
* cp-tree.h: Rename cp_warn_deprecated_use to
cp_handle_deprecated_or_unavailable.
* decl.c (duplicate_decls): Merge unavailability.
(grokdeclarator): Handle unavailability in addition to deprecation.
(type_is_unavailable): New.
(grokparms): Handle unavailability in addition to deprecation.
* decl.h (enum deprecated_states): Add
UNAVAILABLE_DEPRECATED_SUPPRESS.
* decl2.c (cplus_decl_attributes): Propagate unavailability to
templates.
(cp_warn_deprecated_use): Rename to ...
(cp_handle_deprecated_or_unavailable): ... this and amend to handle
the unavailable case. It remains a warning in the case of deprecation
but becomes an error in the case of unavailability.
(cp_warn_deprecated_use_scopes): Handle unavailability.
(mark_used): Likewise.
* parser.c (cp_parser_template_name): Likewise.
(cp_parser_template_argument): Likewise.
(cp_parser_parameter_declaration_list): Likewise.
* typeck.c (build_class_member_access_expr): Likewise.
(finish_class_member_access_expr): Likewise.
* typeck2.c (build_functional_cast_1): Likewise.

gcc/ChangeLog:

* doc/extend.texi: Document unavailable attribute.
* print-tree.c (print_node): Handle unavailable attribute.
* tree-core.h (struct tree_base): Add a bit to carry unavailability.
* tree.c (error_unavailable_use): New.
* tree.h (TREE_UNAVAILABLE): New.
(error_unavailable_use): New.

gcc/objc/ChangeLog:

* objc-act.c (objc_add_property_declaration): Register unavailable
attribute.
(maybe_make_artificial_property_decl): Set available.
(objc_maybe_build_component_ref): Generalise to the method prototype
to count availability.
(objc_build_class_component_ref): Likewise.
(build_private_template): Likewise.
(objc_decl_method_attributes): Handle unavailable attribute.
(lookup_method_in_hash_lists): Amend comments.
(objc_finish_message_expr): Handle unavailability in addition to
deprecation.
(start_class): Likewise.
(finish_class): Likewise.
(lookup_protocol): Likewise.
(objc_declare_protocol): Likewise.
(start_protocol): Register unavailable attribute.
(really_start_method): Likewise.
(objc_gimplify_property_ref): Emit error on encountering an
unavailable entity (and a warning for a deprecated one).

gcc/testsuite/ChangeLog:

* g++.dg/ext/attr-unavailable-1.C: New test.
* g++.dg/ext/attr-unavailable-2.C: New test.
* g++.dg/ext/attr-unavailable-3.C: New test.
* g++.dg/ext/attr-unavailable-4.C: New test.
* g++.dg/ext/attr-unavailable-5.C: New test.
* g++.dg/ext/attr-unava

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

[Iain Sandoe]

Hi Jospeh,

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

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

gcc/c-family/ChangeLog:

* c-attribs.c (handle_unavailable_attribute): New.

gcc/c/ChangeLog:

* c-decl.c (enum deprecated_states): Add unavailable state.
(merge_decls): Copy unavailability.
(quals_from_declspecs): Handle unavailable case.
(start_decl): Amend the logic handling suppression of nested
deprecation states to include unavailability.
(smallest_type_quals_location): Amend comment.
(grokdeclarator): Handle the unavailable deprecation state.
(declspecs_add_type): Set TREE_UNAVAILABLE from the decl specs.
* c-tree.h (struct c_declspecs): Add unavailable_p.
* c-typeck.c (build_component_ref): Handle unavailability.
(build_external_ref): Likewise.

gcc/cp/ChangeLog:

* call.c (build_over_call): Handle unavailable state in addition to
deprecation.
* class.c (type_build_ctor_call): Likewise.
(type_build_dtor_call): Likewise.
* cp-tree.h: Rename cp_warn_deprecated_use to
cp_handle_deprecated_or_unavailable.
* decl.c (duplicate_decls): Merge unavailability.
(grokdeclarator): Handle unavailability in addition to deprecation.
(type_is_unavailable): New.
(grokparms): Handle unavailability in addition to deprecation.
* decl.h (enum deprecated_states): Add
UNAVAILABLE_DEPRECATED_SUPPRESS.
* decl2.c (cplus_decl_attributes): Propagate unavailability to
templates.
(cp_warn_deprecated_use): Rename to ...
(cp_handle_deprecated_or_unavailable): ... this and amend to handle
the unavailable case. It remains a warning in the case of deprecation
but becomes an error in the case of unavailability.
(cp_warn_deprecated_use_scopes): Handle unavailability.
(mark_used): Likewise.
* parser.c (cp_parser_template_name): Likewise.
(cp_parser_template_argument): Likewise.
(cp_parser_parameter_declaration_list): Likewise.
* typeck.c (build_class_member_access_expr): Likewise.
(finish_class_member_access_expr): Likewise.
* typeck2.c (build_functional_cast_1): Likewise.

gcc/ChangeLog:

* doc/extend.texi: Document unavailable attribute.
* print-tree.c (print_node): Handle unavailable attribute.
* tree-core.h (struct tree_base): Add a bit to carry unavailability.
* tree.c (error_unavailable_use): New.
* tree.h (TREE_UNAVAILABLE): New.
(error_unavailable_use): New.

gcc/objc/ChangeLog:

* objc-act.c (objc_add_property_declaration): Register unavailable
attribute.
(maybe_make_artificial_property_decl): Set available.
(objc_maybe_build_component_ref): Generalise to the method prototype
to count availability.
(objc_build_class_component_ref): Likewise.
(build_private_template): Likewise.
(objc_decl_method_attributes): Handle unavailable attribute.
(lookup_method_in_hash_lists): Amend comments.
(objc_finish_message_expr): Handle unavailability in addition to
deprecation.
(start_class): Likewise.
(finish_class): Likewise.
(lookup_protocol): Likewise.
(objc_declare_protocol): Likewise.
(start_protocol): Register unavailable attribute.
(really_start_method): Likewise.
(objc_gimplify_property_ref): Emit error on encountering an
unavailable entity (and a warning for a deprecated one).

gcc/testsuite/ChangeLog:

* g++.dg/ext/attr-unavailable-1.C: New test.
* g++.dg/ext/attr-unavailable-2.C: New test.
* g++.dg/ext/attr-unavailable-3.C: New test.
* g++.dg/ext/attr-unavailable-4.C: New test.
* g++.dg/ext/attr-unavailable-5.C: New test.
* g++.dg/ext/attr-unavailable-6.C: New test.
* g++.dg/ext/attr-unavailable-7.C: New test.
* g++.dg/ext/attr-unavailable-8.C: New tes