kdu_serve::truncate_cache_model

The object manages a model of the cache maintained by a client (real or hypothetical) which immediately caches all compressed data packaged up by the generate_increments function. The present function provides a mechanism for deleting elements from this cache model, either in whole or in part. This may be useful if the client needs to delete elements from its cache to limit memory consumption. It also provides a mechanism for the client to explicitly inform the server of the elements which it wants. To do this, the client may first add all relevant elements to the server's cache model, using a negative bin_id argument in the call to augment_cache_model; it may then remove the elements which it actually wants to receive, using the present function. This strategy for forming client requests will often be inefficient, but it gives the client the control which may be needed to access the image in unusual ways.

The stream_min and stream_max arguments identify a range of code-streams over which the cache model truncation statement should be applied. Frequently, this range will contain only one code-stream; however, it may contain a larger number of streams. The code-streams actually affected by the command are restricted to those which belong to the object's model set (the set of code-streams for which a cache model is currently being applied). Unless specific action is taken to alter the model set, it will include all code-streams which have been referenced by window commands (including this one). However, the client may augment the server's model set by appropriately configuring the kdu_window object supplied to set_window. The present object may also alter the model set, removing some code-streams where its resources do not permit simultaneous modeling of all streams which might be in the client's model set. These changes will be reflected in the window returned via get_window.

The function informs the server that its cache model should include at most the initial available_bytes of the data-bin whose in-class identifier is bin_id and whose class is given by the databin_class argument. If the cache model currently has fewer bytes for this data-bin, the function has no effect. If available_bytes is less than or equal to zero, the object is being informed that it should remove the data-bin from its cache model, meaning that it will be re-transmitted from scratch when serving any window for which the data-bin is relevant.

The available_packets argument is ignored, unless databin_class is KDU_PRECINCT_DATABIN and available_bytes is 0. In this case available_packets indicates the maximum number of packets from the relevant precinct data-bin, which should be kept in the server's cache model. Note that this means that you must choose to specify either a packet limit or a byte limit. There is no way to specify non-trivial limits on both the length and the number of packets simultaneously. If you call this function multiple times specifying alternately a byte limit and a packet limit, it is possible that the internal machinery will use only the most recently specified limit, rather than taking the minimum of the two. This is because reconciling byte and packet limits may be a computationally intensive task if the precinct data does not already happen to be in memory.

If bin_id is negative, the function is automatically applied to all data-bins which belong to the current window. In this case, the code-stream range supplied via stream_min and stream_max is also restricted to those code-streams which are referenced by the current window.

databin_class [int]

stream_min [int]

stream_max [int]

bin_id [kdu_long]

available_bytes [int]

available_packets [int]