Module: Familia::Horreum::ManagementMethods
- Includes:
- AuditMethods, RelatedFieldsManagement, RepairMethods
- Defined in:
- lib/familia/horreum/management.rb
Overview
ManagementMethods - Class-level methods for Horreum model management
This module is extended into classes that include Familia::Horreum, providing class methods for database operations and object management (e.g., Customer.create, Customer.find_by_id)
Key features:
- Includes RelatedFieldsManagement for DataType field handling
- Includes AuditMethods for proactive consistency detection
- Includes RepairMethods for repair and rebuild operations
- Provides utility methods for working with Database objects
Constant Summary
Constants included from AuditMethods
AuditMethods::PARTICIPATION_KEY_TYPES
Instance Method Summary collapse
-
#all(suffix = nil) ⇒ Array<Familia::Horreum>
Loads every object of this class whose key ends in +suffix+.
-
#any? ⇒ Boolean, Redis::Future
Checks if any tracked instances exist (fast, from instances sorted set).
-
#build {|instance| ... } ⇒ Horreum
Builds, populates, and atomically persists a new instance in one step.
-
#cleanup_stale_instance_entry(objkey) ⇒ void
Removes a stale entry from the instances sorted set.
-
#config_name ⇒ String
Converts the class name into a string that can be used to look up configuration values.
-
#count ⇒ Integer, Redis::Future
(also: #size, #length)
Returns the number of tracked instances (fast, from instances sorted set).
-
#create! {|hobj| ... } ⇒ Object
Creates and persists a new instance of the class.
- #dbkey(identifier, suffix = self.suffix) ⇒ Object
-
#dbkey_pattern(identifier_glob = '*', key_suffix = suffix) ⇒ String
Returns a KEYS or SCAN MATCH pattern for this class's keys.
-
#destroy!(identifier, suffix = nil) ⇒ Boolean
Destroys an object in Database with the given identifier.
-
#exists?(identifier, suffix = nil) ⇒ Boolean, Redis::Future
Checks if an object with the given identifier exists in the database.
-
#extract_identifier_from_key(key, key_suffix = suffix) ⇒ String?
Extracts the identifier from a full Redis key by stripping the known prefix and suffix.
-
#familia_name ⇒ Object
Familia::Horreum::DefinitionMethods#familia_name.
-
#find_by_dbkey(objkey, check_exists: true) ⇒ Object?
(also: #find_by_key)
Retrieves and instantiates an object from Database using the full object key.
-
#find_by_identifier(identifier, suffix: nil, check_exists: true) ⇒ Object?
(also: #find_by_id)
Retrieves and instantiates an object from Database using its identifier.
-
#find_keys(suffix = '*') ⇒ Array<String>
Finds all keys in Database matching the given suffix pattern.
-
#in_instances?(identifier) ⇒ Boolean, Redis::Future
Checks whether the given identifier appears in the +instances+ sorted set.
-
#instantiate_from_hash(obj_hash, dbkey: nil) ⇒ Object
private
Instantiates an object from a hash of field values.
-
#key_prefix ⇒ String
Returns the key prefix for this class including the delimiter.
-
#keys_any?(filter = '*') ⇒ Boolean
Checks if any objects exist using blocking KEYS command (production-dangerous).
-
#keys_count(filter = '*') ⇒ Integer
Returns authoritative count using blocking KEYS command (production-dangerous).
-
#load_multi(identifiers, suffix = nil) ⇒ Array<Object>
(also: #load_batch)
Loads multiple objects by their identifiers using pipelined HGETALL commands.
-
#load_multi_by_keys(objkeys) ⇒ Array<Object>
Loads multiple objects by their full dbkeys using pipelined HGETALL commands.
-
#multiget ⇒ Array, Redis::Future
Reads each identifier's key with MGET and parses the stored JSON.
- #rawmultiget(*hids) ⇒ Object
-
#scan_any?(filter = '*') ⇒ Boolean
(also: #any!)
Checks if any objects exist using non-blocking SCAN command (production-safe).
-
#scan_count(filter = '*') ⇒ Integer
(also: #count!)
Returns authoritative count using non-blocking SCAN command (production-safe).
-
#scan_pattern(match_suffix = suffix) ⇒ String
Returns the SCAN pattern for finding all objects of this class.
-
#storage_inspect(identifier_or_key) ⇒ Hash{String => Hash}, ...
Decodes raw HGETALL output for debugging purposes.
Methods included from RepairMethods
#rebuild_instances, #repair_all!, #repair_indexes!, #repair_instances!, #repair_multi_indexes!, #repair_participations!, #repair_related_fields!, #scan_keys
Methods included from AuditMethods
#audit_cross_references, #audit_instances, #audit_multi_indexes, #audit_participations, #audit_related_fields, #audit_unique_indexes, #health_check
Methods included from RelatedFieldsManagement
#attach_class_related_field, #attach_instance_related_field, #configure_related_field
Instance Method Details
#all(suffix = nil) ⇒ Array<Familia::Horreum>
Loads every object of this class whose key ends in +suffix+.
This method uses the KEYS command, which blocks Redis while it scans every key in the database, so like #keys_count it is not meant for production use.
812 813 814 815 816 817 |
# File 'lib/familia/horreum/management.rb', line 812 def all(suffix = nil) Familia.assert_replies_available!("#{self}.all") suffix ||= self.suffix # objects that could not be parsed will be nil object_keys(dbclient.keys(dbkey_pattern('*', suffix))).filter_map { |k| find_by_key(k) } end |
#any? ⇒ Boolean, Redis::Future
For authoritative check, use #scan_any? (production-safe) or #keys_any? (blocking)
Checks if any tracked instances exist (fast, from instances sorted set).
This method provides O(1) performance by querying the instances sorted set.
However, objects deleted outside Familia may leave stale entries.
926 927 928 |
# File 'lib/familia/horreum/management.rb', line 926 def any? Familia.positive?(count) end |
#build {|instance| ... } ⇒ Horreum
Builds, populates, and atomically persists a new instance in one step.
This is a factory wrapper around Horreum#atomic_write for the common case of "create an object, set up its collections, and save -- all at once". The block receives the freshly-built (but not-yet-persisted) instance. Scalar assignments and collection mutations made inside the block are all committed in a single MULTI/EXEC when the block exits:
- Scalar setters (+u.name = ...+) stay in memory until the implicit save queues the HMSET inside the transaction.
- Collection mutations (+u.tags.add(...)+) auto-route into the open transaction because +DataType#dbclient+ honours +Fiber[:familia_transaction]+.
Nothing reaches the database until the block exits, so a factory no longer has to choose between sequencing +save+ before collection writes or reaching for +atomic_write+ directly.
Persistence semantics
+build+ has create-only semantics: it raises RecordExistsError if an object with the same identifier already exists. This follows the principle of least astonishment -- a factory helper should not silently overwrite existing records. Use Persistence#save or Persistence#save_with_collections when you explicitly want overwrite/upsert behaviour.
Concurrency: both paths use a WATCH + MULTI/EXEC optimistic lock on a single connection for race-safe duplicate detection (not a server-side atomic check). Without a block, +build+ delegates to Persistence#save_if_not_exists!. With a block, +atomic_write+ is called with +watch_keys:+ and +pre_check:+ so the existence check runs between WATCH and MULTI -- if the key is created by another client in that window, Redis aborts the transaction and the method retries with exponential backoff (up to 3 attempts). See issue #288.
Without a block
When called without a block there are no collection operations to fold in, so +build+ uses +save_if_not_exists!+ and returns the instance.
Positional and keyword arguments are forwarded to new. The block is NOT forwarded to the constructor -- it is invoked here, after building, with the new instance.
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 |
# File 'lib/familia/horreum/management.rb', line 178 def build(*, **) # Forward only positional/keyword args to the constructor; the block is # a post-build callback, so it must not leak into new/initialize. instance = new(*, **) if block_given? instance.atomic_write( watch_keys: [instance.dbkey], pre_check: -> { raise Familia::RecordExistsError, instance.dbkey if instance.exists? } ) { yield instance } else # No block means no collection ops to fold in, so we can use the # WATCH-guarded save_if_not_exists! directly — race-safe. instance.save_if_not_exists! end instance end |
#cleanup_stale_instance_entry(objkey) ⇒ void
This method returns an undefined value.
Removes a stale entry from the instances sorted set.
Call this explicitly when you detect that an object no longer exists and want to prune its ghost entry from the instances timeline. Finder methods (find_by_dbkey, find_by_id, load) are read-only and will not call this automatically.
335 336 337 338 339 340 341 342 343 344 345 |
# File 'lib/familia/horreum/management.rb', line 335 def cleanup_stale_instance_entry(objkey) return unless respond_to?(:instances) # Key format is prefix:identifier:suffix. Use extract_identifier_from_key # to correctly handle compound identifiers containing the delimiter. identifier = extract_identifier_from_key(objkey) return if identifier.nil? || identifier.empty? instances.remove(identifier) Familia.debug "[cleanup_stale_instance_entry] Removed stale entry: #{identifier}" end |
#config_name ⇒ String
Converts the class name into a string that can be used to look up configuration values. This is particularly useful when mapping familia models with specific database numbers in the configuration.
Familia::Horreum::DefinitionMethods#config_name
225 226 227 228 229 |
# File 'lib/familia/horreum/management.rb', line 225 def config_name return nil if name.nil? name.demodularize.snake_case end |
#count ⇒ Integer, Redis::Future Also known as: size, length
For authoritative count, use #scan_count (production-safe) or #keys_count (blocking)
Returns the number of tracked instances (fast, from instances sorted set).
This method provides O(1) performance by querying the instances sorted set,
which is automatically maintained when objects are created/destroyed through
Familia. However, objects deleted outside Familia (e.g., direct Redis commands)
may leave stale entries.
838 839 840 |
# File 'lib/familia/horreum/management.rb', line 838 def count instances.count end |
#create! {|hobj| ... } ⇒ Object
The behavior of this method depends on the implementation of #new,
exists?, and #save in the class and its superclasses.
Creates and persists a new instance of the class.
This method serves as a factory method for creating and persisting new instances of the class. It combines object instantiation, existence checking, and persistence in a single operation.
The method is flexible in accepting both positional and keyword arguments:
- Positional arguments (*args) are passed directly to the constructor.
- Keyword arguments (**kwargs) are passed as a hash to the constructor.
After instantiation, the method checks if an object with the same identifier already exists. If it does, a Familia::RecordExistsError exception is raised to prevent overwriting existing data.
Concurrency: the duplicate check is race-safe via optimistic locking. It routes through Persistence#save_if_not_exists!, which uses WATCH + MULTI/EXEC on a single connection to abort if the key appears between the check and the write. This is an effective optimistic lock, though not a server-side atomic check (e.g. Lua). See Persistence#save_if_not_exists!.
Finally, the method saves the new instance returns it.
94 95 96 97 98 99 100 101 102 103 104 105 |
# File 'lib/familia/horreum/management.rb', line 94 def create!(...) hobj = new(...) # Race-safe duplicate guard: WATCH + MULTI/EXEC optimistic lock on one # connection (not a server-side atomic check). hobj.save_if_not_exists! # If a block is given, yield the created object # This allows for additional operations on successful creation yield hobj if block_given? hobj end |
#dbkey(identifier, suffix = self.suffix) ⇒ Object
786 787 788 789 790 791 792 793 |
# File 'lib/familia/horreum/management.rb', line 786 def dbkey(identifier, suffix = self.suffix) if identifier.to_s.empty? raise NoIdentifier, "#{self} requires non-empty identifier, got: #{identifier.inspect}" end identifier &&= identifier.to_s Familia.dbkey(prefix, identifier, suffix) end |
#dbkey_pattern(identifier_glob = '*', key_suffix = suffix) ⇒ String
Returns a KEYS or SCAN MATCH pattern for this class's keys.
+identifier_glob+ is used as given, so it may contain glob wildcards. The class prefix, the delimiter and +key_suffix+ are escaped with Familia.escape_glob so they match only themselves: a class whose prefix is "app[1]" does not match the keys of a class whose prefix is "app1".
742 743 744 745 746 747 748 749 750 |
# File 'lib/familia/horreum/management.rb', line 742 def dbkey_pattern(identifier_glob = '*', key_suffix = suffix) if identifier_glob.to_s.empty? raise NoIdentifier, "#{self} requires non-empty identifier pattern, got: #{identifier_glob.inspect}" end parts = [Familia.escape_glob(prefix), identifier_glob.to_s] parts << Familia.escape_glob(key_suffix) unless key_suffix.nil? parts.join(Familia.escape_glob(Familia.delim)) end |
#destroy!(identifier, suffix = nil) ⇒ Boolean
Destroys an object in Database with the given identifier.
Deletes the main hash key, all related fields, and removes the identifier from the +instances+ sorted set. This is the class-level counterpart to the instance method of the same name.
This method is part of Familia's high-level object lifecycle management. While delete!
operates directly on dbkeys, destroy! operates at the object level and is used for
ORM-style operations. Use destroy! when removing complete objects from the system, and
delete! when working directly with dbkeys.
614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 |
# File 'lib/familia/horreum/management.rb', line 614 def destroy!(identifier, suffix = nil) # Loads the record first (to clean its class indexes), which needs replies. Familia.assert_replies_available!("#{self}.destroy!") suffix ||= self.suffix raise Familia::NoIdentifier, "#{self} requires non-empty identifier" if identifier.to_s.empty? objkey = dbkey identifier, suffix # Load the object BEFORE the transaction so its field values are available # for class-level index cleanup. Removing a unique-index entry needs the # field value (e.g. email) to HDEL the right mapping, and reads cannot run # inside MULTI/EXEC. If the hash is already gone (nil) we skip index # cleanup -- without the field values the entries to remove are unknowable. # This mirrors the instance #destroy! (which calls remove_from_class_indexes!) # so both destroy paths leave indexes consistent (see issue #241). loaded = find_by_dbkey(objkey, check_exists: false) # Execute all deletion operations within a transaction transaction do |conn| # Clean up related fields first to avoid orphaned keys if relations? fields = Familia.trace :DESTROY_RELATIONS!, nil, "#{self} has relations: #{fields.keys}" if Familia.debug? # Create a temporary instance to access related fields. # Pass identifier in constructor so init() sees it and can set dependent fields. identifier_field_name = self.identifier_field temp_instance = identifier_field_name ? new(identifier_field_name => identifier.to_s) : new fields.each do |name, _definition| obj = temp_instance.send(name) if Familia.debug? Familia.trace :DESTROY_RELATION!, name, "Deleting related field #{name} (#{Familia.loggable_text(obj.dbkey)})" end conn.del(obj.dbkey) end end # Delete the main object key ret = conn.del(objkey) Familia.trace :DESTROY!, nil, "#{objkey} #{ret.inspect}" if Familia.debug? # Clean up class-level index entries (same as instance #destroy!). # Routes its HDELs into this open transaction via Fiber[:familia_transaction]. loaded&.send(:remove_from_class_indexes!) # Remove from instances collection to avoid ghost entries instances.remove(identifier) if respond_to?(:instances) end end |
#exists?(identifier, suffix = nil) ⇒ Boolean, Redis::Future
Checks if an object with the given identifier exists in the database.
This method constructs the full dbkey using the provided identifier and suffix, then checks if the key exists in the database.
578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 |
# File 'lib/familia/horreum/management.rb', line 578 def exists?(identifier, suffix = nil) raise NoIdentifier, 'Empty identifier' if identifier.to_s.empty? suffix ||= self.suffix objkey = dbkey identifier, suffix ret = dbclient.exists objkey Familia.trace :EXISTS, nil, "#{objkey} #{ret.inspect}" if Familia.debug? # Handle Redis::Future objects during transactions return ret if ret.is_a?(Redis::Future) ret.positive? # differs from Valkey API but I think it's okay bc `exists?` is a predicate method. end |
#extract_identifier_from_key(key, key_suffix = suffix) ⇒ String?
Extracts the identifier from a full Redis key by stripping the known prefix and suffix.
This is safe for compound identifiers that contain the delimiter character (e.g., "mymodel:foo:bar:object" where the identifier is "foo:bar"). A naive split on the delimiter would truncate these.
The key is compared and sliced as bytes. The client returns a key that is not valid UTF-8 as a binary String, and comparing such a key with a prefix that holds non-ASCII characters as Strings raises Encoding::CompatibilityError. The identifier keeps the key's encoding, as the members of the instances sorted set do, so the identifiers of one record compare equal.
774 775 776 777 778 779 780 781 782 783 784 |
# File 'lib/familia/horreum/management.rb', line 774 def extract_identifier_from_key(key, key_suffix = suffix) d = Familia.delim pfx = "#{prefix}#{d}" sfx = "#{d}#{key_suffix}" bkey = key.b size = bkey.bytesize - pfx.bytesize - sfx.bytesize return nil unless size >= 0 && bkey.start_with?(pfx.b) && bkey.end_with?(sfx.b) bkey.byteslice(pfx.bytesize, size).force_encoding(key.encoding) end |
#familia_name ⇒ Object
Familia::Horreum::DefinitionMethods#familia_name
235 236 237 238 239 |
# File 'lib/familia/horreum/management.rb', line 235 def familia_name return nil if name.nil? name.demodularize end |
#find_by_dbkey(objkey, check_exists: true) ⇒ Object? Also known as: find_by_key
This method is read-only. Ghost entries (identifiers lingering in +instances+ after their hash key expires) are not cleaned up here. Use +cleanup_stale_instance_entry+ explicitly when cleanup is desired.
When check_exists: false, HGETALL on non-existent keys returns {} which we detect and return nil (not an empty object instance).
Retrieves and instantiates an object from Database using the full object key.
This method can operate in two modes:
Safe mode (check_exists: true, default):
- First checks if the key exists with EXISTS command
- Returns nil immediately if key doesn't exist
- If exists, retrieves data with HGETALL and instantiates object
- Best for: Single object lookups, defensive code
- Commands: 2 per object (EXISTS + HGETALL)
Optimized mode (check_exists: false):
- Directly calls HGETALL without EXISTS check
- Returns nil if HGETALL returns empty hash (key doesn't exist)
- Otherwise instantiates object with returned data
- Best for: Bulk operations, performance-critical paths, when keys likely exist
- Commands: 1 per object (HGETALL only)
- Reduction: 50% fewer Redis commands
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 |
# File 'lib/familia/horreum/management.rb', line 285 def find_by_dbkey(objkey, check_exists: true) Familia.assert_replies_available!("#{self}.find_by_dbkey") raise ArgumentError, 'Empty key' if objkey.to_s.empty? if check_exists # Safe mode: Check existence first (original behavior) # We use a lower-level method here b/c we're working with the # full key and not just the identifier. does_exist = Familia.positive?(dbclient.exists(objkey)) if Familia.debug? Familia.debug "[find_by_key] #{self} from key #{Familia.loggable_text(objkey)} (exists: #{does_exist})" Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey end # This is the reason for calling exists first. We want to definitively # and without any ambiguity know if the object exists in the database. If it # doesn't, we return nil. If it does, we proceed to load the object. # Otherwise, hgetall will return an empty hash, which will be passed to # the constructor, which will then be annoying to debug. return nil unless does_exist else # Optimized mode: Skip existence check if Familia.debug? Familia.debug "[find_by_key] #{self} from key #{Familia.loggable_text(objkey)} (check_exists: false)" Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey end end obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes Familia.trace :FIND_BY_DBKEY_INSPECT, nil, "#{Familia.loggable_text(objkey)}: #{obj.inspect}" if Familia.debug? # Always check for empty hash to handle race conditions where the key # expires between EXISTS check and HGETALL (when check_exists: true), # or simply doesn't exist (when check_exists: false). return nil if obj.empty? # Create instance and deserialize fields using shared helper method instantiate_from_hash(obj, dbkey: objkey) end |
#find_by_identifier(identifier, suffix: nil, check_exists: true) ⇒ Object? Also known as: find_by_id
Retrieves and instantiates an object from Database using its identifier.
Returns a fully-hydrated instance if the key exists, or +nil+ if it does not. This method never returns a "shell" object with empty fields. If you need an in-memory placeholder without loading from the database, use +new(identifier)+ instead -- but be aware that such an object has no persisted field values and will overwrite existing data if saved.
This method constructs the full dbkey using the provided identifier
and suffix, then delegates to find_by_key for the actual retrieval and
instantiation.
It's a higher-level method that abstracts away the key construction, making it easier to retrieve objects when you only have their identifier.
392 393 394 395 396 397 398 399 400 401 402 403 404 |
# File 'lib/familia/horreum/management.rb', line 392 def find_by_identifier(identifier, suffix: nil, check_exists: true) Familia.assert_replies_available!("#{self}.find_by_identifier") suffix ||= self.suffix return nil if identifier.to_s.empty? objkey = dbkey(identifier, suffix) if Familia.debug? Familia.debug "[find_by_id] #{self} from key #{Familia.loggable_text(objkey)})" Familia.trace :FIND_BY_ID, nil, objkey end find_by_dbkey objkey, check_exists: check_exists end |
#find_keys(suffix = '*') ⇒ Array<String>
Finds all keys in Database matching the given suffix pattern.
677 678 679 680 681 |
# File 'lib/familia/horreum/management.rb', line 677 def find_keys(suffix = '*') delim = Familia.escape_glob(Familia.delim) pattern = [Familia.escape_glob(prefix), '*', suffix].compact.join(delim) dbclient.keys(pattern) || [] end |
#in_instances?(identifier) ⇒ Boolean, Redis::Future
Checks whether the given identifier appears in the +instances+ sorted set.
This is a fast O(log N) ZRANK lookup (SortedSet#member?). It does NOT verify that the underlying hash key still exists in the database -- use #exists? for that. A true result means the object was persisted through Familia at some point and has not been removed from instances since.
558 559 560 561 562 |
# File 'lib/familia/horreum/management.rb', line 558 def in_instances?(identifier) return false if identifier.to_s.empty? instances.member?(identifier) end |
#instantiate_from_hash(obj_hash, dbkey: nil) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
This method:
- Allocates a new instance without calling initialize
- Initializes related DataType fields
- Deserializes and assigns field values from the hash
Instantiates an object from a hash of field values.
This is an internal helper method used by find_by_dbkey, load_multi, and load_multi_by_keys to eliminate code duplication. Not intended for direct use.
1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 |
# File 'lib/familia/horreum/management.rb', line 1007 def instantiate_from_hash(obj_hash, dbkey: nil) instance = allocate instance.instance_variable_set(:@dirty_fields, Concurrent::Map.new) instance.instance_variable_set(:@warned_dirty_signatures, Concurrent::Map.new) instance.send(:initialize_relatives) values = instance.send(:deserialize_stored_fields, obj_hash, dbkey: dbkey) instance.send(:initialize_with_keyword_args, **values) # Object was just loaded from Redis, so it matches DB state exactly. # Clear dirty flags set during field assignment above, as # Horreum#initialize and Horreum#refresh! also do. # # refresh! assigns stored values to an existing object and is meant to # leave it in the state this method produces: unstored fields nil, and # setters that see nil as the old value. It gets there differently. It # deserializes before clearing the fields, then assigns with # initialize_with_keyword_args, and restores the object if an # assignment raises. A change to how stored values are assigned here # likely needs the same change there. instance.send(:clear_dirty!) instance end |
#key_prefix ⇒ String
Returns the key prefix for this class including the delimiter.
Centralizes key prefix generation to prevent bugs from manual string interpolation across the codebase.
704 705 706 |
# File 'lib/familia/horreum/management.rb', line 704 def key_prefix "#{prefix}#{Familia.delim}" end |
#keys_any?(filter = '*') ⇒ Boolean
For production-safe authoritative check, use #scan_any?
Checks if any objects exist using blocking KEYS command (production-dangerous).
⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution. It scans ALL keys in the database and should NEVER be used in production. #scan_any? uses SCAN with a TYPE filter instead and is the production-safe choice.
951 952 953 |
# File 'lib/familia/horreum/management.rb', line 951 def keys_any?(filter = '*') Familia.positive?(keys_count(filter)) end |
#keys_count(filter = '*') ⇒ Integer
For production-safe authoritative count, use #scan_count
Returns authoritative count using blocking KEYS command (production-dangerous).
⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution. It scans ALL keys in the database and should NEVER be used in production. #scan_count uses SCAN with a TYPE filter instead and is the production-safe choice.
866 867 868 869 870 |
# File 'lib/familia/horreum/management.rb', line 866 def keys_count(filter = '*') Familia.assert_replies_available!("#{self}.keys_count") object_keys(dbclient.keys(dbkey_pattern(filter)).compact).size end |
#load_multi(identifiers, suffix = nil) ⇒ Array<Object> Also known as: load_batch
Returns nil for non-existent keys (maintains same contract as find_by_id)
Objects are returned in the same order as input identifiers
Empty/nil identifiers are skipped and return nil in result array
Loads multiple objects by their identifiers using pipelined HGETALL commands.
This method provides significant performance improvements for bulk loading by:
- Batching all HGETALL commands into a single Redis pipeline
- Eliminating network round-trip overhead
- Skipping individual EXISTS checks (like check_exists: false)
Performance characteristics:
- Standard approach: N objects × 2 commands (EXISTS + HGETALL) = 2N round trips
- check_exists: false: N objects × 1 command (HGETALL) = N round trips
- load_multi: 1 pipeline with N commands = 1 round trip
- Improvement: Up to 2N× faster for bulk operations
439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 |
# File 'lib/familia/horreum/management.rb', line 439 def load_multi(identifiers, suffix = nil) Familia.assert_replies_available!("#{self}.load_multi") suffix ||= self.suffix return [] if identifiers.empty? # Build list of valid keys and track their original positions valid_keys = [] valid_positions = [] identifiers.each_with_index do |identifier, idx| next if identifier.to_s.empty? valid_keys << dbkey(identifier, suffix) valid_positions << idx end Familia.trace :LOAD_MULTI, nil, "Loading #{identifiers.size} objects" if Familia.debug? # Pipeline all HGETALL commands multi_result = pipelined do |pipeline| valid_keys.each do |objkey| pipeline.hgetall(objkey) end end # Extract results array from MultiResult results = multi_result.results # Map results back to original positions objects = Array.new(identifiers.size) valid_positions.each_with_index do |pos, result_idx| obj_hash = results[result_idx] # Skip empty hashes (non-existent keys) next if obj_hash.nil? || obj_hash.empty? # Instantiate object using shared helper method objects[pos] = instantiate_from_hash(obj_hash, dbkey: valid_keys[result_idx]) end objects end |
#load_multi_by_keys(objkeys) ⇒ Array<Object>
Returns nil for empty/nil keys, maintaining position alignment with input array
Loads multiple objects by their full dbkeys using pipelined HGETALL commands.
This is a lower-level variant of load_multi that works directly with dbkeys instead of identifiers. Useful when you already have the full keys.
500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 |
# File 'lib/familia/horreum/management.rb', line 500 def load_multi_by_keys(objkeys) Familia.assert_replies_available!("#{self}.load_multi_by_keys") return [] if objkeys.empty? Familia.trace :LOAD_MULTI_BY_KEYS, nil, "Loading #{objkeys.size} objects" if Familia.debug? # Track which positions have valid keys to maintain result array alignment valid_positions = [] objkeys.each_with_index do |objkey, idx| valid_positions << idx unless objkey.to_s.empty? end # Pipeline all HGETALL commands for valid keys multi_result = pipelined do |pipeline| objkeys.each do |objkey| next if objkey.to_s.empty? pipeline.hgetall(objkey) end end # Extract results array from MultiResult results = multi_result.results # Map results back to original positions objects = Array.new(objkeys.size) valid_positions.each_with_index do |pos, result_idx| obj_hash = results[result_idx] # Skip empty hashes (non-existent keys) next if obj_hash.nil? || obj_hash.empty? # Instantiate object using shared helper method objects[pos] = instantiate_from_hash(obj_hash, dbkey: objkeys[pos]) end objects end |
#multiget ⇒ Array, Redis::Future
Reads each identifier's key with MGET and parses the stored JSON.
202 203 204 205 206 |
# File 'lib/familia/horreum/management.rb', line 202 def multiget(...) Familia.transform_reply(rawmultiget(...)) do |values| values.filter_map { |json| Familia::JsonSerializer.parse(json) } end end |
#rawmultiget(*hids) ⇒ Object
208 209 210 211 212 213 214 |
# File 'lib/familia/horreum/management.rb', line 208 def rawmultiget(*hids) hids.collect! { |hobjid| dbkey(hobjid) } return [] if hids.compact.empty? Familia.trace :MULTIGET, nil, "#{hids.size}: #{hids}" if Familia.debug? dbclient.mget(*hids) end |
#scan_any?(filter = '*') ⇒ Boolean Also known as: any!
For fast check (potentially stale), use #any?
Checks if any objects exist using non-blocking SCAN command (production-safe).
This method uses cursor-based SCAN iteration to check for matching keys without blocking Redis. Safe for production use and returns early on first match.
975 976 977 978 979 980 981 982 983 984 985 986 987 988 |
# File 'lib/familia/horreum/management.rb', line 975 def scan_any?(filter = '*') Familia.assert_replies_available!("#{self}.scan_any?") pattern = dbkey_pattern(filter) cursor = "0" loop do cursor, keys = dbclient.scan(cursor, match: pattern, count: 100, type: OBJECT_KEY_TYPE) return true unless keys.empty? break if cursor == "0" end false end |
#scan_count(filter = '*') ⇒ Integer Also known as: count!
For fast count (potentially stale), use #count
Returns authoritative count using non-blocking SCAN command (production-safe).
This method uses cursor-based SCAN iteration to count matching keys without blocking Redis. Safe for production use as it processes keys in chunks.
892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 |
# File 'lib/familia/horreum/management.rb', line 892 def scan_count(filter = '*') Familia.assert_replies_available!("#{self}.scan_count") pattern = dbkey_pattern(filter) count = 0 cursor = "0" loop do cursor, keys = dbclient.scan(cursor, match: pattern, count: 1000, type: OBJECT_KEY_TYPE) count += keys.size break if cursor == "0" end count end |
#scan_pattern(match_suffix = suffix) ⇒ String
Returns the SCAN pattern for finding all objects of this class.
Centralizes SCAN pattern generation to ensure consistency across rebuild strategies and other key enumeration operations.
720 721 722 |
# File 'lib/familia/horreum/management.rb', line 720 def scan_pattern(match_suffix = suffix) dbkey_pattern('*', match_suffix) end |
#storage_inspect(identifier_or_key) ⇒ Hash{String => Hash}, ...
Decodes raw HGETALL output for debugging purposes.
When inspecting data from redis-cli, field values appear as raw JSON-encoded strings (e.g. +"\"UK\""+ for the string +"UK"+). This method retrieves the hash, deserializes each value, and returns a diagnostic hash showing the raw stored form, decoded Ruby value, and Ruby type for every field.
Accepts either an identifier (resolved via +dbkey+) or a full database key (detected by the presence of the class delimiter).
1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 |
# File 'lib/familia/horreum/management.rb', line 1059 def storage_inspect(identifier_or_key) # Determine if this is a full key or an identifier objkey = if identifier_or_key.to_s.include?(Familia.delim) identifier_or_key.to_s else dbkey(identifier_or_key) end Familia.transform_reply(dbclient.hgetall(objkey)) do |raw_hash| next nil if raw_hash.empty? # Use a temporary instance for deserialization (needs serialize_value/deserialize_value) temp = allocate temp.instance_variable_set(:@dirty_fields, Concurrent::Map.new) temp.instance_variable_set(:@warned_dirty_signatures, Concurrent::Map.new) temp.send(:initialize_relatives) pass_dbkey = temp.send(:deserialize_value_takes_dbkey?) raw_hash.each_with_object({}) do |(field, raw_val), result| decoded = if pass_dbkey temp.send(:deserialize_value, raw_val, field_name: field.to_sym, dbkey: objkey) else temp.send(:deserialize_value, raw_val, field_name: field.to_sym) end result[field] = { raw: raw_val, decoded: decoded, type: decoded.class.name } end end end |