From b05d78b4a2f1d895fa76399c951ce9a645fb0ae4 Mon Sep 17 00:00:00 2001 From: Donovan Baarda Date: Tue, 14 Sep 2021 19:02:44 +1000 Subject: Update librsync.h docs about processing directly from large input buffers. This points out that large buffers can be processed directly and can leave a tail of data behind in the input buffer. Using large buffers avoids data copies and can be much faster. --- src/librsync.h | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/src/librsync.h b/src/librsync.h index 83fb27d..fec8fed 100644 --- a/src/librsync.h +++ b/src/librsync.h @@ -312,11 +312,17 @@ LIBRSYNC_EXPORT void rs_sumset_dump(rs_signature_t const *); * entry, and suitable to be passed in on a second call, but they don't * directly tell you how much output data was produced. * - * Note also that if *#avail_in is nonzero on return, then not all of the input - * data has been consumed. The caller should either provide more output buffer - * space and call ::rs_job_iter() again passing the same #next_in and - * #avail_in, or put the remaining input data into some persistent buffer and - * call rs_job_iter() with it again when there is more output space. + * If the input buffer was large enough, it will be processed directly, + * otherwise the data can be copied and accumulated into an internal buffer for + * processing. This means using larger buffers can be much more efficient. + * + * Note also that if #avail_in is nonzero on return, then not all of the input + * data has been consumed. This can happen either because it ran out of output + * buffer space, or because it processed as much data as possible directly from + * the input buffer and needs more input to proceed without copying into + * internal buffers. The caller should provide more output buffer space and/or + * pack the remaining input data into another buffer with more input before + * calling rs_job_iter() again. * * \sa rs_job_iter() */ struct rs_buffers_s { -- cgit v1.2.1