https://gcc.gnu.org/bugzilla/show_bug.cgi?id=87003
--- Comment #1 from David Malcolm <dmalcolm at gcc dot gnu.org> --- It would be good to make the header file be more self-documenting. In general, every pointer argument ought to be non-NULL, but a NULL will be checked for and gracefully rejected. The exception is gcc_jit_location *, which can always be NULL. libgccjit performs error-checking at the API boundary: there are many places where a NULL pointer argument will lead to a failure that puts the context into an "invalid" state, but such a failure will be handled gracefully without segfaulting: https://gcc.gnu.org/onlinedocs/jit/topics/contexts.html#error-handling This means that e.g. C code calling into the API doesn't need to check everywhere for NULL results before passing them back in as arguments to followup calls; it can just check once at the end of populating a context. (FWIW, I notice that the Rust bindings don't do error-handling yet: https://github.com/swgillespie/gccjit.rs#error-handling ) The docs for attribute "nonnull": https://gcc.gnu.org/onlinedocs/gcc-8.2.0/gcc/Common-Function-Attributes.html#Common-Function-Attributes say it: > "...causes the compiler to check that [...] arguments [...] are > non-null. If the compiler determines that a null pointer is passed > in an argument slot marked as non-null, and the -Wnonnull option is > enabled, a warning is issued. The compiler may also choose to make > optimizations based on the knowledge that certain function arguments > will never be null" That last sentence about optimizations makes me a little wary: it *is* possible for such arguments to be NULL (and my test cases make use of this to verify that the API does indeed gracefully handle these errors). But it does seem useful to mark all those arguments, and potentially warn for obvious "NULL in the wrong places" typos. Thoughts?
