multi_json 1.19.1 → 1.21.1

data/lib/multi_json/adapter_selector.rb

@@ -1,4 +1,6 @@
-module MultiJson
+# frozen_string_literal: true
+
+module MultiJSON
   # Handles adapter discovery, loading, and selection
   #
   # Adapters can be specified as:
@@ -10,17 +12,45 @@ module MultiJson
   module AdapterSelector
     extend self
 
-    # Alternate spellings for adapter names
-    ALIASES = {"jrjackson" => "jr_jackson"}.freeze
+    # Per-adapter metadata, in preference order (fastest first). Each
+    # entry maps the adapter symbol to its ``require`` path and the
+    # constant whose presence indicates the backing library is already
+    # loaded. ``loaded`` is a ``::``-separated path so we can walk it
+    # without an explicit ``defined?`` check.
+    #
+    # The hash order is split per platform: on MRI/TruffleRuby the
+    # bundled benchmark suite ranks json_gem ahead of fast_jsonparser/
+    # oj/yajl on Ruby 3.4+; on JRuby the FFI-vs-pure-Ruby tradeoff
+    # hasn't been re-benchmarked yet, so jr_jackson stays first there.
+    # CI re-runs the benchmark with ``--verify-preference`` to fail
+    # if the observed ranking diverges.
+    # :nocov:
+    ADAPTERS = if RUBY_ENGINE == "jruby"
+      {
+        jr_jackson: {require: "jrjackson", loaded: "JrJackson"},
+        json_gem: {require: "json", loaded: "JSON::Ext::Parser"},
+        gson: {require: "gson", loaded: "Gson"},
+        fast_jsonparser: {require: "fast_jsonparser", loaded: "FastJsonparser"},
+        oj: {require: "oj", loaded: "Oj"},
+        yajl: {require: "yajl", loaded: "Yajl"}
+      }.freeze
+    else
+      {
+        json_gem: {require: "json", loaded: "JSON::Ext::Parser"},
+        fast_jsonparser: {require: "fast_jsonparser", loaded: "FastJsonparser"},
+        oj: {require: "oj", loaded: "Oj"},
+        yajl: {require: "yajl", loaded: "Yajl"},
+        jr_jackson: {require: "jrjackson", loaded: "JrJackson"},
+        gson: {require: "gson", loaded: "Gson"}
+      }.freeze
+    end
+    # :nocov:
+    private_constant :ADAPTERS
 
-    # Strategy lambdas for loading adapters based on specification type
-    LOADERS = {
-      Module => ->(adapter, _selector) { adapter },
-      String => ->(name, selector) { selector.send(:load_adapter_by_name, name) },
-      Symbol => ->(name, selector) { selector.send(:load_adapter_by_name, name.to_s) },
-      NilClass => ->(_adapter, selector) { selector.send(:load_adapter, selector.default_adapter) },
-      FalseClass => ->(_adapter, selector) { selector.send(:load_adapter, selector.default_adapter) }
-    }.freeze
+    # Backwards-compatible view of {ADAPTERS} that exposes only the
+    # require paths. Tests still poke at this constant to stub or break
+    # the require step.
+    REQUIREMENT_MAP = ADAPTERS.transform_values { |meta| meta[:require] }.freeze
 
     # Returns the default adapter to use
     #
@@ -29,7 +59,27 @@ module MultiJson
     # @example
     #   AdapterSelector.default_adapter  #=> :oj
     def default_adapter
-      @default_adapter ||= detect_best_adapter
+      Concurrency.synchronize(:default_adapter) { @default_adapter ||= detect_best_adapter }
+    end
+
+    # Returns the default adapter class, excluding the given adapter name
+    #
+    # Used by adapters that only implement one direction (e.g.
+    # FastJsonparser only parses) so the other direction can be delegated
+    # to whichever library MultiJSON would otherwise pick.
+    #
+    # @api private
+    # @param excluded [Symbol] adapter name to skip during detection
+    # @return [Class] the adapter class
+    # @example
+    #   AdapterSelector.default_adapter_excluding(:fast_jsonparser)  #=> MultiJSON::Adapters::Oj
+    def default_adapter_excluding(excluded)
+      Concurrency.synchronize(:default_adapter) do
+        name = loaded_adapter(excluding: excluded)
+        name ||= installable_adapter(excluding: excluded)
+        name ||= fallback_adapter
+        load_adapter_by_name(name.to_s)
+      end
     end
 
     private
