Document setlocale() threadsafety issue

"Fixes" //github.com/harfbuzz/harfbuzz/issues/1191

src/hb-buffer.cc

@@ -1499,6 +1499,8 @@ hb_buffer_reverse_clusters (hb_buffer_t *buffer)
  * it will be set to the process's default language as returned by
  * hb_language_get_default().  This may change in the future by
  * taking buffer script into consideration when choosing a language.
+ * Note that hb_language_get_default() is NOT threadsafe the first time
+ * it is called.  See documentation for that function for details.
  *
  * Since: 0.9.7
  **/

src/hb-common.cc

@@ -361,7 +361,14 @@ hb_language_to_string (hb_language_t language)
 /**
  * hb_language_get_default:
  *
+ * Get default language from current locale.
  *
+ * Note that the first time this function is called, it calls
+ * "setlocale (LC_CTYPE, nullptr)" to fetch current locale.  The underlying
+ * setlocale function is, in many implementations, NOT threadsafe.  To avoid
+ * problems, call this function once before multiple threads can call it.
+ * This function is only used from hb_buffer_guess_segment_properties() by
+ * HarfBuzz itself.
  *
  * Return value: (transfer none):
  *