How do we mark things as unstable?

[danakj]

We want to stabilize numerics, which come with Option. But not stabilize iterators and tuples yet which are found in the Option API.

We need to mark those methods as unstable somehow so they won't be used by accident?

• [[deprecated]]?
• A marker unstable_fn type?
• [[clang::annotate]]?

We also want to mark concepts (e.g. NeverValueField) or types (e.g. Iterator) as unstable.

[[clang::annotate("sus::unstable")]] seems like the most clear choice except it wouldn't do anything. We'd need to just say you can't use them, and we can write a clang-tidy pass that errors on their use?

The use of a clang-only attribute is unfortunate. Not sure how to address this in a cross-compiler way. This would be enough for some projects like Chromium.

[danakj]

Current plan is to put everything unstable into a sus_unstable namespace and then in all the lib headers do

namespace sus {
  using namespace ::sus_unstable;
}

I will need to stop using ::sus::foo and use sus::foo then.

This does nothing for methods, it can only apply to functions and types.

[danakj]

I think sus::unstable::* will be better than sus_unstable::*

Otherwise the unstable headers also have to do using namespace ::sus to get like usize and other things pushed up to sus accessible without qualification. That makes for some weird inconsistency as code moves from unstable to stable.

So we have for stable things:

namespace sus {
  using namespace unstable;
  ...
}

And for unstable things:

namespace sus::unstable {
}

This also allows us to nest an unstable thing inside a set of stable stuff at least at the namespace level without having to move it out below the end of the sus namespace defn.

We can't mark a method on a type as unstable still, unfortunately. We need a different plan for that.

[danakj]

GCC has an unavailable attribute which can be applied to functions, types, and variables.

https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html

Clang 17 now also produces an error if they are used.

https://blog.llvm.org/posts/2023-09-19-diagnostic-improvements-in-clang-17/

So we could #define SUS_USE_UNSTABLE within library headers to remove the unavailable marker from things that are marked with sus_unstable or something?

Would that remove it such that other code doesn't get an error either though?