stream filter: add "no more input" to the filters

[git.git] / convert.h

diff --git a/convert.h b/convert.h
index 17d75098328c65638c435d451564999db3cad281..d799a165b4731f2a44a44eaceffc588d1e9fcfc3 100644 (file)
--- a/convert.h
+++ b/convert.h
@@ -57,6 +57,13 @@ extern int is_null_stream_filter(struct stream_filter *);
  * Use as much input up to *isize_p and fill output up to *osize_p;
  * update isize_p and osize_p to indicate how much buffer space was
  * consumed and filled. Return 0 on success, non-zero on error.
+ *
+ * Some filters may need to buffer the input and look-ahead inside it
+ * to decide what to output, and they may consume more than zero bytes
+ * of input and still not produce any output. After feeding all the
+ * input, pass NULL as input and keep calling this function, to let
+ * such filters know there is no more input coming and it is time for
+ * them to produce the remaining output based on the buffered input.
  */
 extern int stream_filter(struct stream_filter *,
                         const char *input, size_t *isize_p,