Module: Familia::Utils

Included in:
Familia
Defined in:
lib/familia/utils.rb

Instance Method Summary collapse

Instance Method Details

#dbkey(*val) ⇒ String

Creates a dbkey from given values

Parameters:

  • val (Array) —

    elements to join for the key

Returns:



23
24
25
 
# File 'lib/familia/utils.rb', line 23

def dbkey(*val)
  join(*val)
end

#distinguisher(value_to_distinguish, strict_values: true) ⇒ String?

This method determines the appropriate transformation to apply based on the class of the input argument.

The method uses a case statement to handle different classes: - For Symbol, String, Integer, and Float classes, it traces the operation and converts the value to a string. - For Familia::Horreum class, it traces the operation and returns the identifier of the value. - For TrueClass, FalseClass, and NilClass, it traces the operation and converts the value to a string (“true”, “false”, or “”). - For any other class, it traces the operation and returns nil.

Alternative names for value_to_distinguish could be input_value, value, or object.

Parameters:

  • value_to_distinguish (Object) —

    The value to be processed. Keep in mind that all data is stored as a string so whatever the type of the value, it will be converted to a string.

  • strict_values (Boolean) (defaults to: true) —

    Whether to enforce strict value handling. Defaults to true.

Returns:

  • (String, nil) —

    The processed value as a string or nil for unsupported classes.



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/familia/utils.rb', line 93

def distinguisher(value_to_distinguish, strict_values: true)
  case value_to_distinguish
  when ::Symbol, ::String, ::Integer, ::Float
    Familia.trace :TOREDIS_DISTINGUISHER, dbclient, 'string', caller(1..1) if Familia.debug?

    # Symbols and numerics are naturally serializable to strings
    # so it's a relatively low risk operation.
    value_to_distinguish.to_s

  when ::TrueClass, ::FalseClass, ::NilClass
    Familia.trace :TOREDIS_DISTINGUISHER, dbclient, 'true/false/nil', caller(1..1) if Familia.debug?

    # TrueClass, FalseClass, and NilClass are considered high risk because their
    # original types cannot be reliably determined from their serialized string
    # representations. This can lead to unexpected behavior during deserialization.
    # For instance, a TrueClass value serialized as "true" might be deserialized as
    # a String, causing application errors. Even more problematic, a NilClass value
    # serialized as an empty string makes it impossible to distinguish between a
    # nil value and an empty string upon deserialization. Such scenarios can result
    # in subtle, hard-to-diagnose bugs. To mitigate these risks, we raise an
    # exception when encountering these types unless the strict_values option is
    # explicitly set to false.
    #
    raise Familia::HighRiskFactor, value_to_distinguish if strict_values

    value_to_distinguish.to_s #=> "true", "false", ""

  when Familia::Base, Class
    Familia.trace :TOREDIS_DISTINGUISHER, dbclient, 'base', caller(1..1) if Familia.debug?

    # When called with a class we simply transform it to its name. For
    # instances of Familia class, we store the identifier.
    if value_to_distinguish.is_a?(Class)
      value_to_distinguish.name
    else
      value_to_distinguish.identifier
    end

  else
    Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "else1 #{strict_values}", caller(1..1) if Familia.debug?

    if value_to_distinguish.class.ancestors.member?(Familia::Base)
      Familia.trace :TOREDIS_DISTINGUISHER, dbclient, 'isabase', caller(1..1) if Familia.debug?

      value_to_distinguish.identifier

    else
      Familia.trace :TOREDIS_DISTINGUISHER, dbclient, "else2 #{strict_values}", caller(1..1) if Familia.debug?
      raise Familia::HighRiskFactor, value_to_distinguish if strict_values

      nil
    end
  end
end

#join(*val) ⇒ String

Joins array elements with Familia delimiter

Parameters:

  • val (Array) —

    elements to join

Returns:



9
10
11
 
# File 'lib/familia/utils.rb', line 9

def join(*val)
  val.compact.join(Familia.delim)
end

#now(name = Time.now) ⇒ Float

Returns current time in UTC as a float

Parameters:

  • name (Time) (defaults to: Time.now) —

    time object (default: current time)

Returns:

  • (Float) —

    time in seconds since epoch



38
39
40
 
# File 'lib/familia/utils.rb', line 38

def now(name = Time.now)
  name.utc.to_f
end

#qstamp(quantum = 10.minutes, pattern: nil, time: nil) ⇒ Integer, String

A quantized timestamp

Examples:

Familia.qstamp  # Returns an integer timestamp rounded to the nearest 10 minutes
Familia.qstamp(1.hour)  # Uses 1 hour quantum
Familia.qstamp(10.minutes, pattern: '%H:%M')  # Returns a formatted string like "12:30"
Familia.qstamp(10.minutes, time: 1302468980)  # Quantizes the given Unix timestamp
Familia.qstamp(10.minutes, time: Time.now)  # Quantizes the given Time object
Familia.qstamp(10.minutes, pattern: '%H:%M', time: 1302468980)  # Formats a specific time

Parameters:

  • quantum (Integer) (defaults to: 10.minutes) —

    The time quantum in seconds (default: 10 minutes).

  • pattern (String, nil) (defaults to: nil) —

    The strftime pattern to format the timestamp.

  • time (Integer, Float, Time, nil) (defaults to: nil) —

    A specific time to quantize (default: current time).

Returns:

  • (Integer, String) —

    A unix timestamp or formatted timestamp string.



57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/familia/utils.rb', line 57

def qstamp(quantum = 10.minutes, pattern: nil, time: nil)
  time ||= Familia.now
  time = time.to_f if time.is_a?(Time)

  rounded = time - (time % quantum)

  if pattern
    Time.at(rounded).utc.strftime(pattern)
  else
    Time.at(rounded).utc.to_i
  end
end

#serverid(uri) ⇒ Object

Gets server ID without DB component for pool identification



28
29
30
31
32
33
 
# File 'lib/familia/utils.rb', line 28

def serverid(uri)
  # Create a copy of URI without DB for server identification
  uri = uri.dup
  uri.db = nil
  uri.serverid
end

#split(val) ⇒ Array

Splits a string using Familia delimiter

Parameters:

  • val (String) —

    string to split

Returns:

  • (Array) —

    split elements



16
17
18
 
# File 'lib/familia/utils.rb', line 16

def split(val)
  val.split(Familia.delim)
end