lutaml-model 0.8.48 → 0.8.50

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a482362c928135d0733413ae200b20e5a9a7f05af8faf57696bc4461b093d691
-  data.tar.gz: 3b22e8a6881ad4a832d90a6b064d6999a5e5b8a969d507fd467d44c66f7c0279
+  metadata.gz: f2f88962ec380d731bd7a31ce5ff62f9aec9dcef4b7783aebfb128b6b5c86bbb
+  data.tar.gz: b282edc8ccf91c2381315e58a34d54a15642153e673ba31bbbd46c084c7634c4
 SHA512:
-  metadata.gz: a6047ddb9f43fa9a7012e794070891a0d997ca261f2c76f324223a1c1414bab39f1f05b5f627ecde1e21a083b971c4cc002d15928db410e97411b5dcca9a5b97
-  data.tar.gz: b849ae1daa34c19f6f570d1389a2ea43cf3af5ffba5db32bdef33e53a0b7ba960736b511ecfc5f520a926690134a4247227b1fa7a437923a8774a511569f6e88
+  metadata.gz: f92f932e37bed4d355b3a41c1d2599bf23a5f0907f2ba18967f27cb5a572a4be11d080d54d0a73787055b6e9143414928e87086f2269f42acfb77665e9cccda6
+  data.tar.gz: a5801daa0947b0a2308fc720412d0add3cd5956f6a902cf20aa62b0ece6d883ec801dc4c4112319ab161a5d68934d54aac0253d601515823d04440df52011400

data/.github/workflows/performance.yml

@@ -55,4 +55,50 @@ jobs:
         run: rake vendor:compile
 
       - name: Run performance benchmarks
-        run: bundle exec rake performance:compare
+        run: bundle exec rake performance:compare
+  # TODO.max-perf/36: YJIT moves exactly the interpretive paths the
+  # model layer still runs. Sequential off/on probes on one runner give
+  # a directly comparable pair per commit - a measurement leg, not a
+  # gate. The plan fast path shrinks the YJIT win; watch both.
+  performance-yjit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        run: rake vendor:prepare
+
+      - name: Configure bundler
+        run: |
+          mkdir -p .bundle
+          echo "---" > .bundle/config
+          echo 'BUNDLE_BUILD__RUBY___LL: "--with-cflags=-std=gnu17"' >> .bundle/config
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        run: rake vendor:compile
+
+      - name: Probe YJIT off
+        run: bundle exec rake performance:probe
+
+      - name: Probe YJIT on
+        env:
+          RUBY_YJIT_ENABLE: "1"
+        run: bundle exec rake performance:probe

data/docs/_guides/native-engines.adoc

@@ -31,6 +31,36 @@ leptris and yeptris ship prebuilt platform gems for Linux and macOS
 every platform, including Windows. When a gem is absent, lutaml-model
 automatically falls back to the standard engine for that format.
 
