Proposal: Null-conditional throw?

[bartdesmet]

Null-conditional throw?

Null-conditional throw? could be used to express contracts or argument validation logic in a concise manner.

Proposal

The throw? e statement is equivalent to

E t = e;
if ((object)t != null)
    throw t;

where t is a temporary variable to hold the result of evaluating the expression e, and E is the static type of e, which is subject to the same typing constraints as for the existing throw statement.

Example

An example of using throw? is shown below to check the inputs to a method:

static class Bar
{
    public static void Foo(string s, int i)
    {
        throw? Contract.NotNull(s);
        throw? Contract.Range(i, 0, s.Length);

        // ...
    }
}

static class Contract
{
    public static ArgumentNullException NotNull<T>(T argument, [CallerArgumentExpression("argument")]string paramName = null)
    {
        return argument == null ? new ArgumentNullException(paramName) : null;
    }

    public static ArgumentOutOfRangeException Range(int value, int minInclusive, int maxExclusive, [CallerArgumentExpression("value")]string paramName = null)
    {
        if (value < minInclusive)
            return new ArgumentOutOfRangeException(paramName, $"The value should be greater than or equal to {minInclusive}.");
        if (value >= maxExclusive)
            return new ArgumentOutOfRangeException(paramName, $"The value should be less than {maxExclusive}.");

        return null;
    }
}

This example leverages the proposal on CallerArgumentExpression to automatically supply the paramName argument.

Note that the Contract class is not part of this proposal and is solely included to show an example of such methods. Alternatives are possible, including static factory methods on existing exception types:

static class Bar
{
    public static void Foo(string s, int i)
    {
        throw? ArgumentNullException.IfNull(s);
        throw? ArgumentOutOfRangeException.IfNotInRange(i, 0, s.Length);

        // ...
    }
}

Benefits

Existing ways of expressing the example above suffer from a number of issues.

Conciseness

static class Bar
{
    public static void Foo(string s, int i)
    {
        if (s == null)
            throw new ArgumentNullException(nameof(s));
        if (i < 0)
            throw new ArgumentOutOfRangeException(nameof(i), "The value should be greater than or equal to 0.");
        if (i >= s.Length)
            throw new ArgumentOutOfRangeException(nameof(i), $"The value should be greater than or equal to {s.Length}.");

        // ...
    }
}

Combined with localization requirements, the code only gets bigger. To reduce the noise, people sometimes resort to more vague messages by combining predicates:

static class Bar
{
    public static void Foo(string s, int i)
    {
        if (s == null)
            throw new ArgumentNullException(nameof(s));
        if (i < 0 || i >= s.Length)
            throw new ArgumentOutOfRangeException(nameof(i), $"The value should be between 0 and {s.Length}.");

        // ...
    }
}

The throw expression support in C# 7.0 can help to reduce noise in select cases by combining throw with the ?? operator, e.g. for null checking while performing field initialization in constructors. This is a very narrow case.

Call stack preservation

To reduce the noise shown in the previous section, developers sometimes resort to introducing helper methods akin to our Contract class. However, they also make these methods throw:

static class Bar
{
    public static void Foo(string s, int i)
    {
        Contract.NotNull(s);
        Contract.Range(i, 0, s.Length);

        // ...
    }
}

static class Contract
{
    public static void NotNull<T>(T argument, [CallerArgumentExpression("argument")]string paramName = null)
    {
        if (argument == null)
            throw new ArgumentNullException(paramName);
    }

    public static void Range(int value, int minInclusive, int maxExclusive, [CallerArgumentExpression("value")]string paramName = null)
    {
        if (value < minInclusive)
            throw new ArgumentOutOfRangeException(paramName, $"The value should be greater than or equal to {minInclusive}.");
        if (value >= maxExclusive)
            throw new ArgumentOutOfRangeException(paramName, $"The value should be less than {maxExclusive}.");
    }
}

While this is more concise than throw?, it suffers from changing the exception stack trace because the exception is thrown from the helper methods:

System.ArgumentNullException: Value cannot be null.
Parameter name: s
   at Bar.NotNull(String s, String paramName)
   at Bar.Foo(String s, Int32 i)

This causes complexity when analyzing crashes, e.g. the use of immunitized stack frames in exception bucketization and crash analysis tools such as Watson.

Note that .NET Core has an internal StackTraceHidden attribute that was recently introduced (see this PR) to cut out such stack frames when calling StackTrace.ToString. This is effectively a technique to clean up stack traces for well-known helpers such as System.ThrowHelper (amongst other things). A weaker alternative to this proposal would be to make this attribute publicly available to annotate such exception-throwing helper methods.

The alternative is to return Exception objects from these helper methods in order to retain the original throw site. An example of this can be found in the expression tree API, e.g. in IndexExpression:

public static IndexExpression ArrayAccess(Expression array, IEnumerable<Expression> indexes)
{
    ExpressionUtils.RequiresCanRead(array, nameof(array));

    if (!array.Type.IsArray)
    {
        throw Error.ArgumentMustBeArray(nameof(array));
    }

    ...

The first method, RequiresCanRead suffers from changing the throw site of the exception. The second method, ArgumentMustBeArray is simply a constructor for an exception (hiding message localization logic), but fails to incorporate the check, which gets repeated in different places, making it hard to tweak and reuse (shy of introducing a bool-returning method to check for this condition).

One way to improve this code could be to use an out parameter and optionally use C# 7.0 out variables at the use site:

public static IndexExpression ArrayAccess(Expression array, IEnumerable<Expression> indexes)
{
    if (!ExpressionUtils.RequiresCanRead(array, nameof(array), out var ex1))
        throw ex1;

    if (!Error.ArgumentMustBeArray(array, nameof(array), out var ex2))
        throw ex2;

    ...

This way, the throw site is preserved and the helper methods incorporate the checks required. However, a lot of ceremony using a "Try" pattern with an out parameter is brought in.

A conditional throw? statement enables the creation of helper methods that perform checks and optionally construct exception instances, while retaining the original throw site in the call site. In the example shown above, the result would look like:

public static IndexExpression ArrayAccess(Expression array, IEnumerable<Expression> indexes)
{
    throw? ExpressionUtils.RequiresCanRead(array);
    throw? Error.ArgumentMustBeArray(array);

    ...

Besides conciseness and exception stack cleanliness, it also documents the possible control flow paths more clearly (e.g. it may not be obvious that RequiresCanRead may throw).

Performance

It is assumed that the performance impact of calling helper methods to perform validation and construct an exception instance is negligible and that these small Contract methods are eligible (or could be explicitly marked) for inlining.

Drawbacks

One drawback is the potential common pitfall of developers forgetting to use throw? when calling Contract-like methods, causing the returned Exception object to be discarded and never get thrown as intented.

This is more of a library issue which is especially relevant if users were accustomed to existing contract frameworks where such methods typically throw.

Note that this is a more general issue with the result of method calls (or object instantiation) getting discarded:

static void Main()
{
    var p = new Point();
    p.X; // Error, can't be just used for getter side-effects

    var d = new Dictionary<string, int>();
    d["bar"]; // Error, can't be just used for getter side-effects

    int x = 0;
    x++; // OK, only used for the mutation of x, not to obtain the original value

    new string('*', 8); // OK, only used for side-effects of the constructor

    new Thread(_ => { ... }); // OK, but didn't start the thread, as one may expect

    new Timer(...); // OK, but may have pitfalls that GC of the timer causes it to stop (should root)

    string s = "bar";
    string u = s.ToUpper();
    string.Intern(u); // OK, but silent discard of result
    s.ToLower(); // OK, but no useful side-effect other than a possible null-dereference

    Task.FromResult(42); // OK, but no useful side-effect
}

The last example is similar to the one we're dealing with here in the proposed throw? statement when used with Contract methods. To deal with such issues, an unrelated feature could be proposed to annotate a return type as not discard:

class String
{
    [return: NoDiscard]
    public static String Intern(String s) => ...;
}

static class Contract
{
    [return: NoDiscard]
    public static ArgumentNullException NotNull(...) => ...;
}

static class Bar
{
    public static void Foo(string s, int i)
    {
        string.Intern(s); // Warning: Don't discard result
        Contract.NotNull(s); // Warning: Don't discard result
    }
}

A warning would be generated if the result is not used, indicating a common mistake according to the API author. This is somewhat similar to the warning that results when lacking an await on an awaitable expression in the context of an async method, also indicating a common mistake. In all such cases, the user can still suppress the warning using the _ discard syntax or using a #pragma:

static class Bar
{
    public static void Foo(string s, int i)
    {
        // I know better, so I can suppress warnings
        _ = string.Intern(s);
        _ = Contract.NotNull(s);
    }

    public static async Task QuxAsync()
    {
        // Just like I can suppress await warnings
        _ = Task.Run(() => { ... });
    }
}

Given that first-class language support for discard was introduced using the _ syntax, the friction caused by false positive warnings is far less than it was before, requiring the introduction of made-up variable names or the use of #pragma directives.

Other methods that could benefit from such an annotation are Task.From* methods, many methods on string that return new string instances, methods on immutable types (e.g. Update on expression trees, collection editing methods on immutable collections), etc. all of which have no useful side-effect when being called other than for using the object that's returned.

Note that such a hypothetical feature could be implemented using an analyzer that either has a list of known members whose result should not be discarded, or uses a return attribute convention to detect such members. Such an analyzer could also be shipped in the NuGet packages with libraries that could benefit from such use site checks (though one would benefit from the analyzer logic being shared across such libraries, given that it only needs a list of members).

Being implementable using an analyzer, it doesn't require a language change unless a no discard modifier on members would be desirable in lieu of [return: NoDiscard] or another means to list a member as having a no-discard return value. Note that output parameters and possibly even tuple components could benefit from no-discard annotations. A no-discard annotation could also be applied at the type level, e.g. for IDisposable types, where one would at least expect the receiver of an instance to make an attempt at calling Dispose rather than dropping the instance.

Open questions

A conditional throw? expression

Is there a null-conditional throw? expression variant? It seems to have limited use, e.g. in the context of expression-bodied members:

class Bar : IFoo, IDisposable
{
    private bool _disposed;

    public void Foo() => throw? CheckDisposed;

    private ObjectDisposedException CheckDisposed => _disposed ? new ObjectDisposedException("this") : null;

    public void Dispose()
    {
        if (!_disposed)
        {
            _disposed = true;
            // ...
        }
    }
}

When used in a null coalescing operator, a throw? expression's result could either be to throw or to return a default value:

// Right-hand side of assignment evaluates to:
// - s1
// - throw ex if ex is not null
// - null if ex is null
string s2 = s1 ?? throw? ex;

When used in a conditional operator, a throw? expression's result could either be to throw or to return a default value. However, does it cause lifting to null?

// Right-hand side of assignment evaluates to:
// - 42 if b is true
// - throw ex if b is false and ex is not null
// - 0 if b is false and ex is null
int option1 = b ? 42 : throw? ex;

// Right-hand side of assignment evaluates to:
// - 42 if b is true
// - throw ex if b is false and ex is not null
// - null if b is false and ex is null
int? option2 = b ? 42 : throw? ex;

Nullable reference types

How does the feature interact with nullable reference types proposed for C# 8.0? In particular, does a throw? statement degenerate to a throw statement if the expression is known to be non-null?

static void Unreachable()
{
    // Does this trigger a warning suggesting to use throw instead?
    throw? Error;

    // Does this generate an unreachable code warning?
    Console.WriteLine();
}

// Error can never return null in C# 8.0.
static Exception Error => ...

This question even applies without considering nullable reference types, when the expression of a throw? statement is known to be non-null.

static void Unreachable()
{
    // Does this trigger a warning suggesting to use throw instead?
    throw? new Exception();

    // Does this generate an unreachable code warning?
    Console.WriteLine();
}

Conditional compilation

Is the following legal, and does it cause erasure of the entire throw? statement?

static void Bar()
{
    throw? Foo();
}

[Conditional("FALSE")]
static Exception Foo() => new Exception();

Note the declaration of Foo is not legal today, failing with the following error:

CS0578	The Conditional attribute is not valid on 'Foo()' because its return type is not void

This would be useful to deal with e.g. DEBUG-only exceptions (as discussed in the next section to express invariants), but it's not clear that it warrants any revisit of the ConditionalAttribute behavior (or partial methods which behave similarly), for example to return the default value of the return type in case the member is omitted (which would trigger a warning in C# 8.0 for non-nullable reference return types).

Contract APIs

Does this language feature warrant the introduction of common contract methods in the BCL? If so, what style would be preferred?

• Do nothing and leave it to users for now.
• Introduce a single static Contract class has the benefit of being usable with using static for further conciseness. However, it may cause coupling across BCL assembly boundaries.
• Add static factory methods to existing exception types, which clearly convey the type of the exception that could result. It's more verbose but lives in the exception type's assembly.
• Something else?

Where does this feature get positioned in relation to System.Diagnostics.Contracts which has limited use today, given the lack of analysis and rewriting tools?

Is the feature's scope for typical pre-condition checks sufficiently large to warrant its introduction or should another attempt be made at expressing contracts (pre- and post-conditions, invariants, etc.) in lieu of this feature?

Note that throw? statements are also usable for expressing invariants, possibly combined with local functions, as shown below.

static int Max(int[] xs)
{
    throw? NotNull(xs);
    throw? NotEmpty(xs);

    int max = xs[0];

    for (int i = 1; i < xs.Length; i++)
    {
        throw? LoopInvariant();

        if (xs[i] > max)
        {
            max = xs[i];
        }

        Exception LoopInvariant()
        {
            var found = false;

            for (var j = 0; j < i; j++)
            {
                if (xs[j] > max)
                {
                    return new Exception($"Already processed element at index {j} is larger than maximum value {max}.");
                }
                else if (xs[j] == max)
                {
                    found = true;
                }
            }

            if (!found)
            {
                return new Exception($"Maximum value {max} does not equal any of the elements in range 0..{i - 1}.");
            }

            return null;
        }
    }

    return max;
}

More sophistication could be used in the sample above to make the invariant check use Debug.Assert in DEBUG builds using a helper method:

static Exception Assert(bool condition, string message)
{
#if DEBUG
    Debug.Assert(condition, message);
#else
    if (!condition)
        return new Exception(message);
#endif

    return null;
}

This allows for a more concise expression of the loop with its invariants but has the drawback of always allocating error strings. The use of a similar Fail method prevents this:

static Exception Fail(string message)
{
#if DEBUG
    Debug.Fail(message);
    return null;
#else
    return new Exception(message);
#endif
}

With this, we can write:

static int Max(int[] xs)
{
    throw? NotNull(xs);
    throw? NotEmpty(xs);

    int max = xs[0];

    for (int i = 1; i < xs.Length; i++)
    {
        throw? LoopInvariant();

        if (xs[i] > max)
        {
            max = xs[i];
        }

        Exception LoopInvariant()
        {
            var found = false;

            for (var j = 0; j < i; j++)
            {
                if (xs[j] > max)
                {
                    return Fail($"Already processed element at index {j} is larger than maximum value {max}.");
                }
                else if (xs[j] == max)
                {
                    found = true;
                }
            }

            if (!found)
            {
                return Fail($"Maximum value {max} does not equal any of the elements in range 0..{i - 1}.");
            }

            return null;
        }
    }

    return max;
}

In DEBUG builds, the loop would continue after an assert failure (because null is returned from Fail and LoopInvariant), while in RELEASE builds, a runtime exception would occur on the first line of the loop body. If the invariant is only to be checked at development time, it would ideally be conditionally compiled (as discussed in the previous section):

static int Max(int[] xs)
{
    throw? NotNull(xs);
    throw? NotEmpty(xs);

    int max = xs[0];

    for (int i = 1; i < xs.Length; i++)
    {
        throw? LoopInvariant();

        if (xs[i] > max)
        {
            max = xs[i];
        }

        [Conditional("DEBUG")]
        Exception LoopInvariant()
        {
            ...
        }
    }

    return max;
}

An alternative would be to make it always return null in DEBUG builds and have some optimization that can effectively eliminate all the code related to the throw? statement (the local and the branch). There may be some synergy here with proposed C# 8.0 work, though it'd have to track "will always be null" rather than "may be null, or, will never be null" in an inter-procedural manner.

static int Max(int[] xs)
{
    throw? NotNull(xs);
    throw? NotEmpty(xs);

    int max = xs[0];

    for (int i = 1; i < xs.Length; i++)
    {
        throw? LoopInvariant();

        if (xs[i] > max)
        {
            max = xs[i];
        }

        Exception LoopInvariant()
#if DEBUG
            => null;
#else
        {
            ...
        }
#endif
    }

    return max;
}

Note that these examples of invariants merely represent a stretch goal for the proposed feature. With local functions returning void, performing checks and unconditionally throwing, and with a Conditional attribute applied, one can already achieve expressing invariants that only run in DEBUG builds (with the only drawback of moving the throw site to the helper method, which for a local function will have a mangled name).

Specification

In this section, the proposed edits to the C# language specification are shown.

Statements

This section is left unchanged, except for the sections edited below.

Jump statements

Jump statements unconditionally transfer control.

jump_statement
    : break_statement
    | continue_statement
    | goto_statement
    | return_statement
    | throw_statement
    | conditional_throw_statement
    ;

The remainder of this section is left unchanged.

The throw? statement

The throw? statement null-conditionally throws an exception.

conditional_throw_statement
    : 'throw' '?' expression ';'
    ;

A throw? statement with an expression throws the value produced by evaluating the expression if the evaluation of the expression does not produce null. The expression must denote a value of the class type System.Exception, of a class type that derives from System.Exception or of a type parameter type that has System.Exception (or a subclass thereof) as its effective base class. If evaluation of the expression produces null, control is transferred to the end point of the throw? statement.

Let E be the type of expression. A throw? statement of the form:

throw? e;

is then expanded to:

E t = e;
if ((object)t != null)
    throw t;

For additional information on exception propagation behavior, refer to the section describing the throw statement.

Exceptions

This section is left unchanged, except for the section edited below.

Causes of exceptions

Exceptions can be thrown in three different ways.

• A throw statement throws an exception immediately and unconditionally. Control never reaches the statement immediately following the throw.
• A throw? statement throws an exception immediately, if the expression denoting the exception evaluates to a non-null value.
• Certain exceptional conditions that arise during the processing of C# statements and expression cause an exception in certain circumstances when the operation cannot be completed normally. For example, an integer division operation throws a System.DivideByZeroException if the denominator is zero.

[bartdesmet]

Related discussions:

• Null-conditional await as another null-conditional language feature using the '?' syntactic variation.
• Method contracts for a discussion on full-blown method contracts ('requires' etc.), cf. the "Open questions" section in this proposal.

[yaakov-h]

If I can attack your core justification for a moment, regarding call stack preservation:

One alternative to passing up an exception and rethrowing, if you follow @benaadams' adventure, is to inline the call stack to the part that throws.

For example:

using System;
using System.Runtime.CompilerServices;
					
public class Program
{
	public static void Main()
	{
		Foo(null);
	}
	
	static void Foo(object o)
	{
		Requires.NotNull(o, nameof(o));
		
		Console.WriteLine(o.ToString());	
	}
		
}

public static class Requires
{	
	[MethodImpl(MethodImplOptions.AggressiveInlining)]
	public static void NotNull(object o, string name)
	{
		if (o == null) throw new ArgumentNullException(name);
	}
}

In Release configuration, this produces the following call stack:

Unhandled Exception: System.ArgumentNullException: Value cannot be null.
Parameter name: o
   at Program.Foo(Object o) in /private/tmp/thrower/Program.cs:line 13
   at Program.Main() in /private/tmp/thrower/Program.cs:line 9

Another alternative is to use ExceptionDispatchInfo, and use ?.Throw().

[benaadams]

I worry this would bake in deoptimizations.

Scoping-wise, anything to the rhs of throw is cold code; to the lhs is hot code.

Representing throw as a scope block; currently the pattern is:

throw 
{
    ExpensiveCreateException(); // new exception, message resource lookup etc
}

This changes it to

Exception ex = ExpensiveCreateException(); // new exception, message resource lookup etc
if (ex != null)
{
    throw 
    {
         ex;
    }
}

The throw itself and its scope is still moved to cold code, but the code to do with creating the exception; doing resource and string lookup is now inline and hot code?

/cc @AndyAyersMS

[benaadams]

If instead of

E t = e;
if ((object)t != null)
    throw t;

The compiler could rewrite

static class Bar
{
    public static void Foo(string s, int i)
    {
        throw? Contract.NotNull(s);
        throw? Contract.Range(i, 0, s.Length);

        // ...
    }
}

static class Contract
{
    public static ArgumentNullException NotNull<T>(T argument, [CallerArgumentExpression("argument")]string paramName = null)
    {
        return argument == null ? new ArgumentNullException(paramName) : null;
    }

    public static ArgumentOutOfRangeException Range(int value, int minInclusive, int maxExclusive, [CallerArgumentExpression("value")]string paramName = null)
    {
        if (value < minInclusive)
            return new ArgumentOutOfRangeException(paramName, $"The value should be greater than or equal to {minInclusive}.");
        if (value >= maxExclusive)
            return new ArgumentOutOfRangeException(paramName, $"The value should be less than {maxExclusive}.");

        return null;
    }
}

to push the construction the right of the throw:

static class Bar
{
    public static void Foo(string s, int i)
    {
        if (Contract.NotNull(s))
        {
            throw Contract.GetNotNullException(s);
        }
        
        if (Contract.Range(i, 0, s.Length))
        {
            throw Contract.GetRangeException(i, 0, s.Length);
        }

        // ...
    }
}

static class Contract
{
    public static bool NotNull<T>(T argument)
    {
        return argument == null ? true : false;
    }

    public static bool Range(int value, int minInclusive, int maxExclusive)
    {
        if (value < minInclusive)
            return true;
        if (value >= maxExclusive)
            return true;

        return false;
    }
    
    
    public static ArgumentNullException GetNotNullException<T>(T argument, [CallerArgumentExpression("argument")]string paramName = null)
    {
        return new ArgumentNullException(paramName);
    }

    public static ArgumentOutOfRangeException GetRangeException(int value, int minInclusive, int maxExclusive, [CallerArgumentExpression("value")]string paramName = null)
    {
        if (value < minInclusive)
            return new ArgumentOutOfRangeException(paramName, $"The value should be greater than or equal to {minInclusive}.");
            
        return new ArgumentOutOfRangeException(paramName, $"The value should be less than {maxExclusive}.");
    }
}

[benaadams]

Non-Returning methods are better than direct throws; other than the extra entry in call stack; as driect throws can push out the chance to inline (itself an überoptimization; which can lead to a cascade of other optimizations)

Slides 19-22 What's new for performance in .NET Core 2.0

Would be nice if the C# compiler could make use of this in some way; as the Jit doesn't split methods (non-crossgen/ngen/AoT)

/cc @mikedn