@@ -45,23 +95,24 @@ module MultiJson
     # Finds an already-loaded JSON library
     #
     # @api private
+    # @param excluding [Symbol, nil] adapter name to skip during detection
     # @return [Symbol, nil] adapter name if found
-    def loaded_adapter
-      return :fast_jsonparser if defined?(::FastJsonparser)
-      return :oj if defined?(::Oj)
-      return :yajl if defined?(::Yajl)
-      return :jr_jackson if defined?(::JrJackson)
-      return :json_gem if defined?(::JSON::Ext::Parser)
-
-      :gson if defined?(::Gson)
+    def loaded_adapter(excluding: nil)
+      ADAPTERS.each do |name, meta|
+        next if name == excluding
+        return name if Object.const_defined?(meta.fetch(:loaded))
+      end
+      nil
     end
 
     # Tries to require and use an installable adapter
     #
     # @api private
+    # @param excluding [Symbol, nil] adapter name to skip during detection
     # @return [Symbol, nil] adapter name if successfully required
-    def installable_adapter
-      ::MultiJson::REQUIREMENT_MAP.each_key do |adapter_name|
+    def installable_adapter(excluding: nil)
+      REQUIREMENT_MAP.each_key do |adapter_name|
+        next if adapter_name == excluding
         return adapter_name if try_require(adapter_name)
       end
       nil
@@ -73,7 +124,7 @@ module MultiJson
     # @param adapter_name [Symbol] adapter to require
     # @return [Boolean] true if require succeeded
     def try_require(adapter_name)
-      require ::MultiJson::REQUIREMENT_MAP.fetch(adapter_name)
+      require REQUIREMENT_MAP.fetch(adapter_name)
       true
     rescue ::LoadError
       false
@@ -81,62 +132,83 @@ module MultiJson
 
     # Returns the fallback adapter when no others available
     #
+    # The json gem is a Ruby default gem since Ruby 1.9, so in practice
+    # the installable-adapter step always succeeds before reaching this
+    # fallback on any supported Ruby version. The warning below only
+    # fires in tests that deliberately break the require path.
+    #
     # @api private
-    # @return [Symbol] the ok_json adapter name
+    # @return [Symbol] the json_gem adapter name
     def fallback_adapter
       warn_about_fallback unless @default_adapter_warning_shown
       @default_adapter_warning_shown = true
-      :ok_json
+      :json_gem
     end
 
-    # Warns the user about using the slow fallback adapter
+    # Warns the user about reaching the last-resort fallback
     #
     # @api private
     # @return [void]
     def warn_about_fallback
       Kernel.warn(
-        "[WARNING] MultiJson is using the default adapter (ok_json). " \
-        "We recommend loading a different JSON library to improve performance."
+        "[WARNING] MultiJSON is falling back to the json_gem adapter " \
+        "because no other JSON library could be loaded."
       )
     end
 
     # Loads an adapter from a specification
     #
     # @api private
-    # @param adapter_spec [Symbol, String, Module, nil] adapter specification
+    # @param adapter_spec [Symbol, String, Module, nil, false] adapter specification
     # @return [Class] the adapter class
     def load_adapter(adapter_spec)
-      loader = find_loader_for(adapter_spec)
-      return loader.call(adapter_spec, self) if loader
-
-      raise ::LoadError, adapter_spec
+      adapter = case adapter_spec
+      when ::String then load_adapter_by_name(adapter_spec)
+      when ::Symbol then load_adapter_by_name(adapter_spec.to_s)
+      when nil, false then load_adapter(default_adapter)
+      when ::Module then adapter_spec
+      else raise ::LoadError, "expected adapter to be a Symbol, String, or Module, got #{adapter_spec.inspect}"
+      end
+      validate_adapter!(adapter)
     rescue ::LoadError => e
       raise AdapterError.build(e)
     end
 
-    # Finds the appropriate loader for an adapter specification
-    #
-    # @api private
-    # @param adapter_spec [Object] adapter specification
-    # @return [Proc, nil] loader proc if found
-    def find_loader_for(adapter_spec)
-      klass = adapter_spec.class
-      return LOADERS.fetch(klass) if LOADERS.key?(klass)
-
-      LOADERS.fetch(Module) if adapter_spec.is_a?(Module)
-    end
-
     # Loads an adapter by its string name
     #
