ecoportal-api-v2 1.1.6 → 1.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6294103b68ebdbf099d1137865856b10baec21683bd648727976f245cf197ad
-  data.tar.gz: e0500e2c784a46c7a82ca3aa29e44f96d116bd6898e5b35f9174162457208165
+  metadata.gz: 65194be30f026aa431874543d6905b5704ea081c6a3c9ef0bf9741142c4c4253
+  data.tar.gz: 398eaeb83ea38386670715c0fa83144004abdbd8c7edfd8581ecb7b157c8d205
 SHA512:
-  metadata.gz: eb18fb2a167afeaea5eac0db4e13ee58d64fc348ff1ebd33942ad1bb7120cbb828ad2652ed2d6b165d7a1b53eea097338032690e26ee97f5765fd87ba2f97862
-  data.tar.gz: 7a61a35335247d39a0e97574f5b2816a92238d93a9f5b23c62b909a92ae03817057752ffc576ae1414c5e6744a6381b473be4cd2cfc2a0fd4e7582cffd97bdd4
+  metadata.gz: 0761f2079d2493f6fef928f846daf4b6b0413838c4f1252c8cf31742284fc5bcfc0e8d6dbd635f2659b37a34a6b90c09ed42f7db781c868a635188354dbe4bbd
+  data.tar.gz: c979ae5a583898d47c1b8501d19ea651f31013a78461008c4ed6eff69c6b1a271c2c812dbbc2a52bc82d90b7caf67e9a286e8d488639eb8bd5a8fd6678c91659

data/CHANGELOG.md

@@ -1,12 +1,24 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [1.1.7] - 2024-02-xx
+## [1.1.8] - 2024-03-xx
 
 ### Added
 ### Changed
 ### Fixed
 
+## [1.1.7] - 2024-03-xx
+
+### Added
+  - `Ecoportal::API::Common::Concerns::Benchmarkable`
+  - `Ecoportal::API::Common::Conent::CollectionModel`
+    - added ability to define **default** value for `read_only`
+
+### Fixed
+  - `Ecoportal::API::Common::Content::CollectionModel` tidied up item `klass` scoping
+    - **added** some benchmarking too
+    - memoize `@_items`
+
 ## [1.1.6] - 2024-02-29
 
 ### Added

data/lib/ecoportal/api/common/concerns/benchmarkable.rb

