Implement DIP 1038: @mustuse

changelog/mustUse.dd

@@ -0,0 +1,9 @@
+Implement DIP 1038: @mustuse
+
+`@mustuse` is a new attribute that can be applied to a `struct` or `union` type
+to make ignoring an expression of that type into a compile-time error. It can
+be used to implement alternative error-handling mechanisms for code that cannot
+use exceptions, including `@nogc` and BetterC code.
+
+For more information, see
+$(LINK https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1038.md, DIP 1038).

src/build.d

@@ -1530,7 +1530,7 @@ auto sourceFiles()
             dinterpret.d dmacro.d dmangle.d dmodule.d doc.d dscope.d dstruct.d dsymbol.d dsymbolsem.d
             dtemplate.d dtoh.d dversion.d escape.d expression.d expressionsem.d func.d hdrgen.d impcnvtab.d
             imphint.d importc.d init.d initsem.d inline.d inlinecost.d intrange.d json.d lambdacomp.d
-            mtype.d nogc.d nspace.d ob.d objc.d opover.d optimize.d
+            mtype.d mustuse.d nogc.d nspace.d ob.d objc.d opover.d optimize.d
             parse.d parsetimevisitor.d permissivevisitor.d printast.d safe.d sapply.d
             semantic2.d semantic3.d sideeffect.d statement.d statement_rewrite_walker.d
             statementsem.d staticassert.d staticcond.d stmtstate.d target.d templateparamsem.d traits.d

src/dmd/README.md

