1*06f32e7eSjoerg================== 2*06f32e7eSjoergNullability Checks 3*06f32e7eSjoerg================== 4*06f32e7eSjoerg 5*06f32e7eSjoergThis document is a high level description of the nullablility checks. 6*06f32e7eSjoergThese checks intended to use the annotations that is described in this 7*06f32e7eSjoergRFC: http://lists.cs.uiuc.edu/pipermail/cfe-dev/2015-March/041798.html. 8*06f32e7eSjoerg 9*06f32e7eSjoergLet's consider the following 2 categories: 10*06f32e7eSjoerg 11*06f32e7eSjoerg**1) nullable** 12*06f32e7eSjoerg 13*06f32e7eSjoergIf a pointer ``p`` has a nullable annotation and no explicit null check or assert, we should warn in the following cases: 14*06f32e7eSjoerg 15*06f32e7eSjoerg* ``p`` gets implicitly converted into nonnull pointer, for example, we are passing it to a function that takes a nonnull parameter. 16*06f32e7eSjoerg* ``p`` gets dereferenced 17*06f32e7eSjoerg 18*06f32e7eSjoergTaking a branch on nullable pointers are the same like taking branch on null unspecified pointers. 19*06f32e7eSjoerg 20*06f32e7eSjoergExplicit cast from nullable to nonnul: 21*06f32e7eSjoerg 22*06f32e7eSjoerg.. code-block:: cpp 23*06f32e7eSjoerg 24*06f32e7eSjoerg __nullable id foo; 25*06f32e7eSjoerg id bar = foo; 26*06f32e7eSjoerg takesNonNull((_nonnull) bar); // should not warn here (backward compatibility hack) 27*06f32e7eSjoerg anotherTakesNonNull(bar); // would be great to warn here, but not necessary(*) 28*06f32e7eSjoerg 29*06f32e7eSjoergBecause bar corresponds to the same symbol all the time it is not easy to implement the checker that way the cast only suppress the first call but not the second. For this reason in the first implementation after a contradictory cast happens, I will treat bar as nullable unspecified, this way all of the warnings will be suppressed. Treating the symbol as nullable unspecified also has an advantage that in case the takesNonNull function body is being inlined, the will be no warning, when the symbol is dereferenced. In case I have time after the initial version I might spend additional time to try to find a more sophisticated solution, in which we would produce the second warning (*). 30*06f32e7eSjoerg 31*06f32e7eSjoerg**2) nonnull** 32*06f32e7eSjoerg 33*06f32e7eSjoerg* Dereferencing a nonnull, or sending message to it is ok. 34*06f32e7eSjoerg* Converting nonnull to nullable is Ok. 35*06f32e7eSjoerg* When there is an explicit cast from nonnull to nullable I will trust the cast (it is probable there for a reason, because this cast does not suppress any warnings or errors). 36*06f32e7eSjoerg* But what should we do about null checks?: 37*06f32e7eSjoerg 38*06f32e7eSjoerg.. code-block:: cpp 39*06f32e7eSjoerg 40*06f32e7eSjoerg __nonnull id takesNonnull(__nonnull id x) { 41*06f32e7eSjoerg if (x == nil) { 42*06f32e7eSjoerg // Defensive backward compatible code: 43*06f32e7eSjoerg .... 44*06f32e7eSjoerg return nil; // Should the analyzer cover this piece of code? Should we require the cast (__nonnull)nil? 45*06f32e7eSjoerg } 46*06f32e7eSjoerg .... 47*06f32e7eSjoerg } 48*06f32e7eSjoerg 49*06f32e7eSjoergThere are these directions: 50*06f32e7eSjoerg 51*06f32e7eSjoerg* We can either take the branch; this way the branch is analyzed 52*06f32e7eSjoerg* Should we not warn about any nullability issues in that branch? Probably not, it is ok to break the nullability postconditions when the nullability preconditions are violated. 53*06f32e7eSjoerg* We can assume that these pointers are not null and we lose coverage with the analyzer. (This can be implemented either in constraint solver or in the checker itself.) 54*06f32e7eSjoerg 55*06f32e7eSjoergOther Issues to keep in mind/take care of: 56*06f32e7eSjoerg 57*06f32e7eSjoerg* Messaging: 58*06f32e7eSjoerg 59*06f32e7eSjoerg * Sending a message to a nullable pointer 60*06f32e7eSjoerg 61*06f32e7eSjoerg * Even though the method might return a nonnull pointer, when it was sent to a nullable pointer the return type will be nullable. 62*06f32e7eSjoerg * The result is nullable unless the receiver is known to be non null. 63*06f32e7eSjoerg 64*06f32e7eSjoerg * Sending a message to a unspecified or nonnull pointer 65*06f32e7eSjoerg 66*06f32e7eSjoerg * If the pointer is not assumed to be nil, we should be optimistic and use the nullability implied by the method. 67*06f32e7eSjoerg 68*06f32e7eSjoerg * This will not happen automatically, since the AST will have null unspecified in this case. 69*06f32e7eSjoerg 70*06f32e7eSjoergInlining 71*06f32e7eSjoerg-------- 72*06f32e7eSjoerg 73*06f32e7eSjoergA symbol may need to be treated differently inside an inlined body. For example, consider these conversions from nonnull to nullable in presence of inlining: 74*06f32e7eSjoerg 75*06f32e7eSjoerg.. code-block:: cpp 76*06f32e7eSjoerg 77*06f32e7eSjoerg id obj = getNonnull(); 78*06f32e7eSjoerg takesNullable(obj); 79*06f32e7eSjoerg takesNonnull(obj); 80*06f32e7eSjoerg 81*06f32e7eSjoerg void takesNullable(nullable id obj) { 82*06f32e7eSjoerg obj->ivar // we should assume obj is nullable and warn here 83*06f32e7eSjoerg } 84*06f32e7eSjoerg 85*06f32e7eSjoergWith no special treatment, when the takesNullable is inlined the analyzer will not warn when the obj symbol is dereferenced. One solution for this is to reanalyze takesNullable as a top level function to get possible violations. The alternative method, deducing nullability information from the arguments after inlining is not robust enough (for example there might be more parameters with different nullability, but in the given path the two parameters might end up being the same symbol or there can be nested functions that take different view of the nullability of the same symbol). So the symbol will remain nonnull to avoid false positives but the functions that takes nullable parameters will be analyzed separately as well without inlining. 86*06f32e7eSjoerg 87*06f32e7eSjoergAnnotations on multi level pointers 88*06f32e7eSjoerg----------------------------------- 89*06f32e7eSjoerg 90*06f32e7eSjoergTracking multiple levels of annotations for pointers pointing to pointers would make the checker more complicated, because this way a vector of nullability qualifiers would be needed to be tracked for each symbol. This is not a big caveat, since once the top level pointer is dereferenced, the symvol for the inner pointer will have the nullability information. The lack of multi level annotation tracking only observable, when multiple levels of pointers are passed to a function which has a parameter with multiple levels of annotations. So for now the checker support the top level nullability qualifiers only.: 91*06f32e7eSjoerg 92*06f32e7eSjoerg.. code-block:: cpp 93*06f32e7eSjoerg 94*06f32e7eSjoerg int * __nonnull * __nullable p; 95*06f32e7eSjoerg int ** q = p; 96*06f32e7eSjoerg takesStarNullableStarNullable(q); 97*06f32e7eSjoerg 98*06f32e7eSjoergImplementation notes 99*06f32e7eSjoerg-------------------- 100*06f32e7eSjoerg 101*06f32e7eSjoergWhat to track? 102*06f32e7eSjoerg 103*06f32e7eSjoerg* The checker would track memory regions, and to each relevant region a qualifier information would be attached which is either nullable, nonnull or null unspecified (or contradicted to suppress warnings for a specific region). 104*06f32e7eSjoerg* On a branch, where a nullable pointer is known to be non null, the checker treat it as a same way as a pointer annotated as nonnull. 105*06f32e7eSjoerg* When there is an explicit cast from a null unspecified to either nonnull or nullable I will trust the cast. 106*06f32e7eSjoerg* Unannotated pointers are treated the same way as pointers annotated with nullability unspecified qualifier, unless the region is wrapped in ASSUME_NONNULL macros. 107*06f32e7eSjoerg* We might want to implement a callback for entry points to top level functions, where the pointer nullability assumptions would be made. 108