@@ -0,0 +1,160 @@
+module Ecoportal
+  module API
+    module Common
+      module Concerns
+        # @note While benchmarking with multi-thread gives correct results
+        #   for top unique block, will calculate the real time of each individual
+        #   thread, which is way higher than a single thread. However, as they
+        #   run in parallel, the total time would be the valid reference.
+        module Benchmarkable
+          private
+
+          def benchmark_enabled?
+            @benchmark_enabled = true if @benchmark_enabled.nil?
+            @benchmark_enabled
+          end
+
+          def benchmarking(ref = nil, print: false)
+            return yield unless benchmark_enabled?
+            benchmark_mem(ref, print: false) do
+              benchmark_time(ref, print: false) do
+                yield
+              end
+            end.tap do
+              puts "\n#{bench_summary_ref(ref)}" if print
+            end
+          end
+
+          def benchmark_mem(ref = nil, print: false)
+            return yield unless benchmark_enabled?
+            memory_before = memory_usage
+            yield.tap do
+              memory_after = memory_usage
+              mb_footprint = ((memory_after - memory_before) / 1024.0).round(2)
+              bench_add_mem(ref, mb_footprint)
+              puts bench_str_mem(mb, ref: ref, reffix: true) if print
+            end
+          end
+
+          def benchmark_time(ref = nil, print: false)
+            return yield unless benchmark_enabled?
+            result = nil
+            time   = benchmark.realtime do
+              result = yield
+            end.round(2)
+            result.tap do
+              bench_add_time(ref, time)
+              puts bench_str_time(time, ref: ref, reffix: true) if print
+            end
+          end
+
+          def benchmark_summary(ref = nil)
+            return '' unless benchmark_enabled?
+            return bench_summary_ref(ref) unless ref == :all
+
+            bench.keys.each_with_object([]) do |ref, out|
+              out << bench_summary_ref(ref)
+            end.join("\n")
+          end
+
+          def bench_summary_ref(ref = nil)
+            ref_lines = bench_summary_ref_lines(ref)
+            "- #{ref}\n" + "  • " + ref_lines.join("\n  • ")
+          end
+
+          def bench_summary_ref_lines(ref = nil)
+            ref_bench = bench_get(ref)
+            [
+              bench_str_time(*ref_bench[:time].values_at(:avg, :cnt), ref: ref),
+              bench_str_mem(*ref_bench[:mem].values_at(:avg, :cnt), ref: ref)
+            ]
+          end
+
+          def benchmark
+            require 'benchmark'
+            Benchmark
+          end
+
+          def bench
+            @bench ||= {}
+          end
+
+          def bench_add_mem(ref, mem)
+            bench_data_push(bench_get(ref)[:mem], mem)
+          end
+
+          def bench_add_time(ref, time)
+            bench_data_push(bench_get(ref)[:time], time)
+          end
+
+          def bench_get(ref)
+            bench[ref] ||= {
+              time: bench_data,
+              mem:  bench_data
+            }
+          end
+
+          def bench_data
+            {
+              avg: nil,
+              cnt: 0
+            }
+          end
+
+          def bench_data_push(data, value)
+            total       = value + ( (data[:avg] || 0) * data[:cnt])
+            data[:cnt] += 1
+            data[:avg]  = (total / data[:cnt]).round(3)
+            data
+          end
+
+          def bench_str_mem(mem, count = nil, ref: nil, reffix: false)
+            ref = reffix ? ref : nil
+            msg = [ref, 'Memory'].compact.join(' -- ')
+            cnt = count ? " (cnt: #{count})" : ''
+            "#{msg}: #{mem} MB#{cnt}"
+          end
+
+          def active_support_duration?
+            return false unless Kernel.const_defined?(:ActiveSupport)
+            ActiveSupport.const_defined?(:Duration, false)
+          end
+
+          def bench_str_time(time, count = nil, ref: nil, reffix: false)
+            ref      = reffix ? ref : nil
+            msg      = [ref, 'Time'].compact.join(' -- ')
+            total    = (time * count).round(2)
+            str_desc = ''
+            if active_support_duration? && total >= 60
+              duration = ActiveSupport::Duration.build(total.round)
+              str_desc = ": #{duration_to_s(duration)}"
+            end
+            cnt      = count ? " (cnt: #{count}; sum: #{total} s#{str_desc})" : ''
+            "#{msg}: #{time} s#{cnt}"
+          end
+
+          def duration_to_s(value)
+            return "" unless active_support_duration?
+            return "" if value.nil?
+
+            raise ArgumentError, "Expecint ActiveSupport::Duration. Given: #{value.class}" unless value.is_a?(ActiveSupport::Duration)
+            parts = value.parts.map {|pair| pair.reverse.join(" ")}
+            return parts.first if parts.length == 1
+            [parts[..-2].join(", "), parts.last].join(" and ")
+          end
+
+          # @return [Integer] total memory used by this process in KB
+          def memory_usage
+            if Gem.win_platform?
+              wmem = `wmic process where processid=#{Process.pid} get WorkingSetSize | findstr "[0-9]"`
+              return 0 unless wmem
+              wmem.lines.first.chop.strip.to_i / 1024.0
+            else
+              `ps -o rss= -p #{Process.pid}`.to_i
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/concerns.rb

@@ -0,0 +1,10 @@
+module Ecoportal
+  module API
+    module Common
+      module Concerns
+      end
+    end
+  end
+end
+
+require 'ecoportal/api/common/concerns/benchmarkable'

data/lib/ecoportal/api/common/content/array_model.rb

@@ -34,7 +34,7 @@ module Ecoportal
 
           inheritable_class_vars :order_matteres, :uniq
 
-          def initialize(doc = [], parent: self, key: nil, read_only: false)
+          def initialize(doc = [], parent: self, key: nil, read_only: self.class.read_only?)
             super(doc, parent: parent, key: key, read_only: read_only)
           end
 

data/lib/ecoportal/api/common/content/collection_model.rb

@@ -6,7 +6,6 @@ module Ecoportal
         # @note to be able to refer to the correct element of the Collection,
         #   it is required that those elements have a unique `key` that allows to identify them
         class CollectionModel < Content::DoubleModel
-
           class << self
             attr_writer   :klass
             attr_accessor :order_matters, :order_key
@@ -26,24 +25,24 @@ module Ecoportal
             #   - use block to define `klass` callback
             # @note When `klass` is resolved, if the items are of type
             #   `DoubleModel`, it sets on the collection class the `items_key`
