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:
-
Marshal
-
JSON
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
Public Class Methods
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
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
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
@private
# File lib/readthis/serializers.rb, line 149 def flags serializers.values end
Freeze the serializers hash, preventing modification.
@return [self] The serializer instance.
# File lib/readthis/serializers.rb, line 91 def freeze! serializers.freeze self end
@private
# File lib/readthis/serializers.rb, line 144 def marshals serializers.keys end
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 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