class Readthis::Serializers

Instances of the `Serializers` class are used to configure the use of multiple “serializers” for a single cache.

Readthis uses Ruby's `Marshal` module for serializing all values by default. This isn't always the fastest option, and depending on your use case it may be desirable to use a faster but less flexible serializer.

By default Readthis knows about 3 different serializers:

If all cached data can safely be represented as a string then use the pass-through serializer:

Readthis::Cache.new(marshal: Readthis::Passthrough)

You can introduce up to four additional serializers by configuring `serializers` on the Readthis module. For example, if you wanted to use the extremely fast Oj library for JSON serialization:

Readthis.serializers << Oj
# Freeze the serializers to ensure they aren't changed at runtime.
Readthis.serializers.freeze!
Readthis::Cache.new(marshal: Oj)

Be aware that the *order in which you add serializers matters*. Serializers are sticky and a flag is stored with each cached value. If you subsequently go to deserialize values and haven't configured the same serializers in the same order your application will raise errors.

Constants

BASE_SERIALIZERS

Defines the default set of three serializers: Marshal, Passthrough, and JSON. With a hard limit of 7 that leaves 4 additional slots.

SERIALIZER_LIMIT

The hard serializer limit, based on the number of possible values within a single 3bit integer.

Attributes

inverted[R]
serializers[R]

Public Class Methods

new() click to toggle source

Creates a new Readthis::Serializers entity. No configuration is expected during initialization.

# File lib/readthis/serializers.rb, line 57
def initialize
  reset!
end

Public Instance Methods

<<(serializer) click to toggle source

Append a new serializer. Up to 7 total serializers may be configured for any single application be configured for any single application. This limit is based on the number of bytes available in the option flag.

@param [Module] serializer Any object that responds to `dump` and `load` @return [self] Returns itself for possible chaining

@example Adding Oj as an accepted serializer

serializers = Readthis::Serializers.new
serializers << Oj
# File lib/readthis/serializers.rb, line 73
def <<(serializer)
  case
  when serializers.frozen?
    raise SerializersFrozenError
  when serializers.length >= SERIALIZER_LIMIT
    raise SerializersLimitError
  else
    @serializers[serializer] = flags.max.succ
    @inverted = @serializers.invert
  end

  self
end
assoc(serializer) click to toggle source

Find a flag for a serializer object.

@param [Object] serializer Look up a flag by object @return [Number] Corresponding flag for the serializer object @raise [UnknownSerializerError] Indicates that a serializer was

specified, but hasn't been configured for usage.

@example Find the JSON serializer's flag

serializers.assoc(JSON) #=> 1
# File lib/readthis/serializers.rb, line 120
def assoc(serializer)
  flag = serializers[serializer]

  unless flag
    raise UnknownSerializerError, "'#{serializer}' hasn't been configured"
  end

  flag
end
flags() click to toggle source

@private

# File lib/readthis/serializers.rb, line 149
def flags
  serializers.values
end
freeze!() click to toggle source

Freeze the serializers hash, preventing modification.

@return [self] The serializer instance.

# File lib/readthis/serializers.rb, line 91
def freeze!
  serializers.freeze

  self
end
marshals() click to toggle source

@private

# File lib/readthis/serializers.rb, line 144
def marshals
  serializers.keys
end
rassoc(flag) click to toggle source

Find a serializer object by flag value.

@param [Number] flag Integer to look up the serializer object by @return [Module] The serializer object

@example Find the serializer associated with flag 1

serializers.rassoc(1) #=> Marshal
# File lib/readthis/serializers.rb, line 139
def rassoc(flag)
  inverted[flag & SERIALIZER_LIMIT]
end
reset!() click to toggle source

Reset the instance back to the default state. Useful for cleanup during testing.

@return [self] The serializer instance.

# File lib/readthis/serializers.rb, line 102
def reset!
  @serializers = BASE_SERIALIZERS.dup
  @inverted = @serializers.invert

  self
end