+            # @note when `klass` is directly resolved (not via doc) only once
+            #    it will set @klass as resolved and will use this class from now on.
+            #    This is an optimization to cut class lookups
             # @param value [Hash] base `doc` (raw object) to create the object with
             # @yield [doc] identifies the target `class` of the raw object
             # @yieldparam doc [Hash]
             # @yieldreturn [Klass] the target `class`
             # @return [Klass] the target `class`
             def klass(value = NOT_USED, &block)
-              if block
-                @klass = block
-                block.call(value) if value != NOT_USED
+              @klass = block if block_given?
+
+              if @klass && !@class.is_a?(Proc)
+                @klass = resolve_class(@klass, exception: false) unless @klass.is_a?(Class)
                 @klass
-              elsif used_param?(value)
-                if @klass.is_a?(Proc)
-                  @klass.call(value)
-                else
-                  resolve_class(@klass, exception: false)
-                end
+              elsif @klass.is_a?(Proc) && used_param?(value)
+                @klass.call(value)
               else
-                resolve_class(@klass, exception: false)
+                @klass
               end.tap do |result|
                 next unless result.is_a?(Class)
                 next unless result < Ecoportal::API::Common::Content::DoubleModel
@@ -51,6 +50,19 @@ module Ecoportal
               end
             end
 
+            # @return [Boolean] are there the factory logics to build item objects defined?
+            def klass?
+              @klass || @new_item
+            end
+
+            # Optimization
+            def new_item_class_based?
+              return false if @new_item.is_a?(Proc)
+              return false if @klass.is_a?(Proc)
+              return true  if klass.is_a?(Class)
+              false
+            end
+
             # Generates a new object of the target class
             # @note
             #   - use block to define `new_item` callback, which will prevail over `klass`
@@ -60,29 +72,24 @@ module Ecoportal
             # @yield [doc, parent, key] creates an object instance of the target `klass`
             # @yieldparam doc [Hash]
             # @yieldreturn [Klass] instance object of the target `klass`
+            # @parent [CollectionModel] the parent of the new item
+            # @key [Symbol, String] the key value to access the item within collection
+            #   Please observe that items in a CollectionModel are identified via their key attr.
+            #   Meaning that there is actually no need to define this argument.
             # @return [Klass] instance object of the target `klass`
             def new_item(doc = NOT_USED, parent: nil, key: nil, read_only: false, &block)
-              if block
-                @new_item = block
-              elsif used_param?(doc)
-                raise "You should define either a 'klass' or a 'new_item' callback first" unless klass?
-                if @new_item
-                  @new_item.call(doc, parent, key)
-                else
-                  if target_class = self.klass(doc)
-                    doc.is_a?(target_class) ? doc : target_class.new(doc, parent: parent, key: key, read_only: read_only)
-                  else
-                    raise "Could not find a class for: #{doc}"
-                  end
-                end
-              else
-                raise "To define the 'new_item' callback (factory), you need to use a block"
-              end
-            end
+              return (@new_item = block; nil) if block_given
 
-            # @return [Boolean] are there the factory logics to build item objects defined?
-            def klass?
-              @klass || @new_item
+              msg = "To define the 'new_item' callback (factory), you need to use a block"
+              raise msg unless used_param?(doc)
+              msg = "You should define either a 'klass' or a 'new_item' callback first"
+              raise msg unless klass?
+              return @new_item.call(doc, parent, key)    if @new_item.is_a?(Proc)
+
+              raise "Could not find a class for: #{doc}" unless target_class = klass(doc)
+              return doc if doc.is_a?(target_class)
+
+              target_class.new(doc, parent: parent, key: key, read_only: read_only)
             end
 
             def doc_class(name)
@@ -166,6 +173,7 @@ module Ecoportal
               _doc_items.each do |item_doc|
                 elements << new_item(item_doc)
               end
+              @_items = elements if read_only?
             end
           end
 
@@ -275,7 +283,11 @@ module Ecoportal
           private
 
           def new_item(value)
-            self.class.new_item(value, parent: self, read_only: self._read_only)
+            if self.class.new_item_class_based?
+              self.class.klass.new(value, parent: self, read_only: self._read_only)
+            else
+              self.class.new_item(value, parent: self, read_only: self._read_only)
+            end
           end
 
           # Helper to remove tracked down instance variables

data/lib/ecoportal/api/common/content/double_model.rb

@@ -38,6 +38,16 @@ module Ecoportal
               uid(length)
             end
 
