From c2a5894f2dbe9982830066ab9347b059e6e7d845 Mon Sep 17 00:00:00 2001
From: John Firebaugh <john.firebaugh@gmail.com>
Date: Tue, 25 Apr 2017 18:20:26 -0700
Subject: [core] Immutable Impls

---
 include/mbgl/style/layer.hpp                       |  31 ++---
 include/mbgl/style/layers/background_layer.hpp     |  16 ++-
 include/mbgl/style/layers/circle_layer.hpp         |  16 ++-
 include/mbgl/style/layers/custom_layer.hpp         |  13 ++-
 include/mbgl/style/layers/fill_extrusion_layer.hpp |  16 ++-
 include/mbgl/style/layers/fill_layer.hpp           |  16 ++-
 include/mbgl/style/layers/layer.hpp.ejs            |  16 ++-
 include/mbgl/style/layers/line_layer.hpp           |  16 ++-
 include/mbgl/style/layers/raster_layer.hpp         |  16 ++-
 include/mbgl/style/layers/symbol_layer.hpp         |  16 ++-
 include/mbgl/style/light.hpp                       |  16 ++-
 include/mbgl/style/light.hpp.ejs                   |  16 ++-
 include/mbgl/style/source.hpp                      |  29 +++--
 include/mbgl/style/sources/geojson_source.hpp      |  16 ++-
 include/mbgl/style/sources/raster_source.hpp       |  17 ++-
 include/mbgl/style/sources/vector_source.hpp       |  17 ++-
 include/mbgl/util/immutable.hpp                    | 127 +++++++++++++++++++++
 include/mbgl/util/tileset.hpp                      |   5 +
 18 files changed, 336 insertions(+), 79 deletions(-)
 create mode 100644 include/mbgl/util/immutable.hpp

(limited to 'include')

diff --git a/include/mbgl/style/layer.hpp b/include/mbgl/style/layer.hpp
index 56f2c48fa7..10176879c5 100644
--- a/include/mbgl/style/layer.hpp
+++ b/include/mbgl/style/layer.hpp
@@ -2,6 +2,7 @@
 
 #include <mbgl/util/noncopyable.hpp>
 #include <mbgl/util/any.hpp>
+#include <mbgl/util/immutable.hpp>
 #include <mbgl/style/layer_type.hpp>
 #include <mbgl/style/types.hpp>
 
@@ -19,6 +20,7 @@ class RasterLayer;
 class BackgroundLayer;
 class CustomLayer;
 class FillExtrusionLayer;
