ref and out parameters in C# and cannot be marked as variant
"out" means, roughly speaking, "only appears in output positions".
"in" means, roughly speaking, "only appears in input positions".
The real story is a bit more complicated than that, but the keywords were chosen because most of the time this is the case.
Consider a method of an interface or the method represented by a delegate:
delegate void Foo</*???*/ T>(ref T item);
Does T appear in an input position? Yes. The caller can pass a value of T in via item; the callee Foo can read that. Therefore T cannot be marked "out".
Does T appear in an output position? Yes. The callee can write a new value to item, which the caller can then read. Therefore T cannot be marked "in".
Therefore if T appears in a "ref" formal parameter, T cannot be marked as either in or out.
Let's look at some real examples of how things go wrong. Suppose this were legal:
delegate void X<out T>(ref T item);
...
X<Dog> x1 = (ref Dog d)=>{ d.Bark(); }
X<Animal> x2 = x1; // covariant;
Animal a = new Cat();
x2(ref a);
Well dog my cats, we just made a cat bark. "out" cannot be legal.
What about "in"?
delegate void X<in T>(ref T item);
...
X<Animal> x1 = (ref Animal a)=>{ a = new Cat(); }
X<Dog> x2 = x1; // contravariant;
Dog d = new Dog();
x2(ref d);
And we just put a cat in a variable that can only hold dogs. T cannot be marked "in" either.
What about an out parameter?
delegate void Foo</*???*/T>(out T item);
? Now T only appears in an output position. Should it be legal to make T marked as "out"?
Unfortunately no. "out" actually is not different than "ref" behind the scenes. The only difference between "out" and "ref" is that the compiler forbids reading from an out parameter before it is assigned by the callee, and that the compiler requires assignment before the callee returns normally. Someone who wrote an implementation of this interface in a .NET language other than C# would be able to read from the item before it was initialized, and therefore it could be used as an input. We therefore forbid marking T as "out" in this case. That's regrettable, but nothing we can do about it; we have to obey the type safety rules of the CLR.
Furthermore, the rule of "out" parameters is that they cannot be used for input before they are written to. There is no rule that they cannot be used for input after they are written to. Suppose we allowed
delegate void X<out T>(out T item);
class C
{
Animal a;
void M()
{
X<Dog> x1 = (out Dog d) =>
{
d = null;
N();
if (d != null)
d.Bark();
};
x<Animal> x2 = x1; // Suppose this were legal covariance.
x2(out this.a);
}
void N()
{
if (this.a == null)
this.a = new Cat();
}
}
Once more we have made a cat bark. We cannot allow T to be "out".
It is very foolish to use out parameters for input in this way, but legal.
UPDATE: C# 7 has added in as a formal parameter declaration, which means that we now have both in and out meaning two things; this is going to create some confusion. Let me clear that up:
-
in,outandrefon a formal parameter declaration in a parameter list means "this parameter is an alias to a variable supplied by the caller". -
refmeans "the callee may read or write the aliased variable, and it must be known to be assigned before the call. -
outmeans "the callee must write the aliased variable via the alias before it returns normally". It also means that the callee must not read the aliased variable via the alias before it writes it, because the variable might not be definitely assigned. -
inmeans "the callee may read the aliased variable but does not write to it via the alias". The purpose ofinis to solve a rare performance problem, whereby a large struct must be passed "by value" but it is expensive to do so. As an implementation detail,inparameters are typically passed via a pointer-sized value, which is faster than copying by value, but slower on the dereference. - From the CLR's perspective,
in,outandrefare all the same thing; the rules about who reads and writes what variables at what times, the CLR does not know or care. - Since it is the CLR that enforces rules about variance, rules that apply to
refalso apply toinandoutparameters.
In contrast, in and out on type parameter declarations mean "this type parameter must not be used in a covariant manner" and "this type parameter must not be used in a contravariant manner", respectively.
As noted above, we chose in and out for those modifiers because if we see IFoo<in T, out U> then T is used in "input" positions and U is used in "output" positions. Though that is not strictly true, it is true enough in the 99.9% use case that it is a helpful mnemonic.
It is unfortunate that interface IFoo<in T, out U> { void Foo(in T t, out U u); } is illegal because it looks like it ought to work. It cannot work because from the CLR verifier's perspective, those are both ref parameters and therefore read-write.
This is just one of those weird, unintended situations where two features that logically ought to work together do not work well together for implementation detail reasons.
It means you can't have the following declaration:
public delegate R MyDelegate<out R, in A>(ref A arg);
Edit: @Eric Lippert corrected me that this one is still legal:
public delegate void MyDelegate<R, in A>(A arg, out R s);
It actually makes sense, since the R generic parameter is not marked as a variant, so it doesn't violate the rule. However, this one is still illegal:
public delegate void MyDelegate<out R, in A>(A arg, out R s);
Eric Lippert has a great explanation of why this constraint exists.
If you are looking to work around this limitation. You can do it like this:
public static class ResultExtension{
public static bool TryGetValue<T>(this IResult<T> self, out T res) {
if (self.HasValue) {
res = self.Value;
return true;
}
res = default;
return false;
}
}
public interface IResult<out T>
{
bool HasValue { get; }
T Value { get; }
}
This works because there are two structures. One structure gets the covariance and the other gets the out parameter. The out parameter is not marked as variant so the compiler is happy.