Permalink
Reply
Title: Optional Annotations for Memory Safety Categories
Proposal Short Description
Allow an optional AssignExpression (similar to deprecated) for @safe, @trusted, and @system code.
// Currently legal syntax
// Per function safety category
void func1() @safe{}
void func2() @trusted{}
void func3() @system{}
// Everything that follows has safety category applied
@trusted:
void func4(){}
// Everything within braces has safety category applied
@trusted{
void func5(){}
}
// Proposed syntax to also be legal
void func1() @safe("This needs to be safe as it's part of client interface"){}
void func2() @trusted("Code Reviewed by Mike Pull Request #1234567, and is trusted for reason XYZ"){}
void func3() @system("Need to make a system call..."){}
// For consistency, this *could* also be possible as part of the proposal
// Every function below gets the same annotation.
@trusted("Module full of my safe library interface and glue functions"):
void func4(){}
void func_4() @trusted("annotation here overrides top level annotation");
// Annotation, *could* be allowed here as part of proposal for consistency.
@safe("Functions part of library XYZ must all be safe"){
void func5(){}
void func_5() @trusted("annotation here overrides top level annotation");
}
- Part of this idea was born from this thread: https://forum.dlang.org/thread/v88gmi$1v6p$1@digitalmars.com?page=3
- This is an early proposal to gather feedback on if folks would find high value in adding this feature.
Background
The D programming language provides three categories of functions for memory safety: @safe @trusted, and @system. Currently these annotations are placed at the function level and enforce rules within the compiler for how code can be called from each annotated function. Currently functions marked with safe, trusted, and attribute can call following the graph below.
@safe <--> @safe <---> @trusted <--> @system <--> @system
- @safe code provides memory safety gaureentees, and enforces bounds checking (even in release mode). An @safe function can call only into other @safe code, or @trusted code with a @safe interface.
- @trusted code is the 'bridge' between calling @safe and @system code (and otherwise can call other @trusted code). @trusted code otherwise can do anything @system code can (though the interface must be @safe -- see https://dlang.org/spec/function.html#trusted-functions).
- @system code can do anything, and is the current default. @safe code cannot call @system code.
Currently the default for functions in the language is @system. @system code allows operations to be performed that may otherwise cause memory corruption. @trusted code has the capabilities of @system functions, but we require that the function has an @safe interface.
Motivation
The primary motivation for this proposal is to annotate @trusted, @safe, and @system code at the site of the safety category designation. '@trusted' (as an example) annotation is reliant on a programmers verification or code review of the function. The why a function is @trusted however may or may not be documented. Code comments or documentation that otherwise exists (e.g. a pull request) and are not directly on the '@trusted' site may be more likely to grow 'stale'(authors personal anecdote).
@trusted is the particularly interesting to be annotated because it is the bridge between @safe and @system code. The temptation to make code @trusted in order to 'get things to work' should be documented. Observe below.
void func2() @trusted("made @trusted so that code works with @safe code... will update to @safe later");
The idea above is that with the AssignExpression (shown within the quotes above), the documentation is tightly coupled with the important annotation. Tooling may benefit otherwise from being able to directly extract out these annotations for "TODO" or other important notes in these annotations. Source control and the ability to see how these annotations 'change' over time could also provide value to developers for 'why' an interface became trusted/safe/system over time.
Adding an AssignExpression is also interested for @system and @safe and should be considered for consitency. As demonstrated below,
void libraryFunc1() @system("The @safe interface is in progress")
The motivation thus is to ensure memory safety annotations can be cleanly documented at the location of the attribute.
Other Notes
While @safe can be inferred and @system otherwise is the default, it may be of greater importance to have annotations available for @trusted. https://dlang.org/spec/memory-safe-d.html#usage.
- Since Inference can detect @safe, it may be of use to have @safe("Compiler inferred") labeled annotations which could be useful to delineate between compiler generated attributes and explicitly user marked @safe code.
- Otherwise, no change is needed.
- Lack of providing a reason at the cite of a trusted/system/safe function could signal 'in-progress' or 'buggy' code when debugging. Thus documented safety categories may further provide confidence in code correctness.
Breakage to language
- No known/expected breakage to current code, as this is an extension.
- Note under pitfalls difference between getFunctionAttributes and getAttributes however, where I show how with UDA's we could get a useful string of information by a function.
Consistency
- The deprecated attribute currently allows for an AssignExpression as a string literal or manifest constant to provide additional information as to why the deprecation message. https://dlang.org/spec/attribute.html#deprecated
- assert and static_assert also optionally allow an argument list following the initial boolean expression for annotating useful information about expected behavior.
Potential Pitfalls/Discussion
- Adding additional strings to safety attributes will take time to parse and store during compilation in the case of errors during compilation.
- It is possible to use User Defined Attributes (UDAs) to otherwise implement this functionality. The proposed extension to syntax however is again to avoid having many UDAs attached to serve purely as annotations which could be forgotten by programmers. It appears 'getFunctionAttributes' and 'getAttributes' otherwise both return AliasSeq.
// Demonstration of the proposed feature
import std.stdio;
// ----------- Current ----------
void func2() @trusted{
writeln("Do something");
}
// ----------- Possible ---------
// Using UDA's we can do something
// similar to the proposal.
struct trustmore{string x;}
void func() @trusted @trustmore("specific reason for @trusted"){
writeln("Do something");
}
/* ---------- Proposed ----------
void func3() @trusted("reason"){
writeln("Do something");
}
*/
void main(){
// pragma(msg, __traits(getAttributes, func2));
pragma(msg, __traits(getFunctionAttributes, func2));
pragma(msg, __traits(getAttributes, func));
pragma(msg, __traits(getFunctionAttributes, func));
}
// =================================================
// Output
//AliasSeq!("@trusted")
//AliasSeq!(trustmore("specific reason for @trusted"))
//AliasSeq!("@trusted")
// =================================================
-
mixins and templates could also combine multiple UDAs to add annotations. However, the proposed feature as part of the core language I speculate may be useful for tooling later on (e.g. with DMD as a library static analysis, or otherwise as part of error messaging). Being able to pull out the specific memory category (trusted/system/safe) rather than a collection of UDAs I suspect will be easier on the toolside.
-
Stylistically we may want to ask ourselves how adding annotations to the safety category would 'look' when reading/writing code. Below is an example with template constraints, a contract, and other attributes with the proposed feature. Below is a function otherwise to see what this looks like when combining other language features (other annotations, template constraint, and contract).
int func7(T)(T x) pure @nogc
@safe("adding some long documentation to provide value but this does require us to stylistically put safety category on a separate line so we can reasonably read someone elses code. Perhaps d-format can help here.")
if(is(T: int))
in{
assert(x > 5);
}
do {
return x;
}
- The last thought I'll give is whether this opens the floodgates for other attributes (e.g. @nogc, pure, etc.) for allowing annotations as well. I'd like us to focus on the specific use case here where I think there is good value in annotating @trusted per-function or block, which I think is most valuable *and main focus** of this proopsal. But if we accept to move forward with this proposal, as always, it may be worth considering if adding this feature would effect other features (for either improving consistency in the language, or otherwise if this adds too much complexity to the compiler).
Other language references
- The C++ 26 programming language has added `=delete("reason"); https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2573r2.html