+    # ``jrjackson`` (the JrJackson gem's name) is normalized to
+    # ``jr_jackson`` (the adapter file/class name) for backwards
+    # compatibility with the original gem-name alias.
+    #
     # @api private
     # @param name [String] adapter name
     # @return [Class] the adapter class
     def load_adapter_by_name(name)
-      normalized = ALIASES.fetch(name, name).downcase
+      normalized = name.downcase
+      normalized = "jr_jackson" if normalized == "jrjackson"
       require_relative "adapters/#{normalized}"
 
       class_name = normalized.split("_").map(&:capitalize).join
-      ::MultiJson::Adapters.const_get(class_name)
+      ::MultiJSON::Adapters.const_get(class_name)
+    end
+
+    # Validate that an adapter satisfies the documented contract
+    #
+    # Custom adapters are accepted as modules/classes, so fail fast
+    # during adapter resolution rather than later on the first load or
+    # dump call.
+    #
+    # @api private
+    # @param adapter [Module] adapter class or module
+    # @return [Module] the validated adapter
+    # @raise [AdapterError] when the adapter is missing a required class method
+    #   or ParseError constant
+    def validate_adapter!(adapter)
+      raise AdapterError, "Adapter #{adapter} must respond to .load" unless adapter.respond_to?(:load)
+      raise AdapterError, "Adapter #{adapter} must respond to .dump" unless adapter.respond_to?(:dump)
+
+      MultiJSON.parse_error_class_for(adapter)
+      adapter
     end
   end
 end

data/lib/multi_json/adapters/fast_jsonparser.rb

@@ -1,43 +1,73 @@
+# frozen_string_literal: true
+
 require "fast_jsonparser"
-require "oj"
 require_relative "../adapter"
-require_relative "oj_common"
+require_relative "../adapter_selector"
 
-module MultiJson
+module MultiJSON
   module Adapters
-    # Use the FastJsonparser library to load and Oj to dump.
+    # Use the FastJsonparser library to load, and the fastest other
+    # available adapter to dump.
+    #
+    # FastJsonparser only implements parsing, so the ``dump`` side of
+    # the adapter is delegated to whichever adapter MultiJSON would
+    # pick if FastJsonparser weren't installed (oj → yajl → jr_jackson
+    # → json_gem → gson). The delegate is resolved lazily at the first
+    # ``dump`` call, not at file load time, so load order doesn't lock
+    # in the wrong delegate. Require any preferred dump backend before
+    # the first ``dump`` call (typical applications already have ``oj``
+    # loaded by then).
     class FastJsonparser < Adapter
-      include OjCommon
-
-      defaults :load, symbolize_keys: false
-      defaults :dump, mode: :compat, time_format: :ruby, use_to_json: true
+      defaults :load, symbolize_names: false
 
+      # Exception raised when JSON parsing fails
       ParseError = ::FastJsonparser::ParseError
 
+      class << self
+        # Serialize a Ruby object to JSON via the lazy delegate
+        #
+        # @api private
+        # @param object [Object] object to serialize
+        # @param options [Hash] serialization options
+        # @return [String] JSON string
+        # @example
+        #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
+        def dump(object, options = {})
+          dump_delegate.dump(object, options)
+        end
+
+        private
+
+        # Resolve the dump delegate, caching it across calls
+        #
+        # @api private
+        # @return [Class] delegate adapter class
+        def dump_delegate
+          MultiJSON::Concurrency.synchronize(:dump_delegate) do
+            @dump_delegate ||= MultiJSON::AdapterSelector.default_adapter_excluding(:fast_jsonparser)
+          end
+        end
+      end
+
       # Parse a JSON string into a Ruby object
       #
+      # FastJsonparser.parse only accepts ``symbolize_keys`` and raises
+      # on unknown keyword arguments, so the adapter explicitly forwards
+      # MultiJSON's canonical ``:symbolize_names`` option as
+      # FastJsonparser's native ``symbolize_keys:`` kwarg and silently
+      # drops the rest. Pass other options through
+      # ``MultiJSON.parse_options=`` and they'll apply to whichever
+      # adapter MultiJSON selects when fast_jsonparser isn't installed.
+      #
       # @api private
       # @param string [String] JSON string to parse