+class LayerObserver;
 
 /**
  * The runtime representation of a [layer](https://www.mapbox.com/mapbox-gl-style-spec/#layers) from the Mapbox Style
@@ -38,15 +40,6 @@ class FillExtrusionLayer;
  */
 class Layer : public mbgl::util::noncopyable {
 public:
-    class Impl;
-
-protected:
-
-    const LayerType type;
-    Layer(LayerType, std::unique_ptr<Impl>);
-
-public:
-
     virtual ~Layer();
 
     // Check whether this layer is of the given subtype.
@@ -78,7 +71,7 @@ public:
     //
     template <class V>
     auto accept(V&& visitor) {
-        switch (type) {
+        switch (getType()) {
         case LayerType::Fill:
             return visitor(*as<FillLayer>());
         case LayerType::Line:
@@ -98,20 +91,30 @@ public:
         }
     }
 
+    LayerType getType() const;
     const std::string& getID() const;
 
     // Visibility
     VisibilityType getVisibility() const;
-    void setVisibility(VisibilityType);
+    virtual void setVisibility(VisibilityType) = 0;
 
     // Zoom range
     float getMinZoom() const;
-    void setMinZoom(float) const;
     float getMaxZoom() const;
-    void setMaxZoom(float) const;
+    virtual void setMinZoom(float) = 0;
+    virtual void setMaxZoom(float) = 0;
 
     // Private implementation
-    const std::unique_ptr<Impl> baseImpl;
+    class Impl;
+    Immutable<Impl> baseImpl;
+
+    Layer(Immutable<Impl>);
+
+    // Create a layer, copying all properties except id and paint properties from this layer.
+    virtual std::unique_ptr<Layer> cloneRef(const std::string& id) const = 0;
+
+    LayerObserver* observer = nullptr;
+    void setObserver(LayerObserver*);
 
     // For use in SDK bindings, which store a reference to a platform-native peer
     // object here, so that separately-obtained references to this object share
diff --git a/include/mbgl/style/layers/background_layer.hpp b/include/mbgl/style/layers/background_layer.hpp
index 6604a868f3..63708a449f 100644
--- a/include/mbgl/style/layers/background_layer.hpp
+++ b/include/mbgl/style/layers/background_layer.hpp
@@ -19,6 +19,13 @@ public:
     BackgroundLayer(const std::string& layerID);
     ~BackgroundLayer() final;
 
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
     // Paint properties
 
     static PropertyValue<Color> getDefaultBackgroundColor();
@@ -42,15 +49,16 @@ public:
     // Private implementation
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
 
-    BackgroundLayer(const Impl&);
-    BackgroundLayer(const BackgroundLayer&) = delete;
+    Mutable<Impl> mutableImpl() const;
+    BackgroundLayer(Immutable<Impl>);
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 };
 
 template <>
 inline bool Layer::is<BackgroundLayer>() const {
-    return type == LayerType::Background;
+    return getType() == LayerType::Background;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/layers/circle_layer.hpp b/include/mbgl/style/layers/circle_layer.hpp
index 3a3723249f..f40c507e28 100644
--- a/include/mbgl/style/layers/circle_layer.hpp
+++ b/include/mbgl/style/layers/circle_layer.hpp
@@ -27,6 +27,13 @@ public:
     void setFilter(const Filter&);
     const Filter& getFilter() const;
 
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
     // Paint properties
 
     static DataDrivenPropertyValue<float> getDefaultCircleRadius();
@@ -92,15 +99,16 @@ public:
     // Private implementation
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
 
-    CircleLayer(const Impl&);
-    CircleLayer(const CircleLayer&) = delete;
+    Mutable<Impl> mutableImpl() const;
+    CircleLayer(Immutable<Impl>);
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 };
 
 template <>
 inline bool Layer::is<CircleLayer>() const {
-    return type == LayerType::Circle;
+    return getType() == LayerType::Circle;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/layers/custom_layer.hpp b/include/mbgl/style/layers/custom_layer.hpp
index edc8d43f89..79a353b047 100644
--- a/include/mbgl/style/layers/custom_layer.hpp
+++ b/include/mbgl/style/layers/custom_layer.hpp
@@ -55,12 +55,21 @@ public:
                 void* context);
     ~CustomLayer() final;
 
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
     // Private implementation
 
     class Impl;
-    Impl* impl;
+    const Impl& impl() const;
+
+    Mutable<Impl> mutableImpl() const;
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 
-    CustomLayer(const Impl&);
     CustomLayer(const CustomLayer&) = delete;
 };
 
diff --git a/include/mbgl/style/layers/fill_extrusion_layer.hpp b/include/mbgl/style/layers/fill_extrusion_layer.hpp
index 1f79f87fac..bc6890e82f 100644
--- a/include/mbgl/style/layers/fill_extrusion_layer.hpp
+++ b/include/mbgl/style/layers/fill_extrusion_layer.hpp
@@ -27,6 +27,13 @@ public:
     void setFilter(const Filter&);
     const Filter& getFilter() const;
 
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
     // Paint properties
 
     static PropertyValue<float> getDefaultFillExtrusionOpacity();
@@ -74,15 +81,16 @@ public:
     // Private implementation
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
 
