Clarify what RUN_ONCE returns
authorRichard Levitte <levitte@openssl.org>
Thu, 12 Jan 2017 22:13:17 +0000 (23:13 +0100)
committerRichard Levitte <levitte@openssl.org>
Fri, 13 Jan 2017 12:10:21 +0000 (13:10 +0100)
RUN_ONCE really just returns 0 on failure or whatever the init
function returned.  By convention, however, the init function must
return 0 on failure and 1 on success.  This needed to be clarified.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2225)

include/internal/thread_once.h

index 74f6ccb..2242443 100644 (file)
  * RUN_ONCE - use CRYPTO_THREAD_run_once, and check if the init succeeded
  * @once: pointer to static object of type CRYPTO_ONCE
  * @init: function name that was previously given to DEFINE_RUN_ONCE,
- *        DEFINE_RUN_ONCE_STATIC or DECLARE_RUN_ONCE.
+ *        DEFINE_RUN_ONCE_STATIC or DECLARE_RUN_ONCE.  This function
+ *        must return 1 for success or 0 for failure.
  *
- * The return value is 1 on success or 0 in case of error.
+ * The return value is 1 on success (*) or 0 in case of error.
+ *
+ * (*) by convention, since the init function must return 1 on success.
  */
 #define RUN_ONCE(once, init)                                            \
     (CRYPTO_THREAD_run_once(once, init##_ossl_) ? init##_ossl_ret_ : 0)