-      # @param options [Hash] parsing options
+      # @param options [Hash] parsing options (only :symbolize_names is honored)
       # @return [Object] parsed Ruby object
       #
       # @example Parse JSON string
       #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
-        ::FastJsonparser.parse(string, symbolize_keys: options[:symbolize_keys])
-      end
-
-      # Serialize a Ruby object to JSON
-      #
-      # @api private
-      # @param object [Object] object to serialize
-      # @param options [Hash] serialization options
-      # @return [String] JSON string
-      #
-      # @example Serialize object to JSON
-      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
-      def dump(object, options = {})
-        ::Oj.dump(object, prepare_dump_options(options))
+        ::FastJsonparser.parse(string, symbolize_keys: options[:symbolize_names])
       end
     end
   end

data/lib/multi_json/adapters/json_gem.rb

@@ -1,10 +1,13 @@
+# frozen_string_literal: true
+
 require_relative "../adapter"
 require "json"
 
-module MultiJson
+module MultiJSON
   module Adapters
     # Use the JSON gem to dump/load.
     class JsonGem < Adapter
+      # Exception raised when JSON parsing fails
       ParseError = ::JSON::ParserError
 
       defaults :load, create_additions: false, quirks_mode: true
@@ -19,17 +22,28 @@ module MultiJson
 
       # Parse a JSON string into a Ruby object
       #
+      # Non-UTF-8 strings are re-labeled via ``force_encoding`` (not
+      # transcoded) and then validated. This handles the dominant
+      # real-world case: Ruby HTTP libraries return response bodies
+      # tagged as ``ASCII-8BIT`` even when the bytes are valid UTF-8.
+      # ``encode(Encoding::UTF_8)`` would raise on any multi-byte
+      # sequence in that scenario because it tries to transcode each
+      # byte individually from ASCII-8BIT to UTF-8.
+      #
       # @api private
       # @param string [String] JSON string to parse
       # @param options [Hash] parsing options
       # @return [Object] parsed Ruby object
+      # @raise [::JSON::ParserError] when the input is not valid UTF-8
       #
       # @example Parse JSON string
       #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
-        string = string.dup.force_encoding(Encoding::UTF_8) if string.encoding != Encoding::UTF_8
+        if string.encoding != Encoding::UTF_8
+          string = string.dup.force_encoding(Encoding::UTF_8)
+          raise ::JSON::ParserError, "Invalid UTF-8 byte sequence in JSON input" unless string.valid_encoding?
+        end
 
-        options[:symbolize_names] = true if options.delete(:symbolize_keys)
         ::JSON.parse(string, options)
       end
 
@@ -43,16 +57,15 @@ module MultiJson
       # @example Serialize object to JSON
       #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
       def dump(object, options = {})
-        opts = options.except(:adapter)
         json_object = object.respond_to?(:as_json) ? object.as_json : object
-        return ::JSON.dump(json_object) if opts.empty?
+        return ::JSON.dump(json_object) if options.empty?
+        return ::JSON.generate(json_object, options) unless options.key?(:pretty)
 
-        if opts.delete(:pretty)
-          opts = PRETTY_STATE_PROTOTYPE.merge(opts)
-          return ::JSON.pretty_generate(json_object, opts)
-        end
+        # Common case: ``pretty: true`` is the only option, so the merge
+        # would just produce a copy of PRETTY_STATE_PROTOTYPE.
+        return ::JSON.pretty_generate(json_object, PRETTY_STATE_PROTOTYPE) if options.size == 1
 
-        ::JSON.generate(json_object, opts)
+        ::JSON.pretty_generate(json_object, PRETTY_STATE_PROTOTYPE.merge(options.except(:pretty)))
       end
     end
   end

data/lib/multi_json/adapters/oj.rb

@@ -1,23 +1,29 @@
+# frozen_string_literal: true
+
 require "oj"
 require_relative "../adapter"
 require_relative "oj_common"
 
-module MultiJson
+module MultiJSON
+  # Namespace for JSON adapter implementations
+  #
+  # Each adapter wraps a specific JSON library and provides a consistent
+  # interface for loading and dumping JSON data.
   module Adapters
     # Use the Oj library to dump/load.
     class Oj < Adapter
       include OjCommon
 