+== YJIT doubles the model pipeline
+
+The model layer's own work — mapping dispatch, casts, hydration — is
+plain Ruby and exactly the code shape YJIT compiles well; the native
+engines' C work is unaffected either way. On a controlled runner
+(ubuntu-latest, Ruby 3.4, the repository's performance probe):
+
+|===
+| op | YJIT off | YJIT on | change
+
+| from_yaml | 75.1 i/s | 129.7 i/s | +73%
+| to_yaml | 67.3 i/s | 145.1 i/s | +116%
+| from_json | 73.2 i/s | 128.4 i/s | +75%
+| to_json | 115.4 i/s | 255.5 i/s | +121%
+|===
+
+Enable it like any Ruby application does — this is the application's
+call, never a gem's:
+
+[source,sh]
+----
+RUBY_YJIT_ENABLE=1 ruby app.rb
+# or in code, before heavy work:
+RubyVM::YJIT.enable
+----
+
+The opt-in XML plan fast path (see below) moves work out of Ruby and
+into the engine, which shrinks the YJIT win — enabling both is still
+net faster than either alone.
+
 == Selecting adapters explicitly
 
 The engines register as ordinary adapter types, so explicit selection and

data/lib/lutaml/model/serialize/initialization.rb

@@ -350,6 +350,59 @@ module Lutaml
           instance
         end
 
+        # Fast bulk constructor for deserialization-heavy callers
+        # (native extensions building object trees bottom-up).
+        #
+        # Allocates without running #initialize and applies each present
+        # attribute through its compiled writer, which casts the value
+        # and marks it as explicitly set — so defaults, to_hash output,
+        # and using_default? behave exactly as if the instance had been
+        # produced by from_hash. Values may be primitives or already
+        # built instances (instances pass through casting unchanged);
+        # absent keys keep their defaults. Unknown keys raise.
+        #
+        # @param attrs [Hash] attribute names (String or Symbol) to
+        #   pre-cast values
+        # @param register [Symbol, nil] The register context
+        # @return [Object] The hydrated instance
+        def instantiate(attrs = {}, register = nil)
+          instance = allocate_for_deserialization(register)
+          register_id = instance.lutaml_register
+          given = {}
+          attrs.each do |key, value|
+            name = key.to_sym
+            next if name == :lutaml_register
+
+            unless attributes(register_id).key?(name)
+              raise Error, "unknown attribute '#{name}' for #{self}"
+            end
+
+            given[name] = value
+          end
+          attributes(register_id).each do |name, attr|
+            next if attr.derived?
+
+            if given.key?(name)
+              instance.public_send(:"#{name}=", given[name])
+            else
+              # Absent keys seed their default explicitly, mirroring
+              # initialize_attributes: every mapped attribute ends up
+              # set (nil when no default), never left as the
+              # uninitialized sentinel — readers and formatters touch
+              # absent attributes freely.
+              default = attr.default_value(register_id, instance)
+              value = if Lutaml::Model::Utils.uninitialized?(default)
+                        nil
+                      else
+                        attr.cast_value(default, register_id)
+                      end
+              instance.public_send(:"#{name}=", value)
+              instance.using_default_for(name)
+            end
+          end
+          instance
+        end
+
         # Define register-specific attribute methods on the class itself.
         #
         # Called once per (class, register) combination. Replaces per-instance

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.48"
+    VERSION = "0.8.50"
   end
 end

data/lib/lutaml/xml/plan_compiler.rb

@@ -200,7 +200,14 @@ module Lutaml
 
         def compilable_mapping?(mapping)
           mapping.root_element &&
-            !(mapping.respond_to?(:root_mappings) && mapping.root_mappings)
+            !(mapping.respond_to?(:root_mappings) && mapping.root_mappings) &&
+            # lutaml-model#88: when_attribute partitions route same-name
+            # occurrences by attribute value — name-keyed plan rows would
+            # hydrate every occurrence into EVERY partition attribute
+            # (verified double-capture under the flag). The interpretive
+            # filter is the only correct path until the descriptor ABI
+            # grows row predicates.
+            mapping.mappings.none?(&:when_attribute?)
         end
 
         # Attribute for a rule — delegate rules resolve against their

data/lib/lutaml/xml/plan_hydrator.rb

@@ -30,7 +30,11 @@ module Lutaml
 
             child_kwargs[name] = []
           end
-          instance = model_class.new(**attr_kwargs, **child_kwargs)
+          # TODO.max-perf/33: the bulk constructor — allocate +
+          # compiled writers, from_hash semantics — measured ~30x on
+          # hydration-heavy corpora versus the generic constructor.
+          instance = model_class.instantiate(attr_kwargs.merge(child_kwargs),
+                                             register)
           instance.lutaml_parent = parent if parent
           instance.lutaml_root ||= parent&.lutaml_root || parent
           instance.element_order = PlanOrder.build(node) if node && plan[:ordered]

data/spec/lutaml/model/serializable_instantiate_spec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "../../../lib/lutaml/model"
+
+module InstantiateMapping
+  class Part < Lutaml::Model::Serializable
+    attribute :label, :string
+    attribute :count, :integer
+  end
+
+  class Widget < Lutaml::Model::Serializable
+    attribute :name, :string
+    attribute :flag, :boolean
+    attribute :part, Part
+    attribute :tags, :string, collection: true
+
+    key_value do
+      map "name", to: :name
+      map "flag", to: :flag
+      map "part", to: :part
+      map "tags", to: :tags
+    end
+  end
+end
+
+RSpec.describe "Serializable.instantiate" do
+  it "hydrates attributes from primitives" do
+    widget = InstantiateMapping::Widget.instantiate("name" => "w", "flag" => true,
+                                                    "tags" => %w[a b])
+    expect(widget.name).to eq("w")
+    expect(widget.flag).to be(true)
+    expect(widget.tags).to eq(%w[a b])
+  end
+
+  it "accepts pre-built instances for typed attributes" do
+    part = InstantiateMapping::Part.instantiate(label: "p", count: 2)
+    widget = InstantiateMapping::Widget.instantiate(name: "w", part: part)
+
+    expect(widget.part).to equal(part)
+  end
+
+  it "keeps defaults for absent keys and reports them as defaults" do
+    widget = InstantiateMapping::Widget.instantiate
+    # Absent scalars read as the uninitialized sentinel, exactly like the
+    # XML fast path; serialization omits them either way.
+    expect(Lutaml::Model::Utils.uninitialized?(widget.name) ||
+           widget.name.nil?).to be(true)
+    expect(widget).to be_using_default(:name)
+  end
+
+  it "marks set attributes as explicitly set" do
+    widget = InstantiateMapping::Widget.instantiate(name: "w")
+    expect(widget).not_to be_using_default(:name)
+  end
+
+  it "serializes identically to from_hash" do
+    input = { "name" => "w", "flag" => false,
+              "part" => { "label" => "p", "count" => 3 },
+              "tags" => ["x"] }
+    from_hash = InstantiateMapping::Widget.from_hash(input)
+
+    part = InstantiateMapping::Part.instantiate(input["part"])
+    fast = InstantiateMapping::Widget.instantiate(
+      name: "w", flag: false, part: part, tags: ["x"],
+    )
+
+    expect(fast.to_hash).to eq(from_hash.to_hash)
+  end
+
+  it "raises on unknown attribute names" do
+    expect { InstantiateMapping::Widget.instantiate(bogus: 1) }
+      .to raise_error(Lutaml::Model::Error, /unknown attribute/)
+  end
+end

data/spec/lutaml/xml/plan_fast_path_spec.rb

@@ -517,6 +517,83 @@ RSpec.describe "XML plan fast path" do
       expect(model.to_xml).to eq(interpretive)
     end
 
+    # lutaml-model#88: name-keyed plan rows would hydrate every
+    # same-name occurrence into EVERY partition attribute (verified
+    # double-capture) — discriminator models must take the interpretive
+    # path, and a partitioned CHILD model must opt its parent out too.
+    it "falls back to the interpretive path for when_attribute models" do
+      component = Class.new(Lutaml::Model::Serializable) do
+        attribute :text, :string
+
+        xml do
+          element "component"
+          map_element "text", to: :text
+        end
+      end
+      stub_const("PlanFastPath::Component", component)
+
+      partitioned = Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, component, collection: true
+        attribute :purpose, component, collection: true
+
+        xml do
+          element "requirement"
+          map_element "component", when_attribute: "type",
+                                   to: { "guidance" => :guidance,
+                                         "purpose" => :purpose }
+        end
+      end
+      stub_const("PlanFastPath::Partitioned", partitioned)
+
+      req = partitioned.from_xml(<<~XML)
+        <requirement>
+          <component type="guidance"><text>g1</text></component>
+          <component type="purpose"><text>p1</text></component>
+          <component type="guidance"><text>g2</text></component>
+        </requirement>
+      XML
+
+      expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+      expect(req.purpose.map(&:text)).to eq(["p1"])
+
+      expect(Lutaml::Xml::PlanCompiler.compile(partitioned,
+                                               :default)).to be_nil
+    end
+
+    it "opts a parent out when a child model partitions with when_attribute" do
+      component = Class.new(Lutaml::Model::Serializable) do
+        attribute :text, :string
+
+        xml do
+          element "component"
+          map_element "text", to: :text
+        end
+      end
+      inner = Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, component, collection: true
+
+        xml do
+          element "req"
+          map_element "component", to: :guidance,
+                                   when_attribute: { "type" => "guidance" }
+        end
+      end
+      outer = Class.new(Lutaml::Model::Serializable) do
+        attribute :req, inner
+
+        xml do
+          element "holder"
+          map_element "req", to: :req
+        end
+      end
+      stub_const("PlanFastPath::Nested", outer)
+
+      doc = outer.from_xml(
+        "<holder><req><component type=\"guidance\"><text>g1</text></component></req></holder>",
+      )
+      expect(doc.req.guidance.map(&:text)).to eq(["g1"])
+    end
+
     it "round-trips through both fast paths" do
       item = Class.new(Lutaml::Model::Serializable) do
         attribute :id, :integer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.48
+  version: 0.8.50
 platform: ruby
 authors:
 - Ribose Inc.
@@ -1797,6 +1797,7 @@ files:
 - spec/lutaml/model/schema/yaml_schema_spec.rb
 - spec/lutaml/model/sequence_choice_compositor_spec.rb
 - spec/lutaml/model/sequence_spec.rb
+- spec/lutaml/model/serializable_instantiate_spec.rb
 - spec/lutaml/model/serializable_spec.rb
 - spec/lutaml/model/serializable_validation_spec.rb
 - spec/lutaml/model/serialize/builder_spec.rb