@@ -130,6 +130,8 @@ Note that these groups have no strict meaning, the category assignments are a bi
 | [impcnvtab.d](https://github.com/dlang/dmd/blob/master/src/dmd/impcnvtab.d)   | Define an implicit conversion table for basic types                                        |
 | [importc.d](https://github.com/dlang/dmd/blob/master/src/dmd/importc.d)       | Helpers specific to ImportC                                                                |
 | [sideeffect.d](https://github.com/dlang/dmd/blob/master/src/dmd/sideeffect.d) | Extract side-effects of expressions for certain lowerings.                                 |
+| [mustuse.d](https://github.com/dlang/dmd/blob/master/src/dmd/mustuse.d)       | Helpers related to the `@mustuse` attribute                                                |
+
 
 **Compile Time Function Execution (CTFE)**
 

src/dmd/dsymbolsem.d

@@ -51,6 +51,7 @@ import dmd.init;
 import dmd.initsem;
 import dmd.hdrgen;
 import dmd.mtype;
+import dmd.mustuse;
 import dmd.nogc;
 import dmd.nspace;
 import dmd.objc;
@@ -2046,6 +2047,7 @@ private extern(C++) final class DsymbolSemanticVisitor : Visitor
 
         ed.semanticRun = PASS.semantic;
         UserAttributeDeclaration.checkGNUABITag(ed, sc.linkage);
+        checkMustUseReserved(ed);
 
         if (!ed.members && !ed.memtype) // enum ident;
         {
@@ -3056,6 +3058,7 @@ private extern(C++) final class DsymbolSemanticVisitor : Visitor
         funcdecl.visibility = sc.visibility;
         funcdecl.userAttribDecl = sc.userAttribDecl;
         UserAttributeDeclaration.checkGNUABITag(funcdecl, funcdecl.linkage);
+        checkMustUseReserved(funcdecl);
 
         if (!funcdecl.originalType)
             funcdecl.originalType = funcdecl.type.syntaxCopy();
@@ -4770,6 +4773,7 @@ private extern(C++) final class DsymbolSemanticVisitor : Visitor
         }
         cldec.semanticRun = PASS.semantic;
         UserAttributeDeclaration.checkGNUABITag(cldec, sc.linkage);
+        checkMustUseReserved(cldec);
 
         if (cldec.baseok < Baseok.done)
         {
@@ -5475,6 +5479,7 @@ private extern(C++) final class DsymbolSemanticVisitor : Visitor
                 idec.classKind = ClassKind.cpp;
             idec.cppnamespace = sc.namespace;
             UserAttributeDeclaration.checkGNUABITag(idec, sc.linkage);
+            checkMustUseReserved(idec);
 
             if (sc.linkage == LINK.objc)
                 objc.setObjc(idec);

src/dmd/expressionsem.d

@@ -56,6 +56,7 @@ import dmd.initsem;
 import dmd.inline;
 import dmd.intrange;
 import dmd.mtype;
+import dmd.mustuse;
 import dmd.nspace;
 import dmd.opover;
 import dmd.optimize;
@@ -8177,7 +8178,10 @@ private extern (C++) final class ExpressionSemanticVisitor : Visitor
             return;
 
         if (e.type is Type.tvoid)
+        {
+            checkMustUse(e.e1, sc);
             discardValue(e.e1);
+        }
         else if (!e.allowCommaExp && !e.isGenerated)
             e.error("Using the result of a comma expression is not allowed");
     }

src/dmd/frontend.h

@@ -8398,6 +8398,7 @@ struct Id final
     static Identifier* udaGNUAbiTag;
     static Identifier* udaSelector;
     static Identifier* udaOptional;
+    static Identifier* udaMustUse;
     static Identifier* TRUE;
     static Identifier* FALSE;
     static Identifier* dllimport;

src/dmd/id.d

@@ -491,6 +491,7 @@ immutable Msgtable[] msgtable =
     { "udaGNUAbiTag", "gnuAbiTag" },
     { "udaSelector", "selector" },
     { "udaOptional", "optional"},
+    { "udaMustUse", "mustuse" },
 
     // C names, for undefined identifier error messages
     { "NULL" },

src/dmd/mustuse.d

@@ -0,0 +1,247 @@
+/**
+ * Compile-time checks associated with the @mustuse attribute.
+ *
+ * Copyright: Copyright (C) 2022 by The D Language Foundation, All Rights Reserved
+ * License:   $(LINK2 https://www.boost.org/LICENSE_1_0.txt, Boost License 1.0)
+ * Source:    $(LINK2 https://github.com/dlang/dmd/blob/master/src/dmd/mustuse.d, _mustuse.d)
+ * Documentation:  https://dlang.org/phobos/dmd_mustuse.html
+ * Coverage:    https://codecov.io/gh/dlang/dmd/src/master/src/dmd/mustuse.d
+ */
+
+module dmd.mustuse;
+
+import dmd.dscope;
+import dmd.dsymbol;
+import dmd.expression;
+import dmd.globals;
+import dmd.identifier;
+
+// Used in isIncrementOrDecrement
+private static const StringExp plusPlus, minusMinus;
+
+// Loc.initial cannot be used in static initializers, so
+// these need a static constructor.
+static this()
+{
+    plusPlus = new StringExp(Loc.initial, "++");
+    minusMinus = new StringExp(Loc.initial, "--");
+}
+
+/**
+ * Check whether discarding an expression would violate the requirements of
+ * @mustuse. If so, emit an error.
+ *
+ * Params:
+ *   e = the expression to check
+ *   sc = scope in which `e` was semantically analyzed
+ *
+ * Returns: true on error, false on success.
+ */
+bool checkMustUse(Expression e, Scope* sc)
+{
+    import dmd.id : Id;
+
+    assert(e.type);
+    if (auto sym = e.type.toDsymbol(sc))
+    {
+        auto sd = sym.isStructDeclaration();
+        // isStructDeclaration returns non-null for both structs and unions
+        if (sd && hasMustUseAttribute(sd, sc) && !isAssignment(e) && !isIncrementOrDecrement(e))
+        {
+            e.error("ignored value of `@%s` type `%s`; prepend a `cast(void)` if intentional",
+                Id.udaMustUse.toChars(), e.type.toPrettyChars(true));
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Called from a symbol's semantic to check for reserved usage of @mustuse.
+ *
+ * If such usage is found, emits an errror.
+ *
+ * Params:
+ *   sym = symbol to check
+ */
+void checkMustUseReserved(Dsymbol sym)
+{
+    import dmd.errors : error;
+    import dmd.id : Id;
+
+    if (sym.userAttribDecl is null || sym.userAttribDecl.atts is null)
+        return;
+
+    // Can't use foreachUda (and by extension hasMustUseAttribute) while
+    // semantic analysis of `sym` is still in progress
+    // TODO: factor out common code from this function and checkGNUABITag
+    foreach (exp; *sym.userAttribDecl.atts)
+    {
+        if (isMustUseAttribute(exp))
+        {
+            if (sym.isFuncDeclaration())
+            {
+                error(sym.loc, "`@%s` on functions is reserved for future use",
+                    Id.udaMustUse.toChars());
+                sym.errors = true;
+            }
+            else if (sym.isClassDeclaration() || sym.isEnumDeclaration())
+            {
+                error(sym.loc, "`@%s` on `%s` types is reserved for future use",
+                    Id.udaMustUse.toChars(), sym.kind());
+                sym.errors = true;
+            }
+        }
+    }
+}
+
+/**
+ * Returns: true if the given expression is an assignment, either simple (a = b)
+ * or compound (a += b, etc).
+ */
+private bool isAssignment(Expression e)
+{
+    if (e.isAssignExp || e.isBinAssignExp)
+        return true;
+    if (auto ce = e.isCallExp())
+    {
+        if (auto fd = ce.f)
+        {
+            auto id = fd.ident;
+            if (id && isAssignmentOpId(id))
+                return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Returns: true if id is the identifier of an assignment operator overload.
+ */
+private bool isAssignmentOpId(Identifier id)
+{
+    import dmd.id : Id;
+
+    return id == Id.assign
+        || id == Id.addass
+        || id == Id.subass
+        || id == Id.mulass
+        || id == Id.divass
+        || id == Id.modass
+        || id == Id.andass
+        || id == Id.orass
+        || id == Id.xorass
+        || id == Id.shlass
+        || id == Id.shrass
+        || id == Id.ushrass
+        || id == Id.catass
+        || id == Id.indexass
+        || id == Id.slice
+        || id == Id.sliceass
+        || id == Id.opOpAssign
+        || id == Id.opIndexOpAssign
+        || id == Id.opSliceOpAssign
+        || id == Id.powass;
+}
+
+/**
+ * Returns: true if the given expression is an increment (++) or decrement (--).
+ */
+private bool isIncrementOrDecrement(Expression e)
+{
+    import dmd.dtemplate : isExpression;
+    import dmd.globals : Loc;
+    import dmd.id : Id;
+    import dmd.tokens : EXP;
+
+    if (e.op == EXP.plusPlus
+        || e.op == EXP.minusMinus
+        || e.op == EXP.prePlusPlus
+        || e.op == EXP.preMinusMinus)
+        return true;
+    if (auto call = e.isCallExp())
+    {
+        // Check for overloaded preincrement
+        // e.g., a.opUnary!"++"
+        if (auto fd = call.f)
+        {
+            if (fd.ident == Id.opUnary && fd.parent)
+            {
+                if (auto ti = fd.parent.isTemplateInstance())
+                {
+                    auto tiargs = ti.tiargs;
+                    if (tiargs && tiargs.length >= 1)
+                    {
+                        if (auto argExp = (*tiargs)[0].isExpression())
+                        {
+                            auto op = argExp.isStringExp();
+                            if (op && (op.compare(plusPlus) == 0 || op.compare(minusMinus) == 0))
+                                return true;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    else if (auto comma = e.isCommaExp())
+    {
+        // Check for overloaded postincrement
+        // e.g., (auto tmp = a, ++a, tmp)
+        if (comma.e1)
+        {
+            if (auto left = comma.e1.isCommaExp())
+            {
+                if (auto middle = left.e2)
+                {
+                    if (middle && isIncrementOrDecrement(middle))
+                        return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+
+/**
+ * Returns: true if the given symbol has the @mustuse attribute.
+ */
+private bool hasMustUseAttribute(Dsymbol sym, Scope* sc)
+{
+    import dmd.attrib : foreachUda;
+
+    bool result = false;
+
+    foreachUda(sym, sc, (Expression uda) {
+        if (isMustUseAttribute(uda))
+        {
+            result = true;
+            return 1; // break
+        }
+        return 0; // continue
+    });
+
+    return result;
+}
+
+/**
+ * Returns: true if the given expression is core.attribute.mustuse.
+ */
+private bool isMustUseAttribute(Expression e)
+{
+    import dmd.attrib : isCoreUda;
+    import dmd.id : Id;
+
+    // Logic based on dmd.objc.Supported.declaredAsOptionalCount
+    auto typeExp = e.isTypeExp;
+    if (!typeExp)
+        return false;
+
+    auto typeEnum = typeExp.type.isTypeEnum();
+    if (!typeEnum)
+        return false;
+
+    if (isCoreUda(typeEnum.sym, Id.udaMustUse))
+        return true;
+
+    return false;
+}

src/dmd/statementsem.d

@@ -51,6 +51,7 @@ import dmd.importc;
 import dmd.init;
 import dmd.intrange;
 import dmd.mtype;
+import dmd.mustuse;
 import dmd.nogc;
 import dmd.opover;
 import dmd.parse;
@@ -211,7 +212,8 @@ package (dmd) extern (C++) final class StatementSemanticVisitor : Visitor
             if (f.checkForwardRef(s.exp.loc))
                 s.exp = ErrorExp.get();
         }
-
+        if (checkMustUse(s.exp, sc))
+            s.exp = ErrorExp.get();
         if (!(sc.flags & SCOPE.Cfile) && discardValue(s.exp))
             s.exp = ErrorExp.get();
 

test/compilable/must_use_assign.d

@@ -0,0 +1,9 @@
+import core.attribute;
+
+@mustuse struct S {}
+
+void test()
+{
+    S a, b;
+    a = b;
+}

test/compilable/must_use_not_reserved.d

@@ -0,0 +1,5 @@
+import core.attribute;
+
+@mustuse int n;
+@mustuse alias A = int;
+@mustuse template tpl() {}