Class: Familia::ListKey
- Includes:
- DataType::CollectionBase
- Defined in:
- lib/familia/data_type/types/listkey.rb
Instance Attribute Summary collapse
-
#features_enabled ⇒ Object
included
from Features
readonly
Returns the value of attribute features_enabled.
- #logical_database(val = nil) ⇒ Object included from DataType::ClassMethods
-
#parent ⇒ Object
included
from DataType::ClassMethods
Returns the value of attribute parent.
-
#prefix ⇒ Object
included
from DataType::ClassMethods
Returns the value of attribute prefix.
-
#suffix ⇒ Object
included
from DataType::ClassMethods
Returns the value of attribute suffix.
-
#uri(val = nil) ⇒ Object
included
from DataType::ClassMethods
Returns the value of attribute uri.
Attributes included from Settings
#current_key_version, #default_expiration, #delim, #encryption_hkdf_salt, #encryption_hkdf_salt_history, #encryption_keys, #encryption_personalization, #encryption_personalization_history, #logical_database, #prefix, #raise_on_unsaved_parent_write, #schema_path, #schema_validator, #schemas, #strict_write_order, #suffix, #transaction_mode
Class Method Summary collapse
-
.supports_max_length? ⇒ Boolean
ListKey implements :max_length (capped collection, issue #351) with per-end semantics — intentionally not unified with SortedSet's score-based trim: #push trims from the head (keeps the newest tail, LTRIM -max_length -1), while #unshift trims from the tail (keeps the newest head, LTRIM 0 max_length-1).
Instance Method Summary collapse
- #<<(val) ⇒ Object (also: #add_element, #add)
-
#[](idx, count = nil) ⇒ Object, ...
(also: #slice)
The element at +idx+, or the elements of the range or count.
- #at(idx) ⇒ Object
- #collectraw ⇒ Object
-
#each(batch_size: 100) {|element| ... } ⇒ Enumerator, self
Iterates over elements of the list.
-
#eachraw ⇒ Object
The raw iterators need the LRANGE reply to iterate over, so they raise Familia::OperationModeError inside a transaction or pipeline.
- #eachraw_with_index ⇒ Object
-
#element_count ⇒ Integer
(also: #size, #length, #count)
Returns the number of elements in the list.
-
#empty? ⇒ Boolean, Redis::Future
Whether the list has no elements.
-
#enforce_max_length!(keep: :tail) ⇒ Integer, Redis::Future
Trims an already-oversized list down to its :max_length cap.
- #first ⇒ Object
-
#insert(position, pivot, value) ⇒ Integer, Redis::Future
(also: #linsert)
Inserts an element before or after a pivot element.
- #last ⇒ Object
-
#member?(value) ⇒ Boolean, Redis::Future
Whether the list contains +value+.
-
#members(count = -1)) ⇒ Array<Object>, Redis::Future
(also: #all)
Deserialized elements.
- #membersraw(count = -1)) ⇒ Object
-
#move(destination, wherefrom, whereto) ⇒ Object?
(also: #lmove)
Moves an element from this list to another list atomically.
-
#pop(count = nil) ⇒ Object, ...
Removes and returns the last element(s) from the list.
- #push(*values) ⇒ Object (also: #append)
-
#pushx(*values) ⇒ Integer
(also: #rpushx)
Pushes values only if the list already exists.
-
#range(sidx = 0, eidx = -1)) ⇒ Array<Object>, Redis::Future
Deserialized elements.
- #rangeraw(sidx = 0, eidx = -1)) ⇒ Object
-
#remove_element(value, count = 0) ⇒ Integer
(also: #remove)
Removes elements equal to value from the list.
- #selectraw ⇒ Object
-
#set(index, value) ⇒ String
(also: #lset)
Sets the element at the specified index.
-
#shift(count = nil) ⇒ Object, ...
Removes and returns the first element(s) from the list.
-
#to_a(count = -1)) ⇒ Array<Object>
Ruby's conversion to an Array, used by splat and Array().
-
#trim(start, stop) ⇒ String
(also: #ltrim)
Trims the list to the specified range.
- #unshift(*values) ⇒ Object (also: #prepend)
-
#unshiftx(*values) ⇒ Integer
(also: #lpushx)
Pushes values to the head only if the list already exists.
Methods included from DataType::CollectionBase
#collection_type?, #each_record
Methods included from Features::Autoloader
autoload_files, included, normalize_to_config_name
Methods included from DataType::Serialization
#deserialize_value, #deserialize_values, #deserialize_values_with_nil, #serialize_value, #strip_legacy_json_encoding
Methods included from DataType::DatabaseCommands
#current_expiration, #delete!, #echo, #exists?, #expire, #expireat, #persist, #rename, #renamenx, #type
Methods included from DataType::Connection
Methods included from Connection::Behavior
#connect, #create_dbclient, #multi, #normalize_uri, #pipeline, #pipelined, #transaction, #uri=, #url, #url=, #with_connection_scope
Methods included from Settings
#configure, #default_suffix, #dirty_write_warnings, #dirty_write_warnings=, #pipelined_mode, #pipelined_mode=
Methods included from Base
add_feature, #as_json, #expired?, #expires?, find_feature, #generate_id, #to_json, #to_s, #ttl, #update_expiration, #uuid
Constructor Details
This class inherits a constructor from Familia::DataType
Instance Attribute Details
#features_enabled ⇒ Object (readonly) Originally defined in module Features
Returns the value of attribute features_enabled.
#logical_database(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods
#parent ⇒ Object Originally defined in module DataType::ClassMethods
Returns the value of attribute parent.
#prefix ⇒ Object Originally defined in module DataType::ClassMethods
Returns the value of attribute prefix.
#suffix ⇒ Object Originally defined in module DataType::ClassMethods
Returns the value of attribute suffix.
#uri(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods
Returns the value of attribute uri.
Class Method Details
.supports_max_length? ⇒ Boolean
ListKey implements :max_length (capped collection, issue #351) with per-end semantics — intentionally not unified with SortedSet's score-based trim: #push trims from the head (keeps the newest tail, LTRIM -max_length -1), while #unshift trims from the tail (keeps the newest head, LTRIM 0 max_length-1). Either way the max_length most recently written elements survive. NOT capped: pushx/unshiftx, insert, set, move destinations, and external writers.
16 17 18 |
# File 'lib/familia/data_type/types/listkey.rb', line 16 def self.supports_max_length? true end |
Instance Method Details
#<<(val) ⇒ Object Also known as: add_element, add
61 62 63 |
# File 'lib/familia/data_type/types/listkey.rb', line 61 def <<(val) push(val) end |
#[](idx, count = nil) ⇒ Object, ... Also known as: slice
Returns the element at +idx+, or the elements of the range or count. Inside a transaction or pipeline, the LINDEX or LRANGE Future (resolves to the raw element or elements).
133 134 135 136 137 138 139 140 141 142 143 144 145 |
# File 'lib/familia/data_type/types/listkey.rb', line 133 def [](idx, count = nil) if idx.is_a? Range range idx.first, idx.last elsif count case count <=> 0 when 1 then range(idx, idx + count - 1) when 0 then [] when -1 then nil end else at idx end end |
#at(idx) ⇒ Object
267 268 269 |
# File 'lib/familia/data_type/types/listkey.rb', line 267 def at(idx) deserialize_value dbclient.lindex(dbkey, idx) end |
#collectraw ⇒ Object
257 258 259 260 |
# File 'lib/familia/data_type/types/listkey.rb', line 257 def collectraw(&) Familia.assert_replies_available!('ListKey#collectraw') rangeraw.collect(&) end |
#each(batch_size: 100) {|element| ... } ⇒ Enumerator, self
Iterates over elements of the list.
Uses LRANGE pagination for memory-efficient iteration over large lists. Unlike sets, Redis lists do not support SCAN, so we paginate through the list using index ranges.
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 |
# File 'lib/familia/data_type/types/listkey.rb', line 224 def each(batch_size: 100, &block) return to_enum(:each, batch_size: batch_size) unless block Familia.assert_replies_available!('ListKey#each') offset = 0 loop do # LRANGE is inclusive on both ends, so end_idx = offset + batch_size - 1 elements = range(offset, offset + batch_size - 1) break if elements.empty? elements.each(&block) offset += elements.size # If we got fewer than batch_size, we've reached the end break if elements.size < batch_size end self end |
#eachraw ⇒ Object
The raw iterators need the LRANGE reply to iterate over, so they raise Familia::OperationModeError inside a transaction or pipeline.
247 248 249 250 |
# File 'lib/familia/data_type/types/listkey.rb', line 247 def eachraw(&) Familia.assert_replies_available!('ListKey#eachraw') rangeraw.each(&) end |
#eachraw_with_index ⇒ Object
252 253 254 255 |
# File 'lib/familia/data_type/types/listkey.rb', line 252 def eachraw_with_index(&) Familia.assert_replies_available!('ListKey#eachraw_with_index') rangeraw.each_with_index(&) end |
#element_count ⇒ Integer Also known as: size, length, count
Returns the number of elements in the list
22 23 24 |
# File 'lib/familia/data_type/types/listkey.rb', line 22 def element_count dbclient.llen dbkey end |
#empty? ⇒ Boolean, Redis::Future
Returns whether the list has no elements. Inside a transaction or pipeline, the LLEN Future (resolves to the count).
32 33 34 |
# File 'lib/familia/data_type/types/listkey.rb', line 32 def empty? Familia.transform_reply(element_count, &:zero?) end |
#enforce_max_length!(keep: :tail) ⇒ Integer, Redis::Future
Trims an already-oversized list down to its :max_length cap. Capped writes enforce the cap going forward, but nothing runs at definition time: adding max_length: to a live collection leaves the existing overage in place until the next push/unshift. Call this once, e.g. as a migration step, to enforce the cap immediately.
The cap's per-end semantics belong to the write method (push keeps the tail, unshift keeps the head), so a manual trim must be told which end to keep: keep: :tail matches a push-fed list (the default), keep: :head an unshift-fed one.
LLEN and LTRIM run in one MULTI so the removed count is exact even under concurrent writes. Inside a caller transaction or pipeline the pair is queued bare and the pre-trim length's future is returned instead of a count.
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 |
# File 'lib/familia/data_type/types/listkey.rb', line 304 def enforce_max_length!(keep: :tail) max = require_max_length! start, stop = case keep when :tail then [-max, -1] when :head then [0, max - 1] else raise ArgumentError, "keep must be :tail or :head, got #{keep.inspect}" end warn_if_dirty! length = execute_capped_write do |conn| ret = conn.llen(dbkey) conn.ltrim(dbkey, start, stop) ret end update_expiration length.is_a?(Integer) ? [length - max, 0].max : length end |
#first ⇒ Object
421 422 423 |
# File 'lib/familia/data_type/types/listkey.rb', line 421 def first at 0 end |
#insert(position, pivot, value) ⇒ Integer, Redis::Future Also known as: linsert
Inserts an element before or after a pivot element
Refreshes the TTL only when the element was inserted. Inside a transaction or pipeline the insert and the refresh are queued as one EVAL that makes the same decision when it runs, so a missing pivot leaves the list's TTL unchanged there too.
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 |
# File 'lib/familia/data_type/types/listkey.rb', line 349 def insert(position, pivot, value) warn_if_dirty! pos = case position when :before, 'BEFORE' then 'BEFORE' when :after, 'AFTER' then 'AFTER' else raise ArgumentError, "position must be :before or :after, got #{position.inspect}" end conn = dbclient if queued_connection?(conn) return queue_conditional_write(conn, :linsert, pos, serialize_value(pivot), serialize_value(value)) end result = conn.linsert dbkey, pos, serialize_value(pivot), serialize_value(value) update_expiration_if_written(Familia.positive?(result)) result end |
#last ⇒ Object
425 426 427 |
# File 'lib/familia/data_type/types/listkey.rb', line 425 def last at(-1) end |
#member?(value) ⇒ Boolean, Redis::Future
Returns whether the list contains +value+. Inside a transaction or pipeline, the LPOS Future (resolves to the index or nil).
151 152 153 |
# File 'lib/familia/data_type/types/listkey.rb', line 151 def member?(value) Familia.transform_reply(dbclient.lpos(dbkey, serialize_value(value))) { |pos| !pos.nil? } end |
#members(count = -1)) ⇒ Array<Object>, Redis::Future Also known as: all
Returns deserialized elements. Inside a transaction or pipeline, the LRANGE Future (resolves to raw strings).
182 183 184 185 186 |
# File 'lib/familia/data_type/types/listkey.rb', line 182 def members(count = -1) echo :members, Familia.pretty_stack(limit: 1) if Familia.debug count -= 1 if count.positive? range 0, count end |
#membersraw(count = -1)) ⇒ Object
203 204 205 206 |
# File 'lib/familia/data_type/types/listkey.rb', line 203 def membersraw(count = -1) count -= 1 if count.positive? rangeraw 0, count end |
#move(destination, wherefrom, whereto) ⇒ Object? Also known as: lmove
Moves an element from this list to another list atomically
373 374 375 376 377 378 379 380 381 382 383 384 385 386 |
# File 'lib/familia/data_type/types/listkey.rb', line 373 def move(destination, wherefrom, whereto) warn_if_dirty! dest_key = destination.respond_to?(:dbkey) ? destination.dbkey : destination from = wherefrom.to_s.upcase to = whereto.to_s.upcase unless %w[LEFT RIGHT].include?(from) && %w[LEFT RIGHT].include?(to) raise ArgumentError, 'wherefrom and whereto must be :left or :right' end result = dbclient.lmove dbkey, dest_key, from, to update_expiration deserialize_value result end |
#pop(count = nil) ⇒ Object, ...
Removes and returns the last element(s) from the list
96 97 98 99 100 101 102 103 104 105 106 107 |
# File 'lib/familia/data_type/types/listkey.rb', line 96 def pop(count = nil) warn_if_dirty! ret = if count Familia.transform_reply(dbclient.rpop(dbkey, count)) do |result| result.nil? ? nil : deserialize_values(*result) end else deserialize_value dbclient.rpop(dbkey) end update_expiration ret end |
#push(*values) ⇒ Object Also known as: append
This method executes a Redis RPUSH immediately, unlike scalar field setters which are deferred until save. If the parent object has unsaved scalar field changes, consider calling save first to avoid split-brain state.
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
# File 'lib/familia/data_type/types/listkey.rb', line 39 def push(*values) warn_if_dirty! echo :push, Familia.pretty_stack(limit: 1) if Familia.debug serialized = values.flatten.compact.map { |v| serialize_value(v) } unless serialized.empty? if (max = @opts[:max_length]) # Keep the tail: RPUSH appends there, so trimming from the head # retains the max_length newest elements. execute_capped_write do |conn| ret = conn.rpush(dbkey, serialized) conn.ltrim(dbkey, -max, -1) ret end else dbclient.rpush(dbkey, serialized) end end update_expiration self end |
#pushx(*values) ⇒ Integer Also known as: rpushx
Pushes values only if the list already exists
392 393 394 395 396 397 398 399 400 401 402 |
# File 'lib/familia/data_type/types/listkey.rb', line 392 def pushx(*values) return 0 if values.empty? serialized_values = values.flatten.compact.map { |v| serialize_value(v) } return 0 if serialized_values.empty? warn_if_dirty! result = dbclient.rpushx(dbkey, serialized_values) update_expiration_if_written(Familia.positive?(result)) result end |
#range(sidx = 0, eidx = -1)) ⇒ Array<Object>, Redis::Future
Returns deserialized elements. Inside a transaction or pipeline, the LRANGE Future (resolves to raw strings).
169 170 171 172 173 |
# File 'lib/familia/data_type/types/listkey.rb', line 169 def range(sidx = 0, eidx = -1) Familia.transform_reply(rangeraw(sidx, eidx)) do |elements| deserialize_values(*elements) end end |
#rangeraw(sidx = 0, eidx = -1)) ⇒ Object
175 176 177 |
# File 'lib/familia/data_type/types/listkey.rb', line 175 def rangeraw(sidx = 0, eidx = -1) dbclient.lrange(dbkey, sidx, eidx) end |
#remove_element(value, count = 0) ⇒ Integer Also known as: remove
Removes elements equal to value from the list
159 160 161 162 163 164 |
# File 'lib/familia/data_type/types/listkey.rb', line 159 def remove_element(value, count = 0) warn_if_dirty! ret = dbclient.lrem dbkey, count, serialize_value(value) update_expiration ret end |
#selectraw ⇒ Object
262 263 264 265 |
# File 'lib/familia/data_type/types/listkey.rb', line 262 def selectraw(&) Familia.assert_replies_available!('ListKey#selectraw') rangeraw.select(&) end |
#set(index, value) ⇒ String Also known as: lset
Sets the element at the specified index
327 328 329 330 331 332 |
# File 'lib/familia/data_type/types/listkey.rb', line 327 def set(index, value) warn_if_dirty! result = dbclient.lset dbkey, index, serialize_value(value) update_expiration result end |
#shift(count = nil) ⇒ Object, ...
Removes and returns the first element(s) from the list
114 115 116 117 118 119 120 121 122 123 124 125 |
# File 'lib/familia/data_type/types/listkey.rb', line 114 def shift(count = nil) warn_if_dirty! ret = if count Familia.transform_reply(dbclient.lpop(dbkey, count)) do |result| result.nil? ? nil : deserialize_values(*result) end else deserialize_value dbclient.lpop(dbkey) end update_expiration ret end |
#to_a(count = -1)) ⇒ Array<Object>
Ruby's conversion to an Array, used by splat and Array(). A conversion method must return its type, so inside a block to_a refuses instead of returning a Redis::Future; #members passes the Future through.
197 198 199 200 201 |
# File 'lib/familia/data_type/types/listkey.rb', line 197 def to_a(count = -1) Familia.assert_replies_available!('ListKey#to_a') members(count) end |
#trim(start, stop) ⇒ String Also known as: ltrim
Trims the list to the specified range
275 276 277 278 279 280 |
# File 'lib/familia/data_type/types/listkey.rb', line 275 def trim(start, stop) warn_if_dirty! result = dbclient.ltrim dbkey, start, stop update_expiration result end |
#unshift(*values) ⇒ Object Also known as: prepend
This method executes a Redis LPUSH immediately, unlike scalar field setters which are deferred until save. If the parent object has unsaved scalar field changes, consider calling save first to avoid split-brain state.
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 |
# File 'lib/familia/data_type/types/listkey.rb', line 70 def unshift(*values) warn_if_dirty! serialized = values.flatten.compact.map { |v| serialize_value(v) } unless serialized.empty? if (max = @opts[:max_length]) # Keep the head: LPUSH prepends there, so trimming from the tail # retains the max_length newest elements. execute_capped_write do |conn| ret = conn.lpush(dbkey, serialized) conn.ltrim(dbkey, 0, max - 1) ret end else dbclient.lpush(dbkey, serialized) end end update_expiration self end |
#unshiftx(*values) ⇒ Integer Also known as: lpushx
Pushes values to the head only if the list already exists
408 409 410 411 412 413 414 415 416 417 418 |
# File 'lib/familia/data_type/types/listkey.rb', line 408 def unshiftx(*values) return 0 if values.empty? serialized_values = values.flatten.compact.map { |v| serialize_value(v) } return 0 if serialized_values.empty? warn_if_dirty! result = dbclient.lpushx(dbkey, serialized_values) update_expiration_if_written(Familia.positive?(result)) result end |