-    FillExtrusionLayer(const Impl&);
-    FillExtrusionLayer(const FillExtrusionLayer&) = delete;
+    Mutable<Impl> mutableImpl() const;
+    FillExtrusionLayer(Immutable<Impl>);
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 };
 
 template <>
 inline bool Layer::is<FillExtrusionLayer>() const {
-    return type == LayerType::FillExtrusion;
+    return getType() == LayerType::FillExtrusion;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/layers/fill_layer.hpp b/include/mbgl/style/layers/fill_layer.hpp
index 8371ff7a8f..3d08e75a1c 100644
--- a/include/mbgl/style/layers/fill_layer.hpp
+++ b/include/mbgl/style/layers/fill_layer.hpp
@@ -27,6 +27,13 @@ public:
     void setFilter(const Filter&);
     const Filter& getFilter() const;
 
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
     // Paint properties
 
     static PropertyValue<bool> getDefaultFillAntialias();
@@ -74,15 +81,16 @@ public:
     // Private implementation
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
 
-    FillLayer(const Impl&);
-    FillLayer(const FillLayer&) = delete;
+    Mutable<Impl> mutableImpl() const;
+    FillLayer(Immutable<Impl>);
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 };
 
 template <>
 inline bool Layer::is<FillLayer>() const {
-    return type == LayerType::Fill;
+    return getType() == LayerType::Fill;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/layers/layer.hpp.ejs b/include/mbgl/style/layers/layer.hpp.ejs
index 59d7cd6415..033ae88956 100644
--- a/include/mbgl/style/layers/layer.hpp.ejs
+++ b/include/mbgl/style/layers/layer.hpp.ejs
@@ -44,6 +44,13 @@ public:
 <% } -%>
 
 <% } -%>
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
 <% if (layoutProperties.length) { -%>
     // Layout properties
 
@@ -67,15 +74,16 @@ public:
     // Private implementation
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
 
-    <%- camelize(type) %>Layer(const Impl&);
-    <%- camelize(type) %>Layer(const <%- camelize(type) %>Layer&) = delete;
+    Mutable<Impl> mutableImpl() const;
+    <%- camelize(type) %>Layer(Immutable<Impl>);
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 };
 
 template <>
 inline bool Layer::is<<%- camelize(type) %>Layer>() const {
-    return type == LayerType::<%- camelize(type) %>;
+    return getType() == LayerType::<%- camelize(type) %>;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/layers/line_layer.hpp b/include/mbgl/style/layers/line_layer.hpp
index a5f08e553c..6000839d1c 100644
--- a/include/mbgl/style/layers/line_layer.hpp
+++ b/include/mbgl/style/layers/line_layer.hpp
@@ -29,6 +29,13 @@ public:
     void setFilter(const Filter&);
     const Filter& getFilter() const;
 
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
     // Layout properties
 
     static PropertyValue<LineCapType> getDefaultLineCap();
@@ -112,15 +119,16 @@ public:
     // Private implementation
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
 
-    LineLayer(const Impl&);
-    LineLayer(const LineLayer&) = delete;
+    Mutable<Impl> mutableImpl() const;
+    LineLayer(Immutable<Impl>);
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 };
 
 template <>
 inline bool Layer::is<LineLayer>() const {
-    return type == LayerType::Line;
+    return getType() == LayerType::Line;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/layers/raster_layer.hpp b/include/mbgl/style/layers/raster_layer.hpp
index c0351da5d0..ad9a68f1b0 100644
--- a/include/mbgl/style/layers/raster_layer.hpp
+++ b/include/mbgl/style/layers/raster_layer.hpp
@@ -22,6 +22,13 @@ public:
     // Source
     const std::string& getSourceID() const;
 
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
     // Paint properties
 
     static PropertyValue<float> getDefaultRasterOpacity();
@@ -69,15 +76,16 @@ public:
     // Private implementation
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
 
-    RasterLayer(const Impl&);
-    RasterLayer(const RasterLayer&) = delete;
+    Mutable<Impl> mutableImpl() const;
+    RasterLayer(Immutable<Impl>);
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 };
 
 template <>
 inline bool Layer::is<RasterLayer>() const {
-    return type == LayerType::Raster;
+    return getType() == LayerType::Raster;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/layers/symbol_layer.hpp b/include/mbgl/style/layers/symbol_layer.hpp
index ea6bda55d7..e7df5a92ae 100644
--- a/include/mbgl/style/layers/symbol_layer.hpp
+++ b/include/mbgl/style/layers/symbol_layer.hpp
@@ -29,6 +29,13 @@ public:
     void setFilter(const Filter&);
     const Filter& getFilter() const;
 
+    // Visibility
+    void setVisibility(VisibilityType) final;
+
+    // Zoom range
+    void setMinZoom(float) final;
+    void setMaxZoom(float) final;
+
     // Layout properties
 
     static PropertyValue<SymbolPlacementType> getDefaultSymbolPlacement();
@@ -256,15 +263,16 @@ public:
     // Private implementation
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
 
-    SymbolLayer(const Impl&);
-    SymbolLayer(const SymbolLayer&) = delete;
+    Mutable<Impl> mutableImpl() const;
+    SymbolLayer(Immutable<Impl>);
+    std::unique_ptr<Layer> cloneRef(const std::string& id) const final;
 };
 
 template <>
 inline bool Layer::is<SymbolLayer>() const {
-    return type == LayerType::Symbol;
+    return getType() == LayerType::Symbol;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/light.hpp b/include/mbgl/style/light.hpp
index 8212a58dcc..c82792b28d 100644
--- a/include/mbgl/style/light.hpp
+++ b/include/mbgl/style/light.hpp
@@ -1,20 +1,19 @@
 // This file is generated. Do not edit.
 
 #pragma once
+
 #include <mbgl/style/property_value.hpp>
 #include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/types.hpp>
-
-#include <memory>
+#include <mbgl/util/immutable.hpp>
 
 namespace mbgl {
 namespace style {
 
+class LightObserver;
+
 class Light {
 public:
-
-    class Impl;
-
     Light();
     ~Light();
 
@@ -42,7 +41,12 @@ public:
     void setIntensityTransition(const TransitionOptions&);
     TransitionOptions getIntensityTransition() const;
 
-    std::shared_ptr<Impl> impl;
+    class Impl;
+    Immutable<Impl> impl;
+    Mutable<Impl> mutableImpl() const;
+
+    LightObserver* observer = nullptr;
+    void setObserver(LightObserver*);
 };
 
 } // namespace style
diff --git a/include/mbgl/style/light.hpp.ejs b/include/mbgl/style/light.hpp.ejs
index 601e0bd410..adc5b651e3 100644
--- a/include/mbgl/style/light.hpp.ejs
+++ b/include/mbgl/style/light.hpp.ejs
@@ -4,20 +4,19 @@
 // This file is generated. Do not edit.
 
 #pragma once
+
 #include <mbgl/style/property_value.hpp>
 #include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/types.hpp>
-
-#include <memory>
+#include <mbgl/util/immutable.hpp>
 
 namespace mbgl {
 namespace style {
 
+class LightObserver;
+
 class Light {
 public:
-
-    class Impl;
-
     Light();
     ~Light();
 
@@ -29,7 +28,12 @@ public:
     TransitionOptions get<%- camelize(property.name) %>Transition() const;
 
 <% } -%>
-    std::shared_ptr<Impl> impl;
+    class Impl;
+    Immutable<Impl> impl;
+    Mutable<Impl> mutableImpl() const;
+
+    LightObserver* observer = nullptr;
+    void setObserver(LightObserver*);
 };
 
 } // namespace style
diff --git a/include/mbgl/style/source.hpp b/include/mbgl/style/source.hpp
index 4c82e472a6..d19dfd4e36 100644
--- a/include/mbgl/style/source.hpp
+++ b/include/mbgl/style/source.hpp
@@ -1,19 +1,25 @@
 #pragma once
 
-#include <mbgl/util/feature.hpp>
 #include <mbgl/util/noncopyable.hpp>
 #include <mbgl/util/optional.hpp>
-#include <mbgl/util/range.hpp>
 #include <mbgl/util/any.hpp>
+#include <mbgl/util/immutable.hpp>
 #include <mbgl/style/types.hpp>
 
 #include <memory>
 #include <string>
-#include <vector>
 
 namespace mbgl {
+
+class FileSource;
+
 namespace style {
 
+class VectorSource;
+class RasterSource;
+class GeoJSONSource;
+class SourceObserver;
+
 /**
  * The runtime representation of a [source](https://www.mapbox.com/mapbox-gl-style-spec/#sources) from the Mapbox Style
  * Specification.
@@ -49,21 +55,28 @@ public:
         return is<T>() ? reinterpret_cast<const T*>(this) : nullptr;
     }
 
+    SourceType getType() const;
     const std::string& getID() const;
     optional<std::string> getAttribution() const;
 
     // Private implementation
     class Impl;
-    const std::unique_ptr<Impl> baseImpl;
+    Immutable<Impl> baseImpl;
+
+    Source(Immutable<Impl>);
+
+    void setObserver(SourceObserver*);
+    SourceObserver* observer = nullptr;
+
+    virtual void loadDescription(FileSource&) = 0;
+    void dumpDebugLogs() const;
+
+    bool loaded = false;
 
     // For use in SDK bindings, which store a reference to a platform-native peer
     // object here, so that separately-obtained references to this object share
     // identical platform-native peers.
     any peer;
-
-protected:
-    const SourceType type;
-    Source(SourceType, std::unique_ptr<Impl>);
 };
 
 } // namespace style
diff --git a/include/mbgl/style/sources/geojson_source.hpp b/include/mbgl/style/sources/geojson_source.hpp
index 5b39d7821b..2dcfec51aa 100644
--- a/include/mbgl/style/sources/geojson_source.hpp
+++ b/include/mbgl/style/sources/geojson_source.hpp
@@ -5,6 +5,9 @@
 #include <mbgl/util/optional.hpp>
 
 namespace mbgl {
+
+class AsyncRequest;
+
 namespace style {
 
 struct GeoJSONOptions {
@@ -22,21 +25,26 @@ struct GeoJSONOptions {
 class GeoJSONSource : public Source {
 public:
     GeoJSONSource(const std::string& id, const GeoJSONOptions& = {});
+    ~GeoJSONSource() final;
 
     void setURL(const std::string& url);
     void setGeoJSON(const GeoJSON&);
 
     optional<std::string> getURL() const;
 
-    // Private implementation
-
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
+
+    void loadDescription(FileSource&) final;
+
+private:
+    optional<std::string> url;
+    std::unique_ptr<AsyncRequest> req;
 };
 
 template <>
 inline bool Source::is<GeoJSONSource>() const {
-    return type == SourceType::GeoJSON;
+    return getType() == SourceType::GeoJSON;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/sources/raster_source.hpp b/include/mbgl/style/sources/raster_source.hpp
index 395f25e51d..7f23a7ca4b 100644
--- a/include/mbgl/style/sources/raster_source.hpp
+++ b/include/mbgl/style/sources/raster_source.hpp
@@ -5,23 +5,34 @@
 #include <mbgl/util/variant.hpp>
 
 namespace mbgl {
+
+class AsyncRequest;
+
 namespace style {
 
 class RasterSource : public Source {
 public:
     RasterSource(std::string id, variant<std::string, Tileset> urlOrTileset, uint16_t tileSize);
+    ~RasterSource() final;
 
+    const variant<std::string, Tileset>& getURLOrTileset() const;
     optional<std::string> getURL() const;
 
-    // Private implementation
+    uint16_t getTileSize() const;
 
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
+
+    void loadDescription(FileSource&) final;
+
+private:
+    const variant<std::string, Tileset> urlOrTileset;
+    std::unique_ptr<AsyncRequest> req;
 };
 
 template <>
 inline bool Source::is<RasterSource>() const {
-    return type == SourceType::Raster;
+    return getType() == SourceType::Raster;
 }
 
 } // namespace style
diff --git a/include/mbgl/style/sources/vector_source.hpp b/include/mbgl/style/sources/vector_source.hpp
index 8626ce160a..6f16974b40 100644
--- a/include/mbgl/style/sources/vector_source.hpp
+++ b/include/mbgl/style/sources/vector_source.hpp
@@ -5,23 +5,32 @@
 #include <mbgl/util/variant.hpp>
 
 namespace mbgl {
+
+class AsyncRequest;
+
 namespace style {
 
 class VectorSource : public Source {
 public:
     VectorSource(std::string id, variant<std::string, Tileset> urlOrTileset);
+    ~VectorSource() final;
 
+    const variant<std::string, Tileset>& getURLOrTileset() const;
     optional<std::string> getURL() const;
 
-    // Private implementation
-
     class Impl;
-    Impl* const impl;
+    const Impl& impl() const;
+
+    void loadDescription(FileSource&) final;
+
+private:
+    const variant<std::string, Tileset> urlOrTileset;
+    std::unique_ptr<AsyncRequest> req;
 };
 
 template <>
 inline bool Source::is<VectorSource>() const {
-    return type == SourceType::Vector;
+    return getType() == SourceType::Vector;
 }
 
 } // namespace style
diff --git a/include/mbgl/util/immutable.hpp b/include/mbgl/util/immutable.hpp
new file mode 100644
index 0000000000..1d6ff4079a
--- /dev/null
+++ b/include/mbgl/util/immutable.hpp
@@ -0,0 +1,127 @@
+#pragma once
+
+#include <memory>
+
+namespace mbgl {
+
+/**
+ * `Mutable<T>` is a non-nullable uniquely owning reference to a `T`. It can be efficiently converted
+ * to `Immutable<T>`.
+ * 
+ * The lifecycle of `Mutable<T>` and `Immutable<T>` is as follows:
+ * 
+ *   1. Create a `Mutable<T>` using `makeMutable(...)`
+ *   2. Mutate it freely
+ *   3. When you're ready to freeze its state and enable safe cross-thread sharing, move assign or
+ *      move construct it to `Immutable<T>`
+ *
+ * The reason that `Mutable<T>` exists, rather than simply using a `std::unique_ptr<T>`, is to take advantage
+ * of the underlying single-allocation optimization provided by `std::make_shared`.
+ */
+template <class T>
+class Mutable {
+public:
+    Mutable(Mutable&&) = default;
+    Mutable& operator=(Mutable&&) = default;
+
+    Mutable(const Mutable&) = delete;
+    Mutable& operator=(const Mutable&) = delete;
+
+    T* get() { return ptr.get(); }
+    T* operator->() { return ptr.get(); }
+    T& operator*() { return *ptr; }
+
+private:
+    Mutable(std::shared_ptr<T>&& s)
+        : ptr(std::move(s)) {}
+
+    std::shared_ptr<T> ptr;
+
+    template <class S> friend class Immutable;
+    template <class S, class... Args> friend Mutable<S> makeMutable(Args&&...);
+};
+
+template <class T, class... Args>
+Mutable<T> makeMutable(Args&&... args) {
+    return Mutable<T>(std::make_shared<T>(std::forward<Args>(args)...));
+}
+
+/**
+ * `Immutable<T>` is a non-nullable shared reference to a `const T`. Construction requires
+ * a transfer of unique ownership from a `Mutable<T>`; once constructed it has the same behavior
+ * as `std::shared_ptr<const T>` but with better indication of intent.
+ *
+ * Normally one should not share state between threads because it's difficult to verify the
+ * absence of read/write data races. `Immutable` provides a guarantee that no writes are
+ * possible, and instances therefore can be freely transferred and shared between threads.
+ */
+template <class T>
+class Immutable {
+public:
+    template <class S>
+    Immutable(Mutable<S>&& s)
+        : ptr(std::const_pointer_cast<const S>(std::move(s.ptr))) {}
+
+    template <class S>
+    Immutable(Immutable<S>&& s)
+        : ptr(std::move(s.ptr)) {}
+
+    template <class S>
+    Immutable(const Immutable<S>& s)
+        : ptr(s.ptr) {}
+
+    template <class S>
+    Immutable& operator=(Mutable<S>&& s) {
+        ptr = std::const_pointer_cast<const S>(std::move(s.ptr));
+        return *this;
+    }
+
+    template <class S>
+    Immutable& operator=(Immutable<S>&& s) {
+        ptr = std::move(s.ptr);
+        return *this;
+    }
+
+    template <class S>
+    Immutable& operator=(const Immutable<S>& s) {
+        ptr = s.ptr;
+        return *this;
+    }
+
+    const T* get() const { return ptr.get(); }
+    const T* operator->() const { return ptr.get(); }
+    const T& operator*() const { return *ptr; }
+
+    friend bool operator==(const Immutable<T>& lhs, const Immutable<T>& rhs) {
+        return lhs.ptr == rhs.ptr;
+    }
+
+    friend bool operator!=(const Immutable<T>& lhs, const Immutable<T>& rhs) {
+        return lhs.ptr != rhs.ptr;
+    }
+
+private:
+    Immutable(std::shared_ptr<const T>&& s)
+        : ptr(std::move(s)) {}
+
+    std::shared_ptr<const T> ptr;
+
+    template <class S> friend class Immutable;
+    template <class S> friend class EnableImmutableFromThis;
+    template <class S, class U> friend Immutable<S> staticImmutableCast(const Immutable<U>&);
+};
+
+template <class T>
+class EnableImmutableFromThis : public std::enable_shared_from_this<const T> {
+public:
+    Immutable<T> immutableFromThis() const {
+        return Immutable<T>(this->shared_from_this());
+    }
+};
+
+template <class S, class U>
+Immutable<S> staticImmutableCast(const Immutable<U>& u) {
+    return Immutable<S>(std::static_pointer_cast<const S>(u.ptr));
+}
+
+} // namespace mbgl
diff --git a/include/mbgl/util/tileset.hpp b/include/mbgl/util/tileset.hpp
index 1f28a5039a..1256e9fe96 100644
--- a/include/mbgl/util/tileset.hpp
+++ b/include/mbgl/util/tileset.hpp
@@ -18,6 +18,11 @@ public:
     Scheme scheme = Scheme::XYZ;
 
     // TileJSON also includes center, zoom, and bounds, but they are not used by mbgl.
+
+    friend bool operator==(const Tileset& lhs, const Tileset& rhs) {
+        return std::tie(lhs.tiles, lhs.zoomRange, lhs.attribution, lhs.scheme)
+            == std::tie(rhs.tiles, rhs.zoomRange, rhs.attribution, rhs.scheme);
+    }
 };
 
 } // namespace mbgl
-- 
cgit v1.2.1