Handle events

Events report completed style loads, available frames, download progress, and resource failures. The runtime copies each event into a queue, and the host drains that queue on the runtime owner thread.

A host decides which event types it reads. A map and a runtime each carry a subscription, and an event of an unselected type is never built, never queued, and never wakes a parked pump.

Select the event types you read

Name the types on the map for map events, and on the runtime for offline database and offline region events.

handle-events.c

mln_status select_map_events(mln_map map) {
  return mln_map_set_event_mask(
    map, MLN_RUNTIME_EVENT_MASK_MAP_STYLE_LOADED |
           MLN_RUNTIME_EVENT_MASK_MAP_LOADING_FAILED |
           MLN_RUNTIME_EVENT_MASK_MAP_RENDER_UPDATE_AVAILABLE |
           MLN_RUNTIME_EVENT_MASK_MAP_RENDER_FRAME_FINISHED
  );
}

Select the types before the map loads a style. Narrowing a subscription applies to later events and keeps the events already queued. A map and a runtime start with every type the library reports selected, so a host that reads every type keeps that default.

Drain a batch

One drain reports every queued event, in queue order, together with the message text that those events carry. The batch belongs to the runtime, and the next drain for that runtime replaces it.

handle-events.c

mln_runtime_event_batch batch = mln_runtime_event_batch_default();
if (mln_runtime_drain_events(runtime, 0, &batch) != MLN_STATUS_OK) return;

for (size_t index = 0; index < batch.event_count; index++) {
  const char* bytes = (const char*)batch.events + index * batch.event_size;
  const mln_runtime_event* event = (const mln_runtime_event*)bytes;

  // One runtime serves every map under it, and they share this queue.
  if (event->source_type != MLN_RUNTIME_EVENT_SOURCE_MAP) continue;
  if (event->source != observer->map) continue;

  switch (event->type) {
    case MLN_RUNTIME_EVENT_MAP_STYLE_LOADED:
      observer->style_ready = true;
      break;
    case MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE:
      observer->render_pending = true;
      break;
    case MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_FINISHED:
      if (asks_for_a_repaint(event)) observer->render_pending = true;
      break;
    case MLN_RUNTIME_EVENT_MAP_LOADING_FAILED:
      observer->load_failed = true;
      break;
    default:
      break;
  }
}

In C, step through the events by the stride that the batch reports rather than by the size of the event struct. A later library version reports a wider event to a host compiled against an earlier header.

Copy any value you keep, because the next drain replaces the batch. A message is the arena bytes at the event’s own offset: a failed style load carries its failure text there, and a missing-image event carries the image ID.

Pass a maximum event count to take a bounded slice instead of the whole queue. The batch then reports how many events stayed queued.

Match an event to its source

One runtime serves every map created under it, and their events share one queue. Check the source before interpreting the event. This prevents one map from handling another map’s event.

handle-events.c

// One runtime serves every map under it, and they share this queue.
if (event->source_type != MLN_RUNTIME_EVENT_SOURCE_MAP) continue;
if (event->source != observer->map) continue;

Runtime events also use the queue. Check the source kind before comparing a map handle.

Read a payload by its type

An event carries its structured data inline, and the payload type names which typed payload the event holds.

handle-events.c

if (event->payload_type != MLN_RUNTIME_EVENT_PAYLOAD_RENDER_FRAME) {
  return false;
}
return event->payload.render_frame.needs_repaint;

Handle essential events

Most hosts begin with four event kinds.

A style-loaded event means that the style parsed and its sources exist. Add host-owned sources and layers after this event.

A render-update-available event means that the map published a new frame. A render-frame-finished event carries a repaint flag. Draw another frame when the flag is set. Additional frames advance camera animations and label placement.

A loading-failed event carries the failure text for a style or resource request.

Calls report synchronous failures through the binding’s error idiom. Events report failures from work that completes later.

Destroying a map discards that map’s queued events immediately. Read any mirrored state that teardown needs while the map is live.