kdu_cache

Implements a caching compressed data source, i.e., one which offers the KDU_SOURCE_CAP_CACHED capability explained in connection with kdu_compressed_source::get_capabilities.

The object has two types of interfaces: those used to transfer new data into the cache (e.g., data received incrementally over a network connection); and those used to retrieve the cached data. By implementing the acquire_lock and release_lock functions in a derived class, these two sets of functions may be safely invoked from different threads in a multi-threading environment, allowing cache updates to occur asynchronously with cached data access.

When a caching data source is supplied to kdu_codestream::create the image quality obtained when rendering the code-stream data generally improves as more and more compressed data is transferred into the cache using the add_to_databin function. Note carefully that the object must not be passed into kdu_codestream::create at least until the main header data-bin has been completed. This may be verified by calling get_databin_length, with a data-bin class of KDU_MAIN_HEADER_DATABIN. Before passing the object to kdu_codestream::create you must call set_read_scope, passing in these same data-bin class and in-class identifiers ( KDU_MAIN_HEADER_DATABIN and 0, respectively).

Even more functionality may be achieved if you read from a caching data source indirectly via a jp2_source object. To do this, you must first create and open a jp2_family_src object, passing the kdu_cache object in as the jp2_family_src object's data source. You can then open JP2 boxes by passing the jp2_family_src object in the call to jp2_input_box::open or to jp2_source::open. In fact, you may open multiple boxes simultaneously on the same jp2_family_src object (even from multiple threads, if you are careful to implement the synchronization objects offered by the jp2_family_src class. Using the kdu_cache object as a source for JP2 box and JP2 source reading, provides you with additional functionality specifically designed for interacting with the meta-data and with multiple code-streams via the JPIP protocol and allows high level applications to be largely oblivious as to whether the ultimate source of information is local or remote.

Some effort is invested in the implementation of this object to ensure that truly massive compressed images (many Gigabytes in size) may be cached efficiently. In particular, both header data and compressed precinct data are managed using a special sparse cache structure, which supports both efficient random access and dynamic growth.

The present object maintains its own LRU (Least Recently Used) lists which can be used to implement cache management policies when clients have insufficient memory to buffer compressed data indefinitely. The LRU list may be traversed in either direction (most to least recently used data-bins, or vice-versa). Elements may also be promoted or demoted within the list by making appropriate function calls.

The kdu_cache class bears some similarity to kdu_cache. We have decided to implement a new class, rather than modifying the old one, principally for the sake of developers who are already using kdu_cache. The kdu_cache class will eventually be deprecated and replaced with the new one.

kdu_cache {Java: Kdu_cache}

~kdu_cache [virtual] {Java: Native_destroy}

attach_to {Java: Attach_to}

close [virtual] {Java: Close}

add_to_databin [virtual] {Java: Add_to_databin}

get_databin_length [virtual] {Java: Get_databin_length}

promote_databin [virtual] {Java: Promote_databin}

demote_databin [virtual] {Java: Demote_databin}

get_next_codestream [virtual] {Java: Get_next_codestream}

get_next_lru_databin [virtual] {Java: Get_next_lru_databin}

get_next_mru_databin [virtual] {Java: Get_next_mru_databin}

mark_databin [virtual] {Java: Mark_databin}

clear_all_marks [virtual] {Java: Clear_all_marks}

set_all_marks [virtual] {Java: Set_all_marks}

get_databin_prefix [virtual] {Java: Get_databin_prefix}

set_read_scope [virtual] {Java: Set_read_scope}

set_tileheader_scope [virtual] {Java: Set_tileheader_scope}

set_precinct_scope [virtual] {Java: Set_precinct_scope}

read [virtual] {Java: Read}

get_capabilities [virtual] {Java: Get_capabilities}

seek [virtual] {Java: Seek}

get_pos [virtual] {Java: Get_pos}

acquire_lock [virtual] {Java: Acquire_lock}

release_lock [virtual] {Java: Release_lock}

get_peak_cache_memory {Java: Get_peak_cache_memory}

get_transferred_bytes {Java: Get_transferred_bytes}