+            def read_only?
+              @read_only = false if @read_only.nil?
+              @read_only
+            end
+
+            # Be able to define if a class should be read-only
+            def read_only!
+              @read_only = true
+            end
+
             # Same as `attr_reader` but links to a subjacent `Hash` model property
             # @note it does **not** create an _instance variable_
             # @param methods [Array<Symbol>] the method that exposes the value
@@ -176,7 +186,7 @@ module Ecoportal
 
                 define_method method do
                   return instance_variable_get(var) if instance_variable_defined?(var)
-                  new_obj = dim_class.new(parent: self, key: method, read_only: self._read_only)
+                  new_obj = dim_class.new(parent: self, key: method, read_only: self.read_only?)
                   variable_set(var, new_obj)
                 end
               end
@@ -202,7 +212,7 @@ module Ecoportal
             # @param read_only [Boolean] whether or not should try to **work around** items `klass` missing a `key`
             #   - If set to `true` this is meant only for read purposes (won't be able to successufully insert)
             def embeds_many(method, key: method, klass: nil, enum_class: nil,
-              order_matters: false, order_key: nil, read_only: false)
+              order_matters: false, order_key: nil, read_only: self.read_only?)
               if enum_class
                 eclass = enum_class
               elsif klass
@@ -210,6 +220,7 @@ module Ecoportal
                   dim_class.klass         = klass
                   dim_class.order_matters = order_matters
                   dim_class.order_key     = order_key
+                  dim_class.read_only! if read_only
                 end
               else
                 raise "You should either specify the 'klass' of the elements or the 'enum_class'"
@@ -224,7 +235,7 @@ module Ecoportal
 
             private
 
-            def embed(method, key: method, nullable: false, multiple: false, klass:, read_only: false, &block)
+            def embed(method, key: method, nullable: false, multiple: false, klass:, read_only: self.read_only?, &block)
               method = method.to_s.freeze
               var    = instance_variable_name(method).freeze
               k      = key.to_s.freeze
@@ -251,7 +262,7 @@ module Ecoportal
                   end
                 end
 
-                embedded_class.new(doc[k], parent: self, key: k, read_only: self._read_only || read_only).tap do |obj|
+                embedded_class.new(doc[k], parent: self, key: k, read_only: self.read_only? || read_only).tap do |obj|
                   variable_set(var, obj)
                 end
               end
@@ -263,12 +274,12 @@ module Ecoportal
             end
           end
 
-          inheritable_class_vars :forced_model_keys, :key
+          inheritable_class_vars :forced_model_keys, :key, :read_only
 
           # `_key` refers to the parent's property that links to this model
           attr_reader :_parent, :_key, :_read_only
 
-          def initialize(doc = {}, parent: self, key: nil, read_only: false)
+          def initialize(doc = {}, parent: self, key: nil, read_only: self.class.read_only?)
             @_dim_vars  = []
             @_parent    = parent || self
             @_key       = key    || self
@@ -287,6 +298,12 @@ module Ecoportal
             end
           end
 
+          # @note `read_only` allows for some optimizations, such as storing values
+          #   in instance variables, for optimization purposes
+          def read_only?
+            @_read_only
+          end
+
           def root
             return self if is_root?
             _parent.root
@@ -408,6 +425,9 @@ module Ecoportal
             !!defined?(@doc)
           end
 
+          # Both requisites
+          # @note that for optimization purposes, `@doc` var may be used when
+          #   the object is `read_only?`
           def is_root?
             _parent == self && doc_var?
           end

data/lib/ecoportal/api/common.v2.rb

@@ -5,4 +5,5 @@ module Ecoportal
   end
 end
 
+require 'ecoportal/api/common/concerns'
 require 'ecoportal/api/common/content'

data/lib/ecoportal/api/v2_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GEM2_VERSION = "1.1.6"
+    GEM2_VERSION = "1.1.7"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-v2
 version: !ruby/object:Gem::Version
-  version: 1.1.6
+  version: 1.1.7
 platform: ruby
 authors:
 - Oscar Segura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-29 00:00:00.000000000 Z
+date: 2024-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -167,6 +167,8 @@ files:
 - ecoportal-api-v2.gemspec
 - lib/ecoportal/api-v2.rb
 - lib/ecoportal/api/common.v2.rb
+- lib/ecoportal/api/common/concerns.rb
+- lib/ecoportal/api/common/concerns/benchmarkable.rb
 - lib/ecoportal/api/common/content.rb
 - lib/ecoportal/api/common/content/array_model.rb
 - lib/ecoportal/api/common/content/class_helpers.rb