Document a policy regarding memory allocation

In C, the malloc function (and similar memory allocation functions) may 'fail' by returning a NULL pointer, or by some other means. Currently, CRoaring does not have a policy regarding failures in case of memory allocation.

We have some checks in place (bailing out from function when the malloc failed), but there is no testing to see what happens when memory allocations can fail. So it is entirely possible that there are bugs. I would hope that static analysis could reveal such bugs, but I am not sure how to go about it.

We recently add 64-bit roaring bitmaps to C and the implementation did not check for NULLs. I have proposed to add checks at https://github.com/RoaringBitmap/CRoaring/pull/633

How do we handle this?

That's not as clear cut as it seems. On many systems, malloc effectively always succeeds, and the failure comes when you try to access the memory. So checking for a NULL return is less useful than it seems. Furthermore, we specifically allow people to provide their own memory allocators.

The proposal currently is to document our policy (the policy of the CRoaring project). Of course, we first need to agree on the policy. Thus I am inviting comments from anyone who might use CRoaring.

To be clear, I am not looking for code changes (though these would fine) but rather on a policy or agreed-upon convention. Code changes could then be allowed or rejected based on this policy.

Calling on @alexey-milovidov @BenPope @xiaoyong-z @madscientist @SLieve and others...

Credit to @Oppen for pointing out the issue.

Review the current memory-allocation checks and the proposed changes in PR #633, including the newer 64-bit roaring bitmap implementation. Follow the discussion about NULL returns and custom allocators, then document the agreed CRoaring policy so future code changes can be evaluated against it.