gh-99108: Release the GIL around hashlib built-in computation (#104675)

This matches the GIL releasing behavior of our existing `_hashopenssl`
module, extending it to the HACL* built-ins.

Includes adding comments to better describe the ENTER/LEAVE macros
purpose and explain the lock strategy in both existing and new code.

1 files changed, 8 insertions, 1 deletions

diff --git a/Modules/hashlib.h b/Modules/hashlib.h
index 56ae7a5..a8bad9d 100644
--- a/Modules/hashlib.h
+++ b/Modules/hashlib.h
@@ -37,6 +37,13 @@
  * LEAVE_HASHLIB block or explicitly acquire and release the lock inside
  * a PY_BEGIN / END_ALLOW_THREADS block if they wish to release the GIL for
  * an operation.
+ *
+ * These only drop the GIL if the lock acquisition itself is likely to
+ * block. Thus the non-blocking acquire gating the GIL release for a
+ * blocking lock acquisition. The intent of these macros is to surround
+ * the assumed always "fast" operations that you aren't releasing the
+ * GIL around.  Otherwise use code similar to what you see in hash
+ * function update() methods.
  */
 
 #include "pythread.h"
@@ -53,7 +60,7 @@
         PyThread_release_lock((obj)->lock); \
     }
 
-/* TODO(gps): We should probably make this a module or EVPobject attribute
+/* TODO(gpshead): We should make this a module or class attribute
  * to allow the user to optimize based on the platform they're using. */
 #define HASHLIB_GIL_MINSIZE 2048