-      defaults :load, mode: :strict, symbolize_keys: false
+      defaults :load, mode: :strict, symbolize_names: false
       defaults :dump, mode: :compat, time_format: :ruby, use_to_json: true
 
-      # In certain cases OJ gem may throw JSON::ParserError exception instead
-      # of its own class. Also, we can't expect ::JSON::ParserError and
-      # ::Oj::ParseError to always be defined, since it's often not the case.
-      # Because of this, we can't reference those classes directly and have to
-      # do string comparison instead. This will not catch subclasses, but it
-      # shouldn't be a problem since the library is not known to be using it
-      # (at least for now).
+      # In certain cases the Oj gem may throw a ``JSON::ParserError``
+      # exception instead of its own class. Neither ``::JSON::ParserError``
+      # nor ``::Oj::ParseError`` is guaranteed to be defined, so we can't
+      # reference them directly — match by walking the exception's
+      # ancestry by class name instead. This will not catch subclasses
+      # of those classes, which shouldn't be a problem since neither
+      # library is known to subclass them.
       class ParseError < ::SyntaxError
         WRAPPED_CLASSES = %w[Oj::ParseError JSON::ParserError].freeze
         private_constant :WRAPPED_CLASSES
@@ -31,7 +37,7 @@ module MultiJson
         # @example Match parse errors in rescue
         #   rescue ParseError => e
         def self.===(exception)
-          exception.is_a?(::SyntaxError) || WRAPPED_CLASSES.include?(exception.class.to_s)
+          exception.class.ancestors.any? { |ancestor| WRAPPED_CLASSES.include?(ancestor.to_s) }
         end
       end
 
@@ -45,8 +51,7 @@ module MultiJson
       # @example Parse JSON string
       #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
-        options[:symbol_keys] = options[:symbolize_keys]
-        ::Oj.load(string, options)
+        ::Oj.load(string, translate_load_options(options))
       end
 
       # Serialize a Ruby object to JSON
@@ -61,6 +66,24 @@ module MultiJson
       def dump(object, options = {})
         ::Oj.dump(object, prepare_dump_options(options))
       end
+
+      private
+
+      # Translate ``:symbolize_names`` into Oj's ``:symbol_keys``
+      #
+      # Returns a new hash without mutating the input.
+      # ``:symbol_keys`` is always set (true or false) so MultiJSON's
+      # behavior is independent of any global ``Oj.default_options``
+      # the host application may have set. The input is the cached hash
+      # returned from {Adapter.merged_load_options}, so in-place edits
+      # would pollute the cache.
+      #
+      # @api private
+      # @param options [Hash] merged load options
+      # @return [Hash] options with ``:symbolize_names`` translated
+      def translate_load_options(options)
+        options.except(:symbolize_names).merge(symbol_keys: options[:symbolize_names] == true)
+      end
     end
   end
 end

data/lib/multi_json/adapters/oj_common.rb

@@ -1,28 +1,32 @@
-require "rubygems/version"
+# frozen_string_literal: true
 
-module MultiJson
+module MultiJSON
   module Adapters
+    # Shared functionality for the Oj adapter
+    #
+    # Provides option preparation for Oj.dump. Targets Oj 3.x; Oj 2.x is
+    # no longer supported.
+    #
+    # @api private
     module OjCommon
-      OJ_VERSION = Gem::Version.new(::Oj::VERSION)
-      OJ_V2 = OJ_VERSION.segments.first == 2
-      OJ_V3 = OJ_VERSION.segments.first == 3
-      private_constant :OJ_VERSION, :OJ_V2, :OJ_V3
-
-      if OJ_V3
-        PRETTY_STATE_PROTOTYPE = {
-          indent: "  ",
-          space: " ",
-          space_before: "",
-          object_nl: "\n",
-          array_nl: "\n",
-          ascii_only: false
-        }.freeze
-        private_constant :PRETTY_STATE_PROTOTYPE
-      end
+      PRETTY_STATE_PROTOTYPE = {
+        indent: "  ",
+        space: " ",
+        space_before: "",
+        object_nl: "\n",
+        array_nl: "\n",
+        ascii_only: false
+      }.freeze
+      private_constant :PRETTY_STATE_PROTOTYPE
 
       private
 
