Explain the \do_not_use\ source code annotation#226
Explain the \do_not_use\ source code annotation#226pmetras wants to merge 1 commit intoponylang:mainfrom
Conversation
ponylang-main
added
discuss during sync
SeanTAllen
added
the
discuss during sync
|
|
||
| # Motivation | ||
|
|
||
| Sometimes, implementing a trait or interface can only be done partially: some methods don't make sense. For example, in an infinite-precision integer class that implement `SignedInteger` trait, the methods `min_value` and `max_value` have no sense: there is no minimal or maximal values possible, because the trait contract applies only to fixed-width integers. But the `SignedInteger` trait features cover 95% of the infinite-precision implementation, and it isn't worth adding a new type like `SignedInfiniteInteger` to cover these cases. Reusing an existing type makes the class more useful to client programmers that can substitute it to existing types with limited changes in their code. |
There was a problem hiding this comment.
I personally don't find this to be a compelling motivation for this RFC.
It seems like a narrow use case for what would be a broad feature, and furthermore, I think this particular use case would be better solved by either creating a new trait (which has downsides as you mentioned, but is reasonable), or implementing the methods on the trait (as described in my other advice below).
|
|
||
| To continue with the infinite-precision integer example and the `SignedInteger` trait. Here are methods that must be annotated with `\do_not_use\`: | ||
|
|
||
| * `min_value`: There is no minimal value in an infinite integer, as we can't represent -∞ with `SignedInteger` trait. |
There was a problem hiding this comment.
Not related to this RFC's proposal, but to comment on what a reasonable approach would be for your specific use case:
The minimum value of an infinite signed integer would be negative infinity.
I would expect any infinite-precision integer class to be able to represent both positive and negative infinity - instances of the class that would always compare as greater or less than (respectively) every other value.
We have this for floating point values using a particular bit pattern, so I see no reason why an arbitrary-precision integer library couldn't include an inner flag which marks a value as infinite, and handle it appropriately throughout the implemented methods, including this one.
| To continue with the infinite-precision integer example and the `SignedInteger` trait. Here are methods that must be annotated with `\do_not_use\`: | ||
|
|
||
| * `min_value`: There is no minimal value in an infinite integer, as we can't represent -∞ with `SignedInteger` trait. | ||
| * `max_value`: Similarly, there is no maximal value and +∞ can't be represented as we can always create a new value greater than any existing instance. |
There was a problem hiding this comment.
Same as above, I'd expect an "infinite signed integer" library to be able to represent an infinite value.
| * `clz`: No way to count the number of leading `0` bits. Only valid for fixed-size integer representations. | ||
| * `clz_unsafe`: Idem. |
There was a problem hiding this comment.
If I called clz on a variable-width integer implementation, I'd expect the number of leading zero bits reported to be zero, since conceptually there are never any leading bits.
| * `rotl` and `rotr`: Rotating bits can't happen if the width of the integer representation is not fixed. | ||
| * `bit_reverse` and `bswap`: These methods could be implemented with an infinite-precision integer representation, but their meaning is not clear and results probably would surprise the user. |
There was a problem hiding this comment.
It's possible to implement rotation and reversal among the bits that exist in the particular variable-bit-width instance you're calling it on.
Again, I'd expect these both to treat the bit width as being the current bit width of the current value, with a mental model of having no leading zero bits, conceptually.
|
|
||
| # Detailed design | ||
|
|
||
| When the Pony compiler encounters a `\do_not_use\` annotation in the code, it emits a "Do not use" warning message at compilation time with information (source file, line number, method or other [contexts](https://tutorial.ponylang.io/appendices/annotations#what-can-be-annotated) where annotations can be used) where this information has been encountered. The programmer can see that her code uses features that must not be used because results are impredictable. |
There was a problem hiding this comment.
This doesn't give sufficient detail to describe what it means "that her code uses features". What does "use" mean here?
Need a pedantic level of detail on what cases would trigger a warning to judge the merits of an RFC like this.
|
|
||
| # Summary | ||
|
|
||
| Make the compiler emit a "Do not use!" warning when compiling code with the `\do_not_use\` annotation. |
There was a problem hiding this comment.
I think if we were to add this kind of advisory annotation we would also want to take a step back and consider the broader set of use cases (e.g. things like deprecated, and cases I'm not thinking of off the top of my head) rather than accept just this one annotation in the RFC - thinking of the bigger picture would inform a more coherent overall design and user experience.
4 participants
The
\do_not_use\Pony compiler annotation is used to output a warning at compilation-time to the developer that she is using a feature with unpredictable results. She should check the code...