Skip to main content

Threading and lifecycle

Two questions account for most of the surprises in a first MapCore integration: which thread am I allowed to call this from, and who releases this object. Neither has a complicated answer, but both have answers that differ from the obvious guess.

Start-up and shutdown​

IMcMapDevice::Create() initializes the engine and hands back a device. Everything else — terrains, layers, viewports, queries — requires one to exist first.

IMcBase::Release() on the device is the shutdown. Releasing the last device tears the engine down, so this is not a call to make speculatively at the end of a subsystem's life; it ends MapCore for the process.

A device created with ERS_NONE as its rendering system has no rendering system at all. It cannot create viewports and cannot perform GPU-based queries, but non-GPU queries and calculations work normally. This is the configuration for a server or a batch tool that needs MapCore's geometry and data handling without a display.

Thread affinity​

On the web every MapCore call you make runs on the one JavaScript thread (see Web and web workers), so the rules about which thread may call what apply to the desktop and Android builds only. Dispatching asynchronous results applies everywhere, the web included — see PerformPendingCalculations, precisely.

MapCore has a main thread, and it is not necessarily the one you would expect:

The thread that creates the first device becomes MapCore's main (render) thread; creating a viewport re-binds the main thread to the creating thread.

So the main thread is effectively the thread that created the last viewport. If your application creates its device during start-up on one thread and later creates a viewport on another, the main thread has moved. The practical advice is to create the device and all viewports on the same thread, deliberately, and then leave it alone.

What must happen on that thread:

  • IMcMapViewport::Render() and the other rendering entry points.
  • IMcMapDevice::PerformPendingCalculations(). Called from any other thread it does nothing in multi-threaded builds, and the header documents IMcErrors::INVALID_PARAMETERS as the result of calling it off-thread — either way, the work does not get done.

Two creation-time choices that set the threading​

Both are fields of IMcMapDevice::SInitParams, the parameter block the header describes so:

MapCore rendering and spatial queries engine initialization parameters; considered only when creating the first device.

— from Map/IMcMapDevice.h

  • uNumBackgroundThreads — how many background threads load map layers. The default, UINT_MAX, means the number of hardware thread contexts minus one; 0 loads layers on the main thread instead. Layer loading is the work that leaves the main thread by default, so a host that cannot tolerate MapCore working off its own thread passes 0 and accepts that loading then competes with rendering.
  • bMultiThreadedDevice — whether the rendering device is initialised multi-threaded. It must be true in WPF mode, and in any case where a texture MapCore returns is used from a thread other than the main one; otherwise false is recommended, for performance. Decide it up front: the parameters are read only for the first device.

PerformPendingCalculations, precisely​

This one is worth being exact about, because both over- and under-calling it cause problems.

It does three things: it executes GPU-based calculations that were issued from other threads and redirected to the main thread, it performs communication-related work, and it dispatches asynchronous results — for example those from IMcMapDevice::GetWebServerLayers() — to their callbacks.

Render() also performs the communication and asynchronous-results processing. The redirected GPU-based calculations are executed only here. That gives a clear rule:

Your applicationWhat it needs
Renders every frame, issues no GPU calculations off-threadRender() alone is enough
Issues GPU-based calculations from worker threadsPerformPendingCalculations() regularly, on the main thread
Renders only when HasPendingUpdates() says soPerformPendingCalculations() regularly, or asynchronous results stall while nothing is being drawn

The timeout parameter bounds how long one call may spend, in milliseconds; at least one calculation is always performed, and the default of 0 means exactly one. The optional output flag tells you whether calculations remain, so you can decide whether to come back sooner.

Who owns what​

MapCore objects are reference-counted through IMcBase, but the initial count is the part that catches people out. The header states the rules every interface follows:

Base interface of MapCore's reference-counted interfaces: an instance is destroyed when its last reference is released (a map layer, or a resource such as a texture, that MapCore still uses internally is destroyed once MapCore stops using it).