-      # Prepare options for Oj.dump based on Oj version
+      # Prepare options for Oj.dump
+      #
+      # Returns a fresh hash; never mutates the input. The input is the
+      # cached options hash returned from Adapter.merged_dump_options, so
+      # in-place mutation would pollute the cache and corrupt subsequent
+      # dump calls.
       #
       # @api private
       # @param options [Hash] serialization options
@@ -31,16 +35,9 @@ module MultiJson
       # @example Prepare dump options
       #   prepare_dump_options(pretty: true)
       def prepare_dump_options(options)
-        if OJ_V2
-          options[:indent] = 2 if options[:pretty]
-          options[:indent] = options[:indent].to_i if options[:indent]
-        elsif OJ_V3
-          options.merge!(PRETTY_STATE_PROTOTYPE.dup) if options.delete(:pretty)
-        else
-          raise "Unsupported Oj version: #{::Oj::VERSION}"
-        end
+        return options unless options.key?(:pretty)
 
-        options
+        options.except(:pretty).merge(PRETTY_STATE_PROTOTYPE)
       end
     end
   end

data/lib/multi_json/adapters/yajl.rb

@@ -1,10 +1,13 @@
+# frozen_string_literal: true
+
 require "yajl"
 require_relative "../adapter"
 
-module MultiJson
+module MultiJSON
   module Adapters
     # Use the Yajl-Ruby library to dump/load.
     class Yajl < Adapter
+      # Exception raised when JSON parsing fails
       ParseError = ::Yajl::ParseError
 
       # Parse a JSON string into a Ruby object
@@ -17,7 +20,7 @@ module MultiJson
       # @example Parse JSON string
       #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
-        ::Yajl::Parser.new(symbolize_keys: options[:symbolize_keys]).parse(string)
+        ::Yajl::Parser.new(options).parse(string)
       end
 
       # Serialize a Ruby object to JSON

data/lib/multi_json/concurrency.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MultiJSON
+  # Catalog of process-wide mutexes used to serialize MultiJSON's lazy
+  # initializers and adapter swaps. Each mutex protects a distinct
+  # piece of mutable state. Callers go through {.synchronize} rather
+  # than touching the mutex constants directly so the constants
+  # themselves can stay {.private_constant} and the surface of the
+  # module is documented in one place.
+  #
+  # @api private
+  module Concurrency
+    # Catalog of mutexes keyed by symbolic name. Each entry maps the
+    # public name passed to {.synchronize} to the underlying mutex
+    # instance. The names are documented inline so callers can find
+    # what each mutex protects without leaving this file.
+    MUTEXES = {
+      # Guards the {DEPRECATION_WARNINGS_SHOWN} set in `MultiJSON` so the
+      # check-then-add pair in `warn_deprecation_once` doesn't race.
+      deprecation_warnings: Mutex.new,
+      # Guards the process-wide `@adapter` swap in `MultiJSON.use` so two
+      # threads can't interleave their `OptionsCache.reset` and adapter
+      # assignment.
+      adapter: Mutex.new,
+      # Guards the lazy `@default_adapter` initializer and the
+      # `default_adapter_excluding` detection chain in `AdapterSelector`,
+      # so the chain runs at most once and `fallback_adapter`'s one-time
+      # warning fires at most once.
+      default_adapter: Mutex.new,
+      # Guards the lazy `default_load_options` / `default_dump_options`
+      # initializers in `MultiJSON::Options`.
+      default_options: Mutex.new,
+      # Guards the lazy dump-delegate resolution in
+      # `MultiJSON::Adapters::FastJsonparser`.
+      dump_delegate: Mutex.new
+    }.freeze
+    private_constant :MUTEXES
+
+    # Run a block while holding the named mutex
+    #
+    # The ``name`` symbol must be one of the keys in the internal
+    # ``MUTEXES`` table; an unknown name raises ``KeyError`` so a
+    # typo at the call site fails fast instead of silently dropping
+    # synchronization on the floor.
+    #
+    # @api private
+    # @param name [Symbol] mutex identifier
+    # @yield block to execute while holding the mutex
+    # @return [Object] the block's return value
+    # @raise [KeyError] when ``name`` does not match a known mutex
+    # @example
+    #   MultiJSON::Concurrency.synchronize(:adapter) { ... }
+    def self.synchronize(name, &)
+      MUTEXES.fetch(name).synchronize(&)
+    end
+  end
+end