Skip to main content

Tune the local cache

A layer that reads over a network can keep the tiles it has fetched on local disk. That is what makes a network-backed map usable on a slow link — and usable at all once the link is gone. The cache is off by default and is enabled in two places: once for the device, then per layer.

Enable the cache​

On the device. IMcMapDevice::SInitParams carries two fields, and both must be set:

FieldMeaning
strMapLayersLocalCacheFolderPath to the folder holding the cache. NULL, the default, means no cache
uMapLayersLocalCacheSizeInMBMaximum size in MB. 0, the default, disables the cache; UINT_MAX means unlimited

Leaving either at its default means there is no cache to opt into later — every per-layer request then fails with IMcErrors::LOCAL_CACHE_NOT_INIT.

Per layer. Not every layer can cache, and the pattern is not the one you would guess — see Which layers can cache below. Where it is supported, Create() takes a final pLocalCacheLayerParams argument: pass an IMcMapLayer::SLocalCacheLayerParams whose strLocalCacheSubFolder names this layer's own sub-folder of the device cache folder:

IMcMapLayer::SLocalCacheLayerParams CacheParams;
CacheParams.strLocalCacheSubFolder = "orthophoto";

IMcNativeRasterMapLayer *pLayer = NULL;
IMcErrors::ECode eCode = IMcNativeRasterMapLayer::Create(
&pLayer, "http://server/maps/orthophoto", UINT_MAX, false, 0, false,
&ReadCallback, &CacheParams);

The sub-folder is the cache's identity: two layers must not share one, and a second layer naming an occupied sub-folder fails with IMcErrors::LAYER_ALREADY_EXISTS. Conversely, the same layer reopened with the same sub-folder finds its previous contents, which is the whole point — the cache survives the process.

The other field of the struct, strOriginalFolder, is output-only. It is filled when you read parameters back and ignored when you pass them in.

Which layers can cache​

Caching is a property of the layer interface, not of whether the layer happens to read over a network — and the split is counter-intuitive enough to check before you design around it:

LayerTakes pLocalCacheLayerParams
Raster, elevation, material and traversability — converted, raw and web-service formsYes
Vector — convertedYes
Vector — rawOnly a rasterized (MAPNIK:) layer; any other returns IMcErrors::NOT_IMPLEMENTED
Every native-server layerNo
3D model and vector-extrusion layersNo

The two entries worth reading twice are the last two. A native-server layer talks to the Map Layer Server over HTTP and has no cache parameter at all — the most network-dependent layer in the SDK is the one you cannot give a disk cache. And a raw 3D-model or extrusion layer accepts a URL as its source directory, again with nowhere to pass cache parameters.

So "this layer reads over the network, therefore I can cache it" is not a safe inference. Check the interface's Create() signature.

Read the cache back​

IMcMapLayer::GetLocalCacheLayerParams() reports one layer's cache settings. It distinguishes two cases that are easy to conflate: if the device has no cache it fails with IMcErrors::LOCAL_CACHE_NOT_INIT, whereas if the device has one and only this layer was created without it, the call succeeds with NULL strings.

IMcMapDevice::GetMapLayersLocalCacheParams() reports the whole cache: its folder, its maximum size and its current size in MB, and optionally an array of per-layer parameters. It succeeds even when there is no cache — the folder comes back NULL — so it is also the way to ask whether caching is on without provoking an error.

Current size against maximum size is the number worth surfacing in an application that runs for a long time offline, because it is the one that predicts the next trim.

Resize and clear​

IMcMapDevice::SetMapLayersLocalCacheSize() changes the maximum. Lowering it forces an immediate trim, and that is the one call whose failure has a lasting consequence: if the cache cannot be trimmed to the new size, it returns IMcErrors::LOCAL_CACHE_CANT_BE_TRIMMED and deactivates itself. It does not carry on at the old size.

Two calls clear it:

CallRemoves
IMcMapDevice::RemoveMapLayerFromLocalCache()One layer's sub-folder — or every layer, given NULL. Caching stays on
IMcMapDevice::RemoveMapLayersLocalCache()The cache folder itself, and it stops creating or using a local cache at all

Those two are not "one layer" versus "all layers" — the per-layer call with NULL already empties everything while leaving caching enabled. The second turns the feature off. Use it only when that is what you mean.

Both refuse while a cached layer is open, returning IMcErrors::LOCAL_CACHE_HAS_ACTIVE_LAYER. Remove the layers from their terrains first and let them be destroyed; then clear.

Failure modes and their codes​

The first four surface from the layer's Create(), which is why a layer that creates fine without a cache can fail with one. The last two come from the device calls above — a trim that cannot fit, and a removal attempted while a cached layer is still open.

CodeCauseWhat to do
IMcErrors::LOCAL_CACHE_NOT_INITThe device was initialised without a cache folder or with size 0Set both SInitParams fields
IMcErrors::LAYER_ALREADY_EXISTSAnother layer already uses this sub-folderGive the layer its own
IMcErrors::LOCAL_CACHE_CANT_CREATE_DIRThe sub-folder could not be createdCheck the path and write permissions
IMcErrors::CANT_READ_FILEThe cache's own files could not be readThe cache is damaged; remove that layer's sub-folder
IMcErrors::LOCAL_CACHE_CANT_BE_TRIMMEDThe cache cannot be reduced to its maximum sizeThe cache is now deactivated; raise the limit or clear it
IMcErrors::LOCAL_CACHE_HAS_ACTIVE_LAYERA removal was attempted while a cached layer is openDestroy the layers first

Treat all of these as non-fatal in application code. A failed cache is a slower map, not a broken one, and a layer that cannot cache is still worth creating without one.

Caching is one of four things that decide how a networked layer behaves. The others:

  • Requests per fetch. SetNumTilesInNativeServerRequest() sets how many tiles are asked of MapCore's Map Layer Server in a single request; 0 or 1 mean one tile per request, and the default is chosen by MapCore from the layer's type and properties. Native-server layers only.
  • Credentials. IMcMapLayer::SetNativeServerCredentials() sets the token and session ID sent to the Map Layer Server when it requires them. It is static — the credentials are process-wide, not per layer — and GetNativeServerCredentials() reads them back, returning empty strings if they were never set.
  • Retries and concurrency. SInitParams::uWebRequestRetryCount (default 10, 0 to disable) and uAsyncQueryTilesMaxActiveWebRequests (default 10) bound how hard the client retries and how many tile requests for asynchronous queries are in flight at once.

Verified against MapCore 12.5.0

Written from Map/IMcMapLayer.h, Map/IMcMapDevice.h