-/* Equivalent to write_stream_list_serial(), except this takes a @num_threads
- * parameter and will perform compression using that many threads. Falls
- * back to write_stream_list_serial() on certain errors, such as a failure to
- * create the number of threads requested.
- *
- * High level description of the algorithm for writing compressed streams in
- * parallel: We perform compression on chunks of size WIM_CHUNK_SIZE bytes
- * rather than on full files. The currently executing thread becomes the main
- * thread and is entirely in charge of reading the data to compress (which may
- * be in any location understood by the resource code--- such as in an external
- * file being captured, or in another WIM file from which an image is being
- * exported) and actually writing the compressed data to the output file.
- * Additional threads are "compressor threads" and all execute the
- * compressor_thread_proc, where they repeatedly retrieve buffers of data from
- * the main thread, compress them, and hand them back to the main thread.
- *
- * Certain streams, such as streams that do not need to be compressed (e.g.
- * input compression type same as output compression type) or streams of very
- * small size are placed in a list (main_writer_thread_ctx.serial_list) and
- * handled entirely by the main thread at an appropriate time.
- *
- * At any given point in time, multiple streams may be having chunks compressed
- * concurrently. The stream that the main thread is currently *reading* may be
- * later in the list that the stream that the main thread is currently
- * *writing*.
+/*
+ * Write a list of streams to the output WIM file.
+ *
+ * @stream_list
+ * The list of streams to write, specified by a list of `struct
+ * wim_lookup_table_entry's linked by the 'write_streams_list' member.
+ *
+ * @out_fd
+ * The file descriptor, opened for writing, to which to write the streams.
+ *
+ * @write_resource_flags
+ * Flags to modify how the streams are written:
+ *
+ * WRITE_RESOURCE_FLAG_RECOMPRESS:
+ * Force compression of all resources, even if they could otherwise
+ * be re-used by copying the raw data, due to being located in a WIM
+ * file with compatible compression parameters.
+ *
+ * WRITE_RESOURCE_FLAG_PIPABLE:
+ * Write the resources in the wimlib-specific pipable format, and
+ * furthermore do so in such a way that no seeking backwards in
+ * @out_fd will be performed (so it may be a pipe).
+ *
+ * WRITE_RESOURCE_FLAG_PACK_STREAMS:
+ * Pack all the streams into a single resource rather than writing
+ * them in separate resources. This flag is only valid if the WIM
+ * version number has been, or will be, set to
+ * WIM_VERSION_PACKED_STREAMS. This flag may not be combined with
+ * WRITE_RESOURCE_FLAG_PIPABLE.
+ *
+ * @out_ctype
+ * Compression format to use to write the output streams, specified as one
+ * of the WIMLIB_COMPRESSION_TYPE_* constants.
+ * WIMLIB_COMPRESSION_TYPE_NONE is allowed.
+ *
+ * @out_chunk_size
+ * Chunk size to use to write the streams. It must be a valid chunk size
+ * for the specified compression format @out_ctype, unless @out_ctype is
+ * WIMLIB_COMPRESSION_TYPE_NONE, in which case this parameter is ignored.
+ *
+ * @num_threads
+ * Number of threads to use to compress data. If 0, a default number of
+ * threads will be chosen. The number of threads still may be decreased
+ * from the specified value if insufficient memory is detected.
+ *
+ * @lookup_table
+ * If on-the-fly deduplication of unhashed streams is desired, this
+ * parameter must be pointer to the lookup table for the WIMStruct on whose
+ * behalf the streams are being written. Otherwise, this parameter can be
+ * NULL.
+ *
+ * @filter_ctx
+ * If on-the-fly deduplication of unhashed streams is desired, this
+ * parameter can be a pointer to a context for stream filtering used to
+ * detect whether the duplicate stream has been hard-filtered or not. If
+ * no streams are hard-filtered or no streams are unhashed, this parameter
+ * can be NULL.
+ *
+ * This function will write the streams in @stream_list to resources in
+ * consecutive positions in the output WIM file, or to a single packed resource
+ * if WRITE_RESOURCE_FLAG_PACK_STREAMS was specified in @write_resource_flags.
+ * In both cases, the @out_reshdr of the `struct wim_lookup_table_entry' for
+ * each stream written will be updated to specify its location, size, and flags
+ * in the output WIM. In the packed resource case,
+ * WIM_RESHDR_FLAG_PACKED_STREAMS will be set in the @flags field of each
+ * @out_reshdr, and furthermore @out_res_offset_in_wim and @out_res_size_in_wim
+ * of each @out_reshdr will be set to the offset and size, respectively, in the
+ * output WIM of the packed resource containing the corresponding stream.
+ *
+ * Each of the streams to write may be in any location supported by the
+ * resource-handling code (specifically, read_stream_list()), such as the
+ * contents of external file that has been logically added to the output WIM, or
+ * a stream in another WIM file that has been imported, or even a stream in the
+ * "same" WIM file of which a modified copy is being written. In the case that
+ * a stream is already in a WIM file and uses compatible compression parameters,
+ * by default this function will re-use the raw data instead of decompressing
+ * it, then recompressing it; however, with WRITE_RESOURCE_FLAG_RECOMPRESS
+ * specified in @write_resource_flags, this is not done.
+ *
+ * As a further requirement, this function requires that the
+ * @will_be_in_output_wim member be set to 1 on all streams in @stream_list as
+ * well as any other streams not in @stream_list that will be in the output WIM
+ * file, but set to 0 on any other streams in the output WIM's lookup table or
+ * sharing a packed resource with a stream in @stream_list. Still furthermore,
+ * if on-the-fly deduplication of streams is possible, then all streams in
+ * @stream_list must also be linked by @lookup_table_list along with any other
+ * streams that have @will_be_in_output_wim set.
+ *
+ * This function handles on-the-fly deduplication of streams for which SHA1
+ * message digests have not yet been calculated. Such streams may or may not
+ * need to be written. If @lookup_table is non-NULL, then each stream in
+ * @stream_list that has @unhashed set but not @unique_size set is checksummed
+ * immediately before it would otherwise be read for writing in order to
+ * determine if it is identical to another stream already being written or one
+ * that would be filtered out of the output WIM using stream_filtered() with the
+ * context @filter_ctx. Each such duplicate stream will be removed from
+ * @stream_list, its reference count transfered to the pre-existing duplicate
+ * stream, its memory freed, and will not be written. Alternatively, if a
+ * stream in @stream_list is a duplicate with any stream in @lookup_table that
+ * has not been marked for writing or would not be hard-filtered, it is freed
+ * and the pre-existing duplicate is written instead, taking ownership of the
+ * reference count and slot in the @lookup_table_list.
+ *
+ * Returns 0 if every stream was either written successfully or did not need to
+ * be written; otherwise returns a non-zero error code.