Nothing MapCore retrieves comes with a reference for the caller: not an instance a function creates (Create(), Clone(), Load()...), one a getter or a C++ cast such as IMcObjectSchemeNode::CastToLineItem() retrieves, or a callback's argument. So you must hold a reference of your own to every instance you keep a pointer to, including one you create: call AddRef() when you get the pointer, and Release() when you no longer use it. MapCore holds its own references the same way: an interface that holds another, such as a terrain its layers, a viewport its terrains or an item its texture, keeps it alive while it holds it.

The exception is an instance created inside its container, which holds its only reference: overlays, objects, collections and animation states, which leave their container by their Remove(); object locations, removed by IMcObjectScheme::RemoveObjectLocation(); cameras, destroyed by IMcMapViewport::DestroyCamera(); and map environments, which go with their viewport. Never call AddRef() or Release() on them; a pointer to one is valid until it leaves its container or the container is destroyed.

— from IMcBase.h

Those are the rules in C++ and on the web. In C# and Java the wrappers take the reference themselves when they create the managed object, so holding the managed object already owns it: you call no AddRef() (Java has none), and you release by disposing the object or calling Release() — see Language surfaces.

A terrain adds a reference to its coordinate system and to each of its layers, which is what makes sharing safe: the same layer in three terrains, or the same terrain in three viewports, stays alive as long as any of them holds it.

A device and a standalone IMcSpatialQueries object are always stored, so AddRef() each after creating it. Release the device last, after every other MapCore object you own.

Cameras are among the instances a container holds. The viewport's initial camera comes from IMcMapViewport::Create() and further ones from CreateCamera(); the active camera cannot be destroyed, so activate another one first.

Asynchronous work​

Creating a layer does not mean the layer is ready. Loading continues in the background, and IsInitialized() reports whether it has finished. To be told rather than to poll, supply an IMcMapLayer::IReadCallback:

CallbackMeaning
OnInitialized()Loading finished. Check the status argument — this fires on failure too, and the layer pointer can be NULL if the failure happened during creation
OnReadError()A read or communication error occurred
OnRemoved()RemoveLayerAsync() has removed the layer from all its terrains, just before it is deleted
OnReplaced()ReplaceNativeServerLayerAsync() has swapped the layer for a new one everywhere

Every one of these carries an additional data string naming what actually went wrong — the file that could not be read, the request that failed. It is the first thing to log.

The asymmetry to remember: layer removal is asynchronous too. RemoveLayerAsync() returns before the layer is gone, and OnRemoved() is your signal that it is safe to consider the layer finished with. It can also refuse up front — a terrain's elevation layer cannot be removed while a 3D-model layer depends on it (IMcErrors::DTM_LAYER_CANT_BE_REMOVED), so check the synchronous return before waiting for a callback that will never arrive.

warning

Removing a layer can take a terrain out of your viewports. Any terrain left empty by the removal is itself removed from all its viewports. So dropping the last layer of a terrain does not leave you with a blank terrain still mounted — it silently unmounts the terrain everywhere it was shown. If you intend to swap the only layer, add the replacement before removing the original.

Web and web workers​

The web build uses no Emscripten pthreads and no shared memory, so everything you call runs on the one JavaScript thread. In a browser, the work other platforms move to background threads runs concurrently in web workers instead — each with a heap of its own and no memory shared with the page, which is why heap accounting becomes visible in the API. IMcMapDevice::SetWebWorkersHeapLimits() bounds those heaps: a per-worker maximum (default 200 MB, and it should be above 50 MB) and a total across the main thread and all workers (default 10 GB for Wasm64, 6 GB for Wasm32). Under Node.js MapCore creates no workers: the background work runs on the same thread, and the per-worker limit has nothing to bound. To stay inside those limits MapCore deletes workers with large heaps, recreating them later with a minimal heap if they are needed again — so a tight total limit trades memory for the cost of that churn.

GetHeapSize() reports the current heap and takes a flag to include the workers; GetMaxMemoryUsage() and GetMemorySize() complete the picture. These are the numbers to watch when a web application grows slowly unresponsive rather than failing outright.

Verified against MapCore 12.5.0

Written from IMcBase.h, Map/IMcMapDevice.h, Map/IMcMapViewport.h, Map/IMcMapTerrain.h, Map/IMcMapLayer.h, Map/IMcMapCamera.h, Calculations/IMcSpatialQueries.h