Add some warnings on how to use OPENSSL_memory_* functions.

Being called on every malloc or free has some non-trivial implications.

Change-Id: I9f18f307a8b43e30dea2e2f3a47d7da0b188e980
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/46406
Reviewed-by: Adam Langley <agl@google.com>

crypto/mem.c

diff --git a/crypto/mem.c b/crypto/mem.c
index 0491f15..7cb5f21 100644
--- a/crypto/mem.c
+++ b/crypto/mem.c
@@ -107,6 +107,20 @@
 // allocation and freeing. If defined, it is the responsibility of
 // |OPENSSL_memory_free| to zero out the memory before returning it to the
 // system. |OPENSSL_memory_free| will not be passed NULL pointers.
+//
+// WARNING: These functions are called on every allocation and free in
+// BoringSSL across the entire process. They may be called by any code in the
+// process which calls BoringSSL, including in process initializers and thread
+// destructors. When called, BoringSSL may hold pthreads locks. Any other code
+// in the process which, directly or indirectly, calls BoringSSL may be on the
+// call stack and may itself be using arbitrary synchronization primitives.
+//
+// As a result, these functions may not have the usual programming environment
+// available to most C or C++ code. In particular, they may not call into
+// BoringSSL, or any library which depends on BoringSSL. Any synchronization
+// primitives used must tolerate every other synchronization primitive linked
+// into the process, including pthreads locks. Failing to meet these constraints
+// may result in deadlocks, crashes, or memory corruption.
 WEAK_SYMBOL_FUNC(void*, OPENSSL_memory_alloc, (size_t size));
 WEAK_SYMBOL_FUNC(void, OPENSSL_memory_free, (void *ptr));
 WEAK_SYMBOL_FUNC(size_t, OPENSSL_memory_get_size, (void *ptr));