Add multithreading to API documentation and man page

include/FLAC/stream_encoder.h

@@ -1107,6 +1107,50 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order(FLAC__
  */
 FLAC_API FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order(FLAC__StreamEncoder *encoder, uint32_t value);
 
+/** Set the maximum number of threads to use during encoding.
+ *  Set to a value different than 1 to enable multithreaded encoding.
+ *
+ *  Note that enabling multithreading encoding (i.e., setting a value
+ *  different than 1) results in the behaviour of
+ *  FLAC__stream_encoder_finish(), FLAC__stream_encoder_process(),
+ *  FLAC__stream_encoder_process_interleaved() subtly changing.
+ *  For example, calling one of the process functions with enough
+ *  samples to fill a block might not always result in a call to
+ *  the write callback with a frame coding these samples. Instead,
+ *  blocks with samples are distributed among worker threads,
+ *  meaning that the first few calls to those functions will
+ *  return very quickly, while later calls might block if all
+ *  threads are occupied. Also, certain calls to the process
+ *  functions will results in several calls to the write callback,
+ *  while subsequent calls might again return very quickly with no
+ *  calls to the write callback.
+ *
+ *  Also, a call to FLAC__stream_encoder_finish() blocks while
+ *  waiting for all threads to finish, and therefore might take much
+ *  longer than when not multithreading and result in multiple calls
+ *  to the write callback.
+ *
+ *  Calls to the write callback are guaranteed to be in the correct
+ *  order.
+ *
+ *  Currently, passing a value of 0 is synonymous with a value of 1,
+ *  but this might change in the future.
+ *
+ * \default \c 1
+ * \param  encoder  An encoder instance to set.
+ * \param  value    See above.
+ * \assert
+ *    \code encoder != NULL \endcode
+ * \retval uint32_t
+ *    - \c FLAC__STREAM_ENCODER_SET_NUM_THREADS_OK if the number of threads was set correctly,
+ *    - \c FLAC__STREAM_ENCODER_SET_NUM_THREADS_NOT_COMPILED_WITH_MULTITHREADING_ENABLED when
+ *    multithreading was not enabled at compilation,
+ *    - \c FLAC__STREAM_ENCODER_SET_NUM_THREADS_ALREADY_INITIALIZED when the encoder was
+ *    already initialized,
+ *    - \c FLAC__STREAM_ENCODER_SET_NUM_THREADS_TOO_MANY_THREADS when
+ *    the number of threads was larger than the maximum allowed number of threads (currently
+ *    128).
+ */
 FLAC_API uint32_t FLAC__stream_encoder_set_num_threads(FLAC__StreamEncoder *encoder, uint32_t value);
 
 /** Deprecated.  Setting this value has no effect.
@@ -1442,6 +1486,14 @@ FLAC_API uint32_t FLAC__stream_encoder_get_min_residual_partition_order(const FL
  */
 FLAC_API uint32_t FLAC__stream_encoder_get_max_residual_partition_order(const FLAC__StreamEncoder *encoder);
 
+/** Get maximum number of threads setting.
+ *
+ * \param  encoder  An encoder instance to query.
+ * \assert
+ *    \code encoder != NULL \endcode
+ * \retval uint32_t
+ *    See FLAC__stream_encoder_set_num_threads().
+ */
 FLAC_API uint32_t FLAC__stream_encoder_get_num_threads(const FLAC__StreamEncoder *encoder);
 
 /** Get the Rice parameter search distance setting.

man/flac.md

@@ -355,6 +355,15 @@ the HTML documentation.
 	option in combination with custom encoding options meant for
 	archival.
 
+**-j** *\#***, \--threads=***\#*  
+:	Try to set a maximum number of threads to use for encoding. If
+	multithreading was not enabled on compilation or when setting a
+	number of threads that is too high, this fails with a warning. The
+	value of 0 is currently equal to 1 thread (i.e. no multithreading)
+	but may mean something else in the future. Currently the maximum
+	supported number of threads is 128. Using a value higher than the
+	number of available CPU threads harms performance.
+
 **\--replay-gain**
 :	Calculate ReplayGain values and store them as FLAC tags, similar to
 	vorbisgain. Title gains/peaks will be computed for each input file,