allowNullable?

[JakenVeina]

What on earth is the purpose of a throwaway params argument here?

/// <summary>Subscribes nullable reference callbacks with downstream exception protection from static-call syntax.</summary>
/// <param name="source">The source sequence.</param>
/// <param name="onNext">The action to invoke for each value.</param>
/// <param name="onError">The action to invoke for an error.</param>
/// <param name="allowNullable">Reserved for nullable overload resolution.</param>
/// <typeparam name="T">The non-nullable reference value type.</typeparam>
/// <returns>A disposable that cancels the subscription.</returns>
/// <exception cref="ArgumentNullException">A required argument is <see langword="null"/>.</exception>
[System.Runtime.CompilerServices.OverloadResolutionPriority(1)]
public static IDisposable SubscribeSafe<T>(
        IObservable<T?> source,
        Action<T> onNext,
        Action<Exception> onError,
        params bool[] allowNullable)
    where T : class

"Reserved for nullable overload resolution" doesn't really explain anything. This is not a pattern I've ever seen before.

[JungyuOO]

The short version is: it looks like a deliberate overload-resolution hack.

allowNullable does not appear to represent an actual runtime option. Its purpose is to make this overload have a different method signature while still allowing callers to invoke it with the same normal argument list.

The important part is that nullable reference annotations such as:

T

versus:

T?

are primarily compile-time nullability information. They do not give you two distinct CLR reference types that can simply be used to define otherwise identical overloads.

So if the library wants both a nullable-aware and a non-nullable form of something conceptually like:

SubscribeSafe(
    IObservable<T> source,
    Action<T> onNext,
    Action<Exception> onError)

and:

SubscribeSafe(
    IObservable<T?> source,
    Action<T> onNext,
    Action<Exception> onError)

it needs some other difference in the actual parameter list.

That seems to be what this is doing:

params bool[] allowNullable

Because it is a params array, the caller does not need to pass anything:

source.SubscribeSafe(onNext, onError);

but at the metadata/signature level the method now has an additional parameter, so the two overloads can coexist.

The name:

allowNullable

is therefore a bit misleading. It is not really an "allow nullable" switch that the implementation reads.

It is more like:

dummy parameter used to create a distinct nullable-aware overload

The other part of the mechanism is:

[OverloadResolutionPriority(1)]

which tells newer C# compilers to prefer this overload over otherwise competing overloads when resolving the call.

So I believe the intent is roughly:

1. T? expresses the desired nullable API contract to the compiler.
2. The extra params bool[] makes the actual overload signature distinct.
3. OverloadResolutionPriority(1) steers overload selection toward this nullable-aware overload.
4. The allowNullable value itself is never semantically consumed.

That is also why the documentation says:

Reserved for nullable overload resolution

rather than describing what values should be passed to it.

I agree that it is a pretty unusual pattern. I would probably have called the parameter something like nullableOverloadMarker (and hidden it from normal API documentation if possible), because allowNullable makes it sound like callers are expected to provide a boolean option, when in practice they should not pass anything at all.

So unless there is some other use of the array elsewhere in the implementation, I would read it purely as an overload-resolution/signature marker rather than an application-level parameter.

[JakenVeina]

Alright, that make sense. I think it definitely needs that extra documentation clarity.

However, now I'm left asking..... why? What is the significance of having this operator know whether OnNext notifications out of source can have a null value or not? The operator shouldn't be DOING anything with those values, it's just forwarding them on to the onNext parameter, with some exception-handling logic baked in.

Am I to assume that this operator null-checks those values, and DOESN'T pass them to onNext when they're null? That's what the signature would suggest, by the fact that onNext is Action<T>, and not Action<T?>. If that's the behavior, why isn't that documented? And if that's not the behavior... then this operator is defective! It allows the consumer to pass an Action<T>, and then will happily invoke the action with null, even if the consumer has nullability analysis enabled, and has defined the action to not allow for null parameter values. The whole overload is just an extremely roundabout way to disable null-reference analysis.

Primitives/src/Primitives.Shared/SignalOperatorParityMixins.RxNames.SubscribeSafe.cs

Line 67 in a48ca23

return SubscribeSafeCore(source, Witness.Create<T?>(value => onNext(value!), onError));

Why yes, that is in fact EXACTLY what this operator is doing. So, any consumer of this library that happens to make a nullability mistake when using this operator will just get to find out about it in production, instead of having the compiler do what it's supposed to and tell them at design time.

Is this some kind of obscure CLS or COM compatibility requirement?

[JungyuOO]

Thanks for digging into the implementation — I think your reading of it is correct.

I went back and checked both the code and the C# nullability rules, and I don't see any runtime null check in this overload.

The key line is:

return SubscribeSafeCore(
    source,
    Witness.Create<T?>(value => onNext(value!), onError));

The ! here is only the C# null-forgiving operator. It suppresses nullable analysis warnings, but it has no runtime effect.

So if value is actually null, this:

onNext(value!)

still passes null to onNext.

That means the concern you raised about the signature seems valid. The source is:

IObservable<T?>

while the callback is:

Action<T>

For nullable reference types, T and T? are not different CLR runtime types; the distinction is mainly for compiler analysis. So the compiler can treat the callback parameter as non-null while the implementation can still forward a runtime null by using !.

For example:

IObservable<string?> source = ...;

source.SubscribeSafe(
    value => Console.WriteLine(value.Length),
    ex => Console.WriteLine(ex));

The consumer gets no nullable warning for value.Length, but if the observable emits null, the current implementation appears able to invoke that callback with null anyway.

I also checked whether OverloadResolutionPriority points to some CLS or COM interoperability requirement, but I couldn't find evidence of that. Microsoft documents it as an overload-selection mechanism for library authors, not as a CLS/COM compatibility feature.

So my current reading is:

1. params bool[] makes the overload signature distinct.
2. OverloadResolutionPriority(1) influences overload selection.
3. value! suppresses the compiler warning.
4. There is no runtime guarantee here that the callback actually receives a non-null value.

What I can't determine from the implementation alone is why this overload intentionally uses Action<T> instead of Action<T?>.

There may be some historical API compatibility or parity reason, but I wouldn't want to guess without a design note or maintainer comment confirming it.

So I think your concern is reasonable: if forwarding null is intentional, the contract/documentation probably needs to say so explicitly. If the callback is intended to receive only non-null values, then this would seem to need an actual runtime null policy rather than only value!.

I may be missing some historical constraint here, so I'd be interested to hear if a maintainer can shed some light on the original intent.