kdu_codestream::augment_cache_threshold

This function plays an important role in managing the memory consumption and data access overhead associated with persistent input codestreams, in which sufficient information is available to support random access into the JPEG2000 packet data with all packets of any given precinct appearing consecutively. Under these conditions, the internal machinery is able to reload precincts from the compressed data source on demand, either by seeking or by exploiting caching capabilities of the compressed data source. By default, reloadable precincts are loaded only as needed and are unloaded from memory as soon as their code-blocks have been consumed, or the open tile to which they belong is closed. While this policy minimizes internal memory consumption, it can result in quite large access overheads when code-blocks must be accessed very frequently.

To minimize this access burden, the internal machinery provides a caching capability, whereby reloadable precincts which are no longer needed may be moved onto a list of inactive precincts, without immediately unloading their compressed data buffers. These inactive precincts may be reinstantiated without substantial overhead. The present function is used to control the number of compressed data bytes associated with this caching facility. This number of bytes is to be understood as a threshold, which will generally be crossed before any action is taken to force the recycling of resources. The threshold may be crossed substantially if the code-stream precincts are very large or the application's data access patterns are not amenable to resource recycling.

The threshold starts out as 0 and may be augmented as required by calling this function any number of times. If share_buffering has been used to share buffer resources with other codestream management machines, this function controls the caching threshold for all participating entities.

The new size of the threshold, which is extra_bytes larger than the previous value. It is legal to call this function with extra_bytes=0 to find out the current threshold.

extra_bytes [int]