diff options
Diffstat (limited to 'src/liblzma')
| -rw-r--r-- | src/liblzma/api/lzma/base.h | 81 | ||||
| -rw-r--r-- | src/liblzma/api/lzma/container.h | 6 | ||||
| -rw-r--r-- | src/liblzma/lz/lz_encoder.c | 3 | ||||
| -rw-r--r-- | src/liblzma/lz/lz_encoder.h | 12 | ||||
| -rw-r--r-- | src/liblzma/lz/lz_encoder_mf.c | 2 |
5 files changed, 65 insertions, 39 deletions
diff --git a/src/liblzma/api/lzma/base.h b/src/liblzma/api/lzma/base.h index e04e7504..ddbcb033 100644 --- a/src/liblzma/api/lzma/base.h +++ b/src/liblzma/api/lzma/base.h @@ -243,10 +243,19 @@ typedef enum { /** * \brief The `action' argument for lzma_code() + * + * After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or LZMA_FINISH, + * the same `action' must is used until lzma_code() returns LZMA_STREAM_END. + * Also, the amount of input (that is, strm->avail_in) must not be modified + * by the application until lzma_code() returns LZMA_STREAM_END. Changing the + * `action' or modifying the amount of input will make lzma_code() return + * LZMA_PROG_ERROR. */ typedef enum { LZMA_RUN = 0, /**< + * \brief Continue coding + * * Encoder: Encode as much input as possible. Some internal * buffering will probably be done (depends on the filter * chain in use), which causes latency: the input used won't @@ -262,21 +271,37 @@ typedef enum { LZMA_SYNC_FLUSH = 1, /**< - * Encoder: Makes all the data given to liblzma via next_in - * available in next_out without resetting the filters. Call - * lzma_code() with LZMA_SYNC_FLUSH until it returns - * LZMA_STREAM_END. Then continue encoding normally. + * \brief Make all the input available at output + * + * Normally the encoder introduces some latency. + * LZMA_SYNC_FLUSH forces all the buffered data to be + * available at output without resetting the internal + * state of the encoder. This way it is possible to use + * compressed stream for example for communication over + * network. + * + * Only some filters support LZMA_SYNC_FLUSH. Trying to use + * LZMA_SYNC_FLUSH with filters that don't support it will + * make lzma_code() return LZMA_HEADER_ERROR. For example, + * LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does. * - * \note Synchronous flushing is supported only by - * some filters. Using LZMA_SYNC_FLUSH with - * which such filters will make lzma_code() - * return LZMA_HEADER_ERROR. + * Using LZMA_SYNC_FLUSH very often can dramatically reduce + * the compression ratio. With some filters (for example, + * LZMA2), finetuning the compression options may help + * mitigate this problem significantly. * * Decoders don't support LZMA_SYNC_FLUSH. */ LZMA_FULL_FLUSH = 2, /**< + * \brief Make all the input available at output + * + * This is like LZMA_SYNC_FLUSH except that this resets the + * internal encoder state. + * + * + * * Finishes encoding of the current Data Block. All the input * data going to the current Data Block must have been given * to the encoder (the last bytes can still be pending in @@ -291,6 +316,11 @@ typedef enum { LZMA_FINISH = 3 /**< + * \brief Finish the coding operation + * + * + * + * * Finishes the coding operation. All the input data must * have been given to the encoder (the last bytes can still * be pending in next_in). Call lzma_code() with LZMA_FINISH @@ -402,35 +432,30 @@ typedef struct lzma_internal_s lzma_internal; * - defining custom memory hander functions; and * - holding a pointer to coder-specific internal data structures. * - * When a new lzma_stream structure is allocated (either as automatic variable - * on stack or dynamically with malloc()), the new lzma_stream structure must - * be initialized to LZMA_STREAM_INIT. + * The typical usage * - * Before initializing a coder (for example, with lzma_stream_decoder()), + * - After allocating lzma_stream (on stack or with malloc()), it must be + * initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details). * + * - Initialize a coder to the lzma_stream, for example by using + * lzma_easy_encoder() or lzma_auto_decoder(). In contrast to zlib, + * strm->next_in and strm->next_out are ignored by all initialization + * functions, thus it is safe to not initialize them yet. The + * initialization functions always set strm->total_in and strm->total_out + * to zero. * - * Before calling any of the lzma_*_init() functions the first time, - * the application must reset lzma_stream to LZMA_STREAM_INIT. The - * lzma_*_init() function will verify the options, allocate internal - * data structures and store pointer to them into `internal'. Finally - * total_in and total_out are reset to zero. In contrast to zlib, - * next_in and avail_in are ignored by the initialization functions. + * - Use lzma_code() to do the actual work. * - * The actual coding is done with the lzma_code() function. Application - * must update next_in, avail_in, next_out, and avail_out between - * calls to lzma_decode() just like with zlib. + * - Once the coding has been finished, the existing lzma_stream can be + * reused. It is OK to reuse lzma_stream with different initialization + * function without calling lzma_end() first. Old allocations are + * automatically freed. * - * In contrast to zlib, even the decoder requires that there always - * is at least one byte space in next_out; if avail_out == 0, - * LZMA_BUF_ERROR is returned immediatelly. This shouldn't be a problem - * for most applications that already use zlib, but it's still worth - * checking your application. + * - Finally, use lzma_end() to free the allocated memory. * * Application may modify values of total_in and total_out as it wants. * They are updated by liblzma to match the amount of data read and * written, but liblzma doesn't use the values internally. - * - * Application must not touch the `internal' pointer. */ typedef struct { const uint8_t *next_in; /**< Pointer to the next input byte. */ diff --git a/src/liblzma/api/lzma/container.h b/src/liblzma/api/lzma/container.h index 2b719b04..9535ffa9 100644 --- a/src/liblzma/api/lzma/container.h +++ b/src/liblzma/api/lzma/container.h @@ -1,5 +1,5 @@ /** - * \file lzma/FIXME.h + * \file lzma/container.h * \brief File formats * * \author Copyright (C) 1999-2008 Igor Pavlov @@ -255,7 +255,9 @@ extern lzma_ret lzma_auto_decoder( /** * \brief Initializes decoder for LZMA_Alone file * - * The LZMA_Alone decoder supports LZMA_SYNC_FLUSH. FIXME + * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. + * There is no need to use LZMA_FINISH, but allowing it may simplify + * certain types of applications. * * \return - LZMA_OK * - LZMA_MEM_ERROR diff --git a/src/liblzma/lz/lz_encoder.c b/src/liblzma/lz/lz_encoder.c index 6a39d0f5..067f12c7 100644 --- a/src/liblzma/lz/lz_encoder.c +++ b/src/liblzma/lz/lz_encoder.c @@ -143,8 +143,7 @@ fill_window(lzma_coder *coder, lzma_allocator *allocator, const uint8_t *in, coder->mf.read_pos -= pending; // Call the skip function directly instead of using - // lz_dict_skip(), since we don't want to touch - // mf->read_ahead. + // mf_skip(), since we don't want to touch mf->read_ahead. coder->mf.skip(&coder->mf, pending); } diff --git a/src/liblzma/lz/lz_encoder.h b/src/liblzma/lz/lz_encoder.h index 8442dfa0..373cc01b 100644 --- a/src/liblzma/lz/lz_encoder.h +++ b/src/liblzma/lz/lz_encoder.h @@ -95,12 +95,12 @@ struct lzma_mf_s { ////////////////// /// Find matches. Returns the number of distance-length pairs written - /// to the matches array. This is called only via lzma_mf_find. + /// to the matches array. This is called only via lzma_mf_find(). uint32_t (*find)(lzma_mf *mf, lzma_match *matches); /// Skips num bytes. This is like find() but doesn't make the /// distance-length pairs available, thus being a little faster. - /// This is called only via mf_skip function. + /// This is called only via mf_skip(). void (*skip)(lzma_mf *mf, uint32_t num); uint32_t *hash; @@ -117,7 +117,7 @@ struct lzma_mf_s { /// Maximum length of a match supported by the LZ-based encoder. /// If the longest match found by the match finder is find_len_max, - /// lz_dict_find() tries to expand it up to match_len_max bytes. + /// mf_find() tries to expand it up to match_len_max bytes. uint32_t match_len_max; /// When running out of input, binary tree match finders need to know @@ -177,10 +177,10 @@ typedef struct { // also take longer. // // A single encoder loop in the LZ-based encoder may call the match finder -// (lz_dict_find() or lz_dict_skip()) at maximum of after_size times. -// In other words, a single encoder loop may advance lz_dict.read_pos at +// (mf_find() or mf_skip()) at maximum of after_size times. +// In other words, a single encoder loop may advance lzma_mf.read_pos at // maximum of after_size times. Since matches are looked up to -// lz_dict.buffer[lz_dict.read_pos + match_len_max - 1], the total +// lzma_mf.buffer[lzma_mf.read_pos + match_len_max - 1], the total // amount of extra buffer needed after dictionary_size becomes // after_size + match_len_max. // diff --git a/src/liblzma/lz/lz_encoder_mf.c b/src/liblzma/lz/lz_encoder_mf.c index 208bb2ae..d82681b3 100644 --- a/src/liblzma/lz/lz_encoder_mf.c +++ b/src/liblzma/lz/lz_encoder_mf.c @@ -244,7 +244,7 @@ do { \ /// /// \param len_limit Don't look for matches longer than len_limit. /// \param pos lzma_mf.read_pos + lzma_mf.offset -/// \param cur Pointer to current byte (lzma_dict_ptr(mf)) +/// \param cur Pointer to current byte (mf_ptr(mf)) /// \param cur_match Start position of the current match candidate /// \param loops Maximum length of the hash chain /// \param son lzma_mf.son (contains the hash chain) |